# Best Practices for Building High Performance Apps
Source: https://docs.monad.xyz/developer-essentials/best-practices

Learn best practices for building high performance apps on Monad

## Configure web hosting to keep costs under control

* Vercel and Railway provide convenient serverless platforms for hosting your
  application, abstracting away the logistics of web hosting relative to using a
  cloud provider directly. You may end up paying a premium for the convenience,
  especially at higher volumes.
* AWS and other cloud providers offer more flexibility and commodity pricing.
* Before choosing any service, check pricing and be aware that many providers
  offer loss-leader pricing on lower volumes, but then charge higher rates once
  you hit a certain threshold.
  * For example, suppose there is a \$20 plan that includes 1 TB per month of
    data transfer, with \$0.20 per GB beyond that. Do the math to note that the second TB
    (and onward) will cost \$200. If the next tier up says "contact us", don't
    assume the next tier up will be charging \$20 per TB.
  * If you are building a high-traffic app and you aren't careful about serving
    static files more cheaply, it will be easy to exceed the loss-leader tier
    and pay much more than you expect.
* For production deployments on AWS, consider:
  * Amazon S3 + CloudFront for static file hosting and CDN
  * AWS Lambda for serverless functions
  * Amazon ECS or EKS for containerized applications
  * Amazon RDS for database needs
  * This setup typically provides granular cost control and scalability for
    high-traffic applications.

## Use a hardcoded value instead of `eth_estimateGas` call if gas usage is static

Many on-chain actions have a fixed gas cost. The simplest example is that a
transfer of native tokens always costs 21,000 gas, but there are many others.
This makes it unnecessary to call `eth_estimateGas` for each transaction.

Use a hardcoded value instead, as suggested
[here](/developer-essentials/gas-pricing#set-the-gas-limit-explicitly-if-it-is-constant).
Eliminating an `eth_estimateGas` call substantially speeds up the user workflow
in the wallet, and avoids a potential bad behavior in some wallets when
`eth_estimateGas` reverts (discussed in the linked page).

## Reduce `eth_call` latency by submitting multiple requests concurrently

Making multiple `eth_call` requests serially will introduce unnecessary latency
due to multiple round trips to an RPC node. You can make many `eth_call`s
concurrently, either by condensing them into a single `eth_call` or by
submitting a batch of calls. Alternatively, you might find it better to switch
to an indexer.

### Condensing multiple `eth_call`s into one

* **Multicall:** Multicall is a utility smart contract that allows you to
  aggregate multiple read requests (`eth_call`) into a single one. This is
  particularly effective for fetching data points like token balances,
  allowances, or contract parameters simultaneously. The standard `Multicall3`
  contract is deployed at
  [`0xcA11bde05977b3631167028862bE2a173976CA11`](https://monadvision.com/address/0xcA11bde05977b3631167028862bE2a173976CA11) on both Monad Mainnet and Monad Testnet.
  Many libraries offer helper functions to simplify multicall usage, e.g.
  [viem](https://viem.sh/docs/contract/multicall.html). Read more about
  `Multicall3` [here](https://www.multicall3.com).
* **Custom Batching Contracts:** For complex read patterns or scenarios not
  easily handled by the standard multicall contract, you can deploy a custom
  smart contract that aggregates the required data in a single function, which
  can then be invoked via a single `eth_call`.

<Note>
  Multicall executes calls serially as you can see from the code
  [**here**](https://monadvision.com/address/0xcA11bde05977b3631167028862bE2a173976CA11?tab=Contract#file-Multicall3.sol).
  So while using multicall avoids multiple round trips to an RPC server, it is
  still inadvisable to put too many expensive calls into one multicall. A batch
  of calls (explained next) can be executed on the RPC in parallel.
</Note>

### Submitting a batch of calls

Most major libraries support batching multiple RPC requests into a single
message.

For example, `viem` handles `Promise.all()` on an array of promises by
submitting them as a single batch:

```javascript theme={null}
const resultPromises = Array(BATCH_SIZE)
  .fill(null)
  .map(async (_, i) => {
    return await PUBLIC_CLIENT.simulateContract({
        address: ...,
        abi: ...,
        functionName: ...,
        args: [...],
      })
  })
const results = await Promise.all(resultPromises)
```

### Use indexers for read-heavy loads

If your application frequently queries historical events or derived state,
consider using an indexer, as described next.

## Use an indexer instead of repeatedly calling `eth_getLogs` to listen for your events

Below is a quickstart guide for the most popular data indexing solutions. Please
view the [indexer docs](/tooling-and-infra/indexers/) for more details.

### Using Allium

<Note>
  See also: [**Allium**](/tooling-and-infra/indexers/common-data#allium)

  You'll need an Allium account, which you can request
  [here](https://www.allium.so/contact).
</Note>

* Allium Explorer
  * Blockchain analytics platform that provides SQL-based access to
    historical blockchain data (blocks, transactions, logs, traces, and
    contracts).
  * You can create Explorer APIs through the
    [GUI](https://app.allium.so/explorer/api) to query and analyze historical
    blockchain data. When creating a Query for an API
    [here](https://app.allium.so/explorer/queries) (using the `New` button),
    select `Monad Mainnet` or `Monad Testnet` from the chain list.
  * Relevant docs:
    * [Explorer Documentation](https://docs.allium.so/app/overview)
    * [Explorer API](https://docs.allium.so/api/explorer/overview)
* Allium Datastreams
  * Provides real-time blockchain data streams (including blocks,
    transactions, logs, traces, contracts, and balance snapshots) through
    Kafka, Pub/Sub, and Amazon SNS.
  * [GUI](https://app.allium.so/developer/streams/new) to create new streams
    for onchain data. When creating a stream, select the relevant `Monad
    Mainnet` or `Monad Testnet` topics from the `Select topics` dropdown.
  * Relevant docs:
    * [Datastreams Documentation](https://docs.allium.so/data-products-real-time/allium-datastreams)
    * [Getting Started with Google Pub/Sub](https://docs.allium.so/data-products-real-time/allium-datastreams/kafka-pubsub/getting-started-with-google-pub-sub)
* Allium Developers
  * Enables fetching wallet transaction activity and tracking balances
    (native, ERC20, ERC721, ERC1155).
  * For the request's body, use `monad_mainnet` for Monad Mainnet or `monad_testnet` for Monad Testnet as the `chain` parameter.
  * Relevant docs:
    * [API Key Setup Guide](https://docs.allium.so/data-products-real-time/allium-developer/wallet-apis-1#getting-started)
    * [Wallet APIs Documentation](https://docs.allium.so/data-products-real-time/allium-developer/wallet-apis)

### Using Envio HyperIndex

<Note>
  See also: [**Envio**](/tooling-and-infra/indexers/indexing-frameworks#envio)
  and [**Guide: How to use Envio HyperIndex to build a token transfer notification bot**](/guides/indexers/tg-bot-using-envio)
</Note>

* Follow the [quick start](https://docs.envio.dev/docs/HyperIndex/contract-import)
  to create an indexer. In the `config.yaml` file, use network ID `10143` to
  select Monad testnet (used in the example below) or network ID `143` for Monad mainnet.

* Example configuration
  * Sample `config.yaml` file
    ```yaml lines title="config.yaml" theme={null}
    name: your-indexers-name
    networks:
    - id: 10143  # Monad Testnet
      # Optional custom RPC configuration - only add if default indexing has issues
      # rpc_config:
      #   url: YOUR_RPC_URL_HERE  # Replace with your RPC URL (e.g., from Alchemy)
      #   interval_ceiling: 50     # Maximum number of blocks to fetch in a single request
      #   acceleration_additive: 10  # Speed up factor for block fetching
      #   initial_block_interval: 10  # Initial block fetch interval size
      start_block: 0  # Replace with the block you want to start indexing from
      contracts:
      - name: YourContract  # Replace with your contract name
        address:
        - 0x0000000000000000000000000000000000000000  # Replace with your contract address
        # Add more addresses if needed for multiple deployments of the same contract
        handler: src/EventHandlers.ts
        events:
        # Replace with your event signatures
        # Format: EventName(paramType paramName, paramType2 paramName2, ...)
        # Example: Transfer(address from, address to, uint256 amount)
        # Example: OrderCreated(uint40 orderId, address owner, uint96 size, uint32 price, bool isBuy)
        - event: EventOne(paramType1 paramName1, paramType2 paramName2)
        # Add more events as needed
    ```

  * Sample `EventHandlers.ts`
    ```tsx lines title="EventHandlers.ts" theme={null}
    import {
      YourContract,
      YourContract_EventOne,
    } from "generated";

    // Handler for EventOne
    // Replace parameter types and names based on your event definition
    YourContract.EventOne.handler(async ({ event, context }) => {
      // Create a unique ID for this event instance
      const entity: YourContract_EventOne = {
        id: `${event.chainId}_${event.block.number}_${event.logIndex}`,
        // Replace these with your actual event parameters
        paramName1: event.params.paramName1,
        paramName2: event.params.paramName2,
        // Add any additional fields you want to store
      };

      // Store the event in the database
      context.YourContract_EventOne.set(entity);
    })

    // Add more event handlers as needed
    ```

* Important: The `rpc_config` section under a network (check `config.yaml`
  sample) is optional and should only be configured if you experience issues
  with the default Envio setup. This configuration allows you to:
  * Use your own RPC endpoint
  * Configure block fetching parameters for better performance

* Relevant docs:
  * [Overview](https://docs.envio.dev/docs/HyperIndex/overview)

### Using GhostGraph

<Note>
  See also: [**Ghost**](/tooling-and-infra/indexers/indexing-frameworks#ghost)
</Note>

* Relevant docs:
  * [Getting Started](https://docs.tryghost.xyz/category/-getting-started)
  * [Setting up a GhostGraph Indexer on Monad Testnet](/guides/indexers/ghost#setting-up-ghostgraph-indexing)

### Using Goldsky

<Note>
  See also: [**Goldsky**](/tooling-and-infra/indexers/common-data#goldsky)
</Note>

* Goldsky Subgraphs
  * To deploy a Goldsky subgraph follow
    [this guide](https://docs.goldsky.com/subgraphs/deploying-subgraphs#from-source-code).
  * As the network identifier, use `monad-mainnet` for Monad Mainnet or `monad-testnet` for Monad Testnet. For subgraph
    configuration examples, refer to [The Graph Protocol section](#using-the-graphs-subgraph)
    below.
  * For information about querying Goldsky subgraphs, see the
    [GraphQL API documentation](https://docs.goldsky.com/subgraphs/graphql-endpoints).
* Goldsky Mirror
  * Enables direct streaming of on-chain data to your database.
  * For the chain name in the `dataset_name` field when creating a `source`
    for a pipeline, use `monad_mainnet` for Monad Mainnet or `monad_testnet` for Monad Testnet (check below example)
  * Example `pipeline.yaml` config file
    ```yaml lines title="pipeline.yaml" theme={null}
    name: monad-testnet-erc20-transfers
    apiVersion: 3
    sources:
      monad_testnet_erc20_transfers:
        dataset_name: monad_testnet.erc20_transfers
        filter: address = '0x0' # Add erc20 contract address. Multiple addresses can be added with 'OR' operator: address = '0x0' OR address = '0x1'
        version: 1.2.0
        type: dataset
        start_at: earliest

    # Data transformation logic (optional)
    transforms:
      select_relevant_fields:
        sql: |
          SELECT
              id,
              address,
              event_signature,
              event_params,
              raw_log.block_number as block_number,
              raw_log.block_hash as block_hash,
              raw_log.transaction_hash as transaction_hash
          FROM
              ethereum_decoded_logs
        primary_key: id

    # Sink configuration to specify where data goes eg. DB
    sinks:
      postgres:
        type: postgres
        table: erc20_transfers
        schema: goldsky
        secret_name: A_POSTGRESQL_SECRET
        from: select_relevant_fields
    ```
  * Relevant docs:
    * [Getting Started with Mirror](https://docs.goldsky.com/mirror/create-a-pipeline#goldsky-cli)
    * [Data Streaming Guides](https://docs.goldsky.com/mirror/guides/)

### Using QuickNode Streams

<Note>
  See also: [**QuickNode Streams**](/tooling-and-infra/indexers/common-data#quicknode)
</Note>

* On your QuickNode Dashboard, select `Streams` > `Create Stream`. In the create
  stream UI, select Monad Mainnet or Monad Testnet under Network. Alternatively, you can use the
  [Streams REST API](https://www.quicknode.com/docs/streams/rest-api/getting-started)
  to create and manage streams—use `monad-mainnet` for Monad Mainnet or `monad-testnet` for Monad Testnet as the network identifier.
* You can consume a Stream by choosing a destination during stream creation.
  Supported destinations include Webhooks, S3 buckets, and PostgreSQL
  databases. Learn more
  [here](https://www.quicknode.com/docs/streams/destinations).
* Relevant docs:
  * [Getting Started](https://www.quicknode.com/docs/streams/getting-started)

### Using The Graph's Subgraph

<Note>
  See also: [**The Graph**](/tooling-and-infra/indexers/indexing-frameworks#the-graph)
</Note>

* Network ID: Use `monad-mainnet` for Monad Mainnet or `monad-testnet` for Monad Testnet
* Example configuration
  * Sample `subgraph.yaml` file
    ```yaml lines title="subgraph.yaml" theme={null}
    specVersion: 1.2.0
    indexerHints:
      prune: auto
    schema:
      file: ./schema.graphql
    dataSources:
      - kind: ethereum
        name: YourContractName # Replace with your contract name
        network: monad-testnet # Monad testnet configuration
        source:
          address: "0x0000000000000000000000000000000000000000" # Replace with your contract address
          abi: YourContractABI # Replace with your contract ABI name
          startBlock: 0 # Replace with the block where your contract was deployed/where you want to index from
        mapping:
          kind: ethereum/events
          apiVersion: 0.0.9
          language: wasm/assemblyscript
          entities:
            # List your entities here - these should match those defined in schema.graphql
            # - Entity1
            # - Entity2
          abis:
            - name: YourContractABI # Should match the ABI name specified above
              file: ./abis/YourContract.json # Path to your contract ABI JSON file
          eventHandlers:
            # Add your event handlers here, for example:
            # - event: EventName(param1Type, param2Type, ...)
            #   handler: handleEventName
          file: ./src/mapping.ts # Path to your event handler implementations
    ```

  * Sample `mappings.ts` file
    ```tsx lines title="mappings.ts" theme={null}
    import {
      // Import your contract events here
      // Format: EventName as EventNameEvent
      EventOne as EventOneEvent,
      // Add more events as needed
    } from "../generated/YourContractName/YourContractABI" // Replace with your contract name, abi name you supplied in subgraph.yaml

    import {
      // Import your schema entities here
      // These should match the entities defined in schema.graphql
      EventOne,
      // Add more entities as needed
    } from "../generated/schema"

    /**
      * Handler for EventOne
      * Update the function parameters and body according to your event structure
      */
    export function handleEventOne(event: EventOneEvent): void {
      // Create a unique ID for this entity
      let entity = new EventOne(
        event.transaction.hash.concatI32(event.logIndex.toI32())
      )
      
      // Map event parameters to entity fields
      // entity.paramName = event.params.paramName
      
      // Example:
      // entity.sender = event.params.sender
      // entity.amount = event.params.amount

      // Add metadata fields
      entity.blockNumber = event.block.number
      entity.blockTimestamp = event.block.timestamp
      entity.transactionHash = event.transaction.hash

      // Save the entity to the store
      entity.save()
    }

    /**
      * Add more event handlers as needed
      * Format:
      * 
      * export function handleEventName(event: EventNameEvent): void {
      *   let entity = new EventName(
      *     event.transaction.hash.concatI32(event.logIndex.toI32())
      *   )
      *   
      *   // Map parameters
      *   entity.param1 = event.params.param1
      *   entity.param2 = event.params.param2
      *   
      *   // Add metadata
      *   entity.blockNumber = event.block.number
      *   entity.blockTimestamp = event.block.timestamp
      *   entity.transactionHash = event.transaction.hash
      *   
      *   entity.save()
      * }
      */
    ```

  * Sample `schema.graphql` file
    ```graphql lines title="schema.graphql" theme={null}
    # Define your entities here
    # These should match the entities listed in your subgraph.yaml

    # Example entity for a generic event
    type EventOne @entity(immutable: true) {
      id: Bytes!
      
      # Add fields that correspond to your event parameters
      # Examples with common parameter types:
      # paramId: BigInt!              # uint256, uint64, etc.
      # paramAddress: Bytes!          # address
      # paramFlag: Boolean!           # bool
      # paramAmount: BigInt!          # uint96, etc.
      # paramPrice: BigInt!           # uint32, etc.
      # paramArray: [BigInt!]!        # uint[] array
      # paramString: String!          # string
      
      # Standard metadata fields
      blockNumber: BigInt!
      blockTimestamp: BigInt!
      transactionHash: Bytes!
    }

    # Add more entity types as needed for different events
    # Example based on Transfer event:
    # type Transfer @entity(immutable: true) {
    #   id: Bytes!
    #   from: Bytes!                  # address
    #   to: Bytes!                    # address
    #   tokenId: BigInt!              # uint256
    #   blockNumber: BigInt!
    #   blockTimestamp: BigInt!
    #   transactionHash: Bytes!
    # }

    # Example based on Approval event:
    # type Approval @entity(immutable: true) {
    #   id: Bytes!
    #   owner: Bytes!                 # address
    #   approved: Bytes!              # address
    #   tokenId: BigInt!              # uint256
    #   blockNumber: BigInt!
    #   blockTimestamp: BigInt!
    #   transactionHash: Bytes!
    # }
    ```
* Relevant docs:
  * [Quickstart](https://thegraph.com/docs/en/subgraphs/quick-start/)

### Using thirdweb's Insight API

<Note>
  See also: [**thirdweb**](/tooling-and-infra/indexers/common-data#thirdweb)
</Note>

* REST API offering a wide range of on-chain data, including events, blocks,
  transactions, token data (such as transfer transactions, balances, and token
  prices), contract details, and more.
* Use chain ID `143` for Monad Mainnet or `10143` for Monad Testnet when constructing request URLs.
* Relevant docs:
  * [Get started](https://insight.thirdweb.com/reference)

## Manage nonces locally if sending multiple transactions in quick succession

<Note>
  This only applies if you are setting nonces manually. If you are delegating
  this to the wallet, no need to worry about this.
</Note>

* `eth_getTransactionCount` requires a network request. If
  you have multiple transactions from the same wallet in short succession, you
  should implement local nonce tracking.

## Submit multiple transactions concurrently

If you are submitting a series of transactions, instead submitting
sequentially, implement concurrent transaction submission for improved
efficiency.

Before:

```jsx lines theme={null}
for (let i = 0; i < TIMES; i++) {
  const tx_hash = await WALLET_CLIENT.sendTransaction({
    account: ACCOUNT,
    to: ACCOUNT_1,
    value: parseEther('0.1'),
    gasLimit: BigInt(21000),
    baseFeePerGas: BigInt(50000000000),
    chain: CHAIN,
    nonce: nonce + Number(i),
  })
}
```

After:

```jsx lines theme={null}
const transactionsPromises = Array(BATCH_SIZE)
  .fill(null)
  .map(async (_, i) => {
    return await WALLET_CLIENT.sendTransaction({
      to: ACCOUNT_1,
      value: parseEther('0.1'),
      gasLimit: BigInt(21000),
      baseFeePerGas: BigInt(50000000000),
      chain: CHAIN,
      nonce: nonce + Number(i),
    })
  })
const hashes = await Promise.all(transactionsPromises)
```


# Changelog
Source: https://docs.monad.xyz/developer-essentials/changelog/index



We provide several changelogs:

* [Releases](/developer-essentials/changelog/releases): a list of all notable releases. Some releases only apply to one network.
* [Testnet Changelog](/developer-essentials/changelog/testnet): only changes made to `testnet`

## How changes happen in Monad

[Revisions](#revisions) are behavioral changes to the protocol (as contrasted with efficiency
improvements to the client, which don't impact correctness). Revisions are referred to in other
blockchains as hard forks.

Monad tracks revisions with a counter. The client code typically activates revisions at a future
timestamp so that validators can come to agreement about whether to accept the revision and
upgrade ahead of time. When the future timestamp is hit, a supermajority of the validators have
already upgraded, and they update their behavior in sync, allowing the chain to continue without
any pauses.

There are multiple networks (owing to the existence of several test networks). Each network
has a different schedule for when each Revision is adopted. These schedules are tracked in
[ChainConfigs](#chainconfigs).

The node software is under active development, resulting in occasional [releases](/developer-essentials/changelog/releases).
Releases are rolled out to different networks at different schedules, and not all releases apply
to all networks.

### Revisions

Monad revisions are major behavioral changes to the protocol, as defined in
[`revision.h`](https://github.com/category-labs/monad/blob/main/category/vm/evm/monad/revision.h).

<div>
  <table>
    <thead>
      <tr>
        <th>Revision</th>
        <th>Notes</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td><code>MONAD\_NINE</code></td>

        <td>
          <ul>
            <li>\[[MIP-3](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-3.md)] Linear memory implementation</li>
            <li>\[[MIP-4](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-4.md)] Reserve balance precompile</li>
            <li>\[[MIP-5](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-5.md)] Activate Osaka fork (CLZ opcode)</li>
          </ul>
        </td>
      </tr>

      <tr>
        <td><code>MONAD\_EIGHT</code></td>

        <td>
          <ul>
            <li>[Reserve balance](/developer-essentials/reserve-balance) checks now use final state code hash</li>
            <li>\[Staking] Reduce pagination on staking precompile inverse mappings (`precompile_get_delegations()` and `precompile_get_delegators()`) from 100 to 50</li>
          </ul>
        </td>
      </tr>

      <tr>
        <td><code>MONAD\_SEVEN</code></td>

        <td>
          <ul>
            <li>[Opcode pricing](/developer-essentials/opcode-pricing) implemented</li>
          </ul>
        </td>
      </tr>

      <tr>
        <td><code>MONAD\_SIX</code></td>

        <td>
          <ul>
            <li>EIP-2935 bugfix</li>
          </ul>
        </td>
      </tr>

      <tr>
        <td><code>MONAD\_FIVE</code></td>

        <td>
          <ul>
            <li>\[Staking] Lower `ACTIVE_VALIDATOR_STAKE` from `25,000,000 MON` to `10,000,000 MON`</li>
          </ul>
        </td>
      </tr>

      <tr>
        <td><code>MONAD\_FOUR</code></td>

        <td>
          <ul>
            <li>[Staking](/monad-arch/consensus/staking) goes live with the following parameters:<ul><li>`ACTIVE_VALIDATOR_STAKE = 25,000,000 MON`</li><li>`MIN_AUTH_ADDRESS_STAKE = 100,000 MON`</li></ul></li>
            <li>[Reserve balance](/developer-essentials/reserve-balance)</li>
            <li> [EIP-7702](/developer-essentials/eip-7702)</li>
            <li>[Dynamic base fee](/developer-essentials/gas-pricing)</li>
            <li>Min base fee [raised](/developer-essentials/gas-pricing) (50 MON-gwei -> 100 MON-gwei)</li>
            <li>[Per-transaction gas limit](/developer-essentials/gas-pricing) of 30M gas</li>
            <li>Block gas limit (150M -> 200M), i.e. gas per second 375Mgps -> 500Mgps</li>
            <li>Enable [EIP-2935](https://eips.ethereum.org/EIPS/eip-2935) (extended historical block hashes)</li>
            <li>Enable [EIP-7951](https://eips.ethereum.org/EIPS/eip-7951) (P256VERIFY precompile)</li>
            <li>Enable [EIP-2537](https://eips.ethereum.org/EIPS/eip-2537) (BLS12-381 precompiles)</li>
            <li>Raise max contract size for `CREATE`/`CREATE2` to 128 kb</li>
          </ul>
        </td>
      </tr>

      <tr>
        <td><code>MONAD\_THREE</code></td>
        <td><ul><li>[MonadBFT](/monad-arch/consensus/monad-bft) implemented</li> <li>Block time (500ms -> 400ms), i.e. gas per second 300Mgps -> 375Mgps</li></ul></td>
      </tr>

      <tr>
        <td><code>MONAD\_TWO</code></td>
        <td><ul><li>Raise max contract size for plain contract creation transactions (24.5kb -> 128 kb)</li></ul></td>
      </tr>

      <tr>
        <td><code>MONAD\_ONE</code></td>
        <td><ul><li>Block time (1s -> 500ms)</li> <li>Block gas limit (300M -> 150M); gas per second unchanged at 300Mgps</li> <li>Transactions [charged by gas limit](/developer-essentials/gas-pricing)</li></ul></td>
      </tr>
    </tbody>
  </table>
</div>

### ChainConfigs

Each ChainConfig describes one network, including its history of upgrading to different Revisions.
The ChainConfigs are defined in
[`monad-chain-config/src/lib.rs`](https://github.com/category-labs/monad-bft/blob/master/monad-chain-config/src/lib.rs).

| ChainConfig | Notes                                                                    |
| ----------- | ------------------------------------------------------------------------ |
| `mainnet`   | Chain id 143                                                             |
| `testnet`   | Chain id 10143; see [changelog](/developer-essentials/changelog/testnet) |
| `devnet`    | Chain id 20143                                                           |


# Mainnet Changelog
Source: https://docs.monad.xyz/developer-essentials/changelog/mainnet



This is a curated list of only changes affecting [mainnet](/developer-essentials/network-information).

<Note>
  We group changes into

  * protocol changes (generally requiring a new [Revision](/developer-essentials/changelog#revisions))
    * generally tagged with **\[EVM]**, **\[Consensus]**, or **\[Network params]**
  * RPC/SDK behavioral changes (generally tagged with **\[RPC]**)
  * performance changes
    * tagged based on the nature of the change as **\[EVM]**, **\[Consensus]**, or **\[RPC]**
  * internal/node-ops changes (generally tagged as **\[Node ops]**)
</Note>

## v0.13.1 \[2026-03-16]

Revision: [`MONAD_NINE`](/developer-essentials/changelog#revisions) (unchanged)

Tags or hashes:

* `monad-bft` (consensus): [tag `v0.13.1`](https://github.com/category-labs/monad-bft/releases/tag/v0.13.1) (`7db6cea2`)
* `monad` (execution): [tag `v0.13.1`](https://github.com/category-labs/monad/releases/tag/v0.13.1) (`722cbf5b5`)

> **Note:** This is a patch release based on v0.13.0 to fix State Archive node RPC issues. The monad (execution) tag points to the same commit as v0.13.0.

#### Notable robustness changes

* **\[RPC]** Use latest voted as fallback for last\_proposed
  * Ref: [monad-bft PR #2857](https://github.com/category-labs/monad-bft/pull/2857)

## v0.13.0 \[2026-03-12]

Revision: [`MONAD_NINE`](/developer-essentials/changelog#revisions) (upgrade; Thursday, 2026-03-19 at 14:30 GMT)

Tags or hashes:

* `monad-bft` (consensus): [tag `v0.13.0`](https://github.com/category-labs/monad-bft/releases/tag/v0.13.0)
* `monad` (execution): [tag `v0.13.0+1`](https://github.com/category-labs/monad/releases/tag/v0.13.0+1)

> **Note:** The canonical release version is `v0.13.0`. The `+1` build metadata on the monad execution tag indicates a post-release rebuild that includes the reserve balance precompile fallback cost fix ([PR #2109](https://github.com/category-labs/monad/pull/2109)).

#### Highlights

* **RPC: `latest` block tag: `Finalized` -> `Proposed`** — queries with the `latest` block tag now return data from the latest proposed block, reducing query latency for `eth_getBalance`, `eth_call`, and other state queries.
* **RPC: `eth_sendRawTransactionSync`: `Voted` -> `Proposed`** — earlier receipts when using the `eth_sendRawTransactionSync` method.
* **Websocket: `newHeads/logs`: `Finalized` -> `Voted`** — earlier notifications for websocket subscribers to either `newHeads` or `logs`.

#### Notable protocol changes

All updates below are gated by the `MONAD_NINE` revision

* **\[EVM]** [MIP-3](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-3.md): Linear memory implementation
  * Ref: [monad PR #2032](https://github.com/category-labs/monad/pull/2032)
* **\[Execution]** [MIP-4](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-4.md): Reserve balance precompile
  * Ref: [monad PR #2040](https://github.com/category-labs/monad/pull/2040) (scaffolding)
  * Ref: [monad PR #2065](https://github.com/category-labs/monad/pull/2065) (cached/incremental checks)
  * Ref: [monad PR #2086](https://github.com/category-labs/monad/pull/2086) (add dippedIntoReserve)
  * Ref: [monad PR #2106](https://github.com/category-labs/monad/pull/2106) (dippedIntoReserve argument length error)
  * Ref: [monad PR #2109](https://github.com/category-labs/monad/pull/2109) (fallback cost fix for clean spec)
  * Ref: [monad PR #2037](https://github.com/category-labs/monad/pull/2037) (skip reserve checks for init-selfdestruct)
* **\[EVM]** [MIP-5](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-5.md): Activate Osaka fork (CLZ opcode)
  * Ref: [monad PR #2024](https://github.com/category-labs/monad/pull/2024)

> **Hard Fork:** This release activates MONAD\_NINE at timestamp `1773153000` (testnet) / `1773930600` (mainnet). Nodes must upgrade before activation.

#### Notable RPC/SDK changes

* **\[RPC]** Latest blocktag uses proposed blocks
  * Ref: [monad-bft PR #2675](https://github.com/category-labs/monad-bft/pull/2675)
* **\[RPC]** Use voted blocks in websocket notifications
  * Ref: [monad-bft PR #2799](https://github.com/category-labs/monad-bft/pull/2799)
* **\[RPC]** Add experimental flag to RPC doc macro
  * Ref: [monad-bft PR #2773](https://github.com/category-labs/monad-bft/pull/2773)
* **\[RPC]** Refactor RPC middleware for improved request handling
  * Ref: [monad-bft PR #2805](https://github.com/category-labs/monad-bft/pull/2805)
* **\[RPC]** Add decompression guard to RPC
  * Ref: [monad-bft PR #2793](https://github.com/category-labs/monad-bft/pull/2793)

#### Notable robustness changes

* **\[Consensus]** Add signature verifier for Raptorcast
  * Ref: [monad-bft PR #2747](https://github.com/category-labs/monad-bft/pull/2747)
* **\[Consensus]** Fix reactivate logic in r10 decoder
  * Ref: [monad-bft PR #2740](https://github.com/category-labs/monad-bft/pull/2740)
* **\[Execution]** Fix buffer overflow in C->Rust logging
  * Ref: [monad-bft PR #2769](https://github.com/category-labs/monad-bft/pull/2769)
* **\[Consensus]** Add global connect rate limit to wireauth
  * Ref: [monad-bft PR #2765](https://github.com/category-labs/monad-bft/pull/2765)
* **\[Consensus]** Validate ping/pong source address against name record in peer discovery
  * Ref: [monad-bft PR #2752](https://github.com/category-labs/monad-bft/pull/2752)
* **\[Consensus]** Persist voted\_head in ledger
  * Ref: [monad-bft PR #2744](https://github.com/category-labs/monad-bft/pull/2744)
* **\[Consensus]** Add dual UDP packet sender for dataplane
  * Ref: [monad-bft PR #2746](https://github.com/category-labs/monad-bft/pull/2746)
* **\[Execution]** Fix ThreadSanitizer race by joining bootstrap fiber before thread exit
  * Ref: [monad PR #2053](https://github.com/category-labs/monad/pull/2053)
* **\[Execution]** Include account balance in selfdestruct tracer frame
  * Ref: [monad PR #2039](https://github.com/category-labs/monad/pull/2039)
* **\[Consensus]** Ensure proposed head is on canonical chain
  * Ref: [monad-bft PR #2756](https://github.com/category-labs/monad-bft/pull/2756)
* **\[Execution]** Fix sentinel collision in compact virtual chunk offset
  * Ref: [monad PR #2083](https://github.com/category-labs/monad/pull/2083)
* **\[Execution]** Fix potential race condition in execute\_block\_transactions
  * Ref: [monad PR #2092](https://github.com/category-labs/monad/pull/2092)

#### Notable internal changes

* **\[Consensus]** Remove unneeded channels when secondary raptorcast is disabled
  * Ref: [monad-bft PR #2808](https://github.com/category-labs/monad-bft/pull/2808)
* **\[Consensus]** Upgrade alloy to stable release
  * Ref: [monad-bft PR #2792](https://github.com/category-labs/monad-bft/pull/2792)
* **\[Execution]** Add `evm-as` syntactic sugar for VM utilities
  * Ref: [monad PR #2097](https://github.com/category-labs/monad/pull/2097)
* **\[Consensus]** Parametrize wireauth metrics for better observability
  * Ref: [monad-bft PR #2692](https://github.com/category-labs/monad-bft/pull/2692)
* **\[Consensus]** Cleanup block persist implementation
  * Ref: [monad-bft PR #2767](https://github.com/category-labs/monad-bft/pull/2767)
* **\[Consensus]** Fix wip extension in block-persist
  * Ref: [monad-bft PR #2776](https://github.com/category-labs/monad-bft/pull/2776)
* **\[Consensus]** Remove legacy `do_local_insert`
  * Ref: [monad-bft PR #2728](https://github.com/category-labs/monad-bft/pull/2728)
* **\[Consensus]** Add metrics for raptorcast deserialize failures
  * Ref: [monad-bft PR #2789](https://github.com/category-labs/monad-bft/pull/2789)
* **\[RPC]** Reduce RPC event server broadcast channel size
  * Ref: [monad-bft PR #2815](https://github.com/category-labs/monad-bft/pull/2815)
* **\[Consensus]** Pre-TFM base fee cleanup
  * Ref: [monad-bft PR #2664](https://github.com/category-labs/monad-bft/pull/2664)
* **\[Consensus]** Remove pre-TFM reserve balance logic
  * Ref: [monad-bft PR #2622](https://github.com/category-labs/monad-bft/pull/2622)
* **\[RPC]** Simplify hex encoding/decoding in RPC
  * Ref: [monad-bft PR #2806](https://github.com/category-labs/monad-bft/pull/2806)
* **\[Archive]** Add exists(key) to kvstore
  * Ref: [monad-bft PR #2688](https://github.com/category-labs/monad-bft/pull/2688)

## v0.12.7 \[2026-01-29]

Revision: [`MONAD_EIGHT`](/developer-essentials/changelog#revisions) (unchanged)

#### Notable RPC/SDK changes

* **\[RPC]** Allow block hash as block identifier in `eth_estimateGas`
  * Ref: [monad-bft PR #2676](https://github.com/category-labs/monad-bft/pull/2676)
* **\[RPC]** Use `RawValue` for RPC id to preserve original JSON types
  * Reduces effectiveness of DoS attacks using large JSON arrays/dicts in request IDs
  * Ref: [monad-bft PR #2455](https://github.com/category-labs/monad-bft/pull/2455)

#### Notable robustness changes

* **\[Consensus]** Remove consecutive sequence number assertion
  * Ref: [monad-bft PR #2704](https://github.com/category-labs/monad-bft/pull/2704)
* **\[Consensus]** Improve liveness when advancing round using TC from timeout messages
  * Ref: [monad-bft PR #2701](https://github.com/category-labs/monad-bft/pull/2701)
* **\[Consensus]** Disallow creating an empty validator set
  * Ref: [monad-bft PR #2682](https://github.com/category-labs/monad-bft/pull/2682)

#### Notable internal changes

* **\[Consensus]** Add security tests for `secp256k1`
  * Adds Wycheproof tests, malleability tests, and security unit tests
  * Ref: [monad-bft PR #2706](https://github.com/category-labs/monad-bft/pull/2706)
* **\[Node ops]** Update `rkyv` and other dependencies
  * Ref: [monad-bft PR #2702](https://github.com/category-labs/monad-bft/pull/2702)
* **\[Consensus]** Return bound socket addresses synchronously in dataplane
  * Ref: [monad-bft PR #2653](https://github.com/category-labs/monad-bft/pull/2653)
* **\[Consensus]** Rename state backend cache for clarity
  * Ref: [monad-bft PR #2699](https://github.com/category-labs/monad-bft/pull/2699)

## v0.12.6 \[2026-01-14]

Revision: [`MONAD_EIGHT`](/developer-essentials/changelog#revisions) (unchanged)

Tags or hashes:

* `monad-bft`: [tag `v0.12.6`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.6)
* `monad`: [tag `v0.12.6`](https://github.com/category-labs/monad/releases/tag/v0.12.6)

#### Notable RPC/SDK changes

* **\[RPC]** Fix depth bug in selfdestructing call frames
  * Ref: [monad PR #1977](https://github.com/category-labs/monad/pull/1977)
* **\[RPC]** Prestate tracer conformance fixes
  * Ref: [monad PR #1946](https://github.com/category-labs/monad/pull/1946)

#### Notable robustness changes

* **\[Consensus]** Add signature verification rate limiting with authenticated peer bypass
  * Ref: [monad-bft PR #2601](https://github.com/category-labs/monad-bft/pull/2601)
* **\[Consensus]** Validate confirm group message before updating peers
  * Ref: [monad-bft PR #2680](https://github.com/category-labs/monad-bft/pull/2680)
* **\[Consensus]** Use Tai64N directly for wireauth timestamp comparison
  * Ref: [monad-bft PR #2678](https://github.com/category-labs/monad-bft/pull/2678)
* **\[Consensus]** Improve RaptorCast decoding cache eviction
  * Ref: [monad-bft PR #2651](https://github.com/category-labs/monad-bft/pull/2651)
* **\[Consensus]** Fix blocksync in-flight request tracking on cache hydration
  * Ref: [monad-bft PR #2635](https://github.com/category-labs/monad-bft/pull/2635)
* **\[Execution]** Update triedb voted metadata before executing proposal
  * Solves a race condition between Voted updates through websocket and corresponding JSON-RPC calls
  * Ref: [monad PR #1964](https://github.com/category-labs/monad/pull/1964)
* **\[Node ops]** Persist peers periodically for improved discovery resilience
  * Ref: [monad-bft PR #2633](https://github.com/category-labs/monad-bft/pull/2633)

#### Notable performance changes

* **\[Consensus]** Boost dataplane throughput with ring buffer implementation
  * Ref: [monad-bft PR #2596](https://github.com/category-labs/monad-bft/pull/2596)
* **\[Execution]** Native implementation for `MLOAD`, `MSTORE`, `MSTORE8`, `CALLDATALOAD` opcodes
  * Ref: [monad PR #1963](https://github.com/category-labs/monad/pull/1963)
* **\[Execution]** Improve snapshot write performance
  * Ref: [monad PR #1973](https://github.com/category-labs/monad/pull/1973), [monad PR #1960](https://github.com/category-labs/monad/pull/1960)
* **\[Execution]** Optimize database history length adjustment with binary search
  * Ref: [monad PR #1922](https://github.com/category-labs/monad/pull/1922)
* **\[Execution]** Unify single buffer and scatter read handling in AsyncIO
  * Ref: [monad PR #1944](https://github.com/category-labs/monad/pull/1944)

#### Notable internal changes

* **\[Node ops]** Docker single-node container updates for prebuilt images
  * Fixes to [Local Docker installation](https://github.com/category-labs/monad-bft/blob/master/README.md#using-pre-built-images)
  * Ref: [monad-bft PR #2674](https://github.com/category-labs/monad-bft/pull/2674)
* **\[Consensus]** Add support for generic txpool sidecars
  * Enables IPC transaction priority and forwarding controls
  * Ref: [monad-bft PR #2557](https://github.com/category-labs/monad-bft/pull/2557)
* **\[EVM]** Osaka fork preparation
  * Modexp gas changes and upper bound (EIP-7823/EIP-7883)
  * Implement `CLZ` opcode
    * Ref: [monad PR #1970](https://github.com/category-labs/monad/pull/1970), [monad PR #1981](https://github.com/category-labs/monad/pull/1981)
* **\[Node ops]** Accept `--hyphen-style` long options in CLI
  * Ref: [monad PR #2005](https://github.com/category-labs/monad/pull/2005)
* **\[Node ops / Archive]** Archive pipeline improvements
  * Add `WritePolicy` to `KVStore` for conditional write protection (`NoClobber`)
  * Add BFT-uploading stats logging
  * Ref: [monad-bft PR #2649](https://github.com/category-labs/monad-bft/pull/2649), [monad-bft PR #2661](https://github.com/category-labs/monad-bft/pull/2661)
* **\[Node ops]** Simplify RPC txpool status tracking
  * Ref: [monad-bft PR #2644](https://github.com/category-labs/monad-bft/pull/2644)
* **\[Node ops]** Snapshot tooling improvements in `monad_cli`
  * Add `--dump_concurrency_limit` parameter
  * Add sharding support for distributed snapshot creation
  * Ref: [monad PR #1967](https://github.com/category-labs/monad/pull/1967), [monad PR #1965](https://github.com/category-labs/monad/pull/1965)
* **\[Node ops]** Add RaptorCast decoding cache metrics
  * Ref: [monad-bft PR #2667](https://github.com/category-labs/monad-bft/pull/2667)
* **\[Execution]** Add `CommitBuilder` API to execution database
  * Ref: [monad PR #1968](https://github.com/category-labs/monad/pull/1968)
* **\[Execution]** Remove legacy `using_chunks_for_root_offsets` metadata field
  * Ref: [monad PR #1943](https://github.com/category-labs/monad/pull/1943)
* **\[Node ops / Txgen]** Add ERC-4337 + EIP-7702 generator (`erc4337_7702_bundled`)
  * Ref: [monad-bft PR #2628](https://github.com/category-labs/monad-bft/pull/2628)
* **\[Node ops]** Add systemd service scripts for `blockcapd` and execution events archivers
  * Ref: [monad-bft PR #2590](https://github.com/category-labs/monad-bft/pull/2590)
* **\[SDK]** Add `monad_event_resolve_ring_file` API
  * Ref: [monad PR #1741](https://github.com/category-labs/monad/pull/1741)
* **\[Execution]** Enable VM host exception handling outside VM
  * Ref: [monad PR #1990](https://github.com/category-labs/monad/pull/1990)

## v0.12.4 \[2025-12-05]

Revision: [`MONAD_EIGHT`](/developer-essentials/changelog#revisions) (unchanged)

Tags or hashes:

* `monad-bft`: [tag `v0.12.4`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.4)
* `monad`: [tag `v0.12.4`](https://github.com/category-labs/monad/releases/tag/v0.12.4) *(unchanged from v0.12.3)*

#### Notable internal changes

* **\[Node ops]** Fix peer discovery port configuration when constructing self name record
  * Use port from peer discovery config instead of bound socket when constructing self name record.
    This bug affected node operators using a NAT.
  * Ref: [monad-bft PR #2655](https://github.com/category-labs/monad-bft/pull/2655)

## v0.12.3 \[2025-12-04]

Revision: [`MONAD_EIGHT`](/developer-essentials/changelog#revisions) (unchanged)

Tags or hashes:

* `monad-bft`: [tag `v0.12.3`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.3)
* `monad`: [tag `v0.12.3`](https://github.com/category-labs/monad/releases/tag/v0.12.3)

#### Notable RPC/SDK changes

* **\[RPC]** [EIP-7966](https://eips.ethereum.org/EIPS/eip-7966) (`eth_sendRawTransactionSync`) support
  * Ref: [monad-bft PR #2542](https://github.com/category-labs/monad-bft/pull/2542)
* **\[RPC]** Populate `value` field on traces for staking precompile syscalls (added in `0.12.3-rpc-hotfix2`)
  * Ref: [monad PR #1938](https://github.com/category-labs/monad/pull/1938)

#### Notable robustness changes

* **\[Consensus]** Wire authentication protocol for UDP
  * Adds authenticated UDP communication to improve network security
  * Includes replay window adjustments for improved reliability
  * Ref: [monad-bft PR #2417](https://github.com/category-labs/monad-bft/pull/2417), [monad-bft PR #2544](https://github.com/category-labs/monad-bft/pull/2544), [monad-bft PR #2626](https://github.com/category-labs/monad-bft/pull/2626), [monad-bft PR #2091](https://github.com/category-labs/monad-bft/pull/2091)
* **\[Execution]** Improve `statesync` shutdown and fix protocol corruption
  * Modified `statesync_server_recv()` to guarantee complete reads
  * Ref: [monad PR #1930](https://github.com/category-labs/monad/pull/1930)
* **\[RPC]** Prevent reserve balance crash in RPC
  * Add reserve balance violation error messages in call frames
  * Ref: [monad PR #1932](https://github.com/category-labs/monad/pull/1932), [monad-bft PR #2629](https://github.com/category-labs/monad-bft/pull/2629)
  * This was already previously released in `v0.12.2-rpc-hotfix`
* **\[Consensus]** Add timeout to `txpool` IPC stream
  * Prevents hanging connections in transaction pool communication
  * Ref: [monad-bft PR #2619](https://github.com/category-labs/monad-bft/pull/2619)
* **\[Consensus]** Reject timeout certificates with empty signers
  * Adds validation to prevent malformed timeout certificates
  * Ref: [monad-bft PR #2630](https://github.com/category-labs/monad-bft/pull/2630)
* **\[Consensus]** Verify RaptorCast chunk length is non-zero
  * Adds validation to prevent malformed RaptorCast chunks
  * Ref: [monad-bft PR #2638](https://github.com/category-labs/monad-bft/pull/2638)
* **\[Execution]** Fix MPT restore bug that failed to preserve `version_lower_bound`
  * Ref: [monad PR #1955](https://github.com/category-labs/monad/pull/1955)
* **\[Execution]** Fix move trie version forward bug
  * Erase versions that fall out of history range before moving forward to newer versions
  * Ref: [monad PR #1957](https://github.com/category-labs/monad/pull/1957)
* **\[Execution]** Fix dangling pointers to intercode
  * Resolves memory safety issue with `get_code` and `read_code` functions
  * Ref: [monad PR #1941](https://github.com/category-labs/monad/pull/1941)
* **\[Execution]** Add retries to `runloop_monad_ethblocks`
  * Ref: [monad PR #1953](https://github.com/category-labs/monad/pull/1953)

#### Notable performance changes

* **\[RPC]** Improve `eth_getLogs` performance
  * Reduce memory copies and unify receipt-to-logs processing
  * Ref: [monad-bft PR #2588](https://github.com/category-labs/monad-bft/pull/2588), [monad-bft PR #2591](https://github.com/category-labs/monad-bft/pull/2591), [monad-bft PR #2631](https://github.com/category-labs/monad-bft/pull/2631)
* **\[Execution]** Fiber: add support for move-only functors
  * Improves execution efficiency by supporting move semantics
  * Ref: [monad PR #1936](https://github.com/category-labs/monad/pull/1936)

#### Notable internal changes

* **\[RPC / Node ops]** Allow RPC to run without `monad-bft`
  * Enables standalone RPC operation for improved deployment flexibility
  * Ref: [monad-bft PR #2613](https://github.com/category-labs/monad-bft/pull/2613)
* **\[Node ops]** Add `--root-offsets-chunk-count` flag to `monad-mpt` to configure the number of chunks allocated for root offsets
  * Each chunk holds approximately 16.5M blocks. Previously, all nodes were hardcoded to use 2 chunks (max TrieDB capacity of \~33M blocks)
  * New default: 16 **must be a power of 2**
  * Note that the default value of 16 translates to approximately 268M blocks \~ 1240 days. In most cases the limiting factor is disk capacity which will auto-compact when filled to 80%
  * Ref: [monad PR #1937](https://github.com/category-labs/monad/pull/1937)
* **\[Node ops]** Peer discovery improvements
  * Full nodes periodically pull validator name records for dynamic validator discovery
  * Add authenticated UDP port to name record
  * Ref: [monad-bft PR #2607](https://github.com/category-labs/monad-bft/pull/2607), [monad-bft PR #2538](https://github.com/category-labs/monad-bft/pull/2538)
* **\[Node ops / Archive]** Archive infrastructure improvements
  * Refactor `monad-block-writer` for improved reliability with `--max-blocks-per-iter` configuration
  * Async backfill with traces-only archive support
  * Add `require-traces` archiver flag and indexer fallback source
  * Support for historical execution event archiving with generic directory archiving
  * **Potentially breaking: Remove `--start-block` from `monad-archiver` systemd service; operators must use imperative CLI to set start block**
    * Example: `monad-archiver set-start-block --block 1000000 --archive-sink s3://bucket-name/path`
    * Use `--async-backfill` flag to set the async-backfill marker instead of primary marker
  * Ref: [monad-bft PR #2610](https://github.com/category-labs/monad-bft/pull/2610), [monad-bft PR #2606](https://github.com/category-labs/monad-bft/pull/2606), [monad-bft PR #2598](https://github.com/category-labs/monad-bft/pull/2598), [monad-bft PR #2514](https://github.com/category-labs/monad-bft/pull/2514), [monad-bft PR #2612](https://github.com/category-labs/monad-bft/pull/2612), [monad-bft PR #2569](https://github.com/category-labs/monad-bft/pull/2569), [monad-bft PR #2623](https://github.com/category-labs/monad-bft/pull/2623)
* **\[Node ops]** Networking configuration updates
  * Use default MTU 1500
  * Add HDR histogram for broadcast latency tracking in `monad-executor` and `monad-raptorcast`
  * Ref: [monad-bft PR #2576](https://github.com/category-labs/monad-bft/pull/2576), [monad-bft PR #2602](https://github.com/category-labs/monad-bft/pull/2602)
* **\[Consensus]** RaptorCast improvements
  * Clear histogram every 30s and keep only p99 for better latency tracking
  * Fix timer update after receiving control messages to ensure proper keepalives
  * Ref: [monad-bft PR #2627](https://github.com/category-labs/monad-bft/pull/2627), [monad-bft PR #2637](https://github.com/category-labs/monad-bft/pull/2637)
* **\[Consensus]** Dataplane: refactor to use socket handles
  * Prepares dataplane for future extension with authenticated sockets
  * Ref: [monad-bft PR #2458](https://github.com/category-labs/monad-bft/pull/2458)
* **\[Execution]** Replay monad: always execute first block off latest finalized state
  * Ref: [monad PR #1927](https://github.com/category-labs/monad/pull/1927)
* **\[Node ops]** Txgen improvements: README and guide, nonce gaps and legacy tx options, ERC20 pools, Uniswap v3 mode, NFT sale mode, websocket and RPC request generation
  * Ref: [monad-bft PR #2568](https://github.com/category-labs/monad-bft/pull/2568), [monad-bft PR #2567](https://github.com/category-labs/monad-bft/pull/2567), [monad-bft PR #2577](https://github.com/category-labs/monad-bft/pull/2577), [monad-bft PR #2600](https://github.com/category-labs/monad-bft/pull/2600), [monad-bft PR #2527](https://github.com/category-labs/monad-bft/pull/2527), [monad-bft PR #2394](https://github.com/category-labs/monad-bft/pull/2394), [monad-bft PR #2608](https://github.com/category-labs/monad-bft/pull/2608)

## v0.12.2 \[2025-11-18]

The Public Mainnet phase began on 2025-11-24. As such, public mainnet started at [`v0.12.2`](/developer-essentials/changelog/releases#v0122).


# Releases
Source: https://docs.monad.xyz/developer-essentials/changelog/releases



This page catalogues every notable release. Some releases target only specific networks; for a
more intuitive view of upgrades to one network, see:

* [mainnet](/developer-essentials/changelog/mainnet)
* [testnet](/developer-essentials/changelog/testnet)

<Note>
  We group changes into

  * protocol changes (generally requiring a new [Revision](/developer-essentials/changelog#revisions))
    * generally tagged with **\[EVM]**, **\[Consensus]**, or **\[Network params]**
  * RPC/SDK behavioral changes (generally tagged with **\[RPC]**)
  * performance changes
    * tagged based on the nature of the change as **\[EVM]**, **\[Consensus]**, or **\[RPC]**
  * internal/node-ops changes (generally tagged as **\[Node ops]**)
</Note>

## v0.14.3

| Network                                                | Date released | Comment |
| ------------------------------------------------------ | ------------- | ------- |
| [`mainnet`](/developer-essentials/network-information) | 2026-05-14    |         |
| [`testnet`](/developer-essentials/testnets#testnet)    | 2026-05-07    |         |

Tags or hashes:

* `monad-bft` (consensus): [tag `v0.14.3`](https://github.com/category-labs/monad-bft/releases/tag/v0.14.3) (`f2a2092b`)
* `monad` (execution): [tag `v0.14.3`](https://github.com/category-labs/monad/releases/tag/v0.14.3) (`7fcd693f7`)

#### Highlights

* **Authenticated UDP enforcement** — Raptorcast now requires wire-authenticated UDP sockets; previously optional, now enforced for all nodes

#### Notable robustness changes

* **\[Consensus]** Raptorcast: require authenticated UDP socket
  * Ref: [monad-bft PR #2956](https://github.com/category-labs/monad-bft/pull/2956)
  * Enforces authenticated UDP socket setup; previously optional
* **\[Execution]** Fix `DbCache` assert-fail when reading finalized state older than latest finalized block
  * Ref: [monad (execution) PR #2190](https://github.com/category-labs/monad/pull/2190)
  * Replaces assertion with explicit checks; fixes incorrect `truncated` value propagation when walking the chain back past the latest finalized block
* **\[Execution]** Raise `MIN_HISTORY_LENGTH` floor from 257 to 300
  * Ref: [monad (execution) PR #2217](https://github.com/category-labs/monad/pull/2217)
  * Under disk pressure, history could shrink below the 256-block minimum required for the block hash buffer, forcing a full statesync after restart; new floor gives \~44 blocks of headroom
* **\[Execution]** Fix `evm-as` PushLabel encoding at offset zero for pre-Shanghai targets
  * Ref: [monad (execution) PR #2213](https://github.com/category-labs/monad/pull/2213)
  * Fixes incorrect `PUSH0` encoding in the EVM assembler for pre-Shanghai code paths

#### Notable performance changes

* **\[Execution]** Extend trie span optimization to fnext, child\_off, and SharedPtr arrays
  * Ref: [monad (execution) PR #2176](https://github.com/category-labs/monad/pull/2176)
* **\[Execution]** Remove inflight read coalescing from rwdb find path
  * Ref: [monad (execution) PR #2183](https://github.com/category-labs/monad/pull/2183)
* **\[Execution]** Elide DB fetch in `State::is_touched`
  * Ref: [monad (execution) PR #2198](https://github.com/category-labs/monad/pull/2198)
* **\[RPC]** Skip redundant receipt conversion on log retrieval path
  * Ref: [monad-bft PR #2839](https://github.com/category-labs/monad-bft/pull/2839)
  * Avoids building a full `TransactionReceipt` when serving log queries; goes directly from `(TxEnvelope, Receipt)` to `ReceiptEnvelope`, reducing overhead on `eth_getLogs` and related calls

#### Notable internal changes

* **\[Consensus]** Peer discovery: require authenticated UDP in name records
  * Ref: [monad-bft PR #2955](https://github.com/category-labs/monad-bft/pull/2955)
  * Enforces non-zero port policy for authenticated UDP; port 0 was used as an empty value in RLP-encoded peer entries and is now rejected
* **\[Consensus]** Add full nodes message type and handling logic for peer reputation scoring
  * Ref: [monad-bft PR #2914](https://github.com/category-labs/monad-bft/pull/2914), [PR #2915](https://github.com/category-labs/monad-bft/pull/2915)
  * Introduces a new message type for full nodes to send peer participation data to the publisher for reputation scoring
* **\[Consensus]** Peer discovery: drop V1 wire name records
  * Ref: [monad-bft PR #2952](https://github.com/category-labs/monad-bft/pull/2952)
  * Removes backward compatibility with V1 peer wire format; all peers must use V2 name records
* **\[Consensus]** Expose block number by hash retrieval in archive
  * Ref: [monad-bft PR #2980](https://github.com/category-labs/monad-bft/pull/2980)
  * Archive nodes now support block number lookup by block hash
* **\[Consensus]** Raptorcast: round-robin mode for stake-proportional chunk assigner
  * Ref: [monad-bft PR #2970](https://github.com/category-labs/monad-bft/pull/2970)
  * Adds round-robin assignment to the stake-proportional chunk assigner used in deterministic Raptorcast

## v0.14.2

| Network                                                | Date released | Comment |
| ------------------------------------------------------ | ------------- | ------- |
| [`mainnet`](/developer-essentials/network-information) | 2026-04-30    |         |
| [`testnet`](/developer-essentials/testnets#testnet)    | 2026-04-23    |         |

Tags or hashes:

* `monad-bft` (consensus): [tag `v0.14.2`](https://github.com/category-labs/monad-bft/releases/tag/v0.14.2) (`6307011c`)
* `monad` (execution): [tag `v0.14.2`](https://github.com/category-labs/monad/releases/tag/v0.14.2) (`169e5c45b`)

#### Highlights

* **`debug_*` improvements** — new `index` field on traced logs; `eth_call` returns explicit `reserve balance violation` error
* **8-9x speedup on compaction hot path** — trie node array optimization reduces redundant pointer recomputation
* **Fair queue forwarded ingress in txpool** — improves tx forwarding fairness between validators

#### Notable RPC/SDK changes

* **\[RPC]** Move callframe retrieval methods to ChainState
  * Ref: [monad-bft PR #2936](https://github.com/category-labs/monad-bft/pull/2936), [PR #2937](https://github.com/category-labs/monad-bft/pull/2937)
  * Covers block and transaction callframes; deduplicates call frame decoding in debug trace handlers
* **\[RPC]** Include log index in debug trace output; surface reserve balance error in `eth_call`
  * Ref: [monad-bft PR #2658](https://github.com/category-labs/monad-bft/pull/2658)
  * Adds `index` field to each traced log in the debug call tracer, reflecting the global log order within a transaction across all nested call frames; `eth_call` now returns an explicit `reserve balance violation` error instead of a generic failure when a transaction exceeds the sender's reserve balance
* **\[RPC]** Move eth call gas limit config to EthCallHandler
  * Ref: [monad-bft PR #2926](https://github.com/category-labs/monad-bft/pull/2926)
* **\[RPC]** `debug_*` methods now count toward eth call rate limiting
  * Ref: [monad-bft PR #2868](https://github.com/category-labs/monad-bft/pull/2868)
  * `debug_traceCall`, `debug_traceTransaction`, and related methods now update the eth call stats tracker; previously they bypassed it
* **\[RPC]** Enforce max response size earlier for debug RPC methods
  * Ref: [monad-bft PR #2959](https://github.com/category-labs/monad-bft/pull/2959)
* **\[RPC]** Lower RPC batch request limit to match Geth's default
  * Ref: [monad-bft PR #2934](https://github.com/category-labs/monad-bft/pull/2934)

#### Notable robustness changes

* **\[Consensus]** ConfirmGroup message fix
  * Ref: [monad-bft PR #2652](https://github.com/category-labs/monad-bft/pull/2652)
  * Prevents oversized ConfirmGroup messages being rejected by full nodes; introduces NoConfirm response when group reaches max size
* **\[Consensus]** Fix leak in leanudp identity usage map
  * Ref: [monad-bft PR #2930](https://github.com/category-labs/monad-bft/pull/2930)
* **\[Consensus]** Enforce stale message timeout in leanudp
  * Ref: [monad-bft PR #2873](https://github.com/category-labs/monad-bft/pull/2873)
* **\[RPC]** Fix eth call stats tracking memleak in RPC
  * Ref: [monad-bft PR #2910](https://github.com/category-labs/monad-bft/pull/2910)
* **\[Consensus]** Relax statesync assertion for stale DoneSync edge case
  * Ref: [monad-bft PR #2905](https://github.com/category-labs/monad-bft/pull/2905)
* **\[Execution]** Fix possible UB in unaligned read
  * Ref: [monad (execution) PR #2168](https://github.com/category-labs/monad/pull/2168)
* **\[Execution]** Fix incorrect auto\_expire\_version initialization after DB reset
  * Ref: [monad (execution) PR #2167](https://github.com/category-labs/monad/pull/2167)
* **\[Execution]** Fix compaction progress reset during statesync
  * Ref: [monad (execution) PR #2133](https://github.com/category-labs/monad/pull/2133)
  * Fixes compaction head being incorrectly reset to 0 during statesync, causing compaction to restart from the beginning
* **\[Consensus]** Decode exact forwarded transactions
  * Ref: [monad-bft PR #2810](https://github.com/category-labs/monad-bft/pull/2810)
  * Ensures forwarded transactions are decoded with no trailing bytes

#### Notable performance changes

* **\[Consensus]** Front-load cheap consensus validation checks
  * Ref: [monad-bft PR #2928](https://github.com/category-labs/monad-bft/pull/2928)
* **\[Consensus]** Fair queue forwarded ingress in txpool client
  * Ref: [monad-bft PR #2882](https://github.com/category-labs/monad-bft/pull/2882)
* **\[Consensus]** Move forwarded tx pacing into executor, simplify ingress batching
  * Ref: [monad-bft PR #2884](https://github.com/category-labs/monad-bft/pull/2884), [PR #2886](https://github.com/category-labs/monad-bft/pull/2886)
* **\[Consensus]** Drop already-obsolete consensus messages before certificate validation
  * Ref: [monad-bft PR #2927](https://github.com/category-labs/monad-bft/pull/2927)
* **\[Execution]** Optimize trie node array access (8-9x speedup on compaction hot path)
  * Ref: [monad (execution) PR #2163](https://github.com/category-labs/monad/pull/2163)
  * Hoists base pointers for packed node arrays; reduces redundant pointer recomputation in compaction, expiration, and version tracking loops

#### Notable internal changes

* **\[Consensus]** Raptorcast: direct UDP transport
  * Ref: [monad-bft PR #2898](https://github.com/category-labs/monad-bft/pull/2898), [PR #2900](https://github.com/category-labs/monad-bft/pull/2900)
  * Adds a dedicated direct UDP socket for point-to-point traffic, bypassing Raptorcast erasure coding. Eliminates the \~2.5x bandwidth amplification inherent in Raptorcast for unicast sends. Falls back to the Raptorcast path gracefully for peers that don't support it.
  * **Note:** Still in testing — not recommended for production use in this release.
* **\[Consensus]** Wireauth: lower per-instance defaults
  * Ref: [monad-bft PR #2906](https://github.com/category-labs/monad-bft/pull/2906)
* **\[Execution]** Replace system boost fiber with submodule (boost-1.83.0)
  * Ref: [monad (execution) PR #2157](https://github.com/category-labs/monad/pull/2157)
* **\[Execution]** Separate precompile gas cost calculation from runtime implementation
  * Ref: [monad (execution) PR #2099](https://github.com/category-labs/monad/pull/2099), [PR #2098](https://github.com/category-labs/monad/pull/2098)
  * Prep work for zkVM compilation
* **\[Execution]** Remove support for EVMC\_FRONTIER
  * Ref: [monad (execution) PR #2041](https://github.com/category-labs/monad/pull/2041)
* **\[Execution]** Add block-level event recording for Ethereum and Monad replay
  * Ref: [monad (execution) PR #2006](https://github.com/category-labs/monad/pull/2006)
  * Emits BLOCK\_START/BLOCK\_END events during replay, making replay event streams usable for tooling
* **\[Consensus]** Configure shared peer scoring for txpool and raptorcast
  * Ref: [monad-bft PR #2907](https://github.com/category-labs/monad-bft/pull/2907)
* **\[Consensus]** Raptorcast: enforce type-level safety for BroadcastGroup in build target
  * Ref: [monad-bft PR #2843](https://github.com/category-labs/monad-bft/pull/2843)
  * Restricts build target to established groups, eliminating packet builder epoch/round tracking desync risk

## v0.14.1

| Network                                                | Date released | Comment |
| ------------------------------------------------------ | ------------- | ------- |
| [`mainnet`](/developer-essentials/network-information) | 2026-04-09    |         |
| [`testnet`](/developer-essentials/testnets#testnet)    | 2026-04-08    |         |

Tags or hashes:

* `monad-bft` (consensus): [tag `v0.14.1`](https://github.com/category-labs/monad-bft/releases/tag/v0.14.1) (`4ed79392`)
* `monad` (execution): [tag `v0.14.1`](https://github.com/category-labs/monad/releases/tag/v0.14.1) (`54e132cfa`) — same commit as v0.14.0

> **Note:** Patch release on top of v0.14.0. Execution layer unchanged.

#### Notable RPC/SDK changes

* **\[RPC]** Fix `eth_fillTransaction` gas estimation and reserve balance handling
  * Ref: [monad-bft PR #2949](https://github.com/category-labs/monad-bft/pull/2949)
  * Maps reserve-balance failures to a dedicated result instead of collapsing into a generic error; makes omitted-gas fill estimation more permissive with an unbounded-balance state override during fill estimation
  * **Note:** `eth_fillTransaction` with insufficient balance now returns `reserve balance violation` (was: `insufficient balance`). Callers matching on exact error strings should update accordingly.

## v0.14.0

| Network                                                | Date released | Comment |
| ------------------------------------------------------ | ------------- | ------- |
| [`mainnet`](/developer-essentials/network-information) | N/A           |         |
| [`testnet`](/developer-essentials/testnets#testnet)    | 2026-04-02    |         |

Tags or hashes:

* `monad-bft` (consensus): [tag `v0.14.0`](https://github.com/category-labs/monad-bft/releases/tag/v0.14.0) (`2d487de0`)
* `monad` (execution): [tag `v0.14.0`](https://github.com/category-labs/monad/releases/tag/v0.14.0) (`54e132cfa`)

#### Highlights

* **RPC: \~400ms faster receipt queries** — Receipts now tracked in chainstate buffer and available at Proposed time, eliminating trie lookups that added \~400ms on v0.13.0.
* **RPC: `eth_fillTransaction`** — New endpoint to get a fully populated transaction (gas, nonce, etc.) without signing. Useful for wallets and dapps preparing transactions.
* **RPC: Websocket notifications on proposed blocks** — `newHeads` and `logs` subscriptions now emit on proposed blocks instead of voted, reducing notification latency for real-time applications.

#### Notable RPC/SDK changes

* **\[RPC]** `eth_fillTransaction` RPC endpoint
  * Ref: [monad-bft PR #2662](https://github.com/category-labs/monad-bft/pull/2662), [PR #2932](https://github.com/category-labs/monad-bft/pull/2932)
  * PR #2932 fixes several inconsistencies: preserves user-provided `maxFeePerGas` when sufficient, treats `0x0` gas/fee as missing, allows gas fill for failed txs, rejects blob-style requests, handles EIP-2930 legacy-fee correctly
* **\[RPC]** Use proposed blocks in websocket notifications
  * Ref: [monad-bft PR #2817](https://github.com/category-labs/monad-bft/pull/2817)
* **\[RPC]** Transaction receipts in chainstate buffer (\~400ms faster receipt queries)
  * Ref: [monad-bft PR #2809](https://github.com/category-labs/monad-bft/pull/2809), [PR #2818](https://github.com/category-labs/monad-bft/pull/2818)
* **\[RPC]** Consolidate triedb usage to ChainState
  * Ref: [monad-bft PR #2876](https://github.com/category-labs/monad-bft/pull/2876)
* **\[RPC]** Use ChainStateBuffer for RPC logs
  * Ref: [monad-bft PR #2840](https://github.com/category-labs/monad-bft/pull/2840)
* **\[Execution]** Add execution events Rust SDK with path resolution and descriptor info
  * Ref: [monad (execution) PR #2123](https://github.com/category-labs/monad/pull/2123), [PR #2135](https://github.com/category-labs/monad/pull/2135), [PR #2136](https://github.com/category-labs/monad/pull/2136)

#### Notable robustness changes

* **\[Execution]** Remove ASSERT that relied on suboptimality of reserve balance accounting
  * Ref: [monad (execution) PR #2096](https://github.com/category-labs/monad/pull/2096)
* **\[Consensus]** RLP cleanup and stricter decoding enforcement
  * Ref: [monad-bft PR #2785](https://github.com/category-labs/monad-bft/pull/2785)
* **\[Consensus]** Fix zero-length allocation leak in triedb sync read FFI
  * Ref: [monad-bft PR #2816](https://github.com/category-labs/monad-bft/pull/2816)
* **\[Consensus]** Fix dataplane ban expiry TOCTOU underflow
  * Ref: [monad-bft PR #2851](https://github.com/category-labs/monad-bft/pull/2851)
* **\[Archive]** Fix S3 client stuck after sustained outage
  * Ref: [monad-bft PR #2823](https://github.com/category-labs/monad-bft/pull/2823)
* **\[Archive]** Relax checker replica matching for AWS args
  * Ref: [monad-bft PR #2943](https://github.com/category-labs/monad-bft/pull/2943)
  * Handles missing optional AWS fields in stored replica config; avoids dropping replicas from tracked state
* **\[Execution]** Fix runloop\_monad off-by-one when nblocks=1
  * Ref: [monad (execution) PR #2018](https://github.com/category-labs/monad/pull/2018)
* **\[Execution]** Fix RangedGetMachine skipping keys past min prefix
  * Ref: [monad (execution) PR #2110](https://github.com/category-labs/monad/pull/2110)
* **\[Execution]** Fix node writer reentrance causing non-contiguous writes
  * Ref: [monad (execution) PR #2082](https://github.com/category-labs/monad/pull/2082)
* **\[Execution]** Fix undefined behavior in RLP encoding with empty inputs
  * Ref: [monad (execution) PR #2152](https://github.com/category-labs/monad/pull/2152)
* **\[Consensus]** Fix unstable ordering of OpenRPC schemas
  * Ref: [monad-bft PR #2893](https://github.com/category-labs/monad-bft/pull/2893)
* **\[Consensus]** Fix ledger-tail: read author\_address from persisted peers
  * Ref: [monad-bft PR #2888](https://github.com/category-labs/monad-bft/pull/2888)

#### Notable performance changes

* **\[Consensus]** Cache all successful Raptorcast decoding outcomes
  * Ref: [monad-bft PR #2887](https://github.com/category-labs/monad-bft/pull/2887)
* **\[Consensus]** Weighted fair queue for transaction ingestion
  * Ref: [monad-bft PR #2828](https://github.com/category-labs/monad-bft/pull/2828)
* **\[Consensus]** Gas-based peer scoring
  * Ref: [monad-bft PR #2829](https://github.com/category-labs/monad-bft/pull/2829)
* **\[Consensus]** XOR decoder buffers in AVX2 chunks
  * Ref: [monad-bft PR #2863](https://github.com/category-labs/monad-bft/pull/2863)
* **\[Consensus]** Lazy decoder for BLS signature
  * Ref: [monad-bft PR #2861](https://github.com/category-labs/monad-bft/pull/2861)
* **\[Execution]** Improve fast list compaction offset calculation with hysteresis
  * Ref: [monad (execution) PR #2107](https://github.com/category-labs/monad/pull/2107)

#### Notable internal changes

* **\[Consensus]** ⚠️ Make auth UDP fields in `node.toml` required
  * Ref: [monad-bft PR #2891](https://github.com/category-labs/monad-bft/pull/2891)
* **\[Consensus]** Lower max `raptor10_fullnode_redundancy_factor` from 7 to 3
  * Ref: [monad-bft PR #2852](https://github.com/category-labs/monad-bft/pull/2852)
* **\[Node ops]** ⚠️ `monad-ledger-tail`: rename `--node-config-path` to `--peers-path`
  * Ref: [monad-bft PR #2916](https://github.com/category-labs/monad-bft/pull/2916)
  * If you run `monad-ledger-tail` manually or in a custom systemd unit, update the flag name
* **\[Node ops]** Change systemd services from `Restart=no` to `Restart=always`
  * Ref: [monad-bft PR #2860](https://github.com/category-labs/monad-bft/pull/2860)
* **\[Consensus]** Lightweight UDP framing protocol (leanudp)
  * Ref: [monad-bft PR #2827](https://github.com/category-labs/monad-bft/pull/2827)
* **\[Consensus]** Support direct UDP port in peer discovery
  * Ref: [monad-bft PR #2842](https://github.com/category-labs/monad-bft/pull/2842)
* **\[Consensus]** Auth socket with codec abstraction, direct point-to-point routing
  * Ref: [monad-bft PR #2897](https://github.com/category-labs/monad-bft/pull/2897), [PR #2896](https://github.com/category-labs/monad-bft/pull/2896)
* **\[Consensus]** Raptorcast: remove legacy packet parser
  * Ref: [monad-bft PR #2864](https://github.com/category-labs/monad-bft/pull/2864)
* **\[Archive]** Support per-source AWS profile with isolation (`--profile` flag for archiver source/sink/fallback, reads from `.aws/credentials` and `.aws/config`)
  * Ref: [monad-bft PR #2865](https://github.com/category-labs/monad-bft/pull/2865)
* **\[Execution]** Refactor chain: remove `static_validate_header` and `validate_transaction` virtual methods
  * Ref: [monad (execution) PR #2049](https://github.com/category-labs/monad/pull/2049)

## v0.13.1

| Network                                                | Date released | Comment |
| ------------------------------------------------------ | ------------- | ------- |
| [`mainnet`](/developer-essentials/network-information) | 2026-03-16    |         |
| [`testnet`](/developer-essentials/testnets#testnet)    | 2026-03-16    |         |
| [`devnet`](/developer-essentials/testnets#tempnet)     | N/A           |         |

Tags or hashes:

* `monad-bft` (consensus): [tag `v0.13.1`](https://github.com/category-labs/monad-bft/releases/tag/v0.13.1) (`7db6cea2`)
* `monad` (execution): [tag `v0.13.1`](https://github.com/category-labs/monad/releases/tag/v0.13.1) (`722cbf5b5`)

> **Note:** This is a patch release based on v0.13.0 to fix State Archive node RPC issues. The monad (execution) tag points to the same commit as v0.13.0.

#### Notable robustness changes

* **\[RPC]** Use latest voted as fallback for last\_proposed
  * Ref: [monad-bft PR #2857](https://github.com/category-labs/monad-bft/pull/2857)
  * Fixes State Archive node RPC returning stale block data when `last_proposed` is unavailable

## v0.13.0 (MONAD\_NINE)

| Network                                                | Date released | Hardfork timestamp              | Comment                |
| ------------------------------------------------------ | ------------- | ------------------------------- | ---------------------- |
| [`mainnet`](/developer-essentials/network-information) | 2026-03-12    | 1773930600(2026-03-19 14:30UTC) | `MONAD_NINE` hard fork |
| [`testnet`](/developer-essentials/testnets#testnet)    | 2026-03-05    | 1773153000(2026-03-10 14:30UTC) | `MONAD_NINE` hard fork |
| [`devnet`](/developer-essentials/testnets#tempnet)     | N/A           | N/A                             |                        |

Tags or hashes:

* `monad-bft` (consensus): [tag `v0.13.0`](https://github.com/category-labs/monad-bft/releases/tag/v0.13.0)
* `monad` (execution): [tag `v0.13.0+1`](https://github.com/category-labs/monad/releases/tag/v0.13.0+1)

> **Note:** The canonical release version is `v0.13.0`. The `+1` build metadata on the monad execution tag indicates a post-release rebuild that includes the reserve balance precompile fallback cost fix ([PR #2109](https://github.com/category-labs/monad/pull/2109)).

#### Highlights

* **RPC: `latest` block tag: `Finalized` -> `Proposed`** — queries with the `latest` block tag now return data from the latest proposed block, reducing query latency for `eth_getBalance`, `eth_call`, and other state queries.
* **RPC: `eth_sendRawTransactionSync`: `Voted` -> `Proposed`** — earlier receipts when using the `eth_sendRawTransactionSync` method.
* **Websocket: `newHeads/logs`: `Finalized` -> `Voted`** — earlier notifications for websocket subscribers to either `newHeads` or `logs`.

#### Notable protocol changes

All updates below are gated by the `MONAD_NINE` revision

* **\[EVM]** [MIP-3](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-3.md): Linear memory implementation
  * Ref: [monad PR #2032](https://github.com/category-labs/monad/pull/2032)
* **\[Execution]** [MIP-4](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-4.md): Reserve balance precompile
  * Ref: [monad PR #2040](https://github.com/category-labs/monad/pull/2040) (scaffolding)
  * Ref: [monad PR #2065](https://github.com/category-labs/monad/pull/2065) (cached/incremental checks)
  * Ref: [monad PR #2086](https://github.com/category-labs/monad/pull/2086) (add dippedIntoReserve)
  * Ref: [monad PR #2106](https://github.com/category-labs/monad/pull/2106) (dippedIntoReserve argument length error)
  * Ref: [monad PR #2109](https://github.com/category-labs/monad/pull/2109) (fallback cost fix for clean spec)
  * Ref: [monad PR #2037](https://github.com/category-labs/monad/pull/2037) (skip reserve checks for init-selfdestruct)
* **\[EVM]** [MIP-5](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-5.md): Activate Osaka fork (CLZ opcode)
  * Ref: [monad PR #2024](https://github.com/category-labs/monad/pull/2024)

> **Hard Fork:** This release activates MONAD\_NINE at timestamp `1773153000` (testnet) / `1773930600` (mainnet). Nodes must upgrade before activation.

#### Notable RPC/SDK changes

* **\[RPC]** Latest blocktag uses proposed blocks
  * Ref: [monad-bft PR #2675](https://github.com/category-labs/monad-bft/pull/2675)
* **\[RPC]** Use voted blocks in websocket notifications
  * Ref: [monad-bft PR #2799](https://github.com/category-labs/monad-bft/pull/2799)
* **\[RPC]** Add experimental flag to RPC doc macro
  * Ref: [monad-bft PR #2773](https://github.com/category-labs/monad-bft/pull/2773)
* **\[RPC]** Refactor RPC middleware for improved request handling
  * Ref: [monad-bft PR #2805](https://github.com/category-labs/monad-bft/pull/2805)
* **\[RPC]** Add decompression guard to RPC
  * Ref: [monad-bft PR #2793](https://github.com/category-labs/monad-bft/pull/2793)

#### Notable robustness changes

* **\[Consensus]** Add signature verifier for Raptorcast
  * Ref: [monad-bft PR #2747](https://github.com/category-labs/monad-bft/pull/2747)
* **\[Consensus]** Fix reactivate logic in r10 decoder
  * Ref: [monad-bft PR #2740](https://github.com/category-labs/monad-bft/pull/2740)
* **\[Execution]** Fix buffer overflow in C->Rust logging
  * Ref: [monad-bft PR #2769](https://github.com/category-labs/monad-bft/pull/2769)
* **\[Consensus]** Add global connect rate limit to wireauth
  * Ref: [monad-bft PR #2765](https://github.com/category-labs/monad-bft/pull/2765)
* **\[Consensus]** Validate ping/pong source address against name record in peer discovery
  * Ref: [monad-bft PR #2752](https://github.com/category-labs/monad-bft/pull/2752)
* **\[Consensus]** Persist voted\_head in ledger
  * Ref: [monad-bft PR #2744](https://github.com/category-labs/monad-bft/pull/2744)
* **\[Consensus]** Add dual UDP packet sender for dataplane
  * Ref: [monad-bft PR #2746](https://github.com/category-labs/monad-bft/pull/2746)
* **\[Execution]** Fix ThreadSanitizer race by joining bootstrap fiber before thread exit
  * Ref: [monad PR #2053](https://github.com/category-labs/monad/pull/2053)
* **\[Execution]** Include account balance in selfdestruct tracer frame
  * Ref: [monad PR #2039](https://github.com/category-labs/monad/pull/2039)
* **\[Consensus]** Ensure proposed head is on canonical chain
  * Ref: [monad-bft PR #2756](https://github.com/category-labs/monad-bft/pull/2756)
* **\[Execution]** Fix sentinel collision in compact virtual chunk offset
  * Ref: [monad PR #2083](https://github.com/category-labs/monad/pull/2083)
* **\[Execution]** Fix potential race condition in execute\_block\_transactions
  * Ref: [monad PR #2092](https://github.com/category-labs/monad/pull/2092)

#### Notable internal changes

* **\[Consensus]** Remove unneeded channels when secondary raptorcast is disabled
  * Ref: [monad-bft PR #2808](https://github.com/category-labs/monad-bft/pull/2808)
* **\[Consensus]** Upgrade alloy to stable release
  * Ref: [monad-bft PR #2792](https://github.com/category-labs/monad-bft/pull/2792)
* **\[Execution]** Add `evm-as` syntactic sugar for VM utilities
  * Ref: [monad PR #2097](https://github.com/category-labs/monad/pull/2097)
* **\[Consensus]** Parametrize wireauth metrics for better observability
  * Ref: [monad-bft PR #2692](https://github.com/category-labs/monad-bft/pull/2692)
* **\[Consensus]** Cleanup block persist implementation
  * Ref: [monad-bft PR #2767](https://github.com/category-labs/monad-bft/pull/2767)
* **\[Consensus]** Fix wip extension in block-persist
  * Ref: [monad-bft PR #2776](https://github.com/category-labs/monad-bft/pull/2776)
* **\[Consensus]** Remove legacy `do_local_insert`
  * Ref: [monad-bft PR #2728](https://github.com/category-labs/monad-bft/pull/2728)
* **\[Consensus]** Add metrics for raptorcast deserialize failures
  * Ref: [monad-bft PR #2789](https://github.com/category-labs/monad-bft/pull/2789)
* **\[RPC]** Reduce RPC event server broadcast channel size
  * Ref: [monad-bft PR #2815](https://github.com/category-labs/monad-bft/pull/2815)
* **\[Consensus]** Pre-TFM base fee cleanup
  * Ref: [monad-bft PR #2664](https://github.com/category-labs/monad-bft/pull/2664)
* **\[Consensus]** Remove pre-TFM reserve balance logic
  * Ref: [monad-bft PR #2622](https://github.com/category-labs/monad-bft/pull/2622)
* **\[RPC]** Simplify hex encoding/decoding in RPC
  * Ref: [monad-bft PR #2806](https://github.com/category-labs/monad-bft/pull/2806)
* **\[Archive]** Add exists(key) to kvstore
  * Ref: [monad-bft PR #2688](https://github.com/category-labs/monad-bft/pull/2688)

## v0.12.7

| Network                                                | Date released | Comment |
| ------------------------------------------------------ | ------------- | ------- |
| [`mainnet`](/developer-essentials/network-information) | 2026-01-29    |         |
| [`testnet`](/developer-essentials/testnets#testnet)    | 2026-01-20    |         |
| [`devnet`](/developer-essentials/testnets#tempnet)     | N/A           |         |

Tags or hashes:

* `monad-bft`: [tag `v0.12.7`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.7)
* `monad`: [tag `v0.12.7`](https://github.com/category-labs/monad/releases/tag/v0.12.7)

#### Notable RPC/SDK changes

* **\[RPC]** Allow block hash as block identifier in `eth_estimateGas`
  * Ref: [monad-bft PR #2676](https://github.com/category-labs/monad-bft/pull/2676)
* **\[RPC]** Use `RawValue` for RPC id to preserve original JSON types
  * Reduces effectiveness of DoS attacks using large JSON arrays/dicts in request IDs
  * Ref: [monad-bft PR #2455](https://github.com/category-labs/monad-bft/pull/2455)

#### Notable robustness changes

* **\[EVM]** Fix undefined behavior in modexp precompile
  * Ref: [monad PR #2045](https://github.com/category-labs/monad/pull/2045)
* **\[Consensus]** Remove consecutive sequence number assertion
  * Ref: [monad-bft PR #2704](https://github.com/category-labs/monad-bft/pull/2704)
* **\[Consensus]** Improve liveness when advancing round using TC from timeout messages
  * Ref: [monad-bft PR #2701](https://github.com/category-labs/monad-bft/pull/2701)
* **\[Consensus]** Disallow creating an empty validator set
  * Ref: [monad-bft PR #2682](https://github.com/category-labs/monad-bft/pull/2682)

#### Notable internal changes

* **\[Consensus]** Add security tests for `secp256k1`
  * Adds Wycheproof tests, malleability tests, and security unit tests
  * Ref: [monad-bft PR #2706](https://github.com/category-labs/monad-bft/pull/2706)
* **\[Node ops]** Update `rkyv` and other dependencies
  * Ref: [monad-bft PR #2702](https://github.com/category-labs/monad-bft/pull/2702)
* **\[Consensus]** Return bound socket addresses synchronously in dataplane
  * Ref: [monad-bft PR #2653](https://github.com/category-labs/monad-bft/pull/2653)
* **\[Consensus]** Rename state backend cache for clarity
  * Ref: [monad-bft PR #2699](https://github.com/category-labs/monad-bft/pull/2699)

## v0.12.6

| Network                                                | Date released | Comment |
| ------------------------------------------------------ | ------------- | ------- |
| [`mainnet`](/developer-essentials/network-information) | 2026-01-14    |         |
| [`testnet`](/developer-essentials/testnets#testnet)    | 2026-01-07    |         |
| [`devnet`](/developer-essentials/testnets#tempnet)     | N/A           |         |

Tags or hashes:

* `monad-bft`: [tag `v0.12.6`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.6)
* `monad`: [tag `v0.12.6`](https://github.com/category-labs/monad/releases/tag/v0.12.6)

#### Notable RPC/SDK changes

* **\[RPC]** Fix depth bug in selfdestructing call frames
  * Ref: [monad PR #1977](https://github.com/category-labs/monad/pull/1977)
* **\[RPC]** Prestate tracer conformance fixes
  * Ref: [monad PR #1946](https://github.com/category-labs/monad/pull/1946)

#### Notable robustness changes

* **\[Consensus]** Add signature verification rate limiting with authenticated peer bypass
  * Ref: [monad-bft PR #2601](https://github.com/category-labs/monad-bft/pull/2601)
* **\[Consensus]** Validate confirm group message before updating peers
  * Ref: [monad-bft PR #2680](https://github.com/category-labs/monad-bft/pull/2680)
* **\[Consensus]** Use Tai64N directly for wireauth timestamp comparison
  * Ref: [monad-bft PR #2678](https://github.com/category-labs/monad-bft/pull/2678)
* **\[Consensus]** Improve RaptorCast decoding cache eviction
  * Ref: [monad-bft PR #2651](https://github.com/category-labs/monad-bft/pull/2651)
* **\[Consensus]** Fix blocksync in-flight request tracking on cache hydration
  * Ref: [monad-bft PR #2635](https://github.com/category-labs/monad-bft/pull/2635)
* **\[Execution]** Update triedb voted metadata before executing proposal
  * Solves a race condition between Voted updates through websocket and corresponding JSON-RPC calls
  * Ref: [monad PR #1964](https://github.com/category-labs/monad/pull/1964)
* **\[Node ops]** Persist peers periodically for improved discovery resilience
  * Ref: [monad-bft PR #2633](https://github.com/category-labs/monad-bft/pull/2633)

#### Notable performance changes

* **\[Consensus]** Boost dataplane throughput with ring buffer implementation
  * Ref: [monad-bft PR #2596](https://github.com/category-labs/monad-bft/pull/2596)
* **\[Execution]** Native implementation for `MLOAD`, `MSTORE`, `MSTORE8`, `CALLDATALOAD` opcodes
  * Ref: [monad PR #1963](https://github.com/category-labs/monad/pull/1963)
* **\[Execution]** Improve snapshot write performance
  * Ref: [monad PR #1973](https://github.com/category-labs/monad/pull/1973), [monad PR #1960](https://github.com/category-labs/monad/pull/1960)
* **\[Execution]** Optimize database history length adjustment with binary search
  * Ref: [monad PR #1922](https://github.com/category-labs/monad/pull/1922)
* **\[Execution]** Unify single buffer and scatter read handling in AsyncIO
  * Ref: [monad PR #1944](https://github.com/category-labs/monad/pull/1944)

#### Notable internal changes

* **\[Node ops]** Docker single-node container updates for prebuilt images
  * Fixes to [Local Docker installation](https://github.com/category-labs/monad-bft/blob/master/README.md#using-pre-built-images)
  * Ref: [monad-bft PR #2674](https://github.com/category-labs/monad-bft/pull/2674)
* **\[Consensus]** Add support for generic txpool sidecars
  * Enables IPC transaction priority and forwarding controls
  * Ref: [monad-bft PR #2557](https://github.com/category-labs/monad-bft/pull/2557)
* **\[EVM]** Osaka fork preparation
  * Modexp gas changes and upper bound (EIP-7823/EIP-7883)
  * Implement `CLZ` opcode
    * Ref: [monad PR #1970](https://github.com/category-labs/monad/pull/1970), [monad PR #1981](https://github.com/category-labs/monad/pull/1981)
* **\[Node ops]** Accept `--hyphen-style` long options in CLI
  * Ref: [monad PR #2005](https://github.com/category-labs/monad/pull/2005)
* **\[Node ops / Archive]** Archive pipeline improvements
  * Add `WritePolicy` to `KVStore` for conditional write protection (`NoClobber`)
  * Add BFT-uploading stats logging
  * Ref: [monad-bft PR #2649](https://github.com/category-labs/monad-bft/pull/2649), [monad-bft PR #2661](https://github.com/category-labs/monad-bft/pull/2661)
* **\[Node ops]** Simplify RPC txpool status tracking
  * Ref: [monad-bft PR #2644](https://github.com/category-labs/monad-bft/pull/2644)
* **\[Node ops]** Snapshot tooling improvements in `monad_cli`
  * Add `--dump_concurrency_limit` parameter
  * Add sharding support for distributed snapshot creation
  * Ref: [monad PR #1967](https://github.com/category-labs/monad/pull/1967), [monad PR #1965](https://github.com/category-labs/monad/pull/1965)
* **\[Node ops]** Add RaptorCast decoding cache metrics
  * Ref: [monad-bft PR #2667](https://github.com/category-labs/monad-bft/pull/2667)
* **\[Execution]** Add `CommitBuilder` API to execution database
  * Ref: [monad PR #1968](https://github.com/category-labs/monad/pull/1968)
* **\[Execution]** Remove legacy `using_chunks_for_root_offsets` metadata field
  * Ref: [monad PR #1943](https://github.com/category-labs/monad/pull/1943)
* **\[Node ops / Txgen]** Add ERC-4337 + EIP-7702 generator (`erc4337_7702_bundled`)
  * Ref: [monad-bft PR #2628](https://github.com/category-labs/monad-bft/pull/2628)
* **\[Node ops]** Add systemd service scripts for `blockcapd` and execution events archivers
  * Ref: [monad-bft PR #2590](https://github.com/category-labs/monad-bft/pull/2590)
* **\[SDK]** Add `monad_event_resolve_ring_file` API
  * Ref: [monad PR #1741](https://github.com/category-labs/monad/pull/1741)
* **\[Execution]** Enable VM host exception handling outside VM
  * Ref: [monad PR #1990](https://github.com/category-labs/monad/pull/1990)

## v0.12.5

| Network                                                | Date released | Comment            |
| ------------------------------------------------------ | ------------- | ------------------ |
| [`mainnet`](/developer-essentials/network-information) | N/A           |                    |
| [`testnet`](/developer-essentials/testnets#testnet)    | 2025-12-16    | reset from genesis |
| [`devnet`](/developer-essentials/testnets#tempnet)     | N/A           |                    |

Tags or hashes:

* `monad-bft`: [tag `v0.12.5`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.5)
* `monad`: [tag `v0.12.5`](https://github.com/category-labs/monad/releases/tag/v0.12.5)

#### Notable network changes

* **\[Network reset]** `testnet` **reset from genesis** starting from `MONAD_EIGHT`
  * Increases total supply to 100 B, consistent with `mainnet`
  * Clears a path to eliminate dead code (revisions required for early `testnet`)
  * Ref: [monad PR #1983](https://github.com/category-labs/monad/pull/1983), [monad-bft PR #2673](https://github.com/category-labs/monad-bft/pull/2673)

## v0.12.4

| Network                                                | Date released | Comment |
| ------------------------------------------------------ | ------------- | ------- |
| [`mainnet`](/developer-essentials/network-information) | 2025-12-05    |         |
| [`testnet`](/developer-essentials/testnets#testnet)    | 2025-12-05    |         |
| [`devnet`](/developer-essentials/testnets#tempnet)     | 2025-12-05    |         |

Tags or hashes:

* `monad-bft`: [tag `v0.12.4`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.4)
* `monad`: [tag `v0.12.4`](https://github.com/category-labs/monad/releases/tag/v0.12.4) *(unchanged from v0.12.3)*

#### Notable internal changes

* **\[Node ops]** Fix peer discovery port configuration when constructing self name record
  * Use port from peer discovery config instead of bound socket when constructing self name record.
    This bug affected node operators using a NAT.
  * Ref: [monad-bft PR #2655](https://github.com/category-labs/monad-bft/pull/2655)

## v0.12.3

| Network                                                | Date released | Comment |
| ------------------------------------------------------ | ------------- | ------- |
| [`mainnet`](/developer-essentials/network-information) | 2025-12-05    |         |
| [`testnet`](/developer-essentials/testnets#testnet)    | 2025-12-04    |         |
| [`devnet`](/developer-essentials/testnets#tempnet)     | 2025-12-04    |         |

Tags or hashes:

* `monad-bft`: [tag `v0.12.3`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.3)
* `monad`: [tag `v0.12.3`](https://github.com/category-labs/monad/releases/tag/v0.12.3)

#### Notable RPC/SDK changes

* **\[RPC]** [EIP-7966](https://eips.ethereum.org/EIPS/eip-7966) (`eth_sendRawTransactionSync`) support
  * Ref: [monad-bft PR #2542](https://github.com/category-labs/monad-bft/pull/2542)
* **\[RPC]** Populate `value` field on traces for staking precompile syscalls (added in `0.12.3-rpc-hotfix2`)
  * Ref: [monad PR #1938](https://github.com/category-labs/monad/pull/1938)

#### Notable robustness changes

* **\[Consensus]** Wire authentication protocol for UDP
  * Adds authenticated UDP communication to improve network security
  * Includes replay window adjustments for improved reliability
  * Ref: [monad-bft PR #2417](https://github.com/category-labs/monad-bft/pull/2417), [monad-bft PR #2544](https://github.com/category-labs/monad-bft/pull/2544), [monad-bft PR #2626](https://github.com/category-labs/monad-bft/pull/2626), [monad-bft PR #2091](https://github.com/category-labs/monad-bft/pull/2091)
* **\[Execution]** Improve `statesync` shutdown and fix protocol corruption
  * Modified `statesync_server_recv()` to guarantee complete reads
  * Ref: [monad PR #1930](https://github.com/category-labs/monad/pull/1930)
* **\[RPC]** Prevent reserve balance crash in RPC
  * Add reserve balance violation error messages in call frames
  * Ref: [monad PR #1932](https://github.com/category-labs/monad/pull/1932), [monad-bft PR #2629](https://github.com/category-labs/monad-bft/pull/2629)
  * This was already previously released in `v0.12.2-rpc-hotfix`
* **\[Consensus]** Add timeout to `txpool` IPC stream
  * Prevents hanging connections in transaction pool communication
  * Ref: [monad-bft PR #2619](https://github.com/category-labs/monad-bft/pull/2619)
* **\[Consensus]** Reject timeout certificates with empty signers
  * Adds validation to prevent malformed timeout certificates
  * Ref: [monad-bft PR #2630](https://github.com/category-labs/monad-bft/pull/2630)
* **\[Consensus]** Verify RaptorCast chunk length is non-zero
  * Adds validation to prevent malformed RaptorCast chunks
  * Ref: [monad-bft PR #2638](https://github.com/category-labs/monad-bft/pull/2638)
* **\[Execution]** Fix MPT restore bug that failed to preserve `version_lower_bound`
  * Ref: [monad PR #1955](https://github.com/category-labs/monad/pull/1955)
* **\[Execution]** Fix move trie version forward bug
  * Erase versions that fall out of history range before moving forward to newer versions
  * Ref: [monad PR #1957](https://github.com/category-labs/monad/pull/1957)
* **\[Execution]** Fix dangling pointers to intercode
  * Resolves memory safety issue with `get_code` and `read_code` functions
  * Ref: [monad PR #1941](https://github.com/category-labs/monad/pull/1941)
* **\[Execution]** Add retries to `runloop_monad_ethblocks`
  * Ref: [monad PR #1953](https://github.com/category-labs/monad/pull/1953)

#### Notable performance changes

* **\[RPC]** Improve `eth_getLogs` performance
  * Reduce memory copies and unify receipt-to-logs processing
  * Ref: [monad-bft PR #2588](https://github.com/category-labs/monad-bft/pull/2588), [monad-bft PR #2591](https://github.com/category-labs/monad-bft/pull/2591), [monad-bft PR #2631](https://github.com/category-labs/monad-bft/pull/2631)
* **\[Execution]** Fiber: add support for move-only functors
  * Improves execution efficiency by supporting move semantics
  * Ref: [monad PR #1936](https://github.com/category-labs/monad/pull/1936)

#### Notable internal changes

* **\[RPC / Node ops]** Allow RPC to run without `monad-bft`
  * Enables standalone RPC operation for improved deployment flexibility
  * Ref: [monad-bft PR #2613](https://github.com/category-labs/monad-bft/pull/2613)
* **\[Node ops]** Add `--root-offsets-chunk-count` flag to `monad-mpt` to configure the number of chunks allocated for root offsets
  * Each chunk holds approximately 16.5M blocks. Previously, all nodes were hardcoded to use 2 chunks (max TrieDB capacity of \~33M blocks)
  * New default: 16 **must be a power of 2**
  * Note that the default value of 16 translates to approximately 268M blocks \~ 1240 days. In most cases the limiting factor is disk capacity which will auto-compact when filled to 80%
  * Ref: [monad PR #1937](https://github.com/category-labs/monad/pull/1937)
* **\[Node ops]** Peer discovery improvements
  * Full nodes periodically pull validator name records for dynamic validator discovery
  * Add authenticated UDP port to name record
  * Ref: [monad-bft PR #2607](https://github.com/category-labs/monad-bft/pull/2607), [monad-bft PR #2538](https://github.com/category-labs/monad-bft/pull/2538)
* **\[Node ops / Archive]** Archive infrastructure improvements
  * Refactor `monad-block-writer` for improved reliability with `--max-blocks-per-iter` configuration
  * Async backfill with traces-only archive support
  * Add `require-traces` archiver flag and indexer fallback source
  * Support for historical execution event archiving with generic directory archiving
  * **Potentially breaking: Remove `--start-block` from `monad-archiver` systemd service; operators must use imperative CLI to set start block**
    * Example: `monad-archiver set-start-block --block 1000000 --archive-sink s3://bucket-name/path`
    * Use `--async-backfill` flag to set the async-backfill marker instead of primary marker
  * Ref: [monad-bft PR #2610](https://github.com/category-labs/monad-bft/pull/2610), [monad-bft PR #2606](https://github.com/category-labs/monad-bft/pull/2606), [monad-bft PR #2598](https://github.com/category-labs/monad-bft/pull/2598), [monad-bft PR #2514](https://github.com/category-labs/monad-bft/pull/2514), [monad-bft PR #2612](https://github.com/category-labs/monad-bft/pull/2612), [monad-bft PR #2569](https://github.com/category-labs/monad-bft/pull/2569), [monad-bft PR #2623](https://github.com/category-labs/monad-bft/pull/2623)
* **\[Node ops]** Networking configuration updates
  * Use default MTU 1500
  * Add HDR histogram for broadcast latency tracking in `monad-executor` and `monad-raptorcast`
  * Ref: [monad-bft PR #2576](https://github.com/category-labs/monad-bft/pull/2576), [monad-bft PR #2602](https://github.com/category-labs/monad-bft/pull/2602)
* **\[Consensus]** RaptorCast improvements
  * Clear histogram every 30s and keep only p99 for better latency tracking
  * Fix timer update after receiving control messages to ensure proper keepalives
  * Ref: [monad-bft PR #2627](https://github.com/category-labs/monad-bft/pull/2627), [monad-bft PR #2637](https://github.com/category-labs/monad-bft/pull/2637)
* **\[Consensus]** Dataplane: refactor to use socket handles
  * Prepares dataplane for future extension with authenticated sockets
  * Ref: [monad-bft PR #2458](https://github.com/category-labs/monad-bft/pull/2458)
* **\[Execution]** Replay monad: always execute first block off latest finalized state
  * Ref: [monad PR #1927](https://github.com/category-labs/monad/pull/1927)
* **\[Node ops]** Txgen improvements: README and guide, nonce gaps and legacy tx options, ERC20 pools, Uniswap v3 mode, NFT sale mode, websocket and RPC request generation
  * Ref: [monad-bft PR #2568](https://github.com/category-labs/monad-bft/pull/2568), [monad-bft PR #2567](https://github.com/category-labs/monad-bft/pull/2567), [monad-bft PR #2577](https://github.com/category-labs/monad-bft/pull/2577), [monad-bft PR #2600](https://github.com/category-labs/monad-bft/pull/2600), [monad-bft PR #2527](https://github.com/category-labs/monad-bft/pull/2527), [monad-bft PR #2394](https://github.com/category-labs/monad-bft/pull/2394), [monad-bft PR #2608](https://github.com/category-labs/monad-bft/pull/2608)

## v0.12.2

| Network                                                | Date released | Comment |
| ------------------------------------------------------ | ------------- | ------- |
| [`mainnet`](/developer-essentials/network-information) | 2025-11-19    |         |
| [`testnet`](/developer-essentials/testnets#testnet)    | 2025-11-18    |         |
| [`devnet`](/developer-essentials/testnets#tempnet)     | 2025-11-18    |         |

Tags or hashes:

* `monad-bft`: [tag `v0.12.2-rc`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.2-rc)
* `monad`: [tag `v0.12.2-rc`](https://github.com/category-labs/monad/releases/tag/v0.12.2-rc)

#### Notable protocol changes

All updates below are gated by the `MONAD_EIGHT` revision

* **\[Execution]** Reserve balance checks now use the final state code hash. This makes checks
  slightly more liberal (less likely to revert transactions during execution), and also makes the
  implementation closer to the
  [Coq model](https://category-labs.github.io/category-research/reserve-balance-coq-proofs/monad.proofs.reservebal.html#execValidatedTx)
  that was proven correct under some assumptions.
  * This changes the behavior of the following corner case:
    * In transaction 1, account X is sent a small amount of MON (e.g. 5 MON)
    * Then (much later) in transaction 2, someone both deploys a smart contract wallet at account
      X and sends MON out of that smart contract.
    * Previously, transaction 2's execution would treat account X as an EOA and apply reserve
      balance checks on it, thus reverting the transaction because it would be a dipping
      transaction that was not pre-authorized by consensus.
    * After this change, account X will be treated as a smart contract account and
      will be omitted from reserve balance checks.
    * Note that smart contract addresses are deterministic, making it effectively impossible for
      an address that receives a code deployment to also be an EOA (i.e. to correspond to a
      private key).
  * Ref: [monad PR #1916](https://github.com/category-labs/monad/pull/1916),
    [monad PR #1917](https://github.com/category-labs/monad/pull/1917)
* **\[EVM]** Reduce pagination on staking precompile inverse mappings from 100 to 50
  * Applies to `precompile_get_delegations()` and `precompile_get_delegators()`
  * Ref: [monad PR #1920](https://github.com/category-labs/monad/pull/1920)

#### Notable deployment changes

* **\[SDK]** Execution events no longer require a special "preview" release to enable all EVM notifications (there are no more `--exec-events` special versions)
* **\[SDK]** Fix race condition in event ring create
  * Ref: [monad PR #1914](https://github.com/category-labs/monad/pull/1914)

#### Notable robustness changes

* **\[RPC]** Fix `eth_feeHistory`
  * Ref: [monad-bft PR #2366](https://github.com/category-labs/monad-bft/pull/2366)
* **\[Consensus]** Update transaction classification logic to apply emptying before delegation
  * Improves delegation ordering in `try_apply_block_fees`
  * Ref: [monad-bft PR #2561](https://github.com/category-labs/monad-bft/pull/2561)
* **\[Execution]** Failsafe sanity checks for reward system transactions
  * Ref: [monad PR #1921](https://github.com/category-labs/monad/pull/1921)
* **\[RPC]** Check reserve balance in `eth_call`
  * Prevent simulated transactions from violating reserve balance
  * Call `revert_transaction` in `eth_call` implementation
  * Ref: [monad PR #1912](https://github.com/category-labs/monad/pull/1912)
* **\[Node ops]** Fix remotely fetched `forkpoint.toml` write format
  * Ensures forkpoint files are written in the correct format when fetched from remote sources
  * Ref: [monad-bft PR #2554](https://github.com/category-labs/monad-bft/pull/2554)
* **\[Node ops]** Fix `monad-keystore` key corruption issue
  * `to_bls` and `to_secp` now consume secret to prevent corrupted keystore files
  * Add tests for command line keystore app to verify all flags combinations work correctly
  * Ref: [monad-bft PR #2553](https://github.com/category-labs/monad-bft/pull/2553)
* **\[Execution]** Fix bad write offset in `storage_pool` `try_trim_contents()` when bytes to start TRIM is not a multiple of disk page size
  * Ref: [monad PR #1908](https://github.com/category-labs/monad/pull/1908)
* **\[RPC]** Use txpool bridge channel size for ratelimiting
  * Prevents `try_send` method from failing by using channel capacity for `eth_sendRawTransaction` ratelimiting
  * Ref: [monad-bft PR #2506](https://github.com/category-labs/monad-bft/pull/2506)
* **\[Consensus]** Improve RaptorCast message validation
  * Add sanity check for `chunk_id` range in message parsing
  * Reject overflowing `merkle_leaf_idx` in merkle proof construction
  * Update calculation of `encoded_symbol_capacity` in decoder
  * Ref: [monad-bft PR #2541](https://github.com/category-labs/monad-bft/pull/2541)
* **\[Consensus]** Improve RaptorCast group invite response checks
  * Add sanity check to prevent processing group invite accept after reject from same full node
  * Ref: [monad-bft PR #2574](https://github.com/category-labs/monad-bft/pull/2574)
* **\[Consensus]** Update txpool insertion policy - make balance check stricter
  * Ref: [monad-bft PR #2575](https://github.com/category-labs/monad-bft/pull/2575)

#### Notable performance changes

* **\[Consensus]** Add dataplane warnings when priority queues are overrun
  * Sets total priority queue capacity to 100MB per priority queue (200MB total max)
  * Messages will be dropped with warnings logged if capacity is exceeded
  * Ref: [monad-bft PR #2559](https://github.com/category-labs/monad-bft/pull/2559)
* **\[Execution / Node ops]** Remove read-only database `io_uring` SQ poll thread
  * **IMPORTANT**: Operators with `monad-execution` systemctl overrides should make the appropriate changes to eliminate the `--ro_sq_thread_cpu` parameter as demonstrated in [monad-bft PR #2558](https://github.com/category-labs/monad-bft/pull/2558). Overrides are commonly set when running an RPC or archive node with `--trace_calls` enabled.
  * Reduces thread contention during statesync, improving block execution performance
  * Make `ro_sq_thread_cpu` argument optional, remove from default configuration
  * Ref: [monad PR #1911](https://github.com/category-labs/monad/pull/1911), [monad-bft PR #2558](https://github.com/category-labs/monad-bft/pull/2558)
* **\[RPC]** Move recover authority logic inside submitted lambda for `eth_call`
  * Avoid blocking on fiber promises when called from rust thread, preventing performance issues
  * Replace parallelization with single call to `recover_authority()` since `eth_call` transactions have single authority
  * Ref: [monad PR #1827](https://github.com/category-labs/monad/pull/1827)
* **\[Execution]** Remove `iopoll` support
  * Ref: [monad PR #1910](https://github.com/category-labs/monad/pull/1910)

#### Notable internal changes

* **\[Node ops]** Add `monad-version` crate for git version info in binaries
  * Ref: [monad-bft PR #2572](https://github.com/category-labs/monad-bft/pull/2572)
* **\[Node ops]** Add CLI argument for number of fibers in trace transaction execution pool (default: 100)
  * Ref: [monad-bft PR #2584](https://github.com/category-labs/monad-bft/pull/2584)
* **\[Node ops]** Update block reward for mainnet
  * Ref: [monad-bft PR #2582](https://github.com/category-labs/monad-bft/pull/2582)
* **\[Node ops]** Add block writer binary for testing and debugging
  * Ref: [monad-bft PR #2546](https://github.com/category-labs/monad-bft/pull/2546)
* **\[Node ops]** Make cruft timer retention configurable
  * Add environment variable support for artifact retention times (override in `/home/monad/.env`)
  * Ref: [monad-bft PR #2548](https://github.com/category-labs/monad-bft/pull/2548)
* **\[Node ops]** Add warning when restoring from snapshot (hard reset) is required
  * Prompt node operator when local tip is behind by `STATESYNC_BLOCK_THRESHOLD`
  * Ref: [monad-bft PR #2581](https://github.com/category-labs/monad-bft/pull/2581)
* **\[Node ops]** Update `monad-cruft` permissions to monad user
  * Ref: [monad-bft PR #2556](https://github.com/category-labs/monad-bft/pull/2556)
* **\[Node ops]** Fix txpool metrics recording for transaction replacements
  * Ref: [monad-bft PR #2564](https://github.com/category-labs/monad-bft/pull/2564)
* **\[RPC]** Operator can configure RPC worker threads
  * Ref: [monad-bft PR #2562](https://github.com/category-labs/monad-bft/pull/2562)
* **\[Archive]** Add TOML config file support instead of CLI-only configuration
  * Enables `monad-archiver` binary to use `--config` flag for configuration
  * CLI arguments continue to work and take precedence over config file values
  * Ref: [monad-bft PR #2570](https://github.com/category-labs/monad-bft/pull/2570)
* **\[Node ops]** Add random mutations to `txgen` for improved testing
  * Ref: [monad-bft PR #2543](https://github.com/category-labs/monad-bft/pull/2543)
* **\[Node ops]** Add reserve balance coherency tests
  * Ref: [monad-bft PR #2573](https://github.com/category-labs/monad-bft/pull/2573)
* **\[SDK]** Record execution events
  * Includes state access and system transactions
  * Ref: [monad PR #1906](https://github.com/category-labs/monad/pull/1906), [monad PR #1907](https://github.com/category-labs/monad/pull/1907), [monad PR #1913](https://github.com/category-labs/monad/pull/1913)
* **\[SDK]** Explicitly clear flow info that doesn't apply to certain event types
  * Prevents poorly written event clients from reading invalid data
  * Ref: [monad PR #1919](https://github.com/category-labs/monad/pull/1919)
* **\[Execution]** Improve assertion messages with `MONAD_ASSERT_PRINTF`
  * Ref: [monad PR #1918](https://github.com/category-labs/monad/pull/1918)
* **\[Node ops]** Add statesync server metrics
  * Add `SyncDone` metric to track successes and failures
  * Add request timing metric for statesync server
  * Ref: [monad-bft PR #2555](https://github.com/category-labs/monad-bft/pull/2555)
* **\[Node ops]** Disambiguate triedb error logs
  * Improve error message clarity by making each log call unique
  * Ref: [monad-bft PR #2579](https://github.com/category-labs/monad-bft/pull/2579)
* **\[Node ops]** Update devnet chain configs
  * Shorten default devnet epoch length from 50,000 blocks to 10,000 blocks and epoch start delay from 5,000 rounds to 1,000 rounds
  * Ref: [monad-bft PR #2578](https://github.com/category-labs/monad-bft/pull/2578)
* **\[Node ops]** Update test infrastructure
  * Switch `test_state` and `precompiles_test` tests to `TraitsTest`
  * Add `runloop_monad_ethblocks` to CLI for Monad EVM block replay
  * Ref: [monad PR #1905](https://github.com/category-labs/monad/pull/1905), [monad PR #1894](https://github.com/category-labs/monad/pull/1894)
* **\[Execution]** Remove unused cross-thread pipe messaging infrastructure
  * Ref: [monad PR #1915](https://github.com/category-labs/monad/pull/1915)
* **\[Node ops]** Keep manytrace agent alive in node state
  * Ref: [monad-bft PR #2583](https://github.com/category-labs/monad-bft/pull/2583)
* **\[Node ops]** Update keystore documentation
  * Ref: [monad-bft PR #2380](https://github.com/category-labs/monad-bft/pull/2380)
* **\[Node ops]** Add more logging for block validation errors
  * Ref: [monad-bft PR #2550](https://github.com/category-labs/monad-bft/pull/2550)
* **\[Node ops]** Log round leader when processing certificates
  * Ref: [monad-bft PR #2580](https://github.com/category-labs/monad-bft/pull/2580)

## v0.12.1

| Network                                             | Date released | Comment |
| --------------------------------------------------- | ------------- | ------- |
| [`testnet`](/developer-essentials/testnets#testnet) | 2025-11-12    |         |
| [`devnet`](/developer-essentials/testnets#tempnet)  | 2025-11-12    |         |

Tags or hashes:

* `monad-bft`: [tag `v0.12.1`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.1)
* `monad`: [tag `v0.12.1`](https://github.com/category-labs/monad/releases/tag/v0.12.1)

#### Notable RPC/SDK changes

* **\[RPC]** Support for prestate and statediff tracing for the following RPC endpoints:
  * `debug_traceTransaction`
  * `debug_traceBlockByNumber`
  * `debug_traceBlockByHash`
  * Ref: [monad PR #1753](https://github.com/category-labs/monad/pull/1753), [monad-bft PR #2403](https://github.com/category-labs/monad-bft/pull/2403)
* **\[RPC]** New endpoint `eth_createAccessList`
  * Ref: [monad PR #1748](https://github.com/category-labs/monad/pull/1748), [monad-bft PR #2519](https://github.com/category-labs/monad-bft/pull/2519)
* **\[RPC]** Fix serialization for `to` address in historical traces
  * Follow on to [monad-bft PR #2516](https://github.com/category-labs/monad-bft/pull/2516) implemented in `v0.12.0` (in a historical context)
  * Ref: [monad-bft PR #2523](https://github.com/category-labs/monad-bft/pull/2523), [monad PR #1861](https://github.com/category-labs/monad/pull/1861)
* **\[RPC]** Remove artificial block height floor for `eth_call` and RPC queries
  * Previously limited queries using `latest` and `safe` block tags to `finalized + 1`, now uses actual latest voted block
  * Ref: [monad-bft PR #2148](https://github.com/category-labs/monad-bft/pull/2148)
* **\[RPC]** Fix RPC errors when requesting traces for call frames that include a self-destructing transaction
  * Ref: [monad PR #1887](https://github.com/category-labs/monad/pull/1887)
* **\[RPC]** Fix inconsistent results being reported when using state overrides in RPC calls
  * Ref: [monad PR #1812](https://github.com/category-labs/monad/pull/1812)
* **\[RPC]** Fix for a possible denial-of-service attack on RPC nodes by overriding balances in the staking contract
  * Ref: [monad PR #1903](https://github.com/category-labs/monad/pull/1903)

#### Notable robustness changes

* **\[Node ops/Consensus]** Validators limit statesync service to validators and whitelisted full nodes
  * Full nodes service all requests
  * Ref: [monad-bft PR #2524](https://github.com/category-labs/monad-bft/pull/2524)
* **\[Consensus]** More intelligent txpool eviction logic
  * Ref: [monad-bft PR #2525](https://github.com/category-labs/monad-bft/pull/2525)
* **\[Consensus]** Start vote pacing timer on startup
  * Ref: [monad-bft PR #2528](https://github.com/category-labs/monad-bft/pull/2528)
* **\[Consensus]** Fix historical logs `selfdestruct` issue
  * Ref: [monad-bft PR #2531](https://github.com/category-labs/monad-bft/pull/2531)
* **\[Consensus]** Graceful handling of gas limit check
  * Ref: [monad-bft PR #2518](https://github.com/category-labs/monad-bft/pull/2518)
* **\[Consensus]** Remove 0-stake validator support
  * Support for 0-stake validators in the validator set was used as a workaround for lack of full-node support in the past and should no longer be supported
  * Ref: [monad-bft PR #2545](https://github.com/category-labs/monad-bft/pull/2545)

#### Notable performance changes

* **\[Consensus]** Bias statesync requests to responsive peers
  * Support dynamic peer expansion/contraction
  * Nodes no longer panic if all peers are pruned (e.g., not whitelisted by any init peers)
  * Ref: [monad-bft PR #2536](https://github.com/category-labs/monad-bft/pull/2536)
* **\[Consensus]** Drop blocksync requests that hit disk after cache hydration (\~7min after startup)
  * Ref: [monad-bft PR #2533](https://github.com/category-labs/monad-bft/pull/2533)
* **\[Consensus]** Dataplane: replace interval with sleep
  * Ref: [monad-bft PR #2517](https://github.com/category-labs/monad-bft/pull/2517)
* **\[Execution]** Replace data structures in `VersionStack` code to improve performance when pushing and popping EVM call frames.
  * Ref: [monad PR #1802](https://github.com/category-labs/monad/pull/1802), [monad PR #1877](https://github.com/category-labs/monad/pull/1877)

#### Notable internal changes

* **\[Node ops]** Try fetching remote `forkpoint.toml` and `validators.toml` on startup
  * **IMPORTANT**: Nodes now automatically attempt to download configuration files from remote locations on startup, no "Soft Reset" required. This remote fetch is subject to a configurable remote threshold
  * The following env variables must be set to enable this behavior:
    * `REMOTE_FORKPOINT_URL`
    * `REMOTE_VALIDATORS_URL`
  * Ref: [monad-bft PR #2484](https://github.com/category-labs/monad-bft/pull/2484), [monad-bft PR #2534](https://github.com/category-labs/monad-bft/pull/2534)
* **\[Node ops]** Serialize forkpoints in both TOML and RLP formats, with RLP as source of truth; cleanup `get_latest_config` branches
  * Ref: [monad-bft PR #2521](https://github.com/category-labs/monad-bft/pull/2521)
* **\[Node ops/Consensus]** Dynamically expand statesync upstream peers
  * Always initializes to `statesync.init_peers` (no longer defaults to bootstrap peers)
  * If `expand_to_group` is enabled, expands to validator set (for validators) and/or secondary raptorcast peers (for public / prioritized full nodes)
  * Ref: [monad-bft PR #2535](https://github.com/category-labs/monad-bft/pull/2535)
* **\[Node ops/Consensus]** Full nodes no longer default to blocksync from validator set
  * Dedicated full nodes must specify upstream as blocksync override
  * **IMPORTANT**: prioritized/public full nodes can only blocksync *after* joining secondary raptorcast group. `refresh_period` and `invite_lookahead` recommended to be lowered to 20 seconds
  * Ref: [monad-bft PR #2532](https://github.com/category-labs/monad-bft/pull/2532)
* **\[Consensus]** Use epoch field to encode round number for secondary raptorcast
  * Fixes issue where syncing full nodes receive unsolicited chunks from expired groups
  * Ref: [monad-bft PR #2442](https://github.com/category-labs/monad-bft/pull/2442)
* **\[Consensus]** Add statesync server pending requests metric (better load visibility)
  * Ref: [monad-bft PR #2530](https://github.com/category-labs/monad-bft/pull/2530)
* **\[Node ops]** Import `monad-execution` API changes
  * Ref: [monad-bft PR #2522](https://github.com/category-labs/monad-bft/pull/2522)

## v0.12.0

| Network                                             | Date released | Comment                                                                                                                                                |
| --------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`testnet`](/developer-essentials/testnets#testnet) | 2025-11-05    | Revision is set to [`MONAD_SEVEN`](https://www.notion.so/developer-essentials/changelog/README.md#revisions) at 2025-11-05 14:30 GMT                   |
| [`devnet`](/developer-essentials/testnets#tempnet)  | 2025-11-03    | Devnet was reset with this new release, with revision set to [`MONAD_SEVEN`](https://www.notion.so/developer-essentials/changelog/README.md#revisions) |

Tags or hashes:

* `monad-bft`: [tag `v0.12.0`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.0)
* `monad`: [tag `v0.12.0`](https://github.com/category-labs/monad/releases/tag/v0.12.0)

#### Notable protocol changes

* **\[EVM/Network params]** [Opcode/precompile repricing](/developer-essentials/opcode-pricing)
  * Opcode pricing: increase cost of cold storage access
  * Precompile pricing: better align a few underpriced precompile gas costs with the associated hardware / latency costs
  * Ref: [monad PR #1600](https://github.com/category-labs/monad/pull/1600) (for most of the repricings) and [monad PR #1700](https://github.com/category-labs/monad/pull/1700) (for `CREATE`/`CREATE2` repricing), [monad PR #1830](https://github.com/category-labs/monad/pull/1830) (for reduced v2 scope), [monad PR #1871](https://github.com/category-labs/monad/pull/1871) (activation for `MONAD_SEVEN`)
  * Gated by `MONAD_SEVEN` revision
* **\[Consensus/Network params]** \[Staking] Increase `BLOCK_REWARD_MON` from 1 MON to 25 MON
  * Note that this is not gated by `MONAD_SEVEN` (execution hard fork) but by a specific epoch start for `testnet`
  * Ref: [monad-bft PR #2511](https://github.com/category-labs/monad-bft/pull/2511)

#### Notable robustness changes

* **\[Consensus]** Consensus message prioritization in dataplane
  * Priority queues for UDP traffic ensure consensus messages are delivered before other traffic
  * All consensus messages to validators are published and rebroadcast with high priority
  * Ref: [monad-bft PR #2352](https://github.com/category-labs/monad-bft/pull/2352),
    [monad-bft PR #2354](https://github.com/category-labs/monad-bft/pull/2354)
* **\[Consensus]** DoS protection: Reject repeated invalid consensus messages
  * Prevents malicious validators from consuming CPU time by repeatedly sending invalid BLS signatures
  * Ref: [monad-bft PR #2445](https://github.com/category-labs/monad-bft/pull/2445)
* **\[Consensus]** Leader synchronization improvements
  * Forward AdvanceRound messages to current leader to prevent stale views due to message censorship
  * Ref: [monad-bft PR #2485](https://github.com/category-labs/monad-bft/pull/2485)
* **\[Consensus]** Validate group message sender authenticity
  * Ref: [monad-bft PR #2457](https://github.com/category-labs/monad-bft/pull/2457)

#### Notable RPC/SDK changes

* **\[RPC]** Fix `eth_syncing` serialization
  * Ref: [monad-bft PR #2476](https://github.com/category-labs/monad-bft/pull/2476)
* **\[RPC]** Update `debug_getRawReceipts` RLP encoding
  * Ref: [monad-bft PR #2490](https://github.com/category-labs/monad-bft/pull/2490)
* **\[RPC]** Failed contract creation should return null to address
  * Ref: [monad PR #1861](https://github.com/category-labs/monad/pull/1861),
    [monad-bft PR #2516](https://github.com/category-labs/monad-bft/pull/2516)

#### Notable performance changes

* **\[Consensus]** Dataplane: io\_uring batching for UDP sends
  * Replace GSO with io\_uring batching to preserve 64KB burst size while splitting payload
  * Batches multiple UDP sends into single io\_uring submission
  * Ref: [monad-bft PR #2317](https://github.com/category-labs/monad-bft/pull/2317)
* **\[Consensus]** Dataplane: Restore full 1500 byte MTU
  * Ref: [monad-bft PR #2438](https://github.com/category-labs/monad-bft/pull/2438)
* **\[Consensus]** RaptorCast: Modular packet assembly and round-robin ordering
  * Ref: [monad-bft PR #2377](https://github.com/category-labs/monad-bft/pull/2377),
    [monad-bft PR #2469](https://github.com/category-labs/monad-bft/pull/2469),
    [monad-bft PR #2318](https://github.com/category-labs/monad-bft/pull/2318)
* **\[Consensus]** Txpool optimizations
  * Add configurable limits, remove pending pool, refactor last commit state tracking
  * Ref: [monad-bft PR #2487](https://github.com/category-labs/monad-bft/pull/2487),
    [monad-bft PR #2363](https://github.com/category-labs/monad-bft/pull/2363),
    [monad-bft PR #2475](https://github.com/category-labs/monad-bft/pull/2475)
* **\[Archive]** Move indexer read-back to async task
  * Ref: [monad-bft PR #2486](https://github.com/category-labs/monad-bft/pull/2486)
* **\[RPC]** Remove unnecessary lock in request submission path
  * Ref: [monad-bft PR #2416](https://github.com/category-labs/monad-bft/pull/2416)

#### Notable internal changes

* **\[Node ops]** Docker support for local Monad installation
  * Optional `--use-prebuilt` flag to avoid compilation
  * Ref: [monad-bft PR #2456](https://github.com/category-labs/monad-bft/pull/2456),
    [monad-bft PR #2489](https://github.com/category-labs/monad-bft/pull/2489)
* **\[Node ops]** ledger-tail: New CLI configuration options
  * Supports custom paths for ledger, forkpoint, node config, and validators files
  * Fixes default `validators.toml` path
  * Ref: [monad-bft PR #2439](https://github.com/category-labs/monad-bft/pull/2439)
* **\[Node ops]** wal2json: Multi-file support with timestamp filtering
  * Fast timestamp seeking/filtering across multiple files (e.g., `wal2json -a"3:30pm EDT" -b"4:00pm EDT" wal*`)
  * Improved performance with parallel processing and reduced locking
  * Ref: [monad-bft PR #2496](https://github.com/category-labs/monad-bft/pull/2496),
    [monad-bft PR #2493](https://github.com/category-labs/monad-bft/pull/2493)

## v0.11.6-tn1

Revisions [`MONAD_FIVE`](/developer-essentials/changelog#revisions) and
[`MONAD_SIX`](/developer-essentials/changelog#revisions) introduced.
Revision [`MONAD_NEXT`](/developer-essentials/changelog#revisions) re-defined.

| Network                                             | Date released | Comment                                                                   |
| --------------------------------------------------- | ------------- | ------------------------------------------------------------------------- |
| [`testnet`](/developer-essentials/testnets#testnet) | 2025-10-31    | Revision is set to `MONAD_SIX` at 2025-10-31 13:30 GMT                    |
| [`devnet`](/developer-essentials/testnets#tempnet)  | 2025-10-30    | Devnet was reset with this new release, with revision set to `MONAD_NEXT` |

Tags or hashes for `testnet` deployment (no protocol differences):

* `monad-bft`: [tag `v0.11.6-tn1`](https://github.com/category-labs/monad-bft/releases/tag/v0.11.6-tn1)
* `monad`: [tag `v0.11.6-tn1`](https://github.com/category-labs/monad/releases/tag/v0.11.6-tn1)

#### Notable protocol changes - `MONAD_NEXT`

* **\[EVM/Network params]** [Opcode Repricing](/developer-essentials/opcode-pricing)
  * Ref: [monad PR #1600](https://github.com/category-labs/monad/pull/1600) (for most of the
    repricings) and  [monad PR #1700](https://github.com/category-labs/monad/pull/1700) (for
    on storage slot deletion via `SSTORE`
  * Raise the cost of `CREATE` and `CREATE2`
  * Note that this reduces the set of opcode pricings on `MONAD_NEXT` relative to `v0.11.3`.

#### Notable protocol changes - `MONAD_SIX`

* **\[EVM]** EIP-2935 bugfix
  * Ref: [monad PR #1846](https://github.com/category-labs/monad/pull/1846)

#### Notable protocol changes - `MONAD_FIVE`

* **\[Consensus/EVM]** \[Staking] Lower `ACTIVE_VALIDATOR_STAKE` from 25,000,000 MON to **10,000,000 MON**
  * Ref: [monad PR #1810](https://github.com/category-labs/monad/pull/1810)
* **\[EVM]** \[Staking] Add `getProposerValId()` method to return the `val_id` of the most recent block proposer
  * Ref: [monad PR #1815](https://github.com/category-labs/monad/pull/1815)

#### Notable RPC/SDK changes

* **\[RPC]** Fix race condition in block number queries
  * Return triedb block number in ChainState to prevent errors when `eth_getBlockNumber` returns blocks not yet available in triedb
  * Fixes common wallet workflow issue with sequential `eth_getBlockNumber` and `eth_getBalance` calls
  * Ref: [monad-bft PR #2393](https://github.com/category-labs/monad-bft/pull/2393)
* **\[SDK]** Add call frame recording to execution events
  * Ref: [monad PR #1541](https://github.com/category-labs/monad/pull/1541)
  * These will not be recorded unless the `--trace_calls` command line argument is passed to execution
* **\[RPC]** Add `monad_eth_call_executor_get_state()` API for better visibility into `eth_call` requests
  * Ref: [monad PR #1764](https://github.com/category-labs/monad/pull/1764)
  * Returns counts of currently executing/queued requests and error counts

#### Notable robustness changes

* **\[Consensus]** Deterministic timeout certificate tiebreaking
  * When TC contains multiple tips with the same round, tiebreak by tip.qc for consistency
  * Ref: [monad-bft PR #2460](https://github.com/category-labs/monad-bft/pull/2460)
* **\[Consensus]** Transaction nonce overflow validation
  * Ref: [monad-bft PR #2388](https://github.com/category-labs/monad-bft/pull/2388)
* **\[Consensus]** More consistent checks on `EpochChange` between block proposer and validator
  * This addresses an observed chain halt in `testnet-2`
  * Ref: [monad-bft PR #2494](https://github.com/category-labs/monad-bft/pull/2494)

#### Notable performance changes

* **\[EVM]** Use komihash in StateDelta maps
  * Ref: [monad PR #1786](https://github.com/category-labs/monad/pull/1786)
* **\[EVM]** JIT compiler: only emit jump table for contracts with indirect jumps
  * Ref: [monad PR #1749](https://github.com/category-labs/monad/pull/1749)
* **\[RPC]** Improve eth call concurrency with atomic sequence numbers
  * Ref: [monad PR #1759](https://github.com/category-labs/monad/pull/1759)

#### Notable internal changes

* **\[Node ops]** Fuzzer refactor (`--focus` flag addition)
  * Ref: [monad PR #1744](https://github.com/category-labs/monad/pull/1744)
* **\[Node ops]** Build images with debug symbols
  * Ref: [monad-bft PR #2459](https://github.com/category-labs/monad-bft/pull/2459)

## v0.11.3-tn1

Revisions [`MONAD_FOUR`](/developer-essentials/changelog#revisions) and
[`MONAD_NEXT`](/developer-essentials/changelog#revisions) introduced.

| Network                                             | Date released | Comment                                                 |
| --------------------------------------------------- | ------------- | ------------------------------------------------------- |
| [`testnet`](/developer-essentials/testnets#testnet) | 2025-10-13    | Revision is set to `MONAD_FOUR` at 2025-10-14 13:30 GMT |
| [`devnet`](/developer-essentials/testnets#tempnet)  | 2025-10-08    | Revision is set to `MONAD_NEXT` upon upgrade            |

Tags or hashes for `testnet` deployment (no protocol differences):

* `monad-bft`: [tag `v0.11.3-tn1`](https://github.com/category-labs/monad-bft/releases/tag/v0.11.3-tn1)
* `monad`: [hash `3e17265`](https://github.com/category-labs/monad/tree/3e17265fae80710229c657d725d821053cec940b)

#### Notable protocol changes - `MONAD_NEXT`

* **\[EVM/Network params]** [Opcode Repricing](/developer-essentials/opcode-pricing))
  * Ref: [monad PR #1600](https://github.com/category-labs/monad/pull/1600) (for most of the
    repricings) and  [monad PR #1700](https://github.com/category-labs/monad/pull/1700) (for
    `CREATE`/`CREATE2` repricing)
  * Opcodes are repriced as discussed in the
    [Monad Initial Spec Proposal](https://forum.monad.xyz/t/monad-initial-specification-proposal/195)
  * Increase cost of cold storage access
  * Precompiles: better align a few underpriced precompile gas costs with the associated
    hardware / latency costs
  * Note: this release also includes a few opcode repricings in MISP v1.0.2 which were later removed:
  * Increase cost of storage slot creation via `SSTORE`, and increase the percent of gas refunded
    on storage slot deletion via `SSTORE`
  * Raise the cost of `CREATE` and `CREATE2`
* **\[EVM]** Disable CREATE and CREATE2 when executing delegated code
  * Ref: [monad PR #1601](https://github.com/category-labs/monad/pull/1601)

#### Notable protocol changes - `MONAD_FOUR`

* **\[Consensus/EVM]** [Staking](/monad-arch/consensus/staking) is live
  * (many PRs; see
    [staking](https://github.com/category-labs/monad/tree/main/category/execution/monad/staking))
  * Active validator set is now determined by on-chain state of the staking precompile
  * This takes effect starting from a designated `staking_activation` epoch
  * Note: staking rewards do not activate until `staking_rewards_activation` epoch
    (future point in time)
  * External rewards - enable external (non-block-reward) deposits to the validator pool, see
    [monad PR #1625](https://github.com/category-labs/monad/pull/1625)
  * Also added additional events to staking precompile in [monad PR #1742](https://github.com/category-labs/monad/pull/1742)
  * Adds `ValidatorRewarded`, `EpochChanged`, `ClaimRewards` events
* **\[Consensus/EVM]** [Reserve balance](/developer-essentials/reserve-balance) logic is live
  * Ref: [monad-bft PR #2160](https://github.com/category-labs/monad-bft/pull/2160) and
    [monad PR #1537](https://github.com/category-labs/monad/pull/1537)
  * Due to async execution, consensus does not have the latest state available for transaction
    inclusion logic. Reserve balance is a buffer that enables simpler accounting for a given
    account to mitigate the possibility of overspending in that delay window.
  * Per-EOA reserve balance is set to `10 MON`
* **\[Consensus/EVM]** [EIP-7702](/developer-essentials/eip-7702) is live
  * Ref: [monad-bft PR #2160](https://github.com/category-labs/monad-bft/pull/2160), [monad-bft PR #2218](https://github.com/category-labs/monad-bft/pull/2218) and
    [monad PR #1362](https://github.com/category-labs/monad/pull/1362)
* **\[Network params]** Set per-transaction gas limit of 30M gas
  * Ref: [monad-bft PR #2246](https://github.com/category-labs/monad-bft/pull/2246)
  * As discussed in the
    [Monad Initial Spec Proposal](https://forum.monad.xyz/t/monad-initial-specification-proposal/195)
* **\[Network params]** Increase block gas limit from 150M gas (375 Mgas/s) to **200M** gas
  (500 Mgas/s)
  * Ref: [monad-bft PR #2266](https://github.com/category-labs/monad-bft/pull/2266)
* **\[Network params]** Implement [dynamic base fee](/developer-essentials/gas-pricing)
  * Ref: [monad-bft PR #2207](https://github.com/category-labs/monad-bft/pull/2207)
  * As specified in the
    [Monad Initial Spec Proposal](https://forum.monad.xyz/t/monad-initial-specification-proposal/195)
  * Target gas is 80% of a block
  * Raise minimum base fee from 50 MON-gwei to **100 MON-gwei**
* **\[EVM]** Enable [EIP-2935](https://eips.ethereum.org/EIPS/eip-2935) + blockhash
  buffer
  * Ref: [monad PR #1520](https://github.com/category-labs/monad/pull/1520)
* **\[EVM]** Enable [EIP-7951](https://eips.ethereum.org/EIPS/eip-7951) (P256VERIFY
  precompile support)
  * Ref: [monad PR #1518](https://github.com/category-labs/monad/pull/1518)
* **\[EVM]** Enable [EIP-2537](https://eips.ethereum.org/EIPS/eip-2537) (BLS12-381 precompiles)
  * Ref: [monad-bft PR #1342](https://github.com/category-labs/monad/pull/1342) and [monad-bft PR #1350](https://github.com/category-labs/monad/pull/1350)
* **\[EVM]** Raise max contract size for `CREATE`/`CREATE2` to 128 kb
  * Ref: [monad PR #1440](https://github.com/category-labs/monad/pull/1440)
  * This brings `CREATE`/`CREATE2` to parity with toplevel contract creation transactions, which
    had their limit raised in `MONAD_TWO`.
  * Previously, they were unintentionally limited to Ethereum's max initcode size (49.152 kb)
    due to a bug

#### Notable RPC/SDK changes

* **\[SDK]** Added support for [Execution Events](/execution-events)
* **\[RPC]** Extend `eth_call` support for preStateTracer and stateDiffTracer with `debug_traceCall`
  * Ref: [monad-bft PR #2275](https://github.com/category-labs/monad-bft/pull/2275) and
    [monad PR #1471](https://github.com/category-labs/monad/pull/1471)
* **\[RPC]** Support the `withLog` parameter with `callTracer`
  * Ref: [monad-bft PR #2400](https://github.com/category-labs/monad-bft/pull/2400)
  * If `withLog` is set to true, `callTracer` includes event logs in the trace output

#### Notable performance changes

* **\[EVM]** Kernel caching of db reads and writes
  * Ref: [monad PR #1559](https://github.com/category-labs/monad/pull/1559)
  * Utilize available host memory to cache recent DB operations - this cache
    should increase performance of execution and RPC
* **\[RPC]** Improve RPC Db Node Cache and make it memory bounded
  * Ref: [monad PR #1581](https://github.com/category-labs/monad/pull/1581)
  * Note a rename of RPC cli flags: `--eth-call-executor-node-lru-size` to
    `--eth-call-executor-node-lru-max-mem` and a new flag `--triedb-node-lru-max-mem` with
    both default to 100MB.

#### Notable internal changes

* **\[Node ops]** Remove `bft-fullnode` binary; only `bft` binary now
  * Ref: [monad-bft PR #2072](https://github.com/category-labs/monad-bft/pull/2072)
  * `bft-fullnode` removed from `deb` pkg for `v0.11`
* **\[Node ops]** PeerDiscovery: Introduce precheck for peer self name address
* **\[Consensus]** Blocksync: only select blocksync peers from connected nodes
  * Ref: [monad-bft PR #2401](https://github.com/category-labs/monad-bft/pull/2401)
* **\[Consensus]** Raptorcast: DOS protection on decoding state cache
  * Ref: [monad-bft PR #2092](https://github.com/category-labs/monad-bft/pull/2092)
* **\[Node ops]** Secondary raptorcast config change
  * Ref: [monad-bft PR #2378](https://github.com/category-labs/monad-bft/pull/2378)
  * Replace ambiguous secondary raptorcast  `mode` parameter with `enable_publisher` and `enable_client`
* **\[Node ops]** Dynamically reload prioritized full-nodes
  * Ref: [monad-bft PR #2364](https://github.com/category-labs/monad-bft/pull/2364)
* **\[Node ops]** Fix wal2json
  * Ref: [monad-bft PR #2404](https://github.com/category-labs/monad-bft/pull/2404)
* **\[Node ops/RPC]** Support the RPC CLI param `ws-sub-per-conn-limit`
  * Ref: [monad-bft PR #2161](https://github.com/category-labs/monad-bft/pull/2161)
  * Sets the maximum number of websocket subscriptions per connection (default to 100)
* **\[Node ops/RPC]** Add configuration options for high eth-call pool
  * Ref: [monad-bft PR #2387](https://github.com/category-labs/monad-bft/pull/2387)

## v0.11.1

Note: `v0.11.1` was a version that was deployed only on `testnet-2` (a temporary network deprecated
on 2025-10-27) from roughly 2025-09-16 until 2025-10-08; however, it maps some features differently
to revision `MONAD_FOUR` which are no longer memorialized in the codebase. `testnet-2` was reset
before deploying `v0.11.3`.

For all intents and purposes, this version can be ignored. This changelog will compare `v0.11.3`
with `v0.10.4`.

Tags or hashes:

* `monad-bft`: [tag `v0.11.1`](https://github.com/category-labs/monad-bft/releases/tag/v0.11.1)
* `monad`: [hash `7746980`](https://github.com/category-labs/monad/tree/7746980c45b82f812bd8c4d39f4b0a1232ae16de)

## v0.10.4

| Network                                             | Date deployed | Comment                         |
| --------------------------------------------------- | ------------- | ------------------------------- |
| [`testnet`](/developer-essentials/testnets#testnet) | 2025-08-18    | Revision is still `MONAD_THREE` |

Tags or hashes:

* `monad-bft`: [tag `v0.10.4`](https://github.com/category-labs/monad-bft/releases/tag/v0.10.4)
* `monad`: hash `39c42e6`

#### Notable RPC/SDK changes

* **\[RPC]** EIP-4844 related fields in RPC responses are removed.
  * Block headers returned from RPC will no longer have `blobGasUsed` , `excessBlobGas`, and
    `parentBeaconBlockRoot`.

#### Notable performance changes

* **\[Consensus]** Votes are now sent to current round leader. This is a consensus optimization that
  reduces the effective delay due to a round timeout
  * Ref: [monad-bft PR #2093](https://github.com/category-labs/monad-bft/pull/2093)
* **\[Consensus]** Caching of recently-verified quorum certificates
  * Ref: [monad-bft PR #2167](https://github.com/category-labs/monad-bft/pull/2167)
* **\[Node ops]** Enablement of trace calls is now controlled via `monad` (execution) command line
  arg `--trace_calls`.
  * To preserve legacy behavior, `--trace_calls` is currently enabled in the debian package. In the
    future we recommend disabling for validators and enabling it for RPC and archive nodes.
  * This allows voting validators to opt out of computing traces since they're only need for
    RPC nodes.

#### Notable internal changes

* **\[Consensus]** TC forwarding to prioritized and public (non-dedicated) full nodes
  * Ref: [monad-bft PR #2149](https://github.com/category-labs/monad-bft/pull/2149)
  * Prior to `v0.10.4`, all full nodes were subject to lagging behind validators in the event of a
    timeout because round advancement due to TC was not forwarded (and still isn’t to dedicated full
    nodes).
  * As a result, after timeouts, full nodes would frequently forward transactions to the
    next three leaders relative to a stale state. This results in those transactions often missing
    and the ensuing blocks being comparatively empty.
* **\[Node ops]** Bugfix for secondary raptorcast (round gap crash) that affected validators in
  Publisher mode
  * Ref: [monad-bft PR #2090](https://github.com/category-labs/monad-bft/pull/2090)
* **\[Node ops]** `ledger-tail` improvements
  * Ref: [monad-bft PR #2144](https://github.com/category-labs/monad-bft/pull/2144)
  - Reduced memory usage on startup
  - `author_dns` field changed to `author_address` to reflect change in v10 addresses
  - Timeouts and finalizations are tracked and logged
* **\[Consensus]** Txpool account preloading bugfix
  * Ref: [monad-bft PR #2108](https://github.com/category-labs/monad-bft/pull/2108)

## v0.10.3

[`MONAD_THREE`](/developer-essentials/changelog#revisions) revision introduced.

| Network                                             | Date deployed | Comment                                        |
| --------------------------------------------------- | ------------- | ---------------------------------------------- |
| [`testnet`](/developer-essentials/testnets#testnet) | 2025-08-12    | Revision is set to `MONAD_THREE` when upgraded |

#### Notable protocol changes - `MONAD_THREE`

* **\[Consensus]** Consensus mechanism upgraded from [Fast-HotStuff](https://arxiv.org/abs/2010.11454)
  to [MonadBFT](/monad-arch/consensus/monad-bft)
  * This is a major upgrade that adds
    *(i)* [resilience to tail forking](/monad-arch/consensus/monad-bft#no-tail-forking) and
    *(ii)* [1-slot speculative finality](/monad-arch/consensus/monad-bft#speculative-finality)
* **\[Network params]** Block time reduced from 500 ms to **400 ms**

#### Notable RPC/SDK changes

* **\[RPC]** Add support for [real-time data](/monad-arch/realtime-data) via
  [WebSocket](/reference/websockets) and shared memory queue access (docs coming soon):
  * Geth real-time events (via WebSocket)
  * Geth real-time events with Monad extensions (via WebSocket)
  * Real-time data via shared memory queue, for programs on a full node host using the execution event SDK

#### Notable performance changes

* **\[Execution]** Switch to JIT EVM. The bytecode of expensive or frequently-executed contracts is
  compiled directly to native code for faster execution
* **\[Execution]** Switch to using file pointer-based IPC to execute blocks. Previously, the client
  was using a write-ahead log (WAL), which did not take advantage of available consensus
  information and could result in avoidable execution

#### Notable internal changes

* **\[Node ops]** Adds peer discovery
* **\[Node ops]** Adds full node [RaptorCast](/monad-arch/consensus/raptorcast), making the full
  node network scalable

## v0.9.3

| Network                                             | Date deployed | Comment                       |
| --------------------------------------------------- | ------------- | ----------------------------- |
| [`testnet`](/developer-essentials/testnets#testnet) | 2025-05-29    | Revision is still `MONAD_TWO` |

#### Notable RPC/SDK changes

* **\[RPC]** `eth_call` and `eth_estimateGas` limits
  * RPC providers can now set individual per-transaction limits on maximum gas for `eth_call` and
    `eth_estimateGas`
    * Previously the limit would always be the block gas limit (150M), now the RPC provider may
      choose (default: 30M)
    * Controlled with `--eth-call-provider-gas-limit` and `--eth-estimate-gas-provider-gas-limit`
  * Add a maximum timeout for queueing when executing `eth_call` and `eth_estimateGas`
    * Controlled with `--eth_call_executor_queuing_timeout`

#### Notable performance changes

* **\[RPC]** Improve overall `eth_call` performance by maintaining separate queues for cheap and
  expensive `eth_call` operations, so that cheap `eth_call` operations will not be queued behind expensive ones.
  * This adds two new RPC error strings:
    * `failure to submit eth_call to thread pool: queue size exceeded`
    * `failure to execute eth_call: queuing time exceeded timeout threshold`
* **\[RPC]**  Added an archive index for `eth_getLogs` to support queries with address and/or topic
  filters
  * This enables larger block ranges to be queried efficiently, with work proportional to number
    of matching logs instead of number of blocks in range
* **\[Execution]** Better bounding of TrieDB traversals

#### Notable internal changes

* **\[Node ops]**  Performance improvements for slow statesync client upsert
* **\[Node ops]**  Bugfix for execution delay and abrupt history length drops caused by premature
  soft reset
* **\[Node ops]**  `keystore` QOL improvements
  * Support for importing from a private key in hex string format (previously required conversion
    to json file)
  * More helpful documentation via `--help` command

## testnet-1 active set expansion

On 2025-05-02, `testnet-1` experienced an active set expansion

#### Notable internal changes

* **\[Network params]** Testnet validator set expanded from 72 to **99** nodes

## v0.9.2

| Network                                             | Date deployed | Comment                       |
| --------------------------------------------------- | ------------- | ----------------------------- |
| [`testnet`](/developer-essentials/testnets#testnet) | 2025-04-05    | Revision is still `MONAD_TWO` |

#### Notable performance changes

* **\[RPC]** Update to the `eth_call` execution implementation - uses fewer threads to achieve the
  same concurrency as in `v0.9.1`

#### Notable internal changes

* **\[Node ops]** Support for a faster [statesync](/monad-arch/consensus/statesync) mechanism
* **\[RPC]** RPC no longer accepts requests while node is statesyncing
* **\[Node ops]** Some reliability and efficiency improvements to how statesync traffic is carried
  between nodes
* **\[Node ops]** Bugfixes for execution crashes (`monad::mpt::deserialize_node_from_buffer`,
  `'Resource temporarily unavailable`)

- **\[Node ops]** Bug fix for unbounded blocksync requests that result in node OOM failures
- **\[Node ops]** Removal of DNS resolution panic on start up

## v0.9.1

| Network                                             | Date deployed | Comment                        |
| --------------------------------------------------- | ------------- | ------------------------------ |
| [`testnet`](/developer-essentials/testnets#testnet) | 2025-03-24    | Revision is set to `MONAD_TWO` |

#### Notable internal changes

* **\[Node ops]** Bugfix for blocksync errors
* **\[Node ops]** Reliability and efficiency improvements to statesync

## v0.9.0

Revision [`MONAD_TWO`](/developer-essentials/changelog#revisions) introduced.

| Network                                             | Date deployed | Comment                                                |
| --------------------------------------------------- | ------------- | ------------------------------------------------------ |
| [`testnet`](/developer-essentials/testnets#testnet) | 2025-03-14    | Revision is set to `MONAD_TWO` at 2025-03-14 19:00 GMT |

#### Notable protocol changes - `MONAD_TWO`

* **\[EVM]** Max contract size increased from 24kb to **128kb**
  * [example 123 kb contract](https://testnet.monadvision.com/address/0x0E820425e07E4a992C661E4B970e13002d6e52B9?tab=Contract)

#### Notable RPC/SDK changes

* **\[RPC]** `debug_traceTransaction` fixes
  * Fixed a bug where, within one transaction, only the first 100 calls were being traced
  * Added `error` and `revertReason` fields to response data

#### Notable performance changes

* **\[Consensus]** Dataplane v2 - simpler and more efficient implementation; small performance
  improvement in broadcast time
* **\[RPC]** Improvements to RPC performance for `eth_call`

- **\[RPC]** Removed redundant sender\_recovery operation on raw transactions received via RPC

#### Notable internal changes

* **\[Node ops]** Statesync improvements to mitigate negative performance effects on upstream
  validator nodes

- **\[RPC]** EIP-2 signature validation added to RPC transaction validation
- **\[Node ops]** Miscellaneous tracing, logging and metrics additions
- **\[Consensus]** RaptorCast performance improvement when dealing with invalid symbols

## v0.8.1

Revision [`MONAD_ONE`](/developer-essentials/changelog#revisions) introduced.

| Network                                             | Date deployed | Comment                                                |
| --------------------------------------------------- | ------------- | ------------------------------------------------------ |
| [`testnet`](/developer-essentials/testnets#testnet) | 2025-02-14    | Revision is set to `MONAD_ONE` at 2025-02-14 19:00 GMT |

#### Notable protocol changes - `MONAD_ONE`

* **\[Network params]** Block time reduced from 1s to **500 ms**

* **\[Network params]** Block gas limit reduced from 300M to **150M** (to keep gas limit consistent)

* **\[EVM]** Transactions are [charged](/developer-essentials/gas-pricing) based on gas limit,
  not gas consumed

#### Notable RPC/SDK changes

* **\[RPC]** UX improvements for [transaction status](/monad-arch/transaction-lifecycle). RPC
  nodes track status of transactions submitted to them in order to provide updates to users.


# Testnet Changelog
Source: https://docs.monad.xyz/developer-essentials/changelog/testnet



This is a curated list of only changes affecting [testnet](/developer-essentials/testnets#testnet).

<Note>
  We group changes into

  * protocol changes (generally requiring a new [Revision](/developer-essentials/changelog#revisions))
    * generally tagged with **\[EVM]**, **\[Consensus]**, or **\[Network params]**
  * RPC/SDK behavioral changes (generally tagged with **\[RPC]**)
  * performance changes
    * tagged based on the nature of the change as **\[EVM]**, **\[Consensus]**, or **\[RPC]**
  * internal/node-ops changes (generally tagged as **\[Node ops]**)
</Note>

## v0.13.1 \[2026-03-16]

Revision: [`MONAD_NINE`](/developer-essentials/changelog#revisions) (unchanged)

Tags or hashes:

* `monad-bft` (consensus): [tag `v0.13.1`](https://github.com/category-labs/monad-bft/releases/tag/v0.13.1) (`7db6cea2`)
* `monad` (execution): [tag `v0.13.1`](https://github.com/category-labs/monad/releases/tag/v0.13.1) (`722cbf5b5`)

> **Note:** This is a patch release based on v0.13.0 to fix State Archive node RPC issues. The monad (execution) tag points to the same commit as v0.13.0.

#### Notable robustness changes

* **\[RPC]** Use latest voted as fallback for last\_proposed
  * Ref: [monad-bft PR #2857](https://github.com/category-labs/monad-bft/pull/2857)
  * Fixes State Archive node RPC returning stale block data when `last_proposed` is unavailable

## v0.13.0 \[2026-03-05]

Revision: [`MONAD_NINE`](/developer-essentials/changelog#revisions) (upgrade; Tuesday, 2026-03-10 at 14:30 GMT)

Tags or hashes:

* `monad-bft` (consensus): [tag `v0.13.0`](https://github.com/category-labs/monad-bft/releases/tag/v0.13.0)
* `monad` (execution): [tag `v0.13.0+1`](https://github.com/category-labs/monad/releases/tag/v0.13.0+1)

> **Note:** The canonical release version is `v0.13.0`. The `+1` build metadata on the monad execution tag indicates a post-release rebuild that includes the reserve balance precompile fallback cost fix ([PR #2109](https://github.com/category-labs/monad/pull/2109)).

#### Highlights

* **RPC: `latest` block tag: `Finalized` -> `Proposed`** — queries with the `latest` block tag now return data from the latest proposed block, reducing query latency for `eth_getBalance`, `eth_call`, and other state queries.
* **RPC: `eth_sendRawTransactionSync`: `Voted` -> `Proposed`** — earlier receipts when using the `eth_sendRawTransactionSync` method.
* **Websocket: `newHeads/logs`: `Finalized` -> `Voted`** — earlier notifications for websocket subscribers to either `newHeads` or `logs`.

#### Notable protocol changes

All updates below are gated by the `MONAD_NINE` revision

* **\[EVM]** [MIP-3](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-3.md): Linear memory implementation
  * Ref: [monad PR #2032](https://github.com/category-labs/monad/pull/2032)
* **\[Execution]** [MIP-4](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-4.md): Reserve balance precompile
  * Ref: [monad PR #2040](https://github.com/category-labs/monad/pull/2040) (scaffolding)
  * Ref: [monad PR #2065](https://github.com/category-labs/monad/pull/2065) (cached/incremental checks)
  * Ref: [monad PR #2086](https://github.com/category-labs/monad/pull/2086) (add dippedIntoReserve)
  * Ref: [monad PR #2106](https://github.com/category-labs/monad/pull/2106) (dippedIntoReserve argument length error)
  * Ref: [monad PR #2109](https://github.com/category-labs/monad/pull/2109) (fallback cost fix for clean spec)
  * Ref: [monad PR #2037](https://github.com/category-labs/monad/pull/2037) (skip reserve checks for init-selfdestruct)
* **\[EVM]** [MIP-5](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-5.md): Activate Osaka fork (CLZ opcode)
  * Ref: [monad PR #2024](https://github.com/category-labs/monad/pull/2024)

> **Hard Fork:** This release activates MONAD\_NINE at timestamp `1773153000` (testnet) / `1773930600` (mainnet). Nodes must upgrade before activation.

#### Notable RPC/SDK changes

* **\[RPC]** Latest blocktag uses proposed blocks
  * Ref: [monad-bft PR #2675](https://github.com/category-labs/monad-bft/pull/2675)
* **\[RPC]** Use voted blocks in websocket notifications
  * Ref: [monad-bft PR #2799](https://github.com/category-labs/monad-bft/pull/2799)
* **\[RPC]** Add experimental flag to RPC doc macro
  * Ref: [monad-bft PR #2773](https://github.com/category-labs/monad-bft/pull/2773)
* **\[RPC]** Refactor RPC middleware for improved request handling
  * Ref: [monad-bft PR #2805](https://github.com/category-labs/monad-bft/pull/2805)
* **\[RPC]** Add decompression guard to RPC
  * Ref: [monad-bft PR #2793](https://github.com/category-labs/monad-bft/pull/2793)

#### Notable robustness changes

* **\[Consensus]** Add signature verifier for Raptorcast
  * Ref: [monad-bft PR #2747](https://github.com/category-labs/monad-bft/pull/2747)
* **\[Consensus]** Fix reactivate logic in r10 decoder
  * Ref: [monad-bft PR #2740](https://github.com/category-labs/monad-bft/pull/2740)
* **\[Execution]** Fix buffer overflow in C->Rust logging
  * Ref: [monad-bft PR #2769](https://github.com/category-labs/monad-bft/pull/2769)
* **\[Consensus]** Add global connect rate limit to wireauth
  * Ref: [monad-bft PR #2765](https://github.com/category-labs/monad-bft/pull/2765)
* **\[Consensus]** Validate ping/pong source address against name record in peer discovery
  * Ref: [monad-bft PR #2752](https://github.com/category-labs/monad-bft/pull/2752)
* **\[Consensus]** Persist voted\_head in ledger
  * Ref: [monad-bft PR #2744](https://github.com/category-labs/monad-bft/pull/2744)
* **\[Consensus]** Add dual UDP packet sender for dataplane
  * Ref: [monad-bft PR #2746](https://github.com/category-labs/monad-bft/pull/2746)
* **\[Execution]** Fix ThreadSanitizer race by joining bootstrap fiber before thread exit
  * Ref: [monad PR #2053](https://github.com/category-labs/monad/pull/2053)
* **\[Execution]** Include account balance in selfdestruct tracer frame
  * Ref: [monad PR #2039](https://github.com/category-labs/monad/pull/2039)
* **\[Consensus]** Ensure proposed head is on canonical chain
  * Ref: [monad-bft PR #2756](https://github.com/category-labs/monad-bft/pull/2756)
* **\[Execution]** Fix sentinel collision in compact virtual chunk offset
  * Ref: [monad PR #2083](https://github.com/category-labs/monad/pull/2083)
* **\[Execution]** Fix potential race condition in execute\_block\_transactions
  * Ref: [monad PR #2092](https://github.com/category-labs/monad/pull/2092)

#### Notable internal changes

* **\[Consensus]** Remove unneeded channels when secondary raptorcast is disabled
  * Ref: [monad-bft PR #2808](https://github.com/category-labs/monad-bft/pull/2808)
* **\[Consensus]** Upgrade alloy to stable release
  * Ref: [monad-bft PR #2792](https://github.com/category-labs/monad-bft/pull/2792)
* **\[Execution]** Add `evm-as` syntactic sugar for VM utilities
  * Ref: [monad PR #2097](https://github.com/category-labs/monad/pull/2097)
* **\[Consensus]** Parametrize wireauth metrics for better observability
  * Ref: [monad-bft PR #2692](https://github.com/category-labs/monad-bft/pull/2692)
* **\[Consensus]** Cleanup block persist implementation
  * Ref: [monad-bft PR #2767](https://github.com/category-labs/monad-bft/pull/2767)
* **\[Consensus]** Fix wip extension in block-persist
  * Ref: [monad-bft PR #2776](https://github.com/category-labs/monad-bft/pull/2776)
* **\[Consensus]** Remove legacy `do_local_insert`
  * Ref: [monad-bft PR #2728](https://github.com/category-labs/monad-bft/pull/2728)
* **\[Consensus]** Add metrics for raptorcast deserialize failures
  * Ref: [monad-bft PR #2789](https://github.com/category-labs/monad-bft/pull/2789)
* **\[RPC]** Reduce RPC event server broadcast channel size
  * Ref: [monad-bft PR #2815](https://github.com/category-labs/monad-bft/pull/2815)
* **\[Consensus]** Pre-TFM base fee cleanup
  * Ref: [monad-bft PR #2664](https://github.com/category-labs/monad-bft/pull/2664)
* **\[Consensus]** Remove pre-TFM reserve balance logic
  * Ref: [monad-bft PR #2622](https://github.com/category-labs/monad-bft/pull/2622)
* **\[RPC]** Simplify hex encoding/decoding in RPC
  * Ref: [monad-bft PR #2806](https://github.com/category-labs/monad-bft/pull/2806)
* **\[Archive]** Add exists(key) to kvstore
  * Ref: [monad-bft PR #2688](https://github.com/category-labs/monad-bft/pull/2688)

## v0.12.7

Revision: [`MONAD_EIGHT`](/developer-essentials/changelog#revisions) (unchanged)

#### Notable RPC/SDK changes

* **\[RPC]** Allow block hash as block identifier in `eth_estimateGas`
  * Ref: [monad-bft PR #2676](https://github.com/category-labs/monad-bft/pull/2676)
* **\[RPC]** Use `RawValue` for RPC id to preserve original JSON types
  * Reduces effectiveness of DoS attacks using large JSON arrays/dicts in request IDs
  * Ref: [monad-bft PR #2455](https://github.com/category-labs/monad-bft/pull/2455)

#### Notable robustness changes

* **\[Consensus]** Remove consecutive sequence number assertion
  * Ref: [monad-bft PR #2704](https://github.com/category-labs/monad-bft/pull/2704)
* **\[Consensus]** Improve liveness when advancing round using TC from timeout messages
  * Ref: [monad-bft PR #2701](https://github.com/category-labs/monad-bft/pull/2701)
* **\[Consensus]** Disallow creating an empty validator set
  * Ref: [monad-bft PR #2682](https://github.com/category-labs/monad-bft/pull/2682)

#### Notable internal changes

* **\[Consensus]** Add security tests for `secp256k1`
  * Adds Wycheproof tests, malleability tests, and security unit tests
  * Ref: [monad-bft PR #2706](https://github.com/category-labs/monad-bft/pull/2706)
* **\[Node ops]** Update `rkyv` and other dependencies
  * Ref: [monad-bft PR #2702](https://github.com/category-labs/monad-bft/pull/2702)
* **\[Consensus]** Return bound socket addresses synchronously in dataplane
  * Ref: [monad-bft PR #2653](https://github.com/category-labs/monad-bft/pull/2653)
* **\[Consensus]** Rename state backend cache for clarity
  * Ref: [monad-bft PR #2699](https://github.com/category-labs/monad-bft/pull/2699)

## v0.12.6 \[2026-01-07]

Revision: [`MONAD_EIGHT`](/developer-essentials/changelog#revisions) (unchanged)

Tags or hashes:

* `monad-bft`: [tag `v0.12.6`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.6)
* `monad`: [tag `v0.12.6`](https://github.com/category-labs/monad/releases/tag/v0.12.6)

#### Notable RPC/SDK changes

* **\[RPC]** Fix depth bug in selfdestructing call frames
  * Ref: [monad PR #1977](https://github.com/category-labs/monad/pull/1977)
* **\[RPC]** Prestate tracer conformance fixes
  * Ref: [monad PR #1946](https://github.com/category-labs/monad/pull/1946)

#### Notable robustness changes

* **\[Consensus]** Add signature verification rate limiting with authenticated peer bypass
  * Ref: [monad-bft PR #2601](https://github.com/category-labs/monad-bft/pull/2601)
* **\[Consensus]** Validate confirm group message before updating peers
  * Ref: [monad-bft PR #2680](https://github.com/category-labs/monad-bft/pull/2680)
* **\[Consensus]** Use Tai64N directly for wireauth timestamp comparison
  * Ref: [monad-bft PR #2678](https://github.com/category-labs/monad-bft/pull/2678)
* **\[Consensus]** Improve RaptorCast decoding cache eviction
  * Ref: [monad-bft PR #2651](https://github.com/category-labs/monad-bft/pull/2651)
* **\[Consensus]** Fix blocksync in-flight request tracking on cache hydration
  * Ref: [monad-bft PR #2635](https://github.com/category-labs/monad-bft/pull/2635)
* **\[Execution]** Update triedb voted metadata before executing proposal
  * Solves a race condition between Voted updates through websocket and corresponding JSON-RPC calls
  * Ref: [monad PR #1964](https://github.com/category-labs/monad/pull/1964)
* **\[Node ops]** Persist peers periodically for improved discovery resilience
  * Ref: [monad-bft PR #2633](https://github.com/category-labs/monad-bft/pull/2633)

#### Notable performance changes

* **\[Consensus]** Boost dataplane throughput with ring buffer implementation
  * Ref: [monad-bft PR #2596](https://github.com/category-labs/monad-bft/pull/2596)
* **\[Execution]** Native implementation for `MLOAD`, `MSTORE`, `MSTORE8`, `CALLDATALOAD` opcodes
  * Ref: [monad PR #1963](https://github.com/category-labs/monad/pull/1963)
* **\[Execution]** Improve snapshot write performance
  * Ref: [monad PR #1973](https://github.com/category-labs/monad/pull/1973), [monad PR #1960](https://github.com/category-labs/monad/pull/1960)
* **\[Execution]** Optimize database history length adjustment with binary search
  * Ref: [monad PR #1922](https://github.com/category-labs/monad/pull/1922)
* **\[Execution]** Unify single buffer and scatter read handling in AsyncIO
  * Ref: [monad PR #1944](https://github.com/category-labs/monad/pull/1944)

#### Notable internal changes

* **\[Node ops]** Docker single-node container updates for prebuilt images
  * Fixes to [Local Docker installation](https://github.com/category-labs/monad-bft/blob/master/README.md#using-pre-built-images)
  * Ref: [monad-bft PR #2674](https://github.com/category-labs/monad-bft/pull/2674)
* **\[Consensus]** Add support for generic txpool sidecars
  * Enables IPC transaction priority and forwarding controls
  * Ref: [monad-bft PR #2557](https://github.com/category-labs/monad-bft/pull/2557)
* **\[EVM]** Osaka fork preparation
  * Modexp gas changes and upper bound (EIP-7823/EIP-7883)
  * Implement `CLZ` opcode
    * Ref: [monad PR #1970](https://github.com/category-labs/monad/pull/1970), [monad PR #1981](https://github.com/category-labs/monad/pull/1981)
* **\[Node ops]** Accept `--hyphen-style` long options in CLI
  * Ref: [monad PR #2005](https://github.com/category-labs/monad/pull/2005)
* **\[Node ops / Archive]** Archive pipeline improvements
  * Add `WritePolicy` to `KVStore` for conditional write protection (`NoClobber`)
  * Add BFT-uploading stats logging
  * Ref: [monad-bft PR #2649](https://github.com/category-labs/monad-bft/pull/2649), [monad-bft PR #2661](https://github.com/category-labs/monad-bft/pull/2661)
* **\[Node ops]** Simplify RPC txpool status tracking
  * Ref: [monad-bft PR #2644](https://github.com/category-labs/monad-bft/pull/2644)
* **\[Node ops]** Snapshot tooling improvements in `monad_cli`
  * Add `--dump_concurrency_limit` parameter
  * Add sharding support for distributed snapshot creation
  * Ref: [monad PR #1967](https://github.com/category-labs/monad/pull/1967), [monad PR #1965](https://github.com/category-labs/monad/pull/1965)
* **\[Node ops]** Add RaptorCast decoding cache metrics
  * Ref: [monad-bft PR #2667](https://github.com/category-labs/monad-bft/pull/2667)
* **\[Execution]** Add `CommitBuilder` API to execution database
  * Ref: [monad PR #1968](https://github.com/category-labs/monad/pull/1968)
* **\[Execution]** Remove legacy `using_chunks_for_root_offsets` metadata field
  * Ref: [monad PR #1943](https://github.com/category-labs/monad/pull/1943)
* **\[Node ops / Txgen]** Add ERC-4337 + EIP-7702 generator (`erc4337_7702_bundled`)
  * Ref: [monad-bft PR #2628](https://github.com/category-labs/monad-bft/pull/2628)
* **\[Node ops]** Add systemd service scripts for `blockcapd` and execution events archivers
  * Ref: [monad-bft PR #2590](https://github.com/category-labs/monad-bft/pull/2590)
* **\[SDK]** Add `monad_event_resolve_ring_file` API
  * Ref: [monad PR #1741](https://github.com/category-labs/monad/pull/1741)
* **\[Execution]** Enable VM host exception handling outside VM
  * Ref: [monad PR #1990](https://github.com/category-labs/monad/pull/1990)

## v0.12.5 \[2025-12-16]

Revision: [`MONAD_EIGHT`](/developer-essentials/changelog#revisions) (unchanged)

Tags or hashes:

* `monad-bft`: [tag `v0.12.5`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.5)
* `monad`: [tag `v0.12.5`](https://github.com/category-labs/monad/releases/tag/v0.12.5)

#### Notable network changes

* **\[Network reset]** `testnet` reset from genesis starting from `MONAD_EIGHT`
  * Increases total supply to 100 B, consistent with `mainnet`
  * Clears a path to eliminate dead code (revisions required for early `testnet`)
  * Ref: [monad PR #1983](https://github.com/category-labs/monad/pull/1983), [monad-bft PR #2673](https://github.com/category-labs/monad-bft/pull/2673)

<Warning title="Testnet Reset">
  `testnet` has been reset from genesis as of `2025-12-16` (`v0.12.5`). The changelog below this point (pre-`v0.12.5`) is preserved for posterity.
</Warning>

## v0.12.4 \[2025-12-05]

Revision: [`MONAD_EIGHT`](/developer-essentials/changelog#revisions) (unchanged)

Tags or hashes:

* `monad-bft`: [tag `v0.12.4`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.4)
* `monad`: [tag `v0.12.4`](https://github.com/category-labs/monad/releases/tag/v0.12.4) *(unchanged from v0.12.3)*

#### Notable internal changes

* **\[Node ops]** Fix peer discovery port configuration when constructing self name record
  * Use port from peer discovery config instead of bound socket when constructing self name record.
    This bug affected node operators using a NAT.
  * Ref: [monad-bft PR #2655](https://github.com/category-labs/monad-bft/pull/2655)

## v0.12.3 \[2025-12-04]

Revision: [`MONAD_EIGHT`](/developer-essentials/changelog#revisions) (unchanged)

Tags or hashes:

* `monad-bft`: [tag `v0.12.3-rc.2`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.3-rc.2)
* `monad`: [tag `v0.12.3-rc.2`](https://github.com/category-labs/monad/releases/tag/v0.12.3-rc.2)

#### Notable RPC/SDK changes

* **\[RPC]** [EIP-7966](https://eips.ethereum.org/EIPS/eip-7966) (`eth_sendRawTransactionSync`) support
  * Ref: [monad-bft PR #2542](https://github.com/category-labs/monad-bft/pull/2542)
* **\[RPC]** Populate `value` field on traces for staking precompile syscalls (added in `0.12.3-rpc-hotfix2`)
  * Ref: [monad PR #1938](https://github.com/category-labs/monad/pull/1938)

#### Notable robustness changes

* **\[Consensus]** Wire authentication protocol for UDP
  * Adds authenticated UDP communication to improve network security
  * Includes replay window adjustments for improved reliability
  * Ref: [monad-bft PR #2417](https://github.com/category-labs/monad-bft/pull/2417), [monad-bft PR #2544](https://github.com/category-labs/monad-bft/pull/2544), [monad-bft PR #2626](https://github.com/category-labs/monad-bft/pull/2626), [monad-bft PR #2091](https://github.com/category-labs/monad-bft/pull/2091)
* **\[Execution]** Improve `statesync` shutdown and fix protocol corruption
  * Modified `statesync_server_recv()` to guarantee complete reads
  * Ref: [monad PR #1930](https://github.com/category-labs/monad/pull/1930)
* **\[RPC]** Prevent reserve balance crash in RPC
  * Add reserve balance violation error messages in call frames
  * Ref: [monad PR #1932](https://github.com/category-labs/monad/pull/1932), [monad-bft PR #2629](https://github.com/category-labs/monad-bft/pull/2629)
  * This was already previously released in `v0.12.2-rpc-hotfix`
* **\[Consensus]** Add timeout to `txpool` IPC stream
  * Prevents hanging connections in transaction pool communication
  * Ref: [monad-bft PR #2619](https://github.com/category-labs/monad-bft/pull/2619)
* **\[Consensus]** Reject timeout certificates with empty signers
  * Adds validation to prevent malformed timeout certificates
  * Ref: [monad-bft PR #2630](https://github.com/category-labs/monad-bft/pull/2630)
* **\[Consensus]** Verify RaptorCast chunk length is non-zero
  * Adds validation to prevent malformed RaptorCast chunks
  * Ref: [monad-bft PR #2638](https://github.com/category-labs/monad-bft/pull/2638)
* **\[Execution]** Fix MPT restore bug that failed to preserve `version_lower_bound`
  * Ref: [monad PR #1955](https://github.com/category-labs/monad/pull/1955)
* **\[Execution]** Fix move trie version forward bug
  * Erase versions that fall out of history range before moving forward to newer versions
  * Ref: [monad PR #1957](https://github.com/category-labs/monad/pull/1957)
* **\[Execution]** Fix dangling pointers to intercode
  * Resolves memory safety issue with `get_code` and `read_code` functions
  * Ref: [monad PR #1941](https://github.com/category-labs/monad/pull/1941)
* **\[Execution]** Add retries to `runloop_monad_ethblocks`
  * Ref: [monad PR #1953](https://github.com/category-labs/monad/pull/1953)

#### Notable performance changes

* **\[RPC]** Improve `eth_getLogs` performance
  * Reduce memory copies and unify receipt-to-logs processing
  * Ref: [monad-bft PR #2588](https://github.com/category-labs/monad-bft/pull/2588), [monad-bft PR #2591](https://github.com/category-labs/monad-bft/pull/2591), [monad-bft PR #2631](https://github.com/category-labs/monad-bft/pull/2631)
* **\[Execution]** Fiber: add support for move-only functors
  * Improves execution efficiency by supporting move semantics
  * Ref: [monad PR #1936](https://github.com/category-labs/monad/pull/1936)

#### Notable internal changes

* **\[RPC / Node ops]** Allow RPC to run without `monad-bft`
  * Enables standalone RPC operation for improved deployment flexibility
  * Ref: [monad-bft PR #2613](https://github.com/category-labs/monad-bft/pull/2613)
* **\[Node ops]** Add `--root-offsets-chunk-count` flag to `monad-mpt` to configure the number of chunks allocated for root offsets
  * Each chunk holds approximately 16.5M blocks. Previously, all nodes were hardcoded to use 2 chunks (max TrieDB capacity of \~33M blocks)
  * New default: 16 **must be a power of 2**
  * Note that the default value of 16 translates to approximately 268M blocks \~ 1240 days. In most cases the limiting factor is disk capacity which will auto-compact when filled to 80%
  * Ref: [monad PR #1937](https://github.com/category-labs/monad/pull/1937)
* **\[Node ops]** Peer discovery improvements
  * Full nodes periodically pull validator name records for dynamic validator discovery
  * Add authenticated UDP port to name record
  * Ref: [monad-bft PR #2607](https://github.com/category-labs/monad-bft/pull/2607), [monad-bft PR #2538](https://github.com/category-labs/monad-bft/pull/2538)
* **\[Node ops / Archive]** Archive infrastructure improvements
  * Refactor `monad-block-writer` for improved reliability with `--max-blocks-per-iter` configuration
  * Async backfill with traces-only archive support
  * Add `require-traces` archiver flag and indexer fallback source
  * Support for historical execution event archiving with generic directory archiving
  * **Potentially breaking: Remove `--start-block` from `monad-archiver` systemd service; operators must use imperative CLI to set start block**
    * Example: `monad-archiver set-start-block --block 1000000 --archive-sink s3://bucket-name/path`
    * Use `--async-backfill` flag to set the async-backfill marker instead of primary marker
  * Ref: [monad-bft PR #2610](https://github.com/category-labs/monad-bft/pull/2610), [monad-bft PR #2606](https://github.com/category-labs/monad-bft/pull/2606), [monad-bft PR #2598](https://github.com/category-labs/monad-bft/pull/2598), [monad-bft PR #2514](https://github.com/category-labs/monad-bft/pull/2514), [monad-bft PR #2612](https://github.com/category-labs/monad-bft/pull/2612), [monad-bft PR #2569](https://github.com/category-labs/monad-bft/pull/2569), [monad-bft PR #2623](https://github.com/category-labs/monad-bft/pull/2623)
* **\[Node ops]** Networking configuration updates
  * Use default MTU 1500
  * Add HDR histogram for broadcast latency tracking in `monad-executor` and `monad-raptorcast`
  * Ref: [monad-bft PR #2576](https://github.com/category-labs/monad-bft/pull/2576), [monad-bft PR #2602](https://github.com/category-labs/monad-bft/pull/2602)
* **\[Consensus]** RaptorCast improvements
  * Clear histogram every 30s and keep only p99 for better latency tracking
  * Fix timer update after receiving control messages to ensure proper keepalives
  * Ref: [monad-bft PR #2627](https://github.com/category-labs/monad-bft/pull/2627), [monad-bft PR #2637](https://github.com/category-labs/monad-bft/pull/2637)
* **\[Consensus]** Dataplane: refactor to use socket handles
  * Prepares dataplane for future extension with authenticated sockets
  * Ref: [monad-bft PR #2458](https://github.com/category-labs/monad-bft/pull/2458)
* **\[Execution]** Replay monad: always execute first block off latest finalized state
  * Ref: [monad PR #1927](https://github.com/category-labs/monad/pull/1927)
* **\[Node ops]** Txgen improvements: README and guide, nonce gaps and legacy tx options, ERC20 pools, Uniswap v3 mode, NFT sale mode, websocket and RPC request generation
  * Ref: [monad-bft PR #2568](https://github.com/category-labs/monad-bft/pull/2568), [monad-bft PR #2567](https://github.com/category-labs/monad-bft/pull/2567), [monad-bft PR #2577](https://github.com/category-labs/monad-bft/pull/2577), [monad-bft PR #2600](https://github.com/category-labs/monad-bft/pull/2600), [monad-bft PR #2527](https://github.com/category-labs/monad-bft/pull/2527), [monad-bft PR #2394](https://github.com/category-labs/monad-bft/pull/2394), [monad-bft PR #2608](https://github.com/category-labs/monad-bft/pull/2608)

## v0.12.2 \[2025-11-18]

Revision: [`MONAD_EIGHT`](/developer-essentials/changelog#revisions) (upgrade; Wednesday, 2025-11-19 at 14:30 GMT)

Tags or hashes:

* `monad-bft`: [tag `v0.12.2-rc`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.2-rc)
* `monad`: [tag `v0.12.2-rc`](https://github.com/category-labs/monad/releases/tag/v0.12.2-rc)

#### Notable protocol changes

All updates below are gated by the `MONAD_EIGHT` revision

* **\[Execution]** Reserve balance checks now use the final state code hash. This makes checks
  slightly more liberal (less likely to revert transactions during execution), and also makes the
  implementation closer to the
  [Coq model](https://category-labs.github.io/category-research/reserve-balance-coq-proofs/monad.proofs.reservebal.html#execValidatedTx)
  that was proven correct under some assumptions.
  * This changes the behavior of the following corner case:
    * In transaction 1, account X is sent a small amount of MON (e.g. 5 MON)
    * Then (much later) in transaction 2, someone both deploys a smart contract wallet at account
      X and sends MON out of that smart contract.
    * Previously, transaction 2's execution would treat account X as an EOA and apply reserve
      balance checks on it, thus reverting the transaction because it would be a dipping
      transaction that was not pre-authorized by consensus.
    * After this change, account X will be treated as a smart contract account and
      will be omitted from reserve balance checks.
    * Note that smart contract addresses are deterministic, making it effectively impossible for
      an address that receives a code deployment to also be an EOA (i.e. to correspond to a
      private key).
  * Ref: [monad PR #1916](https://github.com/category-labs/monad/pull/1916),
    [monad PR #1917](https://github.com/category-labs/monad/pull/1917)
* **\[EVM]** Reduce pagination on staking precompile inverse mappings from 100 to 50
  * Applies to `precompile_get_delegations()` and `precompile_get_delegators()`
  * Ref: [monad PR #1920](https://github.com/category-labs/monad/pull/1920)

#### Notable deployment changes

* **\[SDK]** Execution events no longer require a special "preview" release to enable all EVM notifications (there are no more `--exec-events` special versions)
* **\[SDK]** Fix race condition in event ring create
  * Ref: [monad PR #1914](https://github.com/category-labs/monad/pull/1914)

#### Notable robustness changes

* **\[RPC]** Fix `eth_feeHistory`
  * Ref: [monad-bft PR #2366](https://github.com/category-labs/monad-bft/pull/2366)
* **\[Consensus]** Update transaction classification logic to apply emptying before delegation
  * Improves delegation ordering in `try_apply_block_fees`
  * Ref: [monad-bft PR #2561](https://github.com/category-labs/monad-bft/pull/2561)
* **\[RPC]** Check reserve balance in `eth_call`
  * Prevent simulated transactions from violating reserve balance
  * Call `revert_transaction` in `eth_call` implementation
  * Ref: [monad PR #1912](https://github.com/category-labs/monad/pull/1912)
* **\[Execution]** Failsafe sanity checks for reward system transactions
  * Ref: [monad PR #1921](https://github.com/category-labs/monad/pull/1921)
* **\[Node ops]** Fix remotely fetched `forkpoint.toml` write format
  * Ensures forkpoint files are written in the correct format when fetched from remote sources
  * Ref: [monad-bft PR #2554](https://github.com/category-labs/monad-bft/pull/2554)
* **\[Node ops]** Fix `monad-keystore` key corruption issue
  * `to_bls` and `to_secp` now consume secret to prevent corrupted keystore files
  * Add tests for command line keystore app to verify all flags combinations work correctly
  * Ref: [monad-bft PR #2553](https://github.com/category-labs/monad-bft/pull/2553)
* **\[Execution]** Fix bad write offset in `storage_pool` `try_trim_contents()` when bytes to start TRIM is not a multiple of disk page size
  * Ref: [monad PR #1908](https://github.com/category-labs/monad/pull/1908)
* **\[RPC]** Use txpool bridge channel size for ratelimiting
  * Prevents `try_send` method from failing by using channel capacity for `eth_sendRawTransaction` ratelimiting
  * Ref: [monad-bft PR #2506](https://github.com/category-labs/monad-bft/pull/2506)
* **\[Consensus]** Improve RaptorCast message validation
  * Add sanity check for `chunk_id` range in message parsing
  * Reject overflowing `merkle_leaf_idx` in merkle proof construction
  * Update calculation of `encoded_symbol_capacity` in decoder
  * Ref: [monad-bft PR #2541](https://github.com/category-labs/monad-bft/pull/2541)
* **\[Consensus]** Improve RaptorCast group invite response checks
  * Add sanity check to prevent processing group invite accept after reject from same full node
  * Ref: [monad-bft PR #2574](https://github.com/category-labs/monad-bft/pull/2574)
* **\[Consensus]** Update txpool insertion policy - make balance check stricter
  * Ref: [monad-bft PR #2575](https://github.com/category-labs/monad-bft/pull/2575)

#### Notable performance changes

* **\[Consensus]** Add dataplane warnings when priority queues are overrun
  * Sets total priority queue capacity to 100MB per priority queue (200MB total max)
  * Messages will be dropped with warnings logged if capacity is exceeded
  * Ref: [monad-bft PR #2559](https://github.com/category-labs/monad-bft/pull/2559)
* **\[Execution / Node ops]** Remove read-only database `io_uring` SQ poll thread
  * **IMPORTANT**: Operators with `monad-execution` systemctl overrides should make the appropriate changes to eliminate the `--ro_sq_thread_cpu` parameter as demonstrated in [monad-bft PR #2558](https://github.com/category-labs/monad-bft/pull/2558). Overrides are commonly set when running an RPC or archive node with `--trace_calls` enabled.
  * Reduces thread contention during statesync, improving block execution performance
  * Make `ro_sq_thread_cpu` argument optional, remove from default configuration
  * Ref: [monad PR #1911](https://github.com/category-labs/monad/pull/1911), [monad-bft PR #2558](https://github.com/category-labs/monad-bft/pull/2558)
* **\[RPC]** Move recover authority logic inside submitted lambda for `eth_call`
  * Avoid blocking on fiber promises when called from rust thread, preventing performance issues
  * Replace parallelization with single call to `recover_authority()` since `eth_call` transactions have single authority
  * Ref: [monad PR #1827](https://github.com/category-labs/monad/pull/1827)
* **\[Execution]** Remove `iopoll` support
  * Ref: [monad PR #1910](https://github.com/category-labs/monad/pull/1910)

#### Notable internal changes

* **\[Node ops]** Add `monad-version` crate for git version info in binaries
  * Ref: [monad-bft PR #2572](https://github.com/category-labs/monad-bft/pull/2572)
* **\[Node ops]** Add CLI argument for number of fibers in trace transaction execution pool (default: 100)
  * Ref: [monad-bft PR #2584](https://github.com/category-labs/monad-bft/pull/2584)
* **\[Node ops]** Update block reward for mainnet
  * Ref: [monad-bft PR #2582](https://github.com/category-labs/monad-bft/pull/2582)
* **\[Node ops]** Add block writer binary for testing and debugging
  * Ref: [monad-bft PR #2546](https://github.com/category-labs/monad-bft/pull/2546)
* **\[Node ops]** Make cruft timer retention configurable
  * Add environment variable support for artifact retention times (override in `/home/monad/.env`)
  * Ref: [monad-bft PR #2548](https://github.com/category-labs/monad-bft/pull/2548)
* **\[Node ops]** Add warning when restoring from snapshot (hard reset) is required
  * Prompt node operator when local tip is behind by `STATESYNC_BLOCK_THRESHOLD`
  * Ref: [monad-bft PR #2581](https://github.com/category-labs/monad-bft/pull/2581)
* **\[Node ops]** Update `monad-cruft` permissions to monad user
  * Ref: [monad-bft PR #2556](https://github.com/category-labs/monad-bft/pull/2556)
* **\[Node ops]** Fix txpool metrics recording for transaction replacements
  * Ref: [monad-bft PR #2564](https://github.com/category-labs/monad-bft/pull/2564)
* **\[RPC]** Operator can configure RPC worker threads
  * Ref: [monad-bft PR #2562](https://github.com/category-labs/monad-bft/pull/2562)
* **\[Archive]** Add TOML config file support instead of CLI-only configuration
  * Enables `monad-archiver` binary to use `--config` flag for configuration
  * CLI arguments continue to work and take precedence over config file values
  * Ref: [monad-bft PR #2570](https://github.com/category-labs/monad-bft/pull/2570)
* **\[Node ops]** Add random mutations to `txgen` for improved testing
  * Ref: [monad-bft PR #2543](https://github.com/category-labs/monad-bft/pull/2543)
* **\[Node ops]** Add reserve balance coherency tests
  * Ref: [monad-bft PR #2573](https://github.com/category-labs/monad-bft/pull/2573)
* **\[SDK]** Record execution events
  * Includes state access and system transactions
  * Ref: [monad PR #1906](https://github.com/category-labs/monad/pull/1906), [monad PR #1907](https://github.com/category-labs/monad/pull/1907), [monad PR #1913](https://github.com/category-labs/monad/pull/1913)
* **\[SDK]** Explicitly clear flow info that doesn't apply to certain event types
  * Prevents poorly written event clients from reading invalid data
  * Ref: [monad PR #1919](https://github.com/category-labs/monad/pull/1919)
* **\[Execution]** Improve assertion messages with `MONAD_ASSERT_PRINTF`
  * Ref: [monad PR #1918](https://github.com/category-labs/monad/pull/1918)
* **\[Node ops]** Add statesync server metrics
  * Add `SyncDone` metric to track successes and failures
  * Add request timing metric for statesync server
  * Ref: [monad-bft PR #2555](https://github.com/category-labs/monad-bft/pull/2555)
* **\[Node ops]** Disambiguate triedb error logs
  * Improve error message clarity by making each log call unique
  * Ref: [monad-bft PR #2579](https://github.com/category-labs/monad-bft/pull/2579)
* **\[Node ops]** Update devnet chain configs
  * Shorten default devnet epoch length from 50,000 blocks to 10,000 blocks and epoch start delay from 5,000 rounds to 1,000 rounds
  * Ref: [monad-bft PR #2578](https://github.com/category-labs/monad-bft/pull/2578)
* **\[Node ops]** Update test infrastructure
  * Switch `test_state` and `precompiles_test` tests to `TraitsTest`
  * Add `runloop_monad_ethblocks` to CLI for Monad EVM block replay
  * Ref: [monad PR #1905](https://github.com/category-labs/monad/pull/1905), [monad PR #1894](https://github.com/category-labs/monad/pull/1894)
* **\[Execution]** Remove unused cross-thread pipe messaging infrastructure
  * Ref: [monad PR #1915](https://github.com/category-labs/monad/pull/1915)
* **\[Node ops]** Keep manytrace agent alive in node state
  * Ref: [monad-bft PR #2583](https://github.com/category-labs/monad-bft/pull/2583)
* **\[Node ops]** Update keystore documentation
  * Ref: [monad-bft PR #2380](https://github.com/category-labs/monad-bft/pull/2380)
* **\[Node ops]** Add more logging for block validation errors
  * Ref: [monad-bft PR #2550](https://github.com/category-labs/monad-bft/pull/2550)
* **\[Node ops]** Log round leader when processing certificates
  * Ref: [monad-bft PR #2580](https://github.com/category-labs/monad-bft/pull/2580)

## v0.12.1 \[2025-11-12]

Revision: [`MONAD_SEVEN`](/developer-essentials/changelog#revisions) (unchanged)

Tags or hashes:

* `monad-bft`: [tag `v0.12.1`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.1)
* `monad`: [tag `v0.12.1`](https://github.com/category-labs/monad/releases/tag/v0.12.1)

#### Notable RPC/SDK changes

* **\[RPC]** Support for prestate and statediff tracing for the following RPC endpoints:
  * `debug_traceTransaction`
  * `debug_traceBlockByNumber`
  * `debug_traceBlockByHash`
  * Ref: [monad PR #1753](https://github.com/category-labs/monad/pull/1753), [monad-bft PR #2403](https://github.com/category-labs/monad-bft/pull/2403)
* **\[RPC]** New endpoint `eth_createAccessList`
  * Ref: [monad PR #1748](https://github.com/category-labs/monad/pull/1748), [monad-bft PR #2519](https://github.com/category-labs/monad-bft/pull/2519)
* **\[RPC]** Fix serialization for `to` address in historical traces
  * Follow on to [monad-bft PR #2516](https://github.com/category-labs/monad-bft/pull/2516) implemented in `v0.12.0` (in a historical context)
  * Ref: [monad-bft PR #2523](https://github.com/category-labs/monad-bft/pull/2523), [monad PR #1861](https://github.com/category-labs/monad/pull/1861)
* **\[RPC]** Remove artificial block height floor for `eth_call` and RPC queries
  * Previously limited queries using `latest` and `safe` block tags to `finalized + 1`, now uses actual latest voted block
  * Ref: [monad-bft PR #2148](https://github.com/category-labs/monad-bft/pull/2148)
* **\[RPC]** Fix RPC errors when requesting traces for call frames that include a self-destructing transaction
  * Ref: [monad PR #1887](https://github.com/category-labs/monad/pull/1887)
* **\[RPC]** Fix inconsistent results being reported when using state overrides in RPC calls
  * Ref: [monad PR #1812](https://github.com/category-labs/monad/pull/1812)
* **\[RPC]** Fix for a possible denial-of-service attack on RPC nodes by overriding balances in the staking contract
  * Ref: [monad PR #1903](https://github.com/category-labs/monad/pull/1903)

#### Notable robustness changes

* **\[Node ops/Consensus]** Validators limit statesync service to validators and whitelisted full nodes
  * Full nodes service all requests
  * Ref: [monad-bft PR #2524](https://github.com/category-labs/monad-bft/pull/2524)
* **\[Consensus]** More intelligent txpool eviction logic
  * Ref: [monad-bft PR #2525](https://github.com/category-labs/monad-bft/pull/2525)
* **\[Consensus]** Start vote pacing timer on startup
  * Ref: [monad-bft PR #2528](https://github.com/category-labs/monad-bft/pull/2528)
* **\[Consensus]** Fix historical logs `selfdestruct` issue
  * Ref: [monad-bft PR #2531](https://github.com/category-labs/monad-bft/pull/2531)
* **\[Consensus]** Graceful handling of gas limit check
  * Ref: [monad-bft PR #2518](https://github.com/category-labs/monad-bft/pull/2518)
* **\[Consensus]** Remove 0-stake validator support
  * Support for 0-stake validators in the validator set was used as a workaround for lack of full-node support in the past and should no longer be supported
  * Ref: [monad-bft PR #2545](https://github.com/category-labs/monad-bft/pull/2545)

#### Notable performance changes

* **\[Consensus]** Bias statesync requests to responsive peers
  * Support dynamic peer expansion/contraction
  * Nodes no longer panic if all peers are pruned (e.g., not whitelisted by any init peers)
  * Ref: [monad-bft PR #2536](https://github.com/category-labs/monad-bft/pull/2536)
* **\[Consensus]** Drop blocksync requests that hit disk after cache hydration (\~7min after startup)
  * Ref: [monad-bft PR #2533](https://github.com/category-labs/monad-bft/pull/2533)
* **\[Consensus]** Dataplane: replace interval with sleep
  * Ref: [monad-bft PR #2517](https://github.com/category-labs/monad-bft/pull/2517)
* **\[Execution]** Replace data structures in `VersionStack` code to improve performance when pushing and popping EVM call frames
  * Ref: [monad PR #1802](https://github.com/category-labs/monad/pull/1802), [monad PR #1877](https://github.com/category-labs/monad/pull/1877)

#### Notable internal changes

* **\[Node ops]** Try fetching remote `forkpoint.toml` and `validators.toml` on startup
  * **IMPORTANT**: Nodes now automatically attempt to download configuration files from remote locations on startup, no "Soft Reset" required. This remote fetch is subject to a configurable remote threshold
  * The following env variables must be set to enable this behavior:
    * `REMOTE_FORKPOINT_URL`
    * `REMOTE_VALIDATORS_URL`
  * Ref: [monad-bft PR #2484](https://github.com/category-labs/monad-bft/pull/2484), [monad-bft PR #2534](https://github.com/category-labs/monad-bft/pull/2534)
* **\[Node ops]** Serialize forkpoints in both TOML and RLP formats, with RLP as source of truth; cleanup `get_latest_config` branches
  * Ref: [monad-bft PR #2521](https://github.com/category-labs/monad-bft/pull/2521)
* **\[Node ops/Consensus]** Dynamically expand statesync upstream peers
  * Always initializes to `statesync.init_peers` (no longer defaults to bootstrap peers)
  * If `expand_to_group` is enabled, expands to validator set (for validators) and/or secondary raptorcast peers (for public / prioritized full nodes)
  * Ref: [monad-bft PR #2535](https://github.com/category-labs/monad-bft/pull/2535)
* **\[Node ops/Consensus]** Full nodes no longer default to blocksync from validator set
  * Dedicated full nodes must specify upstream as blocksync override
  * **IMPORTANT**: prioritized/public full nodes can only blocksync *after* joining secondary raptorcast group. `refresh_period` and `invite_lookahead` recommended to be lowered to 20 seconds
  * Ref: [monad-bft PR #2532](https://github.com/category-labs/monad-bft/pull/2532)
* **\[Consensus]** Use epoch field to encode round number for secondary raptorcast
  * Fixes issue where syncing full nodes receive unsolicited chunks from expired groups
  * Ref: [monad-bft PR #2442](https://github.com/category-labs/monad-bft/pull/2442)
* **\[Consensus]** Add statesync server pending requests metric (better load visibility)
  * Ref: [monad-bft PR #2530](https://github.com/category-labs/monad-bft/pull/2530)
* **\[Node ops]** Import `monad-execution` API changes
  * Ref: [monad-bft PR #2522](https://github.com/category-labs/monad-bft/pull/2522)

## v0.12.0 \[2025-11-04]

Revision: [`MONAD_SEVEN`](/developer-essentials/changelog#revisions) (upgrade; Wednesday, 2025-11-05 at 14:30 GMT)

Tags or hashes:

* `monad-bft`: [tag `v0.12.0`](https://github.com/category-labs/monad-bft/releases/tag/v0.12.0)
* `monad`: [tag `v0.12.0`](https://github.com/category-labs/monad/releases/tag/v0.12.0)

#### Notable protocol changes

* **\[EVM/Network params]** [Opcode/precompile repricing](/developer-essentials/opcode-pricing)
  * Opcode pricing: increase cost of cold storage access
  * Precompile pricing: better align a few underpriced precompile gas costs with the associated hardware / latency costs
  * Ref: [monad PR #1600](https://github.com/category-labs/monad/pull/1600) (for most of the repricings) and [monad PR #1700](https://github.com/category-labs/monad/pull/1700) (for `CREATE`/`CREATE2` repricing), [monad PR #1830](https://github.com/category-labs/monad/pull/1830) (for reduced v2 scope), [monad PR #1871](https://github.com/category-labs/monad/pull/1871) (activation for `MONAD_SEVEN`)
  * Gated by `MONAD_SEVEN` revision
* **\[Consensus/Network params]** \[Staking] Increase `BLOCK_REWARD_MON` from 1 MON to 25 MON
  * Note that this is not gated by `MONAD_SEVEN` (execution hard fork) but by a specific epoch start for `testnet`
  * Ref: [monad-bft PR #2511](https://github.com/category-labs/monad-bft/pull/2511)

#### Notable robustness changes

* **\[Consensus]** Consensus message prioritization in dataplane
  * Priority queues for UDP traffic ensure consensus messages are delivered before other traffic
  * All consensus messages to validators are published and rebroadcast with high priority
  * Ref: [monad-bft PR #2352](https://github.com/category-labs/monad-bft/pull/2352),
    [monad-bft PR #2354](https://github.com/category-labs/monad-bft/pull/2354)
* **\[Consensus]** DoS protection: Reject repeated invalid consensus messages
  * Prevents malicious validators from consuming CPU time by repeatedly sending invalid BLS signatures
  * Ref: [monad-bft PR #2445](https://github.com/category-labs/monad-bft/pull/2445)
* **\[Consensus]** Leader synchronization improvements
  * Forward AdvanceRound messages to current leader to prevent stale views due to message censorship
  * Ref: [monad-bft PR #2485](https://github.com/category-labs/monad-bft/pull/2485)
* **\[Consensus]** Validate group message sender authenticity
  * Ref: [monad-bft PR #2457](https://github.com/category-labs/monad-bft/pull/2457)

#### Notable RPC/SDK changes

* **\[RPC]** Fix `eth_syncing` serialization
  * Ref: [monad-bft PR #2476](https://github.com/category-labs/monad-bft/pull/2476)
* **\[RPC]** Update `debug_getRawReceipts` RLP encoding
  * Ref: [monad-bft PR #2490](https://github.com/category-labs/monad-bft/pull/2490)
* **\[RPC]** Failed contract creation should return null to address
  * Ref: [monad PR #1861](https://github.com/category-labs/monad/pull/1861),
    [monad-bft PR #2516](https://github.com/category-labs/monad-bft/pull/2516)

#### Notable performance changes

* **\[Consensus]** Dataplane: io\_uring batching for UDP sends
  * Replace GSO with io\_uring batching to preserve 64KB burst size while splitting payload
  * Batches multiple UDP sends into single io\_uring submission
  * Ref: [monad-bft PR #2317](https://github.com/category-labs/monad-bft/pull/2317)
* **\[Consensus]** Dataplane: Restore full 1500 byte MTU
  * Ref: [monad-bft PR #2438](https://github.com/category-labs/monad-bft/pull/2438)
* **\[Consensus]** RaptorCast: Modular packet assembly and round-robin ordering
  * Ref: [monad-bft PR #2377](https://github.com/category-labs/monad-bft/pull/2377),
    [monad-bft PR #2469](https://github.com/category-labs/monad-bft/pull/2469),
    [monad-bft PR #2318](https://github.com/category-labs/monad-bft/pull/2318)
* **\[Consensus]** Txpool optimizations
  * Add configurable limits, remove pending pool, refactor last commit state tracking
  * Ref: [monad-bft PR #2487](https://github.com/category-labs/monad-bft/pull/2487),
    [monad-bft PR #2363](https://github.com/category-labs/monad-bft/pull/2363),
    [monad-bft PR #2475](https://github.com/category-labs/monad-bft/pull/2475)
* **\[Archive]** Move indexer read-back to async task
  * Ref: [monad-bft PR #2486](https://github.com/category-labs/monad-bft/pull/2486)
* **\[RPC]** Remove unnecessary lock in request submission path
  * Ref: [monad-bft PR #2416](https://github.com/category-labs/monad-bft/pull/2416)

#### Notable internal changes

* **\[Node ops]** Docker support for local Monad installation
  * Optional `--use-prebuilt` flag to avoid compilation
  * Ref: [monad-bft PR #2456](https://github.com/category-labs/monad-bft/pull/2456),
    [monad-bft PR #2489](https://github.com/category-labs/monad-bft/pull/2489)
* **\[Node ops]** ledger-tail: New CLI configuration options
  * Supports custom paths for ledger, forkpoint, node config, and validators files
  * Fixes default `validators.toml` path
  * Ref: [monad-bft PR #2439](https://github.com/category-labs/monad-bft/pull/2439)
* **\[Node ops]** wal2json: Multi-file support with timestamp filtering
  * Fast timestamp seeking/filtering across multiple files (e.g., `wal2json -a"3:30pm EDT" -b"4:00pm EDT" wal*`)
  * Improved performance with parallel processing and reduced locking
  * Ref: [monad-bft PR #2496](https://github.com/category-labs/monad-bft/pull/2496),
    [monad-bft PR #2493](https://github.com/category-labs/monad-bft/pull/2493)

## v0.11.6 \[2025-10-30]

Revision: [`MONAD_SIX`](/developer-essentials/changelog#revisions) (upgrade; Friday, 2025-10-31 at 13:30 GMT)

Revision: [`MONAD_FIVE`](/developer-essentials/changelog#revisions) (upgrade; Tuesday, 2025-10-28 at 13:30 GMT)

Tags or hashes:

* `monad-bft`: [tag `v0.11.6-tn1`](https://github.com/category-labs/monad-bft/releases/tag/v0.11.6-tn1)
* `monad`: [tag `v0.11.6-tn1`](https://github.com/category-labs/monad/releases/tag/v0.11.6-tn1)

#### Notable protocol changes - `MONAD_SIX`

* **\[EVM]** EIP-2935 bugfix
  * Ref: [monad PR #1846](https://github.com/category-labs/monad/pull/1846)

#### Notable protocol changes - `MONAD_FIVE`

* **\[Consensus/EVM]** \[Staking] Lower `ACTIVE_VALIDATOR_STAKE` from 25,000,000 MON to **10,000,000 MON**
  * Ref: [monad PR #1810](https://github.com/category-labs/monad/pull/1810)
* **\[EVM]** \[Staking] Add `getProposerValId()` method to return the `val_id` of the most recent block proposer
  * Ref: [monad PR #1815](https://github.com/category-labs/monad/pull/1815)

#### Notable RPC/SDK changes

* **\[RPC]** Fix race condition in block number queries
  * Return triedb block number in ChainState to prevent errors when `eth_getBlockNumber` returns blocks not yet available in triedb
  * Fixes common wallet workflow issue with sequential `eth_getBlockNumber` and `eth_getBalance` calls
  * Ref: [monad-bft PR #2393](https://github.com/category-labs/monad-bft/pull/2393)
* **\[SDK]** Add call frame recording to execution events
  * Ref: [monad PR #1541](https://github.com/category-labs/monad/pull/1541)
  * These will not be recorded unless the `--trace_calls` command line argument is passed to execution
* **\[RPC]** Add `monad_eth_call_executor_get_state()` API for better visibility into `eth_call` requests
  * Ref: [monad PR #1764](https://github.com/category-labs/monad/pull/1764)
  * Returns counts of currently executing/queued requests and error counts

#### Notable robustness changes

* **\[Consensus]** Deterministic timeout certificate tiebreaking
  * When TC contains multiple tips with the same round, tiebreak by tip.qc for consistency
  * Ref: [monad-bft PR #2460](https://github.com/category-labs/monad-bft/pull/2460)
* **\[Consensus]** Transaction nonce overflow validation
  * Ref: [monad-bft PR #2388](https://github.com/category-labs/monad-bft/pull/2388)
* **\[Consensus]** More consistent checks on `EpochChange` between block proposer and validator
  * This addresses an observed chain halt in `testnet-2`
  * Ref: [monad-bft PR #2494](https://github.com/category-labs/monad-bft/pull/2494)

#### Notable performance changes

* **\[EVM]** Use komihash in StateDelta maps
  * Ref: [monad PR #1786](https://github.com/category-labs/monad/pull/1786)
* **\[EVM]** JIT compiler: only emit jump table for contracts with indirect jumps
  * Ref: [monad PR #1749](https://github.com/category-labs/monad/pull/1749)
* **\[RPC]** Improve eth call concurrency with atomic sequence numbers
  * Ref: [monad PR #1759](https://github.com/category-labs/monad/pull/1759)

#### Notable internal changes

* **\[Node ops]** Fuzzer refactor (`--focus` flag addition)
  * Ref: [monad PR #1744](https://github.com/category-labs/monad/pull/1744)
* **\[Node ops]** Build images with debug symbols
  * Ref: [monad-bft PR #2459](https://github.com/category-labs/monad-bft/pull/2459)

## v0.11.3 \[2025-10-14]

Revision: [`MONAD_FOUR`](/developer-essentials/changelog#revisions) (upgrade; takes effect
at 2025-10-14 13:30 GMT)

Tags or hashes:

* `monad-bft`: [tag `v0.11.3-tn1`](https://github.com/category-labs/monad-bft/releases/tag/v0.11.3-tn1)
* `monad`: [hash `3e17265`](https://github.com/category-labs/monad/tree/3e17265fae80710229c657d725d821053cec940b)

#### Notable protocol changes - `MONAD_FOUR`

* **\[Consensus/EVM]** [Staking](/monad-arch/consensus/staking) is live
  * (many PRs; see
    [staking](https://github.com/category-labs/monad/tree/main/category/execution/monad/staking))
  * Active validator set is now determined by on-chain state of the staking precompile
  * This takes effect starting from a designated `staking_activation` epoch
  * Note: staking rewards do not activate until `staking_rewards_activation` epoch
    (future point in time)
  * External rewards - enable external (non-block-reward) deposits to the validator pool, see
    [monad PR #1625](https://github.com/category-labs/monad/pull/1625)
  * Also added additional events to staking precompile in [monad PR #1742](https://github.com/category-labs/monad/pull/1742)
    * Adds `ValidatorRewarded`, `EpochChanged`, `ClaimRewards` events
* **\[Consensus/EVM]** [Reserve balance](/developer-essentials/reserve-balance) logic is live
  * Ref: [monad-bft PR #2160](https://github.com/category-labs/monad-bft/pull/2160) and
    [monad PR #1537](https://github.com/category-labs/monad/pull/1537)
  * Due to async execution, consensus does not have the latest state available for transaction
    inclusion logic. Reserve balance is a buffer that enables simpler accounting for a given
    account to mitigate the possibility of overspending in that delay window.
  * Per-EOA reserve balance is set to `10 MON`
* **\[Consensus/EVM]** [EIP-7702](/developer-essentials/eip-7702) is live
  * Ref: [monad-bft PR #2160](https://github.com/category-labs/monad-bft/pull/2160), [monad-bft PR #2218](https://github.com/category-labs/monad-bft/pull/2218) and
    [monad PR #1362](https://github.com/category-labs/monad/pull/1362)
* **\[Network params]** Set per-transaction gas limit of 30M gas
  * Ref: [monad-bft PR #2246](https://github.com/category-labs/monad-bft/pull/2246)
  * As discussed in the
    [Monad Initial Spec Proposal](https://forum.monad.xyz/t/monad-initial-specification-proposal/195)
* **\[Network params]** Increase block gas limit from 150M gas (375 Mgas/s) to **200M** gas
  (500 Mgas/s)
  * Ref: [monad-bft PR #2266](https://github.com/category-labs/monad-bft/pull/2266)
* **\[Network params]** Implement [dynamic base fee](/developer-essentials/gas-pricing)
  * Ref: [monad-bft PR #2207](https://github.com/category-labs/monad-bft/pull/2207)
  * As specified in the
    [Monad Initial Spec Proposal](https://forum.monad.xyz/t/monad-initial-specification-proposal/195)
  * Target gas is 80% of a block
  * Raise minimum base fee from 50 MON-gwei to **100 MON-gwei**
* **\[EVM]** Enable [EIP-2935](https://eips.ethereum.org/EIPS/eip-2935) + blockhash
  buffer
  * Ref: [monad PR #1520](https://github.com/category-labs/monad/pull/1520)
* **\[EVM]** Enable [EIP-7951](https://eips.ethereum.org/EIPS/eip-7951) (P256VERIFY
  precompile support)
  * Ref: [monad PR #1518](https://github.com/category-labs/monad/pull/1518)
* **\[EVM]** Enable [EIP-2537](https://eips.ethereum.org/EIPS/eip-2537) (BLS12-381 precompiles)
  * Ref: [monad-bft PR #1342](https://github.com/category-labs/monad/pull/1342) and [monad-bft PR #1350](https://github.com/category-labs/monad/pull/1350)
* **\[EVM]** Raise max contract size for `CREATE`/`CREATE2` to 128 kb
  * Ref: [monad PR #1440](https://github.com/category-labs/monad/pull/1440)
  * This brings `CREATE`/`CREATE2` to parity with toplevel contract creation transactions, which
    had their limit raised in `MONAD_TWO`.
  * Previously, they were unintentionally limited to Ethereum's max initcode size (49.152 kb)
    due to a bug

#### Notable RPC/SDK changes

* **\[SDK]** Added support for [Execution Events](/execution-events)
* **\[RPC]** Extend `eth_call` support for preStateTracer and stateDiffTracer with `debug_traceCall`
  * Ref: [monad-bft PR #2275](https://github.com/category-labs/monad-bft/pull/2275) and
    [monad PR #1471](https://github.com/category-labs/monad/pull/1471)
* **\[RPC]** Support the `withLog` parameter with `callTracer`
  * Ref: [monad-bft PR #2400](https://github.com/category-labs/monad-bft/pull/2400)
  * If `withLog` is set to true, `callTracer` includes event logs in the trace output

#### Notable performance changes

* **\[EVM]** Kernel caching of db reads and writes
  * Ref: [monad PR #1559](https://github.com/category-labs/monad/pull/1559)
  * Utilize available host memory to cache recent DB operations - this cache
    should increase performance of execution and RPC
* **\[RPC]** Improve RPC Db Node Cache and make it memory bounded
  * Ref: [monad PR #1581](https://github.com/category-labs/monad/pull/1581)
  * Note a rename of RPC cli flags: `--eth-call-executor-node-lru-size` to
    `--eth-call-executor-node-lru-max-mem` and a new flag `--triedb-node-lru-max-mem` with
    both default to 100MB.

#### Notable internal changes

* **\[Node ops]** Remove `bft-fullnode` binary; only `bft` binary now
  * Ref: [monad-bft PR #2072](https://github.com/category-labs/monad-bft/pull/2072)
  * `bft-fullnode` removed from `deb` pkg for `v0.11`
* **\[Node ops]** PeerDiscovery: Introduce precheck for peer self name address
* **\[Consensus]** Blocksync: only select blocksync peers from connected nodes
  * Ref: [monad-bft PR #2401](https://github.com/category-labs/monad-bft/pull/2401)
* **\[Consensus]** Raptorcast: DOS protection on decoding state cache
  * Ref: [monad-bft PR #2092](https://github.com/category-labs/monad-bft/pull/2092)
* **\[Node ops]** Secondary raptorcast config change
  * Ref: [monad-bft PR #2378](https://github.com/category-labs/monad-bft/pull/2378)
  * Replace ambiguous secondary raptorcast  `mode` parameter with `enable_publisher` and `enable_client`
* **\[Node ops]** Dynamically reload prioritized full-nodes
  * Ref: [monad-bft PR #2364](https://github.com/category-labs/monad-bft/pull/2364)
* **\[Node ops]** Fix wal2json
  * Ref: [monad-bft PR #2404](https://github.com/category-labs/monad-bft/pull/2404)
* **\[Node ops/RPC]** Support the RPC CLI param `ws-sub-per-conn-limit`
  * Ref: [monad-bft PR #2161](https://github.com/category-labs/monad-bft/pull/2161)
  * Sets the maximum number of websocket subscriptions per connection (default to 100)
* **\[Node ops/RPC]** Add configuration options for high eth-call pool
  * Ref: [monad-bft PR #2387](https://github.com/category-labs/monad-bft/pull/2387)

## v0.10.4 \[2025-08-18]

Revision: [`MONAD_THREE`](/developer-essentials/changelog#revisions) (unchanged)

Tags or hashes:

* `monad-bft`: [tag `v0.10.4`](https://github.com/category-labs/monad-bft/releases/tag/v0.10.4)
* `monad`: [hash `39c42e6`](https://github.com/category-labs/monad/tree/39c42e6ea5b2fccf8f4aa951da9d6281885511a5)

#### Notable RPC/SDK changes

* **\[RPC]** EIP-4844 related fields in RPC responses are removed.
  * Block headers returned from RPC will no longer have `blobGasUsed` , `excessBlobGas`, and
    `parentBeaconBlockRoot`.

#### Notable performance changes

* **\[Consensus]** Votes are now sent to current round leader. This is a consensus optimization that
  reduces the effective delay due to a round timeout
  * Ref: [monad-bft PR #2093](https://github.com/category-labs/monad-bft/pull/2093)
* **\[Consensus]** Caching of recently-verified quorum certificates
  * Ref: [monad-bft PR #2167](https://github.com/category-labs/monad-bft/pull/2167)
* **\[Node ops]** Enablement of trace calls is now controlled via `monad` (execution) command line
  arg `--trace_calls`.
  * To preserve legacy behavior, `--trace_calls` is currently enabled in the debian package. In the
    future we recommend disabling for validators and enabling it for RPC and archive nodes.
  * This allows voting validators to opt out of computing traces since they're only needed for
    RPC nodes.

#### Notable internal changes

* **\[Consensus]** TC forwarding to prioritized and public (non-dedicated) full nodes
  * Ref: [monad-bft PR #2149](https://github.com/category-labs/monad-bft/pull/2149)
  * Prior to `v0.10.4`, all full nodes were subject to lagging behind validators in the event of a
    timeout because round advancement due to TC was not forwarded (and still isn’t to dedicated full
    nodes).
  * As a result, after timeouts, full nodes would frequently forward transactions to the
    next three leaders relative to a stale state. This results in those transactions often missing
    and the ensuing blocks being comparatively empty.
* **\[Node ops]** Bugfix for secondary raptorcast (round gap crash) that affected validators in
  Publisher mode
  * Ref: [monad-bft PR #2090](https://github.com/category-labs/monad-bft/pull/2090)
* **\[Node ops]** `ledger-tail` improvements
  * Ref: [monad-bft PR #2144](https://github.com/category-labs/monad-bft/pull/2144)
  - Reduced memory usage on startup
  - `author_dns` field changed to `author_address` to reflect change in v10 addresses
  - Timeouts and finalizations are tracked and logged
* **\[Consensus]** Txpool account preloading bugfix
  * Ref: [monad-bft PR #2108](https://github.com/category-labs/monad-bft/pull/2108)

## v0.10.3 \[2025-08-12]

Revision: [`MONAD_THREE`](/developer-essentials/changelog#revisions) (upgrade; takes
effect immediately - not time-gated)

#### Notable protocol changes - `MONAD_THREE`

* **\[Consensus]** Consensus mechanism upgraded from [Fast-HotStuff](https://arxiv.org/abs/2010.11454)
  to [MonadBFT](/monad-arch/consensus/monad-bft). This is a major upgrade that adds
  *(i)* [resilience to tail forking](/monad-arch/consensus/monad-bft#no-tail-forking) and
  *(ii)* [1-slot speculative finality](/monad-arch/consensus/monad-bft#speculative-finality)
* **\[Network params]** Block time reduced from 500 ms to **400 ms**

#### Notable RPC/SDK changes

* **\[RPC]** Add support for [real-time data](/monad-arch/realtime-data) via
  [WebSocket](/reference/websockets) and shared memory queue access (docs coming soon):
  * Geth real-time events (via WebSocket)
  * Geth real-time events with Monad extensions (via WebSocket)
  * Real-time data via shared memory queue, for programs on a full node host using the execution event SDK

#### Notable performance changes

* **\[Execution]** Switch to JIT EVM. The bytecode of expensive or frequently-executed contracts is
  compiled directly to native code for faster execution
* **\[Execution]** Switch to using file pointer-based IPC to execute blocks. Previously, the client
  was using a write-ahead log (WAL), which did not take advantage of available consensus
  information and could result in avoidable execution

#### Notable internal changes

* **\[Node ops]** Adds peer discovery
* **\[Node ops]** Adds full node [RaptorCast](/monad-arch/consensus/raptorcast), making the full
  node network scalable

## v0.9.3 \[2025-05-29]

Revision: [`MONAD_TWO`](/developer-essentials/changelog#revisions) (unchanged)

#### Notable RPC/SDK changes

* **\[RPC]** `eth_call` and `eth_estimateGas` limits
  * RPC providers can now set individual per-transaction limits on maximum gas for `eth_call` and
    `eth_estimateGas`
    * Previously the limit would always be the block gas limit (150M), now the RPC provider may
      choose (default: 30M)
    * Controlled with `--eth-call-provider-gas-limit` and `--eth-estimate-gas-provider-gas-limit`
  * Add a maximum timeout for queueing when executing `eth_call` and `eth_estimateGas`
    * Controlled with `--eth_call_executor_queuing_timeout`

#### Notable performance changes

* **\[RPC]** Improve overall `eth_call` performance by maintaining separate queues for cheap and
  expensive `eth_call` operations, so that cheap `eth_call` operations will not be queued behind expensive ones.
  * This adds two new RPC error strings:
    * `failure to submit eth_call to thread pool: queue size exceeded`
    * `failure to execute eth_call: queuing time exceeded timeout threshold`
* **\[RPC]**  Added an archive index for `eth_getLogs` to support queries with address and/or topic
  filters
  * This enables larger block ranges to be queried efficiently, with work proportional to number
    of matching logs instead of number of blocks in range
* **\[Execution]** Better bounding of TrieDB traversals

#### Notable internal changes

* **\[Node ops]**  Performance improvements for slow statesync client upsert
* **\[Node ops]**  Bugfix for execution delay and abrupt history length drops caused by premature
  soft reset
* **\[Node ops]**  `keystore` QOL improvements
  * Support for importing from a private key in hex string format (previously required conversion
    to json file)
  * More helpful documentation via `--help` command

## testnet-1 active set expansion \[2025-05-02]

#### Notable internal changes

* **\[Network params]** Testnet validator set expanded from 72 to **99** nodes

## v0.9.2 \[2025-04-05]

Revision: [`MONAD_TWO`](/developer-essentials/changelog#revisions) (unchanged)

#### Notable performance changes

* **\[RPC]** Update to the `eth_call` execution implementation - uses fewer threads to achieve the
  same concurrency as in `v0.9.1`

#### Notable internal changes

* **\[Node ops]** Support for a faster [statesync](/monad-arch/consensus/statesync) mechanism
* **\[RPC]** RPC no longer accepts requests while node is statesyncing
* **\[Node ops]** Some reliability and efficiency improvements to how statesync traffic is carried
  between nodes
* **\[Node ops]** Bugfixes for execution crashes (`monad::mpt::deserialize_node_from_buffer`,
  `'Resource temporarily unavailable`)

- **\[Node ops]** Bug fix for unbounded blocksync requests that result in node OOM failures
- **\[Node ops]** Removal of DNS resolution panic on start up

## v0.9.1 \[2025-03-24]

Revision: [`MONAD_TWO`](/developer-essentials/changelog#revisions) (unchanged)

#### Notable internal changes

* **\[Node ops]** Bugfix for blocksync errors
* **\[Node ops]** Reliability and efficiency improvements to statesync

## v0.9.0 \[2025-03-14]

Revision: [`MONAD_TWO`](/developer-essentials/changelog#revisions) (upgrade; takes effect
at 2025-03-14 at 19:00 GMT)

#### Notable protocol changes - `MONAD_TWO`

* **\[EVM]** Max contract size increased from 24kb to **128kb**
  * [example 123 kb contract](https://testnet.monadvision.com/address/0x0E820425e07E4a992C661E4B970e13002d6e52B9?tab=Contract)

#### Notable RPC/SDK changes

* **\[RPC]** `debug_traceTransaction` fixes
  * Fixed a bug where, within one transaction, only the first 100 calls were being traced
  * Added `error` and `revertReason` fields to response data

#### Notable performance changes

* **\[Consensus]** Dataplane v2 - simpler and more efficient implementation; small performance
  improvement in broadcast time
* **\[RPC]** Improvements to RPC performance for `eth_call`

- **\[RPC]** Removed redundant sender\_recovery operation on raw transactions received via RPC

#### Notable internal changes

* **\[Node ops]** Statesync improvements to mitigate negative performance effects on upstream
  validator nodes

- **\[RPC]** EIP-2 signature validation added to RPC transaction validation
- **\[Node ops]** Miscellaneous tracing, logging and metrics additions
- **\[Consensus]** RaptorCast performance improvement when dealing with invalid symbols

## v0.8.1 \[2025-02-14]

Revision: [`MONAD_ONE`](/developer-essentials/changelog#revisions) (upgrade; takes effect
at 2025-02-14 at 19:00 GMT)

#### Notable protocol changes - `MONAD_ONE`

* **\[Network params]** Block time reduced from 1s to **500 ms**
* **\[Network params]** Block gas limit reduced from 300M to **150M** (to keep gas limit consistent)
* **\[EVM]** Transactions are [charged](/developer-essentials/gas-pricing) based on gas limit,
  not gas consumed

#### Notable RPC/SDK changes

* **\[RPC]** UX improvements for [transaction status](/monad-arch/transaction-lifecycle). RPC
  nodes track status of transactions submitted to them in order to provide updates to users.


# Differences between Monad and Ethereum
Source: https://docs.monad.xyz/developer-essentials/differences



<Tip>
  To take into account these differences, there is a custom [Monad Foundry](/tooling-and-infra/toolkits/monad-foundry)
  to ensure that your local development environment matches Monad's onchain behavior.
</Tip>

This list assembles notable behavioral differences between Monad and Ethereum from the
perspective of a smart contract developer.

## Virtual Machine

1. The maximum contract code size limit is 128 KB (up from 24 KB in Ethereum). Consequently, the
   max init code size limit is 256 KB (up from 48 KB in Ethereum).

2. A few opcodes and precompiles are repriced, to reweight relative scarcities of resources due
   to Monad optimizations. See [Opcode Pricing](/developer-essentials/opcode-pricing).

3. The `secp256r1` (P256) verification precompile at `0x0100` per
   [EIP-7951](https://eips.ethereum.org/EIPS/eip-7951) is supported, enabling on-chain
   verification of WebAuthn/passkey signatures.
   See [Precompiles](/developer-essentials/precompiles#p256-signature-verification).

## Transactions

1. Transactions are charged based on gas limit rather than gas usage, i.e. total gas deducted
   from the sender's balance is `value + gas_bid * gas_limit`. As discussed in
   [Gas in Monad](/developer-essentials/gas-pricing), this is a DoS-prevention measure for
   asynchronous execution.

2. Consensus and execution utilize the [Reserve Balance](/developer-essentials/reserve-balance) mechanism to ensure
   that all transactions included in consensus can be paid for. This mechanism places light
   restrictions on transaction inclusion at consensus time, and defines select conditions under
   which a transaction will revert at execution time.

3. Due to the Reserve Balance mechanism, you may see transactions in the blockchain which
   ultimately fail due to trying to spend too much MON relative to account balance.
   These transactions still pay for gas and are valid transactions whose result is execution
   reversion. This isn't a protocol difference, as many reverting Ethereum transactions are
   included in the chain, but it may be different from expectation.
   [Longer discussion](/developer-essentials/reserve-balance#transactions-that-are-included-but-revert).

4. Transaction type 3 (EIP-4844 aka blob transactions) is not supported.

5. There is no global mempool. For efficiency, transactions are forwarded to the next few leadersas
   described in [Local Mempool](/monad-arch/consensus/local-mempool).

## EIP-7702 Delegation

1. If an EOA is EIP-7702-delegated, its balance cannot be lowered below 10 MON due to the
   [Reserve Balance](/developer-essentials/reserve-balance) rules. If the delegation is removed, dipping below 10 MON
   is allowed. [Discussion](/developer-essentials/eip-7702#delegated-eoas-cant-dip-below-10-mon).

2. If an EOA is EIP-7702-delegated, when it is called as a smart contract, the
   `CREATE` and `CREATE2` opcodes are banned. [Discussion](/developer-essentials/eip-7702#delegated-contract-code-cannot-call-createcreate2).

## Historical Data

Due to Monad's high throughput, full nodes do not provide access to arbitrary historic state, as
this would require too much storage. See [Historical Data](/developer-essentials/historical-data) for a fuller
discussion.

## RPC

See: [RPC Differences](/reference/rpc-differences)


# EIP-7702 on Monad
Source: https://docs.monad.xyz/developer-essentials/eip-7702



## Summary

[EIP-7702](https://eips.ethereum.org/EIPS/eip-7702)
is supported on Monad with the same workflow as in Ethereum: users sign a message
authorizing the delegation to a specific account, which they or someone else can submit
using transaction type `0x04`. After that occurs, the EOA becomes "delegated", i.e. it
can be called like a smart contract account with code equal to the account it has delegated to.

EIP-7702-delegated accounts behave the same on Monad as on Ethereum in most cases.

The two main nuances are:

1. If an EOA is EIP-7702-delegated, transactions that would reduce its balance to below 10 MON will
   unconditionally revert.
   * If the balance is below 10 MON but is unchanged or increased by this transaction, the
     transaction succeeds
   * If the delegation is removed, dipping below 10 MON is allowed under certain conditions
   * [Details](#delegated-eoas-cant-dip-below-10-mon)
2. When the EOA is treated like a smart contract, that code cannot call `CREATE` or `CREATE2`.
   [Details](#delegated-contract-code-cannot-call-createcreate2)

## EIP-7702 Primer

[EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) allows Externally Owned Accounts (EOAs)
to add code to themselves, granting themselves the ability to add new capabilities previously
reserved for smart contract accounts, such as transaction batching, gas sponsorship, and
alternative authentication.

To do this, the EOA signs an authorization designating a specific address as the source
of its code. EIP-7702 introduces a new transaction type (type `0x04`) that submits this
authorization. The authorization can be submitted by the EOA themselves, or by anyone else.

EIP-7702 enables account abstraction directly on an EOA. It is an extension of EIP-4337,
which introduced standards for smart contract wallets with flexible validation logic, but which
had to assume a separate UserOp mempool and bundler infrastructure for submitting transactions.

In Ethereum's account-based model, there are two separate roles - "fee payer" (transaction
submitter, i.e. who pays for gas to execute a transaction) and "asset owner" (spend authorizer,
i.e. who holds keys with the power to spend from a balance). Originally, EOAs played both roles.
Under EIP-4337, the roles were split - a smart contract wallet holds title to assets (and has
its own logic for validating that spend was authorized), but fees must still be paid by an
EOA, hence the roles are definitively split.

With EIP-7702, EOAs are allowed to have code, thus allowing the same account to play both roles
again.

In essence, EIP-7702 makes it possible for today's EOAs to gain smart wallet-like powers
such as multisig, social recovery, session keys, and gas sponsorship **without abandoning their
current accounts**, bridging the gap between the old EOA model and the future of full account
abstraction.

## EIP-7702 on Monad

EIP-7702-delegated accounts behave the same on Monad as on Ethereum in most cases.

The two main nuances are:

1. If an EOA is EIP-7702-delegated, transactions that would reduce its balance to below 10 MON will
   unconditionally revert.
   * If the balance is below 10 MON but is unchanged or increased by this transaction, the
     transaction succeeds
   * If the delegation is removed, dipping below 10 MON is allowed under certain conditions
   * [Details](#delegated-eoas-cant-dip-below-10-mon)
2. When the EOA is treated like a smart contract, that code cannot call `CREATE` or `CREATE2`.
   [Details](#delegated-contract-code-cannot-call-createcreate2)

### Delegated EOAs can't dip below 10 MON

In Monad, the [Reserve Balance](/developer-essentials/reserve-balance) rules carve out a budget of 10 MON
for consensus-time balance checks for inflight transactions from each EOA.  ("Inflight" means
transactions seen by consensus since the delayed view of state, 3 blocks ago.)

Execution protects that budget by reverting if the balance of any EOA would *dip below* 10 MON
by an amount greater than the transaction's max gas fee. (*"Dip below"* means *"decrement
**and** drop below"*; if an EOA's MON balance is unchanged, that doesn't count as dipping.)

* An [exception](/developer-essentials/reserve-balance#addressing-the-drawback) is made to this
  execution-time policy for **undelegated** EOAs where a transaction hasn't been seen from this
  EOA in several blocks. That exception is what allows undelegated EOAs to submit transactions
  that would cause their balance to dip below 10 MON by amounts greater than the transaction's max gas fee.

* However, this exception can't be made for EIP-7702-delegated accounts. Delegation
  breaks the invariant that an EOA's balance can only be reduced by transactions signed by
  that EOA. There is not a reliable way to be sure (at the time of consensus) that another inflight
  transaction hasn't spent funds from an EIP-7702-delegated account, therefore the exception made
  for undelegated accounts doesn't apply to **delegated** accounts.

An delegated account may be emptied by undelegating first.

To be clear, EIP-7702-delegated accounts are **not** required to have a 10 MON balance. For example,
a delegated EOA *A* with a balance of 5 MON can still be called by a gas sponsor, and the transaction
will succeed as long as *A* ends with 5 MON or more still.

This is discussed further [here](/developer-essentials/reserve-balance#eip-7702-delegated-accounts).

### Delegated contract code cannot call `CREATE/CREATE2`

There is another difference: when contract code is executing in the context of an
EIP‑7702‑delegated EOA (for example, because a contract `CALL`s that EOA’s address),
the `CREATE` and `CREATE2` opcodes are not permitted.
Any attempt to execute `CREATE` or `CREATE2` in such a frame causes that call frame to revert,
and the caller (if any) observes the call as failed
(the `CALL`/`DELEGATECALL`/`CALLCODE` returns 0).

This prevents delegated code from changing the EOA’s nonce in ways that would make it
difficult to statically validate transactions from that account.

In contrast, normal contract‑creation transactions sent from a delegated
EOA (transactions with no `to` field, where the transaction `data` is treated as init code)
are allowed and behave as on Ethereum.

Other than those differences, EIP-7702-delegated accounts behave normally with respect to both
ordinary transactions sent by the EOA, and transactions that treat the EOA as a
smart contract.

## FAQ

<Accordion title="What does an EIP-7702 (set code transaction) look like?">
  An EIP-7702 transaction is an [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718)
  transaction with TransactionType `0x04`.

  This transaction type is only used to set code; once the code is set for an EOA, subsequent
  transactions will most likely use the default transaction type (TransactionType `0x02`;
  [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559)) transactions to interact with the EOA.

  Here is an example of an EIP-7702 transaction in a block explorer:

  <img alt="explorer_example" />
</Accordion>

<Accordion title="Is it necessary for the EIP-7702 type transaction to be initiated by the EOA itself?">
  No, the EOA can sign an "authorization tuple" which can then be used by the sponsoring
  entity to send the transaction. This will allow EOAs to behave like smart contracts
  without any funds for gas!
</Accordion>

<Accordion title="How can I find out to which address EOA is currently delegating to?">
  On successful delegation to a smart contract, the following code is deployed at the EOA's
  address.

  `0xef0100` (3 bytes) + `smart_contract_address` (20 bytes)

  Example: If `0xabc...` (EOA) delegates to `0x493...` (smart contract), then code at
  `0xabc...` (EOA) is `0xef0100493...`

  Thus, you may determine the delegated address by inspecting the code.
</Accordion>

<Accordion title="What if the EOA is pointing to another EOA which is also pointing to a smart contract?">
  The chain of delegation is not followed; only the immediate code that the first EOA is
  pointing to is used.
</Accordion>

<Accordion title="How do I clear the delegation on an EOA?">
  Initiate a `0x04` type transaction from the EOA with `0x000...` (dead address) as the new
  delegated account.
</Accordion>

<Accordion title="Does the delegation expire?">
  No, the delegation remains valid in perpetuity unless another `0x04` transaction is sent
  changing the delegation to a different (or null) account.
</Accordion>

<Accordion title="Is EIP-7702 compatible with ERC-4337?">
  Yes; after delegating with EIP-7702, any EOA may behave like an EIP-4337 smart account.
  Simply initiate a transaction of type `0x04` while pointing to an address containing code
  for the 4337-compatible smart account.
</Accordion>

<Accordion title="What happens if the EOA is pointing to a precompile address for code?">
  If that's an Ethereum precompile, the `CALL`, `STATICCALL`, `DELEGATECALL`, and `CALLCODE` opcodes,
  when called with enough gas, proceed with execution as if the EOA has no code.

  If that's a Monad precompile, calls revert as if the EOA has code starting with an
  invalid instruction.
</Accordion>

<Accordion title="Can you give me an example of submitting an EIP-7702 transaction using viem?">
  ```ts theme={null}
  import { createWalletClient, http, parseEther } from 'viem'
  import { monadTestnet } from 'viem/chains'
  import { privateKeyToAccount } from 'viem/accounts'

  const account = privateKeyToAccount('0x...')

  const walletClient = createWalletClient({
    account,
    chain: monadTestnet,
    transport: http(),
  })

  const authorization = await walletClient.signAuthorization({
    account,
    contractAddress: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2'
  })

  const hash = await walletClient.sendTransaction({
    authorizationList: [authorization],
    data: '0xdeadbeef',
    to: walletClient.account.address,
  })
  ```
</Accordion>


# Gas Pricing
Source: https://docs.monad.xyz/developer-essentials/gas-pricing



## Summary

Monad, like Ethereum, charges for processing transactions based on the complexity of the
transaction. Complexity is measured in units of **gas**.

This page summarizes how gas is charged, i.e. the conversion between the gas of a transaction
and the amount of MON that a user will have to pay.
A separate page, [Opcode Pricing](/developer-essentials/opcode-pricing), describes how much
each opcode costs in units of gas.

| Feature                   | Detail                                                                                                                                                                                         |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Gas charged**           | The gas charged for a transaction is the **gas limit**. [Discussion](#gas-limit-not-gas-used)                                                                                                  |
| **Price per gas**         | EIP-1559-compatible, i.e. price paid per unit of gas is the sum of a system-controlled base fee and a user-specified priority fee. [Discussion](#eip-1559-compatibility)                       |
| **Base fee**              | Base fee (aka `base_price_per_gas`) follows a dynamic controller, similar to the EIP-1559 controller but with slower increases and faster decreases. [Details](#base_price_per_gas-controller) |
| **Minimum base fee**      | 100 MON-gwei (`100 * 10^-9 MON`)                                                                                                                                                               |
| **Block gas limit**       | 200M gas                                                                                                                                                                                       |
| **Transaction gas limit** | 30M gas                                                                                                                                                                                        |
| **Opcode pricing**        | See [Opcode Pricing](/developer-essentials/opcode-pricing)                                                                                                                                     |
| **Transaction ordering**  | Default Monad client behavior is to order transactions according to a Priority Gas Auction (descending total gas price).                                                                       |

<Note>
  These changes are covered formally in the
  [Monad Initial Spec Proposal](https://category-labs.github.io/category-research/monad-initial-spec-proposal.pdf)
</Note>

## Gas definitions

A common point of confusion among users is the distinction between **gas** of a transaction (units
of work) and the **gas price** of a transaction (price in native tokens per unit of work).

| Feature                         | Definition                                                                                                                                                                                                                                                                                  |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Gas**                         | A unit of work. Gas measures the amount of work the network has to do to process something.<br /><br /> Since the network has multiple kinds of resources (network bandwidth, CPU, SSD bandwidth, and state growth), gas is inherently a projection from many dimensions into a single one. |
| **Gas price (price\_per\_gas)** | The **price** (in native tokens) paid **to process one unit** of gas.                                                                                                                                                                                                                       |
| **Gas limit**                   | The maximum **number of units of gas** that a transaction is allowed to consume.                                                                                                                                                                                                            |

## Gas limit, not gas used

In Monad, the gas charged for a transaction is the gas limit set in the transaction, rather than
the gas used in the course of execution.

This is a design decision to support asynchronous execution. Under asynchronous execution,
leaders build blocks (and validators vote on block validity) prior to executing.

If the protocol charged `gas_used`, a user could submit a transaction with a large `gas_limit`
that actually consumes very little gas. This transaction would take up a lot of space toward the
block gas limit but wouldn't pay very much for taking up that space, opening up a DOS vector.

```
gas_paid = gas_limit * price_per_gas
```

## EIP-1559 Compatibility

Monad supports EIP-1559.

EIP-1559 (type 2) transactions have the parameters  `priority_price_per_gas` and
`max_price_per_gas`, which, together with `base_price_per_gas` (a system parameter that changes
each block), determine the gas bid for the transaction:

```
price_per_gas = min(base_price_per_gas + priority_price_per_gas, max_price_per_gas)
```

Notes:

* `base_price_per_gas` is a system parameter that changes each block. Every transaction in the
  same block will have the same `base_price_per_gas`
* Users specify `priority_price_per_gas` and `max_price_per_gas` when signing a transaction
* Since everyone in the same block will pay the same `base_price_per_gas`, the
  `priority_price_per_gas` is a way for users to pay more to prioritize their transactions.
* Since users don't determine `base_price_per_gas`, the `max_price_per_gas` is a safeguard that
  limits the amount they may end up paying. Of course, if that value is set too low, the
  transaction will not end up being chosen for inclusion.

[This](https://www.blocknative.com/blog/eip-1559-fees) article provides another good explanation
of EIP-1559 gas pricing.

## `base_price_per_gas` controller

Monad uses a different controller for `base_price_per_gas` than Ethereum:

$$
\begin{align*}
\mathrm{block\_gas}_{k} &= \sum\limits_{\mathrm{tx} \in \mathrm{block}_k}\mathrm{gas\_limit}_\mathrm{tx}\\
\mathrm{base\_price\_per\_gas}_{k+1} &= \max\left\{\text{min\_base\_price\_per\_gas}, \mathrm{base\_price\_per\_gas}_k \cdot \exp \left(
\eta_k \cdot \frac{\mathrm{block\_gas}_{k} - \text{target}}{\text{block\_gas\_limit} - \text{target}}
\right) \right\} \\
\eta_k &= \frac{\text{max\_step\_size}\cdot\epsilon}{\epsilon+\sqrt{\mathrm{moment}_k - \mathrm{trend}_k^2}} \\
\mathrm{trend}_{k+1} &= \beta\cdot \mathrm{trend}_k + (1-\beta)\cdot \left(\text{target}-\mathrm{block\_gas}_{k} \right) \\
\mathrm{moment}_{k+1} &= \beta\cdot \mathrm{moment}_k + (1-\beta)\cdot \left(\text{target}-\mathrm{block\_gas}_{k} \right)^2
\end{align*}
$$

This inductive formula starts with

$$
\begin{align*}
\mathrm{base\_price\_per\_gas}_{0} &= 0 \\
\mathrm{moment}_{0} &= 0 \\
\mathrm{trend}_{0} &= 0
\end{align*}
$$

and with the following parameters:

$$
\begin{align*}
\mathrm{max\_step\_size} &= 1/28 \\
\mathrm{target} &= 160\text{M}\ \text{(80\% full)}\ \\
\beta &= 0.96 \\
\epsilon &= \mathrm{target} = 160\text{M}
\end{align*}
$$

And

$$
\text{min\_base\_price\_per\_gas} = 100\ \text{MON-gwei}\ (100 \times 10^{-9}\ \text{MON})
$$

Compared to the `base_price_per_gas` controller in Ethereum, this controller increases more
slowly and decreases more quickly. This is to avoid underutilization of blockspace due to an overpriced `base_price_per_gas`.

For a more comprehensive discussion of Monad controller design considerations and behavior, check out [this](https://www.category.xyz/blogs/redesigning-a-base-fee-for-monad) blog post from Category Labs.

## Recommendations for developers

### Set the gas limit explicitly if it is constant

Many on-chain actions have a fixed gas cost. The simplest example is that a transfer of native
tokens always costs 21,000 gas, but there are many others.

For actions where the gas cost of the transaction is known ahead of time, it is recommended to set
it directly prior to handing the transaction off to the wallet. This offers several benefits:

* It reduces latency and gives users a better experience, since the wallet doesn't have to call
  `eth_estimateGas` and wait for the RPC to respond.
* It retains greater control over the user experience, avoiding cases where the wallet sets a high
  gas limit in a corner case as described in the warning below.

<Warning>
  Some wallets, including MetaMask, are known to have the following behavior: when
  `eth_estimateGas` is called and the contract call reverts, they set the gas limit for this
  transaction to a very high value.

  This is the wallet's way of giving up on setting the gas limit and accepting whatever gas usage is
  at execution time. However, it doesn't make sense on Monad where the full gas limit is charged.

  Contract call reversion happens whenever the user is trying to do something impossible. For
  example, a user might be trying to mint an NFT that has minted out.

  If the gas limit is known ahead of time, setting it explicitly is best practice, since it ensures
  the wallet won't handle this case unexpectedly.
</Warning>


# Historical Data
Source: https://docs.monad.xyz/developer-essentials/historical-data



## Summary

Monad full nodes provide access to all historic transactional data (blocks, transactions, receipts,
events, and traces).

Monad full nodes do not provide access to arbitrary historic state.

<Note title="solution">
  <div>
    There is a special RPC service at

    <CopyToClipboard>
      [`https://rpc-mainnet.monadinfra.com`](https://rpc-mainnet.monadinfra.com)
    </CopyToClipboard>

    that provides access to historical data. The following methods at that service support queries
    referring to historical state:

    <ul>
      <li>[`debug_traceCall`](/reference/json-rpc/debug_traceCall)</li>
      <li>[`eth_call`](/reference/json-rpc/eth_call)</li>
      <li>[`eth_createAccessList`](/reference/json-rpc/eth_createAccessList)</li>
      <li>[`eth_estimateGas`](/reference/json-rpc/eth_estimateGas)</li>
      <li>[`eth_getBalance`](/reference/json-rpc/eth_getBalance)</li>
      <li>[`eth_getCode`](/reference/json-rpc/eth_getCode)</li>
      <li>[`eth_getTransactionCount`](/reference/json-rpc/eth_getTransactionCount)</li>
      <li>[`eth_getStorageAt`](/reference/json-rpc/eth_getStorageAt)</li>
    </ul>
  </div>
</Note>

## Background

Blockchains are stateful systems; there are two main kinds of data:

1. **transactional data** (the list of transactions and their artifacts); and
2. **state data** (the current state of the world, resulting from applying those transactions
   sequentially; stored in a merkle trie).

Transactional data consists of

* blocks
* transactions
* receipts produced by executing those transactions
* events (logs) emitted by smart contracts in the course of execution
* detailed traces from each transaction's execution

State data consists of

* for each account, its native token balance
* for each smart contract, the storage mapping (which maps storage slots to values)

A typical node in a blockchain holds the current state, which is constantly being updated as new transactions are added. Recent historical states may be available as well, depending on how costly each incremental version is and how much disk space is available.

For reference, imagine maintaining a MySQL or Postgres table, where each `INSERT` or `UPDATE` query is a transaction. If the table is small enough, then it may be feasible to cache every new version of the table, but if it's a large table, you would probably expect to only have access to the current version.

The following describes historical data access in Monad:

## Transactional data

Monad full nodes provide access to all historic transactional data (blocks, transactions, receipts, events, and traces).[^1]

## State

In Ethereum, a "full node" offers chain state for the current block and each block up to 128 blocks ago, while an "archive node" offers per-block chain state since genesis. That is, an Ethereum "archive node" is a differently-configured full node, run on a box with a large disk. This terminology is described further [here](https://chainstack.com/evm-nodes-a-dive-into-the-full-vs-archive-mode/).

In Monad, every "full node" is an "archive node" in the sense that every node maintains as many historical per-block state tries as it can. This means that the lookback depends on the size of disk chosen by the RPC provider. For a 2 TB SSD, this recently has corresponded to about 40,000 blocks, although it depends on the amount of state diffs in each block.

Due to Monad's high throughput, **full nodes do not provide access to arbitrary historic state**, as this would require too much storage.[^2]

Methods like `eth_call` may reference recent states up to the point where the state trie was evicted.

When writing smart contracts, it is recommended to use events to log any state that will be needed later, or use a [smart contract indexer](/tooling-and-infra/indexers/indexing-frameworks) to compute it off-chain.

[^1]: Implementation detail: recent transactional data is stored directly on the node, while older data is stored in a separate archive node as configured and operated by the RPC provider.

[^2]: With sufficient SSD capacity, a Monad full node would behave similarly to an Ethereum "archive" node in providing access to historical state since genesis. But in practice, due to larger changesets for each block (up to 5,000 transactions per block vs \~200 for Ethereum, i.e. 25x larger blocks) and more frequent blocks (0.4s for Monad vs 12s for Ethereum, i.e. 30x more frequent) no RPC provider is currently offering access to arbitrarily-far-back historical state.


# Developer Essentials
Source: https://docs.monad.xyz/developer-essentials/index



## Quick Reference

<CardGroup>
  <Card title="Network Information - Mainnet" href="/developer-essentials/network-information">
    Chain config, RPC, block explorers and canonical deployments
  </Card>

  <Card title="Tokens and Bridges" href="/developer-essentials/network-information/tokens-and-bridges">
    Token addresses and bridge links
  </Card>

  <Card title="Deployment Summary" href="/developer-essentials/summary">
    Everything you need to know when deploying on Monad
  </Card>

  <Card title="Tooling & Infra" href="/tooling-and-infra">
    Third-party infra supporting Monad Testnet
  </Card>

  <Card title="RPC Reference" href="/reference">
    JSON-RPC API
  </Card>

  <Card title="Differences between Monad & Ethereum" href="/developer-essentials/differences" />
</CardGroup>

## Finer Details

<CardGroup>
  <Card title="Transactions" href="/developer-essentials/transactions">
    Supported transaction types and format (TLDR: same as Ethereum,
    except no EIP-4844 transaction type)
  </Card>

  <Card title="Gas Pricing" href="/developer-essentials/gas-pricing">
    Why the gas limit is charged + details of the base fee controller
  </Card>

  <Card title="Opcode Pricing" href="/developer-essentials/opcode-pricing">
    Opcode pricing adjustments
  </Card>

  <Card title="Precompiles" href="/developer-essentials/precompiles">
    Supported precompiles, including P256 signature verification and staking
  </Card>

  <Card title="Staking" href="/reference/staking/overview">
    Staking behavior + staking precompile reference
  </Card>

  <Card title="Reserve Balance" href="/developer-essentials/reserve-balance">
    How the reserve balance ensures safety under asynchronous execution
  </Card>

  <Card title="EIP-7702" href="/developer-essentials/eip-7702">
    EIP-7702 reference
  </Card>

  <Card title="Historical Data" href="/developer-essentials/historical-data">
    Data retention policy for state and ledger data
  </Card>
</CardGroup>

## Best Practices

<CardGroup>
  <Card title="Best Practices" href="/developer-essentials/best-practices">
    Recommendations for building high-performance apps
  </Card>
</CardGroup>

## Monad's Architecture in Depth

<CardGroup>
  <Card title="Monad for Devs" href="/introduction/monad-for-developers">
    One-page summary of Monad architecture
  </Card>

  <Card title="Monad Architecture" href="/monad-arch" />
</CardGroup>

## Changelog

<CardGroup>
  <Card title="Changelog" href="/developer-essentials/changelog">
    Revision list and changelog
  </Card>
</CardGroup>

## Testnet

<CardGroup>
  <Card title="Network Information - Testnets" href="/developer-essentials/testnets">
    Links and canonical deployments for testnets
  </Card>
</CardGroup>

## Get Support

<CardGroup>
  <Card title="Discord" href="https://discord.gg/monaddev">
    Join other Monad developers on Discord
  </Card>

  <Card title="Telegram" href="https://t.me/+06Kv7meSPn80M2U8">
    Join other Monad developers on Telegram
  </Card>
</CardGroup>


# Network Information - Mainnet
Source: https://docs.monad.xyz/developer-essentials/network-information/index



<div>
  <table>
    <thead>
      <tr>
        <th>Name</th>
        <th>Value</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Network Name</td>

        <td>
          <CopyToClipboard>`Monad Mainnet`</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Chain ID</td>

        <td>
          <CopyToClipboard>`143`</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Currency Symbol</td>

        <td>
          <CopyToClipboard>`MON`</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>RPC URL</td>
        <td>[see below](#public-rpc-endpoints)</td>
      </tr>

      <tr>
        <td>Block Explorer (MonadVision)</td>

        <td>
          <CopyToClipboard>[https://monadvision.com](https://monadvision.com)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Block Explorer (Monadscan)</td>

        <td>
          <CopyToClipboard>[https://monadscan.com](https://monadscan.com)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Block Explorer (Socialscan)</td>

        <td>
          <CopyToClipboard>[https://monad.socialscan.io](https://monad.socialscan.io)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Network Visualization</td>

        <td>
          <CopyToClipboard>[https://gmonads.com](https://gmonads.com)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Current version / revision</td>
        <td>[`v0.13.1`](/developer-essentials/changelog/releases#v0131) / [`MONAD_NINE`](/developer-essentials/changelog#revisions)</td>
      </tr>
    </tbody>
  </table>
</div>

Other [block explorers](/tooling-and-infra/block-explorers) supported:

* Detailed traces: [Phalcon Explorer](https://blocksec.com/explorer) and [Tenderly](https://dashboard.tenderly.co/explorer)
* UserOps: [Jiffyscan](https://jiffyscan.xyz/?network=monad)

### Public RPC Endpoints

Public RPC endpoints are rate-limited but should be sufficient for basic usage. If you
need a higher-limit RPC endpoint, please see [RPC Providers](/tooling-and-infra/rpc-providers).

Websocket endpoints start with `wss://`. See [Websocket Reference](/reference/websockets) for
further information.

<div>
  <table>
    <thead>
      <tr>
        <th>RPC URL</th>
        <th>Provider</th>
        <th>Rate Limits</th>
        <th>Batch Call Limit</th>
        <th>Notes</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          <CopyToClipboard>`https://rpc.monad.xyz`</CopyToClipboard><br /><CopyToClipboard>`wss://rpc.monad.xyz`</CopyToClipboard>
        </td>

        <td>QuickNode</td>
        <td>25 rps</td>
        <td>100</td>

        <td />
      </tr>

      <tr>
        <td>
          <CopyToClipboard>`https://rpc1.monad.xyz`</CopyToClipboard><br /><CopyToClipboard>`wss://rpc1.monad.xyz`</CopyToClipboard>
        </td>

        <td>Alchemy</td>
        <td>15 rps</td>
        <td>100</td>
        <td>`debug_` and `trace_` methods disabled</td>
      </tr>

      <tr>
        <td>
          <CopyToClipboard>`https://rpc2.monad.xyz`</CopyToClipboard><br /><CopyToClipboard>`wss://rpc2.monad.xyz`</CopyToClipboard>
        </td>

        <td>Goldsky Edge</td>
        <td>300 per 10s</td>
        <td>10</td>
        <td>historical state lookups (e.g. `eth_call`) supported; see [discussion](/developer-essentials/historical-data)</td>
      </tr>

      <tr>
        <td>
          <CopyToClipboard>`https://rpc3.monad.xyz`</CopyToClipboard><br /><CopyToClipboard>`wss://rpc3.monad.xyz`</CopyToClipboard>
        </td>

        <td>Ankr</td>
        <td>300 per 10s</td>
        <td>10</td>
        <td>`debug_` methods disabled</td>
      </tr>

      <tr>
        <td>
          <CopyToClipboard>`https://rpc-mainnet.monadinfra.com`</CopyToClipboard><br /><CopyToClipboard>`wss://rpc-mainnet.monadinfra.com`</CopyToClipboard>
        </td>

        <td>MF</td>
        <td>20 rps</td>
        <td>1</td>
        <td>historical state lookups (e.g. `eth_call`) supported; see [discussion](/developer-essentials/historical-data)</td>
      </tr>
    </tbody>
  </table>
</div>

See [RPC Limits](/reference/rpc-limits) for additional detail on method-specific limits.

### Supported Infrastructure

See the [Tooling and Infrastructure](/tooling-and-infra) page for a list of providers
supporting mainnet.

### Canonical Contracts

<div>
  <table>
    <thead>
      <tr>
        <th>Name</th>
        <th>Address</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Wrapped MON</td>

        <td>
          <CopyToClipboard>[`0x3bd359C1119dA7Da1D913D1C4D2B7c461115433A`](https://monadvision.com/address/0x3bd359C1119dA7Da1D913D1C4D2B7c461115433A)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[Create2Deployer](https://github.com/pcaversaccio/create2deployer)</td>

        <td>
          <CopyToClipboard>[`0x13b0D85CcB8bf860b6b79AF3029fCA081AE9beF2`](https://monadvision.com/address/0x13b0D85CcB8bf860b6b79AF3029fCA081AE9beF2)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[CreateX](https://github.com/pcaversaccio/createx)</td>

        <td>
          <CopyToClipboard>[`0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed`](https://monadvision.com/address/0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[ERC-2470 Singleton Factory](https://eips.ethereum.org/EIPS/eip-2470)</td>

        <td>
          <CopyToClipboard>[`0xce0042b868300000d44a59004da54a005ffdcf9f`](https://monadvision.com/address/0xce0042b868300000d44a59004da54a005ffdcf9f)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[ERC-4337 EntryPoint v0.6](https://github.com/eth-infinitism/account-abstraction/blob/v0.6.0/contracts/core/EntryPoint.sol)</td>

        <td>
          <CopyToClipboard>[`0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789`](https://monadvision.com/address/0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[ERC-4337 SenderCreator v0.6](https://github.com/eth-infinitism/account-abstraction/blob/v0.6.0/contracts/core/SenderCreator.sol)</td>

        <td>
          <CopyToClipboard>[`0x7fc98430eAEdbb6070B35B39D798725049088348`](https://monadvision.com/address/0x7fc98430eAEdbb6070B35B39D798725049088348)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[ERC-4337 EntryPoint v0.7](https://github.com/eth-infinitism/account-abstraction/releases)</td>

        <td>
          <CopyToClipboard>[`0x0000000071727De22E5E9d8BAf0edAc6f37da032`](https://monadvision.com/address/0x0000000071727De22E5E9d8BAf0edAc6f37da032)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[ERC-4337 SenderCreator v0.7](https://github.com/eth-infinitism/account-abstraction/blob/v0.7.0/contracts/core/SenderCreator.sol)</td>

        <td>
          <CopyToClipboard>[`0xEFC2c1444eBCC4Db75e7613d20C6a62fF67A167C`](https://monadvision.com/address/0xEFC2c1444eBCC4Db75e7613d20C6a62fF67A167C)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[ERC-6492 UniversalSigValidator](https://eips.ethereum.org/EIPS/eip-6492)</td>

        <td>
          <CopyToClipboard>[`0xdAcD51A54883eb67D95FAEb2BBfdC4a9a6BD2a3B`](https://monadvision.com/address/0xdAcD51A54883eb67D95FAEb2BBfdC4a9a6BD2a3B)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[Foundry Deterministic Deployer](https://getfoundry.sh/guides/deterministic-deployments-using-create2/)</td>

        <td>
          <CopyToClipboard>[`0x4e59b44847b379578588920ca78fbf26c0b4956c`](https://monadvision.com/address/0x4e59b44847b379578588920ca78fbf26c0b4956c)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[Multicall3](https://www.multicall3.com/)</td>

        <td>
          <CopyToClipboard>[`0xcA11bde05977b3631167028862bE2a173976CA11`](https://monadvision.com/address/0xcA11bde05977b3631167028862bE2a173976CA11)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[MultiSend](https://github.com/safe-fndn/safe-smart-account/blob/v1.3.0/contracts/libraries/MultiSend.sol)</td>

        <td>
          <CopyToClipboard>[`0x998739BFdAAdde7C933B942a68053933098f9EDa`](https://monadvision.com/address/0x998739BFdAAdde7C933B942a68053933098f9EDa)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[MultiSendCallOnly](https://github.com/safe-fndn/safe-smart-account/blob/v1.3.0/contracts/libraries/MultiSendCallOnly.sol)</td>

        <td>
          <CopyToClipboard>[`0xA1dabEF33b3B82c7814B6D82A79e50F4AC44102B`](https://monadvision.com/address/0xA1dabEF33b3B82c7814B6D82A79e50F4AC44102B)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[Permit2](https://github.com/Uniswap/permit2)</td>

        <td>
          <CopyToClipboard>[`0x000000000022d473030f116ddee9f6b43ac78ba3`](https://monadvision.com/address/0x000000000022d473030f116ddee9f6b43ac78ba3)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[Safe](https://github.com/safe-fndn/safe-smart-account/blob/v1.3.0/contracts/GnosisSafe.sol)</td>

        <td>
          <CopyToClipboard>[`0x69f4D1788e39c87893C980c06EdF4b7f686e2938`](https://monadvision.com/address/0x69f4D1788e39c87893C980c06EdF4b7f686e2938)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[SafeL2](https://github.com/safe-fndn/safe-smart-account/blob/v1.3.0/contracts/GnosisSafeL2.sol)</td>

        <td>
          <CopyToClipboard>[`0xfb1bffC9d739B8D520DaF37dF666da4C687191EA`](https://monadvision.com/address/0xfb1bffC9d739B8D520DaF37dF666da4C687191EA)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[SafeSingletonFactory](https://github.com/safe-fndn/safe-singleton-factory/blob/main/source/deterministic-deployment-proxy.yul)</td>

        <td>
          <CopyToClipboard>[`0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7`](https://monadvision.com/address/0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[SimpleAccount](https://github.com/eth-infinitism/account-abstraction/blob/develop/contracts/accounts/SimpleAccount.sol)</td>

        <td>
          <CopyToClipboard>[`0x68641DE71cfEa5a5d0D29712449Ee254bb1400C2`](https://monadvision.com/address/0x68641DE71cfEa5a5d0D29712449Ee254bb1400C2)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[Simple7702Account](https://github.com/eth-infinitism/account-abstraction/blob/develop/contracts/accounts/Simple7702Account.sol)</td>

        <td>
          <CopyToClipboard>[`0xe6Cae83BdE06E4c305530e199D7217f42808555B`](https://monadvision.com/address/0xe6Cae83BdE06E4c305530e199D7217f42808555B)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[Sub Zero VanityMarket](https://github.com/Philogy/sub-zero-contracts)</td>

        <td>
          <CopyToClipboard>[`0x000000000000b361194cfe6312EE3210d53C15AA`](https://monadvision.com/address/0x000000000000b361194cfe6312EE3210d53C15AA)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[Zoltu Deterministic Deployment Proxy](https://github.com/Zoltu/deterministic-deployment-proxy)</td>

        <td>
          <CopyToClipboard>[`0x7A0D94F55792C434d74a40883C6ed8545E406D12`](https://monadvision.com/address/0x7A0D94F55792C434d74a40883C6ed8545E406D12)</CopyToClipboard>
        </td>
      </tr>
    </tbody>
  </table>
</div>

### Ecosystem contract addresses

See the [protocols](https://github.com/monad-crypto/protocols) repo.

### Tokens

See [Tokens and Bridges](/developer-essentials/network-information/tokens-and-bridges) or the [token-list](https://github.com/monad-crypto/token-list) repo.


# Tokens and Bridges
Source: https://docs.monad.xyz/developer-essentials/network-information/tokens-and-bridges



This page is generated from the [**token-list**](https://github.com/monad-crypto/token-list) repo. See the repo (or the [raw json](https://raw.githubusercontent.com/monad-crypto/token-list/refs/heads/main/tokenlist-mainnet.json)) for a fuller list of tokens.

<Info title="Bridging to Monad">
  Assets issued natively on another chain are bridged to Monad via a few different bridges, including LayerZero OFT, Chainlink CCIP, Hyperlane, and the 2/2 NTT Bridge, typically designated by the asset issuer.

  To bridge an asset to Monad, users typically have two options:

  1. Use a frontend integrating the native bridge, e.g.
     * [Stargate](https://stargate.finance/?dstChain=monad\&dstToken=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE) for LayerZero OFT
     * [Transporter](https://app.transporter.io/?tab=token\&to=monad) for Chainlink CCIP
     * [Nexus](http://nexus.hyperlane.xyz/) for Hyperlane
     * [MonadBridge](https://monadbridge.com/?toChain=Monad\&toToken=WETH\&fromChain=Ethereum\&fromToken=ETH) for 2/2 NTT
  2. Use a bridge aggregator that incorporates multiple solvers and cross-chain swaps, and has selective coverage of native bridges:
     * [Jumper](https://jumper.exchange/?fromChain=1\&toChain=143\&toToken=0x0000000000000000000000000000000000000000) - incorporates multiple solvers and select OFTs and CCIP-bridged assets via [Glacis](https://li.fi/knowledge-hub/li-fi-partners-with-glacis-to-accelerate-the-adoption-of-interop-token/).

  Option 1 ensures the native (wrapping/unwrapping) mechanism is considered, but Option 2 may be convenient if bridging from a remote chain or executing a cross-chain swap.

  The tables below link to the appropriate bridge (option 1) for each asset. Notable markets are linked based on TVL/volume.
</Info>

## Bridged Assets

### Dollar-related

<div>
  <table>
    <thead>
      <tr>
        <th>Symbol</th>
        <th>Name</th>
        <th>Address</th>
        <th>Bridge + Link</th>
        <th>Bridgeable from</th>
        <th>Select Markets</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>`AUSD`</td>
        <td>Agora USD</td>
        <td><CopyToClipboard>[`0x00000000eFE302BEAA2b3e6e1b18d08D69a9012a`](https://monadvision.com/token/0x00000000eFE302BEAA2b3e6e1b18d08D69a9012a)</CopyToClipboard></td>
        <td>LayerZero OFT ([Stargate](https://stargate.finance/?srcChain=ethereum\&srcToken=0x00000000eFE302BEAA2b3e6e1b18d08D69a9012a\&dstChain=monad\&dstToken=0x00000000eFE302BEAA2b3e6e1b18d08D69a9012a))</td>
        <td>Eth, Avax, Base</td>
        <td>[Curve 3pool](https://www.curve.finance/dex/monad/pools/factory-stable-ng-2)<br />[Uni AUSD/USDC](https://app.uniswap.org/explore/pools/monad/0xd112fde908d7342135fc7297cc53d25bf7a11d6c6e21fe7ac3e73c40f70827e8)</td>
      </tr>

      <tr>
        <td>`USDC`</td>
        <td>USD Coin</td>
        <td><CopyToClipboard>[`0x754704Bc059F8C67012fEd69BC8A327a5aafb603`](https://monadvision.com/token/0x754704Bc059F8C67012fEd69BC8A327a5aafb603)</CopyToClipboard></td>
        <td>Circle CCTP ([link](https://monadbridge.com/?fromChain=Ethereum\&fromToken=USDC\&toChain=Monad\&toToken=USDC))</td>
        <td>17 chains</td>
        <td>[Curve 3pool](https://www.curve.finance/dex/monad/pools/factory-stable-ng-2)</td>
      </tr>

      <tr>
        <td>`USDT0`</td>
        <td>Tether USD</td>
        <td><CopyToClipboard>[`0xe7cd86e13AC4309349F30B3435a9d337750fC82D`](https://monadvision.com/token/0xe7cd86e13AC4309349F30B3435a9d337750fC82D)</CopyToClipboard></td>
        <td>LayerZero OFT ([Stargate](https://stargate.finance/?srcChain=ethereum\&srcToken=0xdAC17F958D2ee523a2206206994597C13D831ec7\&dstChain=monad\&dstToken=0xe7cd86e13AC4309349F30B3435a9d337750fC82D))</td>
        <td>18 chains</td>
        <td>[Curve 3pool](https://www.curve.finance/dex/monad/pools/factory-stable-ng-2)<br />[Uni AUSD/USDT0](https://app.uniswap.org/explore/pools/monad/0xe56868928b91fcd5ebeada3d0ec8767f2bbfeb1e7da181203d13f6af76b03bf9)</td>
      </tr>

      <tr>
        <td>`USD1`</td>
        <td>USD1</td>
        <td><CopyToClipboard>[`0x111111d2bf19e43C34263401e0CAd979eD1cdb61`](https://monadvision.com/token/0x111111d2bf19e43C34263401e0CAd979eD1cdb61)</CopyToClipboard></td>
        <td>Chainlink CCIP ([Transporter](https://app.transporter.io/?from=mainnet\&tab=token\&to=monad\&token=USD1))</td>
        <td>Eth</td>
        <td>[PCS USD1/USDC](https://pancakeswap.finance/liquidity/pool/monad/0x8CcB070b6F871AbA552972c76D3b7DF8d88Ffa1a)</td>
      </tr>

      <tr>
        <td>`thBILL`</td>
        <td>Theo Short Duration UST Fund</td>
        <td><CopyToClipboard>[`0xfDD22Ce6D1F66bc0Ec89b20BF16CcB6670F55A5a`](https://monadvision.com/token/0xfDD22Ce6D1F66bc0Ec89b20BF16CcB6670F55A5a)</CopyToClipboard></td>
        <td>LayerZero OFT ([Stargate](https://stargate.finance/?srcChain=ethereum\&srcToken=0x5FA487BCa6158c64046B2813623e20755091DA0b\&dstChain=monad\&dstToken=0xfDD22Ce6D1F66bc0Ec89b20BF16CcB6670F55A5a))</td>
        <td>Eth, Arb, Base, +4</td>
        <td>[Uni thBILL/USDC](https://app.uniswap.org/explore/pools/monad/0xeF6F8aa2d7018b3A3b33cf214DebD87e9638e043)</td>
      </tr>

      <tr>
        <td>`wsrUSD`</td>
        <td>Wrapped srUSD</td>
        <td><CopyToClipboard>[`0x4809010926aec940b550D34a46A52739f996D75D`](https://monadvision.com/token/0x4809010926aec940b550D34a46A52739f996D75D)</CopyToClipboard></td>
        <td>LayerZero OFT ([Stargate](https://stargate.finance/?srcChain=ethereum\&srcToken=0xd3fD63209FA2D55B07A0f6db36C2f43900be3094\&dstChain=monad\&dstToken=0x4809010926aec940b550D34a46A52739f996D75D))</td>
        <td>Eth</td>

        <td />
      </tr>

      <tr>
        <td>`yzUSD`</td>
        <td>Yuzu USD</td>
        <td><CopyToClipboard>[`0x9dcB0D17eDDE04D27F387c89fECb78654C373858`](https://monadvision.com/token/0x9dcB0D17eDDE04D27F387c89fECb78654C373858)</CopyToClipboard></td>
        <td>LayerZero OFT ([Stargate](https://stargate.finance/?srcChain=ethereum\&srcToken=0x387167e5C088468906Bcd67C06746409a8E44abA\&dstChain=monad\&dstToken=0x9dcB0D17eDDE04D27F387c89fECb78654C373858))</td>
        <td>Eth, Plasma</td>

        <td />
      </tr>

      <tr>
        <td>`syzUSD`</td>
        <td>Staked Yuzu USD</td>
        <td><CopyToClipboard>[`0x484be0540aD49f351eaa04eeB35dF0f937D4E73f`](https://monadvision.com/token/0x484be0540aD49f351eaa04eeB35dF0f937D4E73f)</CopyToClipboard></td>
        <td>LayerZero OFT ([Stargate](https://stargate.finance/?srcChain=ethereum\&srcToken=0x6DFF69eb720986E98Bb3E8b26cb9E02Ec1a35D12\&dstChain=monad\&dstToken=0x484be0540aD49f351eaa04eeB35dF0f937D4E73f))</td>
        <td>Eth, Plasma</td>

        <td />
      </tr>
    </tbody>
  </table>
</div>

### Eth-related

<div>
  <table>
    <thead>
      <tr>
        <th>Symbol</th>
        <th>Name</th>
        <th>Address</th>
        <th>Bridge + Link</th>
        <th>Bridgeable from</th>
        <th>Select Markets</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>`WETH`</td>
        <td>Wrapped Ether</td>
        <td><CopyToClipboard>[`0xEE8c0E9f1BFFb4Eb878d8f15f368A02a35481242`](https://monadvision.com/token/0xEE8c0E9f1BFFb4Eb878d8f15f368A02a35481242)</CopyToClipboard></td>
        <td>NTT 2/2 ([MonadBridge](https://monadbridge.com/?fromChain=Ethereum\&fromToken=ETH\&toChain=Monad\&toToken=WETH))</td>
        <td>many</td>
        <td>[Uni WETH/MON](https://app.uniswap.org/explore/pools/monad/0x3783b51e33900eb366a9e8473c76cda441e7170d2e5d96927f30c16a7add93aa)<br />[Uni USDC/WETH](https://app.uniswap.org/explore/pools/monad/0xad408916c1c310da9c258d4c128a7bf50fd9edc42a218cc970da39cfc8a05d93)</td>
      </tr>

      <tr>
        <td>`ezETH`</td>
        <td>Renzo Restaked ETH</td>
        <td><CopyToClipboard>[`0x2416092f143378750bb29b79eD961ab195CcEea5`](https://monadvision.com/token/0x2416092f143378750bb29b79eD961ab195CcEea5)</CopyToClipboard></td>
        <td>Hyperlane ([Nexus](https://nexus.hyperlane.xyz/?token=ezETH\&origin=ethereum\&destination=monad))</td>
        <td>many</td>
        <td>[Curve ezETH/WETH](https://www.curve.finance/dex/monad/pools/factory-stable-ng-15)</td>
      </tr>

      <tr>
        <td>`rETH`</td>
        <td>Rocket Pool ETH</td>
        <td><CopyToClipboard>[`0xC50f2e735eDd9dCD8Ccd41EcFE9894E679e3195f`](https://monadvision.com/token/0xC50f2e735eDd9dCD8Ccd41EcFE9894E679e3195f)</CopyToClipboard></td>
        <td>Chainlink CCIP ([Transporter](https://app.transporter.io/?from=mainnet\&tab=token\&to=monad\&token=RETH))</td>
        <td>Eth</td>

        <td />
      </tr>

      <tr>
        <td>`wstETH`</td>
        <td>Lido Wrapped Staked ETH</td>
        <td><CopyToClipboard>[`0x10Aeaf63194db8d453d4D85a06E5eFE1dd0b5417`](https://monadvision.com/token/0x10Aeaf63194db8d453d4D85a06E5eFE1dd0b5417)</CopyToClipboard></td>
        <td>Chainlink CCIP ([Transporter](https://app.transporter.io/?tab=token\&to=monad\&token=wstETH))</td>
        <td>Eth, Ink, Plasma</td>
        <td>[Uni wstETH/WETH](https://app.uniswap.org/explore/pools/monad/0x55d7ed991392eb9597a76a5f41dfb964e291452c15107c0e64fd3d25925394ce)</td>
      </tr>

      <tr>
        <td>`weETH`</td>
        <td>Wrapped EtherFi ETH</td>
        <td><CopyToClipboard>[`0xA3D68b74bF0528fdD07263c60d6488749044914b`](https://monadvision.com/token/0xA3D68b74bF0528fdD07263c60d6488749044914b)</CopyToClipboard></td>
        <td>LayerZero OFT ([Stargate](https://stargate.finance/?srcChain=ethereum\&srcToken=0xCd5fE23C85820F7B72D0926FC9b05b43E359b7ee\&dstChain=monad\&dstToken=0xA3D68b74bF0528fdD07263c60d6488749044914b))</td>
        <td>Eth, Base</td>
        <td>[Uni weETH/WETH](https://app.uniswap.org/explore/pools/monad/0x2884b37c4a144e7047a1377ba7201d4b8ea318f0240369e01dc400f04e6cac40)</td>
      </tr>

      <tr>
        <td>`pufETH`</td>
        <td>pufETH</td>
        <td><CopyToClipboard>[`0x37D6382B6889cCeF8d6871A8b60E667115eDDBcF`](https://monadvision.com/token/0x37D6382B6889cCeF8d6871A8b60E667115eDDBcF)</CopyToClipboard></td>
        <td>LayerZero OFT ([Stargate](https://stargate.finance/?srcChain=ethereum\&srcToken=0xD9A442856C234a39a81a089C06451EBAa4306a72\&dstChain=monad\&dstToken=0x37D6382B6889cCeF8d6871A8b60E667115eDDBcF))</td>
        <td>Eth, Base, +3</td>

        <td />
      </tr>
    </tbody>
  </table>
</div>

### BTC-related

<div>
  <table>
    <thead>
      <tr>
        <th>Symbol</th>
        <th>Name</th>
        <th>Address</th>
        <th>Bridge + Link</th>
        <th>Bridgeable from</th>
        <th>Select Markets</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>`cbBTC`</td>
        <td>Coinbase Wrapped BTC</td>
        <td><CopyToClipboard>[`0xd18B7EC58Cdf4876f6AFebd3Ed1730e4Ce10414b`](https://monadvision.com/token/0xd18B7EC58Cdf4876f6AFebd3Ed1730e4Ce10414b)</CopyToClipboard></td>
        <td>Chainlink CCIP ([Transporter](https://app.transporter.io/?from=base\&tab=token\&to=monad\&token=cbBTC))</td>
        <td>Base</td>
        <td>[Curve cbBTC/WBTC/LBTC](https://www.curve.finance/dex/monad/pools/0xd2634e05ebed90bd0a6c0e93d48d7bd8036653b1)<br />[Uni USDC/cbBTC](https://app.uniswap.org/explore/pools/monad/0x7fc6232a9ec6cc4e9434640dcde5ee08ccae3b07de3247bf788fc9e2051b449e)</td>
      </tr>

      <tr>
        <td>`WBTC`</td>
        <td>Wrapped Bitcoin</td>
        <td><CopyToClipboard>[`0x0555E30da8f98308EdB960aa94C0Db47230d2B9c`](https://monadvision.com/token/0x0555E30da8f98308EdB960aa94C0Db47230d2B9c)</CopyToClipboard></td>
        <td>LayerZero OFT ([Stargate](https://stargate.finance/?srcChain=ethereum\&srcToken=0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599\&dstChain=monad\&dstToken=0x0555E30da8f98308EdB960aa94C0Db47230d2B9c))</td>
        <td>Eth, Base, +15</td>
        <td>[Curve cbBTC/WBTC/LBTC](https://www.curve.finance/dex/monad/pools/0xd2634e05ebed90bd0a6c0e93d48d7bd8036653b1)<br />[Uni MON/WBTC](https://app.uniswap.org/explore/pools/monad/0x1c93dd2f2f47439330150bf728c3beeaad71de45420a49183214898b044b65d1)<br />[Uni WBTC/USDC](https://app.uniswap.org/explore/pools/monad/0xd77c0f253764f5d5fbc78e13888afcc35c839262e6b21cd02baa9d8551a9898a)</td>
      </tr>

      <tr>
        <td>`LBTC`</td>
        <td>Lombard Staked Bitcoin</td>
        <td><CopyToClipboard>[`0xecAc9C5F704e954931349Da37F60E39f515c11c1`](https://monadvision.com/token/0xecAc9C5F704e954931349Da37F60E39f515c11c1)</CopyToClipboard></td>
        <td>Chainlink CCIP ([Transporter](https://app.transporter.io/?from=mainnet\&tab=token\&to=monad\&token=LBTC))</td>
        <td>Eth, Avax, Base, BNB, Sonic</td>
        <td>[Curve cbBTC/WBTC/LBTC](https://www.curve.finance/dex/monad/pools/0xd2634e05ebed90bd0a6c0e93d48d7bd8036653b1)<br />[Curve Bitcoin Converter](https://www.curve.finance/dex/monad/pools/factory-stable-ng-8)</td>
      </tr>

      <tr>
        <td>`BTC.b`</td>
        <td>BTC.b</td>
        <td><CopyToClipboard>[`0xB0F70C0bD6FD87dbEb7C10dC692a2a6106817072`](https://monadvision.com/token/0xB0F70C0bD6FD87dbEb7C10dC692a2a6106817072)</CopyToClipboard></td>
        <td>Chainlink CCIP ([Transporter](https://app.transporter.io/?from=mainnet\&tab=token\&to=monad\&token=BTC.b))</td>
        <td>Eth, Avax</td>
        <td>[Curve Bitcoin Converter](https://www.curve.finance/dex/monad/pools/factory-stable-ng-8)</td>
      </tr>

      <tr>
        <td>`SolvBTC`</td>
        <td>Solv BTC</td>
        <td><CopyToClipboard>[`0xaE4EFbc7736f963982aACb17EFA37fCBAb924cB3`](https://monadvision.com/token/0xaE4EFbc7736f963982aACb17EFA37fCBAb924cB3)</CopyToClipboard></td>
        <td>Chainlink CCIP ([Transporter](https://app.transporter.io/?from=mainnet\&tab=token\&to=monad\&token=SolvBTC))</td>
        <td>Eth</td>

        <td />
      </tr>

      <tr>
        <td>`xSolvBTC`</td>
        <td>xSolvBTC</td>
        <td><CopyToClipboard>[`0xc99F5c922DAE05B6e2ff83463ce705eF7C91F077`](https://monadvision.com/token/0xc99F5c922DAE05B6e2ff83463ce705eF7C91F077)</CopyToClipboard></td>
        <td>Chainlink CCIP ([Transporter](https://app.transporter.io/?from=mainnet\&tab=token\&to=monad\&token=xSolvBTC))</td>
        <td>Eth</td>

        <td />
      </tr>
    </tbody>
  </table>
</div>

### Others

<div>
  <table>
    <thead>
      <tr>
        <th>Symbol</th>
        <th>Name</th>
        <th>Address</th>
        <th>Bridge + Link</th>
        <th>Bridgeable from</th>
        <th>Select Markets</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>`WSOL`</td>
        <td>Wrapped SOL</td>
        <td><CopyToClipboard>[`0xea17E5a9efEBf1477dB45082d67010E2245217f1`](https://monadvision.com/token/0xea17E5a9efEBf1477dB45082d67010E2245217f1)</CopyToClipboard></td>
        <td>Wormhole ([Portal](https://monadbridge.com/?fromChain=Solana\&fromToken=SOL\&toChain=Monad\&toToken=SOL))</td>
        <td>many</td>

        <td />
      </tr>

      <tr>
        <td>`XAUt0`</td>
        <td>Tether Gold</td>
        <td><CopyToClipboard>[`0x01bFF41798a0BcF287b996046Ca68b395DbC1071`](https://monadvision.com/token/0x01bFF41798a0BcF287b996046Ca68b395DbC1071)</CopyToClipboard></td>
        <td>LayerZero OFT ([Stargate](https://stargate.finance/?srcChain=ethereum\&srcToken=0x68749665FF8D2d112Fa859AA293F07A622782F38\&dstChain=monad\&dstToken=0x01bFF41798a0BcF287b996046Ca68b395DbC1071))</td>
        <td>Eth, Arb, Sol, +10</td>
        <td>[Uni XAUt0/AUSD](https://app.uniswap.org/explore/pools/monad/0xe1a8600687e4d06ca4787e5d0ccdacb1d360bfc9ca6ca2a49a688e14d0ef37b4)</td>
      </tr>
    </tbody>
  </table>
</div>

## Natively-Issued Assets

<div>
  <table>
    <thead>
      <tr>
        <th>Symbol</th>
        <th>Name</th>
        <th>Address</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>`WMON`</td>
        <td>Wrapped MON</td>
        <td><CopyToClipboard>[`0x3bd359C1119dA7Da1D913D1C4D2B7c461115433A`](https://monadvision.com/token/0x3bd359C1119dA7Da1D913D1C4D2B7c461115433A)</CopyToClipboard></td>
      </tr>

      <tr>
        <td>`mEDGE`</td>
        <td>Midas mEDGE</td>
        <td><CopyToClipboard>[`0x1c8eE940B654bFCeD403f2A44C1603d5be0F50Fa`](https://monadvision.com/token/0x1c8eE940B654bFCeD403f2A44C1603d5be0F50Fa)</CopyToClipboard></td>
      </tr>
    </tbody>
  </table>
</div>

## Market Data

* [Defined](https://www.defined.fi/tokens/discover?network=mon)
* [GeckoTerminal](https://www.geckoterminal.com/monad/pools)
* [MonadVision Tokens](https://monadvision.com/tokens)
* [DeFiLlama Monad](https://defillama.com/chain/monad)

## Bridge Integrations

See [Cross-Chain](/tooling-and-infra/cross-chain) for a list of supported bridges and bridge aggregators.

## MON on other blockchains

<Accordion title="Partial list of wrapped MON addresses on other blockchains">
  <div>
    <table>
      <thead>
        <tr>
          <th>Name</th>
          <th>Blockchain</th>
          <th>Address</th>
          <th>Notes</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`WMON`</td>
          <td>Solana</td>

          <td>
            <CopyToClipboard>[`CrAr4RRJMBVwRsZtT62pEhfA9H5utymC2mVx8e7FreP2`](https://orb.helius.dev/address/CrAr4RRJMBVwRsZtT62pEhfA9H5utymC2mVx8e7FreP2)</CopyToClipboard>
          </td>

          <td />
        </tr>

        <tr>
          <td>`WMON`</td>
          <td>Ethereum</td>

          <td>
            <CopyToClipboard>[`0x6917037f8944201b2648198a89906edf863b9517`](https://etherscan.io/token/0x6917037f8944201b2648198a89906edf863b9517)</CopyToClipboard>
          </td>

          <td>2/2 NTT</td>
        </tr>
      </tbody>
    </table>
  </div>
</Accordion>


# Opcode Pricing
Source: https://docs.monad.xyz/developer-essentials/opcode-pricing



## Summary

Monad is a highly optimized system that introduces efficiencies across all dimensions -
compute, state access, and bandwidth utilization. However, the multiplier relative to legacy
EVM systems is not equal across all dimensions. As a result, some opcode gas price
changes are needed so that applications can unlock the full potential of the chain.

To minimize the number of gas price changes, rather than adjusting the gas pricing of almost
all opcodes down, Monad instead adjusts a few opcode prices up. This has the same relative
effect as discounting almost all opcodes.

The following costs are changed:

* [Cold access to state](#cold-access-cost)
* [A few precompiles](#precompiles)

All other costs are as on Ethereum; [evm.codes](https://www.evm.codes/) is a helpful reference.

<Note>
  These changes are covered formally in the
  [Monad Initial Spec Proposal](https://category-labs.github.io/category-research/monad-initial-spec-proposal.pdf)
</Note>

## Why are changes needed?

The EVM's current pricing model needs adaptation to support a high-performance, low-fee regime.
The pricing model assigns a weight (gas amount) to each opcode based on perceived costliness to
the system, then charges the user only based on the calculated sum of weights. As resource
scarcity changes - and especially in the event of a completely new system - those weightings
must be revised.

The changes described in this page make the minimal set of adjustments to allow Monad to
deliver high performance and low fees, while minimizing disruption to users and protecting
the system against DOS attacks.

## Cold access cost

To account for the relatively higher cost of state reads from disk when compared to computation in the Monad execution client,
the cost for "cold" account and storage access costs changes:

| Access Type | Ethereum | Monad |
| ----------- | -------- | ----- |
| Account     | 2600     | 10100 |
| Storage     | 2100     | 8100  |

The following opcodes are impacted because of the differed gas costs:

* Account access: `BALANCE`, `EXTCODESIZE`, `EXTCODECOPY`, `EXTCODEHASH`, `CALL`, `CALLCODE`,
  `DELEGATECALL`, `STATICCALL`, `SELFDESTRUCT`
* Storage access: `SLOAD`, `SSTORE`

<Note>
  Gas costs for warm account access (100 gas) and storage access (100 gas) are the same on Monad as on Ethereum.
</Note>

## Precompiles

A few [precompiles](/developer-essentials/precompiles) have been repriced to accurately reflect their relative costs in execution.

| Precompile   | Address | Ethereum            | Monad               | Multiplier |
| ------------ | ------- | ------------------- | ------------------- | ---------- |
| `ecRecover`  | `0x01`  | 3000                | 6000                | 2          |
| `ecAdd`      | `0x06`  | 150\*               | 300\*               | 2          |
| `ecMul`      | `0x07`  | 6000\*              | 30,000\*            | 5          |
| `ecPairing`  | `0x08`  | 45,000\*            | 225,000\*           | 5          |
| `blake2f`    | `0x09`  | $\text{rounds} * 1$ | $\text{rounds} * 2$ | 2          |
| `point eval` | `0x0a`  | 50,000              | 200,000             | 4          |

∗: Per input/operation, as defined in the respective precompile specification


# Precompiles
Source: https://docs.monad.xyz/developer-essentials/precompiles

How to use Monad's precompiled contracts

Precompiles are contracts at predefined addresses that provide cryptographic and utility functions
implemented natively rather than in EVM bytecode. They are callable like any other contract
via `CALL` or `STATICCALL`.

Monad supports all Ethereum precompiles as of the Fusaka fork (`0x01` to `0x11`), plus two
additional precompiles:

* **`0x0100`** — [P256 signature verification](#p256-signature-verification-0x0100) ([EIP-7951](https://eips.ethereum.org/EIPS/eip-7951))
* **`0x1000`** — [Staking precompile](#staking-precompile-0x1000)

## Ethereum precompiles

### Cryptographic and hashing

| Address | Name        | Gas                     | Description                   |
| ------- | ----------- | ----------------------- | ----------------------------- |
| `0x01`  | `ecRecover` | `6000`                  | ECDSA public key recovery     |
| `0x02`  | `sha256`    | `60 + 12 * word_size`   | SHA-256 hash function         |
| `0x03`  | `ripemd160` | `600 + 120 * word_size` | RIPEMD-160 hash function      |
| `0x09`  | `blake2f`   | `rounds * 2`            | BLAKE2 compression function F |

### Arithmetic and utility

| Address | Name       | Gas                                                | Description                                |
| ------- | ---------- | -------------------------------------------------- | ------------------------------------------ |
| `0x04`  | `identity` | `15 + 3 * word_size`                               | Returns the input unchanged                |
| `0x05`  | `modexp`   | [see evm.codes](https://www.evm.codes/precompiled) | Arbitrary-precision modular exponentiation |

### Elliptic curve alt\_bn128

| Address | Name        | Gas       | Description                          |
| ------- | ----------- | --------- | ------------------------------------ |
| `0x06`  | `ecAdd`     | `300`     | Point addition on alt\_bn128         |
| `0x07`  | `ecMul`     | `30,000`  | Scalar multiplication on alt\_bn128  |
| `0x08`  | `ecPairing` | `225,000` | Bilinear pairing check on alt\_bn128 |

### KZG commitment

| Address | Name         | Gas       | Description                                                                                                   |
| ------- | ------------ | --------- | ------------------------------------------------------------------------------------------------------------- |
| `0x0a`  | `point_eval` | `200,000` | KZG commitment verification ([EIP-4844](https://eips.ethereum.org/EIPS/eip-4844#point-evaluation-precompile)) |

### BLS12-381

These precompiles provide operations on the BLS12-381 curve per [EIP-2537](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2537.md).

| Address | Name                  | Gas                                                                           | Description                             |
| ------- | --------------------- | ----------------------------------------------------------------------------- | --------------------------------------- |
| `0x0b`  | `bls12_g1_add`        | `375`                                                                         | Point addition in G1                    |
| `0x0c`  | `bls12_g1_msm`        | [see EIP-2537](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2537.md) | Multi-scalar multiplication in G1       |
| `0x0d`  | `bls12_g2_add`        | `600`                                                                         | Point addition in G2                    |
| `0x0e`  | `bls12_g2_msm`        | [see EIP-2537](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2537.md) | Multi-scalar multiplication in G2       |
| `0x0f`  | `bls12_pairing_check` | [see EIP-2537](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2537.md) | Pairing check over (G1, G2) point pairs |
| `0x10`  | `bls12_map_fp_to_g1`  | `5500`                                                                        | Map base field element to G1 point      |
| `0x11`  | `bls12_map_fp2_to_g2` | `23800`                                                                       | Map extension field element to G2 point |

## P256 signature verification

Address `0x0100` verifies signatures on the `secp256r1` (P256) elliptic curve per
[EIP-7951](https://eips.ethereum.org/EIPS/eip-7951).

<Note>
  EIP-7951 supersedes [RIP-7212](https://github.com/ethereum/RIPs/blob/master/RIPS/rip-7212.md).
  If you are migrating from a chain that uses RIP-7212 at `0x100`, note that the address and
  interface are identical — only the EIP designation has changed.
</Note>

The P256 curve is used by WebAuthn, Apple Secure Enclave, Android Keystore, and hardware
security modules. With this precompile, you can verify passkey signatures on-chain, enabling
biometric authentication flows for smart accounts without relying on off-chain signature
verification.

### Input and output

The precompile accepts exactly **160 bytes**:

| Offset | Size     | Parameter | Description             |
| ------ | -------- | --------- | ----------------------- |
| 0      | 32 bytes | `hash`    | Message hash            |
| 32     | 32 bytes | `r`       | Signature component r   |
| 64     | 32 bytes | `s`       | Signature component s   |
| 96     | 32 bytes | `qx`      | Public key x-coordinate |
| 128    | 32 bytes | `qy`      | Public key y-coordinate |

All values are big-endian encoded as 256-bit unsigned integers.

**Returns:**

* `0x0000...0001` (32 bytes) on a valid signature
* Empty bytes on an invalid signature or malformed input

**Gas cost:** 6900

### Solidity example

```solidity theme={null}
address constant P256_VERIFY = address(0x0100);

function verifyP256Signature(
    bytes32 hash,
    uint256 r,
    uint256 s,
    uint256 qx,
    uint256 qy
) internal view returns (bool) {
    (bool success, bytes memory result) = P256_VERIFY.staticcall(
        abi.encodePacked(hash, r, s, qx, qy)
    );
    return success && result.length == 32 && abi.decode(result, (uint256)) == 1;
}
```

For passkey infrastructure and embedded wallet providers on Monad, see
[Embedded Wallets](/tooling-and-infra/wallet-infra/embedded-wallets).

## Staking precompile

Address `0x1000` provides the interface for validator delegation, undelegation, reward claims,
and staking queries. Gas costs vary by function.

* [Staking overview](/reference/staking/overview) — key concepts, common actions, and constraints
* [Staking API reference](/reference/staking/api) — full method signatures, parameters, gas costs, events, and ABI

## Gas pricing differences

A few precompiles (`0x01`, `0x06`, `0x07`, `0x08`, `0x09`, `0x0a`) are repriced relative to
Ethereum to reflect their relative costs in Monad's execution environment. The gas values in
the tables above reflect Monad's pricing. See
[Opcode pricing](/developer-essentials/opcode-pricing#precompiles) for a comparison.

## Source code

See the [precompile implementation](https://github.com/category-labs/monad/blob/main/category/execution/ethereum/precompiles.cpp).


# Reserve Balance
Source: https://docs.monad.xyz/developer-essentials/reserve-balance



## Introduction

The **Reserve Balance** mechanism is a set of light constraints - at consensus time on which
transactions can be **included**, and at execution time on which transactions **don't revert** - which
allow Monad to simultaneously support [asynchronous execution](/monad-arch/consensus/asynchronous-execution)
and [EIP-7702](/developer-essentials/eip-7702).

The Reserve Balance mechanism is designed to preserve safety under asynchronous execution
without interfering with normal usage patterns. **Most users and developers need not worry
about the Reserve Balance constraints**, however we provide the details here for those
encountering corner cases.

## Summary

Asynchronous execution means that nodes achieve consensus on a block proposal prior to executing
the transactions in that block. Execution is required to be completed in the next `k` (delay
factor) blocks. (Currently `k=3`. *NOTE*: In the context of discussing [block states](/monad-arch/consensus/block-states)
and [asynchronous execution](/monad-arch/consensus/asynchronous-execution), letter `D` is
usually used to denote the same parameter.)

Because consensus operates on a `k`-block delayed view of the global state, it is necessary
to adjust the consensus and execution rules slightly to allow consensus to safely build
and validate blocks that include only transactions whose gas costs can be paid for.

Monad introduces the **Reserve Balance** mechanism to allow consensus and execution
to collaborate across a multi-block lag to ensure that all EOAs must have enough MON
in their account to pay for gas for any transaction included in the blockchain.

<Info title="Inflight transaction">
  Throughout this document, an **inflight transaction** refers to a transaction that has
  been included in a block less than `k` blocks ago.
</Info>

Here is a very brief summary of the rules:

* From the perspective of a particular EOA, MON spent from that EOA in the course of a transaction
  is partitioned into two parts: **gas spend** and **value spend**.
  * In the case where the EOA was the sender:
    * **gas spend** is `gas_price * gas_limit`;
    * **value spend** is the `value` parameter on that transaction.
  * In the case where the EOA wasn't the sender (where they previously delegated via EIP-7702 and some other
    EOA submitted a transaction which called this EOA):
    * **gas spend** is 0;
    * **value spend** is whatever MON is sent out during the course of executing this EOA's code.
* Let `user_reserve_balance = 10 MON`
* *Execution time*: during execution, transactions revert due to **value spend** when that
  account's ending balance (before refunds) dips below `user_reserve_balance`, except in certain circumstances described below.
* *Consensus time*: For each account, consensus has a budget for the **gas spend** for all inflight
  transactions; this budget is `user_reserve_balance` (or the account's balance from the lagged
  execution state, whichever is lower). The budget is further reduced if the first inflight
  transaction earned the exception mentioned above, by that transaction's **value spend**.
  When performing block validity checks for block `n`, consensus checks that the budget is not exceeded.

<Info>
  See also the formal definition in the
  [Monad Initial Spec](https://category-labs.github.io/category-research/monad-initial-spec-proposal.pdf)
  proposal from Category Labs.
</Info>

## Parameters

| Parameter              | Value  |
| ---------------------- | ------ |
| `user_reserve_balance` | 10 MON |

## Why is reserve balance needed?

Monad has asynchronous execution: consensus is allowed to progress with building and
validating blocks without waiting for execution to catch up. Specifically, proposing
and validating consensus block `n` only requires knowledge of the state obtained after
applying block `n-k`.

While asynchronous execution has performance benefits, it introduces a novel challenge:
how is consensus supposed to know the validity of a block if it does not have the latest
state?

Let’s illustrate this challenge with an example (for our examples, we will use `k = 3`):

Consensus is validating block 4, which contains a transaction `t` from Alice with the
relevant fields as:

```
sender=Alice, to=Bob, value=100, gas=1
```

Consensus only has the state that was obtained by executing block 1:

```
block=1, balances={Alice: 110}
```

If consensus simply accepts block 4 as valid because Alice appears to have enough
balance, it risks a safety failure. For instance, Alice may have already spent her
balance in transaction `t’` in block 2. This creates a denial-of-service (DoS)
vector, as Alice could cause consensus to include many transactions for free.

## First attempt at a solution

One idea is for the consensus client to statically inspect transactions in blocks 2
and later, checking if Alice has spent any value in her transactions. This would let
consensus reject block 4 as invalid if any transaction before `t` (such as `t'`) in
blocks 2, 3, or 4 originates from Alice and spends some value or gas.

While this is a fine solution on the face of it, it suffers from two shortcomings:

1. Suppose, as part of smart contract execution in blocks 2 or 3, Alice received a lot
   of currency. She would have had enough balance to pay for transaction `t` despite
   `t'` existing, if only we had the latest state. So, rejecting transactions based
   solely on static checks is overly restrictive.

2. It is not only restrictive, it is also not safe with EIP-7702. With EIP-7702, Alice
   could have her account delegated to a smart contract, which can transfer out currency
   from Alice’s account in a way that is not statically inspectable by consensus.
   Concretely in our example, Alice does not need to send a transaction like `t'` from
   her account in order to spend currency from her account, if her account is delegated.
   A spend could potentially be triggered by a transaction submitted by anyone else.
   So our static check would not succeed and it may be unsafe to accept block 4 as valid
   even if we don’t see any other transaction from Alice in blocks 2, 3 and 4.

## Reserve balance as the solution

### Simple version

Intuitively, the core idea of reserve balance is as follows: if consensus and execution
agree ahead of time that, for each EOA, execution will prevent the ending balance from
dropping below a certain pre-determined threshold known to consensus (`user_reserve_balance`),
up to the sender's **gas spend** allowance, then consensus can safely include a series of transactions whose running
**gas spend** stays below `user_reserve_balance`, without knowing the latest state and
without being vulnerable to the DoS vector described above.

This concept can be generalized as follows:

* *Execution time*: after execution (before gas refunds), a reserve-balance check is applied to
  the ending balance. For a non-sender account, the ending balance must not be lower than
  `min(balance at transaction start, user_reserve_balance)`. For the sender, the ending balance may be lower
  by at most the transaction's **gas spend** (unless the emptying exception below applies).
  Excessive intermediate debits during execution are allowed as long as the ending balance is sufficient.
* *Consensus time*: For each account, consensus has a budget for the **gas spend** for all inflight
  transactions; this budget is `user_reserve_balance` (or the account's balance from the lagged
  execution state, whichever is lower).
  When performing block validity checks for block `n`, consensus checks that the budget is not exceeded.

In Monad, `user_reserve_balance` is currently set to `10 MON` for each EOA.

The above rule is sufficient to ensure all transactions included in consensus can be paid
for, thus solving our problem. However, it has a drawback, which is that EOAs can't spend
all of their MON, and EOAs with balances below `user_reserve_balance` won't be able to send
any successful transactions.

For instance, the following behaviors might be desired, but are currently blocked
by the above rule (with `user_reserve_balance` set to `10 MON`):

* Alice has a balance of 5 MON and wants to send 4.99 MON to Bob (plus pay 0.01 MON
  in gas)
* Alice has a balance of 20 MON and wants to swap 18 MON into a memecoin (plus pay
  0.01 MON in gas)

To address this, we add some additional conditions under which transactions are allowed.

### Addressing the drawback

First let's define an "emptying transaction":

<Info title="Emptying Transaction">
  A transaction is an **"emptying transaction"** iff

  * the sender is undelegated.
  * the sender has not sent any other transaction within the past `k` blocks.
  * nobody has sent a delegation or undelegation request for the sender within the past `k` blocks, including in this transaction.

  Such transactions are eligible for the emptying exception (see rules below).
</Info>

Notice that if a user account is **not** EIP-7702-delegated, then consensus can simply
inspect transactions statically in order to estimate the lowest a user’s balance can
possibly go. (This is because an undelegated user’s account can only be debited due to value
transfers and gas fees specified in the transaction data).

Therefore, we add the following exception to the reversion rule:

3. *Execution policy*: for each **undelegated** account sender:
   * *if* a transaction is an emptying transaction
   * *then* allow that transaction to proceed anyway (an "emptying transaction").
4. *Consensus policy*: for each **undelegated** account sender:
   * *if* a transaction is an emptying transaction
   * *then* statically inspect that transaction's total MON needs (i.e. `gas_bid * gas_limit + value`),
     and take into account the fact that execution will still allow this transaction through. This
     means that for any subsequent transactions in the next `k` blocks, the reserve balance that
     consensus is working with will be lower by `value`.

This rule lets execution allow consistently-undelegated accounts to dip below the reserve balance
once every `k` blocks. Since `k` blocks is 1.2 seconds, this policy should allow most small
accounts to still interact with the blockchain normally.
Note that an account is not eligible for the exception criteria if there was recent (within `k` blocks) undelegation request for the account even if it was already undelegated at that time.

See [Full specification](#full-specification) for details.

The additional policy allows both of the examples mentioned at the end of the previous section,
as long as they are the first transaction sent by the sender in `k` blocks.

## Discussion

### EIP-7702-delegated accounts

If an EOA is not EIP-7702-delegated, then the reserve balance is rarely invasive, even
if the EOA's balance is very low, because most transactions are the first transaction in `k=3` blocks
sent by that EOA.

But what if the EOA *is* EIP-7702-delegated? What is the impact?

* The only transactions that will revert are ones in which the balance of an EIP-7702-delegated EOA **dips below** 10 MON.
  * *'Dips below'* means *'decrements **and** drops below'*.
  * Transactions where the EOA's balance ends above or at 10 MON are fine.
  * Transactions where the EOA's balance is unchanged or increases are fine.
  * **Only** transactions that decrement the balance **and** result in a final balance
    below 10 MON are reverted.
  * Delegated EOAs cannot use the emptying exception described above.

For example, many sponsored gas workflows have users set up EIP-7702-delegated EOAs that
don't interact with MON at all (i.e. they start out empty, and only receive MON involuntarily).
Under a typical such workflow, a sponsor submits a transaction that calls into the EOA as
smart contract. This workflow works fine in Monad; it's fine for the EOA in question to
have a zero or very small balance.

The only case where a sponsored gas workflow will be blocked is if the EOA's balance is
(say) 6 MON, and the sponsored transaction calls code that tries to transfer (say) 1 MON out of the EOA.

### Transactions that are included but revert

Because of the Reserve Balance rules, you may see transactions *included* in the chain whose
execution *reverts*, such as transactions trying to transfer out more MON than are in the account
balance.

These transactions are still *valid* transactions that pay for gas, but the
*result* of these transactions is nothing except for gas being decremented from the sender.
They are included because at the time of consensus, the proposer cannot be sure that the account
isn't going to receive more MON from someone else, and the sender has the budget to pay for gas.

Ethereum includes many transactions whose execution reverts, so this is not a protocol difference.
However, in practice, Ethereum block builders may screen out transactions with insufficient balance
to process a transfer out, so this behavior may be different from what you're accustomed to seeing.

## Full specification

See the
[reserve balance spec](https://category-labs.github.io/category-research/monad-initial-spec-proposal.pdf)
for the formal set of Reserve Balance rules.

Algorithms 1 and 2 implement this check for consensus and execution, respectively.

Algorithm 3 implements the mechanism to detect the dipping into the reserve balance
(Algorithm 2 uses Algorithm 3 to revert transactions that dip).

Algorithm 4 specifies the criteria for emptying transactions:

* The sender account must be undelegated in the prior `k` blocks. This is checked
  statically by verifying the account was undelegated in a known state in the past
  `k` blocks, and there have been no delegation or undelegation requests in the last
  `k` blocks (this can be inspected statically).
* There must not be another transaction from the same sender in the prior k blocks.

Here is a quick summary of the reserve balance rules at consensus time:

#### If the account is not delegated and there are no inflight transactions

If the account is not delegated, and there are no previous inflight transactions, then consensus
checks that the gas fee for this transaction is less than the balance from the lagged state.

$$
\text{gas\_fees}(\text{tx}) \leq \text{balance}
$$

#### If the account is not delegated and has one emptying inflight transaction

If the account is not delegated, and there is one previous inflight transaction, then
consensus has to take into account the inflight transaction's total MON expenditures
(including `value`):

$$
\text{let adjusted\_balance} = \text{balance} - (\text{first\_tx.value} + \text{gas\_fees}(\text{first\_tx}))
$$

$$
\text{let } \text{reserve} = \min(\text{user\_reserve\_balance}(t.\text{sender}), \text{adjusted\_balance}) \quad
$$

A new transaction can only be included if the sum of all inflight transactions' gas fees
(excluding the first one) is less than the reserve:

$$
\sum_{tx \in I[1:]} \text{gas\_fees}(tx) \leq \text{reserve}
$$

#### All other cases

The reserve is equal to minimum of systemwide reserve balance (`10 MON`) or the
account's balance at block `n - k`:

$$
\text{reserve} = \min(\text{user\_reserve\_balance}(t.\text{sender}), \text{balance})
$$

A new transaction can only be included if the sum of all inflight transactions' gas fees
is less than the reserve:

$$
\sum_{tx \in I} \text{gas\_fees}(tx) \leq \text{reserve}
$$

## Adjusting the reserve balance

The reserve balance is currently the same for every account (`10 MON`).
In a future version, the protocol could allow users, through a stateful precompile, to
customize their reserve balance.

## Coq proofs

The safety of the reserve balance specification has been formally proved in Coq.

The full proofs documentation is available
[here](https://category-labs.github.io/category-research/reserve-balance-coq-proofs).

The consensus check is formalized in Coq as `consensusAcceptableTxs`. The predicate,
`consensusAcceptableTxs s ltx`, defines the criteria for the consensus module to accept
the list of transactions `ltx` on top of state `s`.

The proof shows that `consensusAcceptableTxs s ltx` implies that when the execution
module executes all the transactions in ltx one by one on top of s, none of them will
fail due to having insufficient balance to cover gas fees. The proof is by induction
on the list `ltx`: one can think of this as doing natural induction on the length of `ltx`.
The proof in the inductive step involves unfolding the definitions of the consensus
and execution checks and considering all the cases. In each case, the estimates of
effective reserve balance in consensus checks is shown to be conservative with respect
to what happens in execution.

## Additional examples

To test your understanding, here are some examples along with the expected outcome.
Each example is independent.

In the following examples, we use `start_block = 2`, meaning the initial balances
and reserves are after block 1. We also specify the reserve balance parameter for
each example, although it is a constant system wide parameter.

For each transaction, the expected result is indicated by a code:

* **2**: Successfully executed
* **1**: Included but reverted during execution (due to reserve balance dip)
* **0**: Excluded by consensus

### Example 1: Basic transaction inclusion

Initial state:

```
Alice: balance = 100, reserve = 10
Bob: balance = 5, reserve = 10
```

Transactions:

```
Block 2: [
  Alice: send 1 MON, fee 0.05 — Expected: 2
  Bob: send 2 MON, fee 0.05 — Expected: 2
]
```

Final balances:

```
Alice: 98.95
Bob: 2.95
```

### Example 2: Low reserve balance but high balance

Initial state:

```
Alice: balance = 100, reserve = 1
```

Transactions:

```
Block 2: [
  Alice: send 3 MON, fee 2 — Expected: 2 (emptying transaction)
  Alice: send 3 MON, fee 2 — Expected: 0 (excluded)
]
```

Final balance:

```
Alice: 95.0
```

### Example 3: Multi-block, low reserve but high balance

Initial state:

```
Alice: balance = 100, reserve = 1
```

Transactions:

```
Block 2: [
  Alice: send 3 MON, fee 2 — Expected: 2
]

Block 5: [
  Alice: send 3 MON, fee 2 — Expected: 2
]
```

Final balance:

```
Alice: 90.0
```

### Example 4: Comprehensive

Initial state:

```
Alice: balance = 100, reserve = 1
```

Transactions:

```
Block 2: [
  Alice: send 99 MON, fee 0.1 — Expected: 2 (large emptying transaction)
]

Block 3: [
  Alice: send 0.5 MON, fee 0.99 — Expected: 0 (excluded)
]

Block 4: [
  Alice: send 0.8 MON, fee 0.1 — Expected: 1 (included but reverted)
]

Block 5: [
  Alice: send 0 MON, fee 0.9 — Expected: 0 (excluded)
  Alice: send 5 MON, fee 0.1 — Expected: 1 (included but reverted)
  Alice: send 5 MON, fee 0.8 — Expected: 0 (excluded)
]
```

Final balance:

```
Alice: 0.70
```

### Example 5: Edge case — zero value transactions

Initial state:

```
Alice: balance = 2, reserve = 1
```

Transactions:

```
Block 2: [
  Alice: send 0 MON, fee 0.5 — Expected: 2
  Alice: send 0 MON, fee 0.6 — Expected: 2
  Alice: send 0 MON, fee 0.5 — Expected: 0 (exceeds reserve)
]
```

Final balance:

```
Alice: 0.9
```

### Example 6: Reserve balance boundary

Initial state:

```
Alice: balance = 10, reserve = 2
```

Transactions:

```
Block 2: [
  Alice: send 1 MON, fee 2 — Expected: 2 (matches reserve)
  Alice: send 0 MON, fee 0.01 — Expected: 2
]
```

Final balance:

```
Alice: 6.99
```

### Example 7: Account delegated in the interim

Initial state:

```
Alice: balance = 15, reserve = 10
```

Transactions:

```
Block 1: []

Block 2: [
  Alice is delegated
  Bob on behalf of Alice: send 5 MON, fee 0 — Expected: 2 (executed)
  Alice is undelegated
]

Block 3: [
  Alice: send 3 MON, fee 0.1 — Expected: 1 (included but reverted)
]

Block 4: []

Block 5: [
  Alice: send 0 MON, fee 8 - Expected: 2 (executed)
]
```

Final balance:

```
Alice: 1.9
```

**NOTE**: If execution would not have reverted transaction in `Block 3` (by checking delegation
status in prior `k` blocks), consensus would include transaction in `Block 5` which would later run
out of MON for the fee.

Also, consider `Block 2` is empty instead. Transaction in `Block 3` is then an emptying transaction,
which proceeds with execution, but transaction in `Block 5` is excluded as not having enough reserve
for fee.

### Example 8: Account receives MON before second inflight tx

Initial state:

```
Alice: balance = 15, reserve = 10
```

Transactions:

```
Block 1: []

Block 2: [
  Alice: send 6 MON, fee 0.1 - Expected: 2 (executed, emptying tx)
]

Block 3: [
  Alice receives 6 MON from a smart contract 
  Alice: send 7 MON, fee 0.1 — Expected: 1 (included but reverted, cannot be 2nd emptying so soon)
]

Block 4: []

Block 5: [
  Alice: send 0 MON, fee 8 - Expected: 2 (executed)
]
```

Final balance:

```
Alice: 6.8
```

**NOTE**: If execution would not have reverted the 2nd transaction in `Block 3` (from Alice; by
checking existence of emptying transactions in prior `k` blocks), consensus would include
transaction in `Block 5` which would later run out of MON for the fee.

Also, consider `Block 2` is empty instead. Transaction in `Block 3` (from Alice) is then an emptying
transaction, which proceeds with execution, but transaction in `Block 5` is excluded as one
potentially not having enough reserve for fee - consensus doesn't see Alice being credited in
`Block 3`.


# Deployment Summary for Developers
Source: https://docs.monad.xyz/developer-essentials/summary

Deployment Summary for Developers

This page summarizes what you need to know when developing or deploying smart contracts for
Monad.

## Start with

* [Network Information](/developer-essentials/network-information) - for RPC & block explorer URLs, and canonical
  contract deployments.
* [Differences between Monad and Ethereum](/developer-essentials/differences)
* [`protocols` repo](https://github.com/monad-crypto/protocols) (add yours!)
* [`token-list` repo](https://github.com/monad-crypto/token-list) (add yours!)
* [RPC API](/reference/json-rpc/) - an interactive reference

## Supported Tooling & Infra

Here are some of the most commonly-requested tools:

| Tool                                                    | Status | Notes                                                                   |
| ------------------------------------------------------- | ------ | ----------------------------------------------------------------------- |
| [Tenderly](https://dashboard.tenderly.co/explorer)      | ✅      |                                                                         |
| [Safe](https://app.safe.global)                         | ✅      |                                                                         |
| [Monadscan](https://monadscan.com) (by Etherscan)       | ✅      |                                                                         |
| [MonadVision](https://monadvision.com) (by Blockvision) | ✅      |                                                                         |
| [Foundry](https://getfoundry.sh)                        | ✅      | Use the [Monad Foundry](/tooling-and-infra/toolkits/monad-foundry) fork |
| [Viem](https://github.com/wevm/viem)                    | ✅      | `viem >= 2.40.0`                                                        |

<br />

See [Tooling and Infra](/tooling-and-infra) for a complete list of what is supported,
including:

| Category                                                                                                   |
| ---------------------------------------------------------------------------------------------------------- |
| [AA Infra](/tooling-and-infra/wallet-infra/account-abstraction)                                            |
| [Analytics](/tooling-and-infra/analytics)                                                                  |
| [Block Explorers](/tooling-and-infra/block-explorers)                                                      |
| [Cross-Chain](/tooling-and-infra/cross-chain)                                                              |
| [Custody](/tooling-and-infra/custody)                                                                      |
| [Embedded Wallets](/tooling-and-infra/wallet-infra/embedded-wallets)                                       |
| [Indexers - Common Data](/tooling-and-infra/indexers/common-data) (e.g. token balances, transfers, trades) |
| [Indexing Frameworks (incl Subgraphs)](/tooling-and-infra/indexers/indexing-frameworks)                    |
| [Onramps](/tooling-and-infra/onramps)                                                                      |
| [Oracles](/tooling-and-infra/oracles)                                                                      |
| [RPC Providers](/tooling-and-infra/rpc-providers)                                                          |

## Accounts

<div>
  <table>
    <thead>
      <tr>
        <th />

        <th />
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Address space</td>
        <td>Same address space as Ethereum (last 20 bytes of ECDSA public key)</td>
      </tr>

      <tr>
        <td>EIP-7702</td>
        <td>Supported. See [EIP-7702 reference](/developer-essentials/eip-7702)</td>
      </tr>
    </tbody>
  </table>
</div>

## Smart Contracts

For deployment and verification guides, see:

* [Deploy a Contract](/guides/deploy-smart-contract)
* [Verify a Contract](/guides/verify-smart-contract)
* [MonadVision verification guide](https://docs.blockvision.org/reference/verify-smart-contract-on-monad-explorer)

<div>
  <table>
    <thead>
      <tr>
        <th />

        <th />
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Opcodes</td>
        <td>All [opcodes](https://www.evm.codes/) as of the Fusaka fork are supported.</td>
      </tr>

      <tr>
        <td>Precompiles</td>
        <td>All Ethereum precompiles as of the Fusaka fork (`0x01` to `0x11`), plus P256 signature verification at `0x0100` ([EIP-7951](https://eips.ethereum.org/EIPS/eip-7951)) and the staking precompile at `0x1000`. See [Precompiles](/developer-essentials/precompiles)</td>
      </tr>

      <tr>
        <td>Max contract size</td>
        <td>128 kb (up from 24.5 kb in Ethereum)</td>
      </tr>
    </tbody>
  </table>
</div>

## Transaction types

Full article: [Transactions](/developer-essentials/transactions)

<div>
  <table>
    <thead>
      <tr>
        <th />

        <th />
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Transaction types</td>
        <td>Supported:
        <ul><li>0 ("legacy")</li>
        <li>1 ("EIP-2930")</li>
        <li>2 ("EIP-1559", the "default" on Ethereum)</li>
        <li>4 (["EIP-7702"](/developer-essentials/eip-7702))</li></ul>
        Not supported:
        <ul><li>3 ("EIP-4844")</li></ul></td>
      </tr>
    </tbody>
  </table>
</div>

## Gas limits

<div>
  <table>
    <thead>
      <tr>
        <th />

        <th />
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Per-transaction gas limit</td>
        <td>30M gas</td>
      </tr>

      <tr>
        <td>Block gas limit</td>
        <td>200M gas</td>
      </tr>

      <tr>
        <td>Block gas target</td>
        <td>80% (160M gas)</td>
      </tr>

      <tr>
        <td>Gas throughput</td>
        <td>500M gas/sec (200M gas/block divided by 0.4 sec/block)</td>
      </tr>
    </tbody>
  </table>
</div>

## Gas pricing

Full article: [Gas pricing](/developer-essentials/gas-pricing)

<div>
  <table>
    <thead>
      <tr>
        <th />

        <th />
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Gas charged</td>
        <td>The **gas limit** is what is charged. That is: total tokens deducted from the sender's balance is `value + gas_price * gas_limit`. See [discussion](/developer-essentials/gas-pricing#gas-limit-not-gas-used).</td>
      </tr>

      <tr>
        <td>EIP-1559 dynamics</td>
        <td>Monad is EIP-1559-compatible; base fee and priority fee work as on Ethereum. [EIP-1559 explainer](/developer-essentials/gas-pricing#eip-1559-compatibility)</td>
      </tr>

      <tr>
        <td>Base fee</td>
        <td>Min base fee of 100 MON-gwei (100 \* 10^-9 MON).<br />The base fee controller is similar to Ethereum's but stays elevated for less time ([details](/developer-essentials/gas-pricing#base_price_per_gas-controller)).</td>
      </tr>
    </tbody>
  </table>
</div>

## Opcode pricing

Full article: [Opcode Pricing](/developer-essentials/opcode-pricing)

Opcode pricing is the same as on Ethereum (see: [evm.codes](https://www.evm.codes/)), **except**
for the below repricings needed to reweight relative scarcities of resources due to Monad
optimizations.

<div>
  <table>
    <thead>
      <tr>
        <th>Item</th>
        <th>Ethereum</th>
        <th>Monad</th>
        <th>Notes</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Cold access cost - account</td>
        <td>2,600</td>
        <td>10,100</td>
        <td>Affected opcodes: `BALANCE`, `EXTCODESIZE`, `EXTCODECOPY`, `EXTCODEHASH`, `CALL`, `CALLCODE`, `DELEGATECALL`, `STATICCALL`, `SELFDESTRUCT`<br />See [details](/developer-essentials/opcode-pricing#cold-access-cost)</td>
      </tr>

      <tr>
        <td>Cold access cost - storage</td>
        <td>2,100</td>
        <td>8,100</td>
        <td>Affected opcodes: `SLOAD`, `SSTORE`. See [details](/developer-essentials/opcode-pricing#cold-access-cost)</td>
      </tr>

      <tr>
        <td>`ecRecover`, `ecAdd`, `ecMul`, `ecPairing`, `blake2f`, `point_eval` precompiles</td>

        <td />

        <td />

        <td>See [details](/developer-essentials/opcode-pricing#precompiles)<br /><br />Precompiles `0x01`, `0x06`, `0x07`, `0x08`, `0x09`, `0x0a`</td>
      </tr>
    </tbody>
  </table>
</div>

## Timing considerations

<div>
  <table>
    <thead>
      <tr>
        <th />

        <th />
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Block frequency</td>
        <td>400 ms</td>
      </tr>

      <tr>
        <td>`TIMESTAMP` opcode</td>
        <td>As in Ethereum, `TIMESTAMP` is a second-granularity unix timestamp. Since blocks
        are every 400 ms, this means that 2-3 blocks will likely have the same timestamp.</td>
      </tr>

      <tr>
        <td>Finality</td>
        <td>Blocks are finalized after two blocks (800 ms). Once a block is finalized, it
        cannot be reorged. See
        [MonadBFT](/monad-arch/consensus/monad-bft) for a fuller discussion.</td>
      </tr>

      <tr>
        <td>Speculative finality</td>
        <td>Blocks can be
        [speculatively finalized](/monad-arch/consensus/monad-bft#speculative-finality)
        after one block (400 ms), when it is marked as being in the `Voted` stage.<br /><br />
        Speculative finality can revert under very rare circumstances (see fuller discussion
        [here](/monad-arch/consensus/monad-bft#speculative-finality)).</td>
      </tr>
    </tbody>
  </table>
</div>

## Mempool

Full article: [Local Mempool](/monad-arch/consensus/local-mempool)

Monad does not have a global mempool, as this approach is not suitable for high-performance
blockchains.

Each validator maintains a local mempool with transactions that it is aware of. When an RPC
receives a transaction, it forwards it strategically to upcoming leaders, repeating this process
if it doesn't observe the transaction getting included.

Although this is an important part of Monad's design, it is not one that should generally affect
smart contract developers in their system designs.

## Parallel Execution and JIT Compilation

Monad utilizes [parallel execution](/monad-arch/execution/parallel-execution) and
[JIT compilation](/monad-arch/execution/native-compilation) for efficiency,
but smart contract developers don't need to change anything to account for this.

In Monad, transactions are still linearly ordered, and the only correct outcome of execution is
the result as if the transactions were serially executed. All aspects of parallel execution can
be treated by smart contract developers as implementation details.
See [further discussion](/monad-arch/execution/parallel-execution).

## Asynchronous Execution

Full article: [Asynchronous Execution](/monad-arch/consensus/asynchronous-execution)

Monad utilizes asynchronous execution for efficiency, but most developers shouldn't need to
change anything.

Developers with significant off-chain financial logic (e.g. exchanges, bridges, and
stablecoin/RWA issuers) should wait until blocks reach the
[`Verified`](/monad-arch/consensus/block-states#verified)
phase (aka state root finality), three blocks later than
[`Finalized`](/monad-arch/consensus/block-states#finalized),
to be sure that the entire network agrees with their own node's local execution of a
finalized block.

<Accordion title="Async execution and block stages">
  Asynchronous execution is a technique that allows Monad to substantially
  increase execution throughput by decoupling consensus from execution. In asynchronous execution,
  validators **vote first, execute later** - because once the transaction order is determined, the
  state is determined. Afterward, each node executes locally. There is a
  [delayed merkle root](/monad-arch/consensus/asynchronous-execution#delayed-merkle-root)
  three blocks later which confirms that the network got the same state trie as local execution.

  From the developer perspective:

  * Someone submits a transaction through your frontend which interacts with your smart contract.
    You make note of the hash.
  * A block gets [`Proposed`](/monad-arch/consensus/block-states#proposed) with the transaction included.
  * The block gets [`Voted`](/monad-arch/consensus/block-states#voted) (speculatively finalized)
    one block later. (`T+1`)
  * The block gets [`Finalized`](/monad-arch/consensus/block-states#finalized) one block later
    (`T+2`)
  * The block gets [`Verified`](/monad-arch/consensus/block-states#verified) (state root
    finalized) three blocks later (`T+5`)

  You listen for transaction receipts by calling
  [`eth_getTransactionReceipt`](/reference/json-rpc/eth_getTransactionReceipt).
  Receipts will first be available after a block becomes `Proposed` (speculatively executed).

  Your choice of when to update your UI to give feedback to the user depends on risk preference, but
  for most applications it is reasonable to do so when the block becomes `Proposed` because speculative
  finality reversion is extremely rare. A more conservative approach would be to wait until the
  block is `Finalized`, since then you will never have to handle a reorg. Waiting until `Verified`
  is not generally necessary (except for the aforementioned developers with off-chain financial
  logic).
</Accordion>

## Reserve balance

Full article: [Reserve Balance](/developer-essentials/reserve-balance)

Monad introduces the Reserve Balance mechanism to enable Asynchronous Execution.

The Reserve Balance mechanism places light restrictions on when transactions can be included at
consensus time, and imposes some conditions under which transactions will revert at execution time.

The Reserve Balance mechanism is designed to preserve safety under asynchronous execution without
interfering with normal usage patterns. Most users and developers need not worry about the Reserve
Balance constraints.

| Parameter               | Value  |
| ----------------------- | ------ |
| Default reserve balance | 10 MON |

## EIP-7702

EIP-7702 is supported; see the full notes [here](/developer-essentials/eip-7702).

There are two caveats:

1. If an EOA is EIP-7702-delegated, its balance cannot be lowered below 10 MON due to the
   [Reserve Balance](/developer-essentials/reserve-balance) rules. (If the delegation is removed, dipping below 10 MON
   is allowed.) [Discussion](/developer-essentials/eip-7702#delegated-eoas-cant-dip-below-10-mon).

2. If an EOA is EIP-7702-delegated, when it is called as a smart contract, the
   `CREATE` and `CREATE2` opcodes are banned. [Discussion](/developer-essentials/eip-7702#delegated-contract-code-cannot-call-createcreate2).

## Reading blockchain data

The following methods are supported for reading blockchain data:

<div>
  <table>
    <thead>
      <tr>
        <th />

        <th />
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>JSON-RPC</td>
        <td>See [RPC API](/reference/json-rpc). Monad supports all standard RPC methods
        from Ethereum. Differences are noted in [RPC Differences](/reference/rpc-differences). For rate limits, see [here](/reference/rpc-limits).</td>
      </tr>

      <tr>
        <td>WebSocket</td>
        <td>See the [WebSocket Guide](/reference/websockets).<br /><br />
        Monad implements the `eth_subscribe` method with the following subscription types:<ul>
        <li>`newHeads` and `logs`</li>
        <li>`monadNewHeads` and `monadLogs` (similar, but include additional data for tracking
        each block's progression through consensus)</li></ul>
        The `syncing` and `newPendingTransactions` subscription types are not supported.
        For more details see [Real-time Data Sources](/monad-arch/realtime-data/data-sources).</td>
      </tr>

      <tr>
        <td>Execution Events</td>
        <td>See [Execution Events](/execution-events).<br /><br />
        The Execution Events system allows developers to build high-performance applications
        that receive lowest-latency event data from a Monad node via shared memory queue.</td>
      </tr>
    </tbody>
  </table>
</div>

You can also use the supported [Indexers](/tooling-and-infra/indexers).

## Historic data

Monad full nodes provide access to all historic ledger data (blocks, transactions, receipts,
events, and traces). Monad full nodes do not provide access to arbitrary historic state as
discussed [here](/developer-essentials/historical-data).

There is a special RPC service at <CopyToClipboard>[`https://rpc-mainnet.monadinfra.com`](https://rpc-mainnet.monadinfra.com)</CopyToClipboard>
that provides access to historical data.

## Recommended Open Source Tooling Versions

* `foundry`: use the [Monad Foundry](/tooling-and-infra/toolkits/monad-foundry) fork, which incorporates Monad gas pricing and precompiles
* `viem >= 2.40.0` (just to bring in [monad.ts](https://github.com/wevm/viem/blob/main/src/chains/definitions/monad.ts))
* `alloy-chains >= 0.2.20`

## Canonical contract addresses

See [Canonical Contracts](/developer-essentials/network-information#canonical-contracts-on-testnet)

## Source code

* [`monad-bft`](https://github.com/category-labs/monad-bft) (consensus)
* [`monad`](https://github.com/category-labs/monad) (execution)

## Running a full node

See [Node Operations](/node-ops)

## Need Help?

Please ask in the [developer discord](https://discord.gg/monaddev). We are here to help!


# Network Information - Testnets
Source: https://docs.monad.xyz/developer-essentials/testnets



## Summary

| Network             | Purpose                                                                 |
| ------------------- | ----------------------------------------------------------------------- |
| [testnet](#testnet) | Primary testnet environment with hundreds of apps deployed              |
| [tempnet](#tempnet) | Transient network subject to resets; used as a sandbox for new features |

## testnet

<Warning title="Testnet Reset">
  `testnet` was [reset from genesis on 2025-12-16](/developer-essentials/changelog/testnet#v0125-2025-12-16). Canonical contracts listed below will be redeployed.
</Warning>

<div>
  <table>
    <thead>
      <tr>
        <th>Name</th>
        <th>Value</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Chain ID</td>

        <td>
          <CopyToClipboard>`10143`</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Network Name</td>

        <td>
          <CopyToClipboard>`Monad Testnet`</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Currency Symbol</td>

        <td>
          <CopyToClipboard>`MON`</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>RPC URL</td>
        <td>[see below](#public-rpc-endpoints)</td>
      </tr>

      <tr>
        <td>Block Explorer (MonadVision)</td>

        <td>
          <CopyToClipboard>[https://testnet.monadvision.com](https://testnet.monadvision.com)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Block Explorer (Monadscan)</td>

        <td>
          <CopyToClipboard>[https://testnet.monadscan.com](https://testnet.monadscan.com/)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Block Explorer (Socialscan)</td>

        <td>
          <CopyToClipboard>[https://monad-testnet.socialscan.io](https://monad-testnet.socialscan.io/)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Network visualization</td>

        <td>
          <CopyToClipboard>[https://www.gmonads.com/?network=testnet](https://www.gmonads.com/?network=testnet)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>App hub</td>
        <td>[https://testnet.monad.xyz/](https://testnet.monad.xyz/)</td>
      </tr>

      <tr>
        <td>Faucet</td>
        <td>[https://faucet.monad.xyz](https://faucet.monad.xyz)</td>
      </tr>

      <tr>
        <td>Current version / revision</td>
        <td>[`v0.13.1`](/developer-essentials/changelog/testnet#v0131-2026-03-16) / [`MONAD_NINE`](/developer-essentials/changelog#revisions)</td>
      </tr>

      <tr>
        <td>Changelog</td>
        <td>[(link)](/developer-essentials/changelog/testnet)</td>
      </tr>
    </tbody>
  </table>
</div>

### Public RPC Endpoints

Websocket endpoints start with `wss://`. See [Websocket Reference](/reference/websockets) for
further information.

<div>
  <table>
    <thead>
      <tr>
        <th>RPC URL</th>
        <th>Provider</th>
        <th>Rate Limits</th>
        <th>Batch Requests</th>
        <th>Archive Support</th>
        <th>Notes</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          <CopyToClipboard>`https://testnet-rpc.monad.xyz`</CopyToClipboard><br /><CopyToClipboard>`wss://testnet-rpc.monad.xyz`</CopyToClipboard>
        </td>

        <td>QuickNode</td>
        <td>50 rps</td>
        <td>100</td>
        <td>✅</td>
        <td>25 rps for `eth_call` and `eth_estimateGas`</td>
      </tr>

      <tr>
        <td>
          <CopyToClipboard>`https://rpc.ankr.com/monad_testnet`</CopyToClipboard>
        </td>

        <td>Ankr</td>
        <td>300 reqs / 10s<br /><br />12000 reqs / 10 min</td>
        <td>100</td>
        <td>❌</td>
        <td>`debug_*` methods are not allowed</td>
      </tr>

      <tr>
        <td>
          <CopyToClipboard>`https://rpc-testnet.monadinfra.com`</CopyToClipboard><br /><CopyToClipboard>`wss://rpc-testnet.monadinfra.com`</CopyToClipboard>
        </td>

        <td>Monad Foundation</td>
        <td>20 rps</td>
        <td>not allowed</td>
        <td>✅</td>

        <td />
      </tr>
    </tbody>
  </table>
</div>

See [RPC Limits](/reference/rpc-limits) for additional detail on method-specific limits.

### Canonical Contracts

<div>
  <table>
    <thead>
      <tr>
        <th>Name</th>
        <th>Address</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Wrapped MON</td>

        <td>
          <CopyToClipboard>[`0xFb8bf4c1CC7a94c73D209a149eA2AbEa852BC541`](https://testnet.monadvision.com/address/0xFb8bf4c1CC7a94c73D209a149eA2AbEa852BC541)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>CreateX</td>

        <td>
          <CopyToClipboard>[`0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed`](https://testnet.monadvision.com/address/0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Foundry Deterministic Deployer</td>

        <td>
          <CopyToClipboard>[`0x4e59b44847b379578588920ca78fbf26c0b4956c`](https://testnet.monadvision.com/address/0x4e59b44847b379578588920cA78FbF26c0B4956C)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>[ERC-6492 UniversalSigValidator](https://eips.ethereum.org/EIPS/eip-6492)</td>

        <td>
          <CopyToClipboard>[`0xdAcD51A54883eb67D95FAEb2BBfdC4a9a6BD2a3B`](https://testnet.monadvision.com/address/0xdAcD51A54883eb67D95FAEb2BBfdC4a9a6BD2a3B)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>EntryPoint v0.6</td>

        <td>
          <CopyToClipboard>[`0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789`](https://testnet.monadvision.com/address/0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>EntryPoint v0.7</td>

        <td>
          <CopyToClipboard>[`0x0000000071727De22E5E9d8BAf0edAc6f37da032`](https://testnet.monadvision.com/address/0x0000000071727De22E5E9d8BAf0edAc6f37da032)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Multicall3</td>

        <td>
          <CopyToClipboard>[`0xcA11bde05977b3631167028862bE2a173976CA11`](https://testnet.monadvision.com/address/0xcA11bde05977b3631167028862bE2a173976CA11)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Permit2</td>

        <td>
          <CopyToClipboard>[`0x000000000022d473030f116ddee9f6b43ac78ba3`](https://testnet.monadvision.com/address/0x000000000022d473030f116ddee9f6b43ac78ba3)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>SafeSingletonFactory</td>

        <td>
          <CopyToClipboard>[`0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7`](https://testnet.monadvision.com/address/0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7)</CopyToClipboard>
        </td>
      </tr>
    </tbody>
  </table>
</div>

#### Safe v1.4.1 Contracts

<div>
  <table>
    <thead>
      <tr>
        <th>Name</th>
        <th>Address</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Safe</td>

        <td>
          <CopyToClipboard>[`0x41675C099F32341bf84BFc5382aF534df5C7461a`](https://testnet.monadvision.com/address/0x41675C099F32341bf84BFc5382aF534df5C7461a)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>SafeL2</td>

        <td>
          <CopyToClipboard>[`0x29fcB43b46531BcA003ddC8FCB67FFE91900C762`](https://testnet.monadvision.com/address/0x29fcB43b46531BcA003ddC8FCB67FFE91900C762)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>SafeProxyFactory</td>

        <td>
          <CopyToClipboard>[`0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67`](https://testnet.monadvision.com/address/0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>MultiSend</td>

        <td>
          <CopyToClipboard>[`0x38869bf66a61cF6bDB996A6aE40D5853Fd43B526`](https://testnet.monadvision.com/address/0x38869bf66a61cF6bDB996A6aE40D5853Fd43B526)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>MultiSendCallOnly</td>

        <td>
          <CopyToClipboard>[`0x9641d764fc13c8B624c04430C7356C1C7C8102e2`](https://testnet.monadvision.com/address/0x9641d764fc13c8B624c04430C7356C1C7C8102e2)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>CompatibilityFallbackHandler</td>

        <td>
          <CopyToClipboard>[`0xfd0732Dc9E303f09fCEf3a7388Ad10A83459Ec99`](https://testnet.monadvision.com/address/0xfd0732Dc9E303f09fCEf3a7388Ad10A83459Ec99)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>SignMessageLib</td>

        <td>
          <CopyToClipboard>[`0xd53cd0aB83D845Ac265BE939c57F53AD838012c9`](https://testnet.monadvision.com/address/0xd53cd0aB83D845Ac265BE939c57F53AD838012c9)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>CreateCall</td>

        <td>
          <CopyToClipboard>[`0x9b35Af71d77eaf8d7e40252370304687390A1A52`](https://testnet.monadvision.com/address/0x9b35Af71d77eaf8d7e40252370304687390A1A52)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>SimulateTxAccessor</td>

        <td>
          <CopyToClipboard>[`0x3d4BA2E0884aa488718476ca2FB8Efc291A46199`](https://testnet.monadvision.com/address/0x3d4BA2E0884aa488718476ca2FB8Efc291A46199)</CopyToClipboard>
        </td>
      </tr>
    </tbody>
  </table>
</div>

### Testnet Tokens (partial list)

See [tokenlist-testnet.json](https://github.com/monad-crypto/token-list/blob/main/tokenlist-testnet.json).

## tempnet

`tempnet` runs the `devnet` ChainConfig with version `v0.12.3`.

<div>
  <table>
    <thead>
      <tr>
        <th>Name</th>
        <th>Value</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Purpose</td>
        <td>Transient network; sandbox for new features. Currently a sandbox for the [Opcode pricing changes](/developer-essentials/opcode-pricing)</td>
      </tr>

      <tr>
        <td>Chain ID</td>

        <td>
          <CopyToClipboard>`20143`</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>RPC URL</td>
        <td>Please submit [this form](https://tally.so/r/wLlvlj). You will need to join the [Monad Developer Discord](https://discord.gg/monaddev)</td>
      </tr>

      <tr>
        <td>Block Explorer</td>
        <td>n/a</td>
      </tr>

      <tr>
        <td>Faucet</td>
        <td>Please submit [this form](https://tally.so/r/wLlvlj). You will need to join the [Monad Developer Discord](https://discord.gg/monaddev)</td>
      </tr>

      <tr>
        <td>Current version / revision</td>
        <td>[`v0.12.3`](/developer-essentials/changelog/testnet#v0123-2025-12-04) / [`MONAD_EIGHT`](/developer-essentials/changelog#revisions)</td>
      </tr>
    </tbody>
  </table>
</div>


# Transactions
Source: https://docs.monad.xyz/developer-essentials/transactions



## Summary

* Same address space and transaction format/fields as Ethereum, so the same wallet software is
  supported.
* Transaction types 0 ("legacy"), 1 ("EIP-2930"), 2 ("EIP-1559"), and 4 ("EIP-7702") are currently supported.
* Pre-[EIP-155](https://eips.ethereum.org/EIPS/eip-155) transactions are allowed on the protocol
  level, as in Ethereum and many other EVM-compatible blockchains. As a result, users are
  discouraged from using an Ethereum address that had previously sent pre-EIP-155 transactions.

## Address space

Same address space as Ethereum (last 20 bytes of ECDSA public key)

## Transaction format

[Same as Ethereum](https://ethereum.org/en/developers/docs/transactions/). Monad transactions use
the same typed transaction envelope introduced in
[EIP-2718](https://eips.ethereum.org/EIPS/eip-2718), encoded with
[RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/).

## Transaction types

These [transaction types](https://ethereum.org/en/developers/docs/transactions/#typed-transaction-envelope)
are supported:

* Type 0 ("legacy")
* Type 1 (["EIP-2930"](https://eips.ethereum.org/EIPS/eip-2930))
* Type 2 (["EIP-1559"](https://eips.ethereum.org/EIPS/eip-1559); the default in Ethereum)
* Type 4 (["EIP-7702"](https://eips.ethereum.org/EIPS/eip-7702)) (see [EIP-7702 on Monad](/developer-essentials/eip-7702))

These types are not supported:

* Type 3 ("EIP-4844")

## Access lists

Access lists ([EIP-2930](https://eips.ethereum.org/EIPS/eip-2930)) are supported but not required.

## Transactions without a chain\_id

[EIP-155](https://eips.ethereum.org/EIPS/eip-155) introduced a transaction standard that includes a
chain id, to prevent transactions from one blockchain from being replayed on another one.

Transactions on Monad should always set the chain id, except for one very specific corner case:

<Note>
  **The corner case:** Some standard smart contracts such as ERC-1820 use a keyless deployment method
  (also known as Nick's method) that exploits replayability, as discussed
  [here](https://eips.ethereum.org/EIPS/eip-1820#deployment-method). In this method, a transaction is
  submitted on Ethereum but is intended to be replayed on other chains in order to have the contract
  deployed at the same address on other blockchains.
</Note>

In order to support this use case, pre-EIP-155 transactions are still allowed on the protocol level
(i.e. according to consensus rules) on Monad. This makes Monad consistent with most blockchains
including Ethereum. (Blockchains that have tried disallowing pre-EIP-155 transactions at the
protocol level have typically ended up reversing course, e.g.
[Celo](https://github.com/celo-org/celo-blockchain/issues/1734).)

However, because of this, please heed the following warning:

<Warning>
  Because replay of pre-EIP-155 transactions is allowed, it is discouraged to send funds to an
  Ethereum address that had previously sent pre-EIP-155 transactions.
</Warning>


# Advanced topics
Source: https://docs.monad.xyz/execution-events/advanced



## When are events published?

Execution events are recorded roughly "as they are happening" inside the
execution daemon: you see a `BLOCK_START` event at roughly the same moment
that the execution daemon beings processing a new block, followed by the
start of the first transaction (a `TXN_HEADER_START` event) about 1 millisecond
later. Most transaction-related events are recorded less than one
microsecond after the transaction they describe has completed.

Execution of a typical transaction will emit a few dozen events, but large
transactions can emit hundreds of events. The `TXN_EVM_OUTPUT` event -- which
is recorded as soon as the transaction is finished -- provides a summary
accounting of how many more events related to that transaction will follow
(how many logs, how many call frames, etc.), so that memory to store the
subsequent event data can be preallocated. For example in Rust,
[`Vec::reserve`](https://doc.rust-lang.org/std/vec/struct.Vec.html#method.reserve)
is often called here. An event like `TXN_EVM_OUTPUT` is referred as a "header
event" in the documentation: it is an event whose content describes some summary
information and the number of subsequent, related events that will be recorded
later with more details.

All these events are recorded as soon as the transaction is "committed" to the
currently-executing block. This happens before the block has finished
executing, and should not be confused with the unrelated notion of "commitment"
in the consensus algorithm. Although there are complex speculative execution
optimizations inside the execution daemon, the recording of a transaction takes
place when all work on a particular transaction has finished. This is referred
to as "transaction commit" time.

This is a different than the block-at-a-time style update you would see in,
for example, the Geth real-time events WebSocket protocol (which our RPC server
also [supports](/reference/websockets)). Certain properties of the block
(its hash, its state root, etc.) are not known at the time you see a
transaction's events, because the rest of the block is still executing. If you
would like block-at-a-time updates, the Rust SDK contains
[some utilities](/execution-events/rust-api#block-level-utilities)
which will aggregate the events back into complete, block-oriented updates.

One thing to be careful of: although transactions are always committed to a
block in index order, they might be recorded out of order. That is, you must
assume that the set of execution events that make up transactions 2 and 3
could be "mixed together" in any order. This is because of optimizations in
the event recording code path.

However, *for a particular transaction* (e.g., transaction 3) events pertaining
to that transaction are always recorded in the same order: first all of the
logs, then all the call frames, then all the state access records. Each of
these is recorded in *index order*, i.e., log 2 is always recorded before
log 3.

Consider the following diagram:

```
  ╔═Events═════════════════════════════╗
  ║                                    ║
  ║ ┌───────────────────────────────┐  ║
  ║ │ event type:  TXN_EVM_OUTPUT   │  ║
  ║ │ transaction: 1                │  ║
  ║ │ log count:   2                │  ║
  ║ └───────────────────────────────┘  ║
  ║                                    ║
  ║ ┌───────────────────────────────┐  ║
  ║ │ event type:  TXN_LOG          │  ║
  ║ │ transaction: 1                │  ║
  ║ │ log index:   0                │  ║
  ║ │ <log details>                 │  ║
  ║ └───────────────────────────────┘  ║
  ║                                    ║
  ║ ┌───────────────────────────────┐  ║
  ║ │ event type:  TXN_EVM_OUTPUT   │  ║
  ║ │ transaction: 0                │  ║
  ║ │ log count:   3                │  ║
  ║ └───────────────────────────────┘  ║
  ║                                    ║
  ║ ┌───────────────────────────────┐  ║
  ║ │ event type:  TXN_LOG          │  ║
  ║ │ transaction: 0                │  ║
  ║ │ log index:   0                │  ║
  ║ │ <log details>                 │  ║
  ║ └───────────────────────────────┘  ║
  ║                                    ║
  ║ ┌───────────────────────────────┐  ║
  ║ │ event type:  TXN_LOG          │  ║
  ║ │ transaction: 0                │  ║
  ║ │ log index:   1                │  ║
  ║ │ <log details>                 │  ║
  ║ └───────────────────────────────┘  ║
  ║                                    ║
  ║ ┌───────────────────────────────┐  ║
  ║ │ event type:  TXN_LOG          │  ║
  ║ │ transaction: 1                │  ║
  ║ │ log index:   1                │  ║
  ║ │ <log details>                 │  ║
  ║ └───────────────────────────────┘  ║
  ║                                    ║
  ║ ┌───────────────────────────────┐  ║
  ║ │ event type:  TXN_LOG          │  ║
  ║ │ transaction: 0                │  ║
  ║ │ log index:   2                │  ║
  ║ │ <log details>                 │  ║
  ║ └───────────────────────────────┘  ║
  ║                                    ║
  ╚════════════════════════════════════╝
```

A few things to note here:

* Unlike most diagrams in the documentation, the events are shown in a
  simplified, "merged" form; in real events, some of this information is
  stored in the event descriptor and some is stored in the event payload,
  but they're combined to make the diagram simpler

* It shows two transactions, with transaction indices 0 and 1. Although
  transaction 0 completes first in the EVM, its `TXN_EVM_OUTPUT` event is
  recorded *after* than the `TXN_EVM_OUTPUT` of transaction 1

* Events from the transactions are interleaved: sometimes the next one relates
  to transaction 0, sometimes to transaction 1, and there is no meaningful order
  between them

* Despite the transactions being out-of-order with respect to each other,
  all the events associated with a particular transaction are always in relative
  order, i.e., the log indicies for a particular transaction will always be seen
  in `log_index` order, as above

This is easy to understand if you imagine all of a transaction's events being
recorded by a different thread. For a particular transaction, its thread always
records that transaction's events in order, but the "transaction threads"
themselves race against each other, recording in a non-deterministic order.

This is similar to what really happens, except the transactions are recorded on
[fibers](https://en.wikipedia.org/wiki/Fiber_\(computer_science\)) rather than
full threads.

## Sequence numbers and the lifetime detection algorithm

All event descriptors are tagged with an incrementing sequence number
starting at 1. Sequence numbers are 64-bit unsigned integers which do not
repeat unless the execution daemon is restarted. Zero is not valid sequence
number.

Also note that the sequence number modulo the descriptor array size equals
the array index where the *next* event descriptor will be located. This is
shown below with a concrete example where the descriptor array size is 64.
Note that the last valid index in the array is 63, then access wraps around
to the beginning of the array at index 0.

```
                                                         ◇
                                                         │
  ╔═...═════════════════════════Event descriptor array═══╬═══════════════════...═╗
  ║                                                      │                       ║
  ║     ┌─Event────────┐┌─Event────────┐┌─Event────────┐ │ ┌─Event─────────┐     ║
  ║     │              ││              ││              │ │ │               │     ║
  ║     │ seqnum = 318 ││ seqnum = 319 ││ seqnum = 320 │ │ │ seqnum = 256  │     ║
  ║     │              ││              ││              │ │ │               │     ║
  ║     └──────────────┘└──▲───────────┘└──────────────┘ │ └───────────────┘     ║
  ║            61          │   62              63        │         0             ║
  ╚═...════════════════════╬═════════════════════════════╬═══════════════════...═╝
                           │                             │
                           ■                             ◇
                           Next event                    Ring buffer
                                                         wrap-around to
      ┌──────────────────────────────┐                   zero is here
      │last read sequence number     │
      │(last_seqno) is initially 318 │
      └──────────────────────────────┘
```

In this example:

* We keep track of the "last seen sequence number" (`last_seqno`) which has
  value `318` to start; being the "last" sequence number means we have already
  finished reading the event with this sequence number, which lives at array
  index `61`

* `318 % 64` is `62`, so we will find the potential next event at that index
  *if* it has been produced

* Observe that the sequence number of the item at index `62` is `319`, which
  is the last seen sequence number plus 1 (`319 == 318 + 1`). This means that
  event `319` has been produced, and its data can be safely read from that
  slot

* When we're ready to advance to the next event, the last seen sequence
  number will be incremented to `319`. As before, we can find the *next*
  event (if it has been produced) at `319 % 64 == 63`. The event at this
  index bears the sequence number `320`, which is again the last seen
  sequence number + 1, therefore this event is also valid

* When advancing a second time, we increment the last seen sequence number
  to `320`. This time, the event at index `320 % 64 == 0` is *not* `321`,
  but is a smaller number, `256`. This means the next event has not been
  written yet, and we are seeing an older event in the same slot. We've
  seen all of the currently available events, and will need to check again
  later once a new event is written

* Alternatively we might have seen a much larger sequence number, like
  `384` (`320 + 64`). This would mean that we consumed events too slowly, so
  slowly that the 63 events in the range `[321, 384)` were produced in the
  meantime. These were subsequently overwritten, and are now lost. They can
  be replayed using services external to event ring API, but *within* the
  event ring API itself there is no way to recover them

## Lifetime of an event payload, zero copy vs. memcpy APIs

Because of the descriptor overwrite behavior, an event descriptor might be
overwritten by the execution daemon while a reader is still examining its
data. To deal with this, the reader API makes a copy of the event descriptor.
If it detects that the event descriptor changed during the copy operation, it
reports a gap. Copying an event descriptor is fast, because it is only a
single cache line in size.

This is not the case for event payloads, which could potentially be very
large. This means a `memcpy(3)` of an event payload could be expensive, and
it would be advantageous to read the payload bytes directly from the payload
buffer's shared memory segment: a "zero-copy" API. This exposes the user to
the possibility that the event payload could be overwritten while still
using it, so two solutions are provided:

1. A simple detection mechanism allows payload overwrite to be detected at
   any time: the writer keeps track of the minimum payload offset value
   (*before* modular arithmetic is applied) that is still valid. If the
   offset value in the event descriptor is smaller than this, it is no
   longer safe to read the event payload

2. A payload `memcpy`-style API is also provided. This uses the detection
   mechanism above in the following way: first, the payload is copied to
   a user-provided buffer. Before returning, it checks if the lifetime
   remained valid after the copy finished. If so, then an overwrite did not
   occur during the copy, so the copy must be valid. Otherwise, the copy is
   invalid

The reason to prefer the zero-copy APIs is that they do less work. The
reason to prefer memcpy APIs is that it is not always easy (or possible) to
"undo" the work you did if you find out later that the event payload was
corrupted by an overwrite while you were working with it. The most logical
thing to do in that case is start by copying the data to stable location,
and if the copy isn't valid, to never start the operation.

An example user of the zero-copy API is the `eventwatch` example C program,
which can turn events into printed strings that are sent to `stdout`. The
expensive work of formatting a hexdump of the event payload is performed
using the original payload memory. If an overwrite happened during the
string formatting, the hexdump output buffer will be wrong, but that is OK:
it will not be sent to `stdout` until the end. Once formatting is complete,
`eventwatch` checks if the payload expired and if so, writes an error to
`stderr` instead of writing the formatted buffer to `stdout`.

Whether you should copy or not depends on the characteristics of the reader,
namely how easily it can deal with "aborting" processing.

## Location of event ring files

For performance reasons, we prefer that event ring files be created on a
[hugetlbfs](https://www.kernel.org/doc/html/v4.18/admin-guide/mm/hugetlbpage.html#hugetlbpage)
in-memory filesystem. Files created on such a filesystem will be backed by
physically-contiguous large pages, which improves performance by about 15% in
internal benchmarks.

This can be a hassle though: it is unusual for a program to require that a
file be placed on a *particular kind* of filesystem, and this requirement adds
some overhead. In practice, this means additional configuration steps that a
system administrator must perform when setting up a Monad node, and some
additional concepts that SDK users must learn about.

The issues are:

1. A hugetlbfs filesystem must be mounted somewhere on the host; usually by
   default (e.g., on a Ubuntu default installation) there will not be a
   hugetlbfs filesystem already present

2. Whomever configures a hugetlbfs filesystem must make sure that any user
   that needs to open the event ring file has the appropriate permissions

3. The path to the event ring file (which will be somewhere on that filesystem)
   must be passed into all programs that need to open it; since we don't know
   where the administrator will mount the filesystem, we can't easily hard-code
   a location for it in either the documentation or the source code

To simplify the developer experience as much as possible, we follow three
conventions. Each convention adds more "convenience default behavior" so that
everything will "just work" for most users, but you are free to ignore any of
the conventions and do things in your own way.

<Note title="hugetlbfs is not required">
  The event ring library does not require a hugetlbfs filesystem: it can work
  with *any* kind of regular file.  The C function that maps an event ring's
  shared memory segments -- `monad_event_ring_mmap` -- only takes a file
  descriptor, and does not know or care where this descriptor comes from. The
  only constraints on it are those placed by the `mmap(2)` system call itself.

  These conventions are about adding a reasonable default for how the mount
  point is set up, and helper functions for finding event ring files in that
  location. You should try to use them because they provide a performance
  benefit, but you are free to come up with a file descriptor in any way you
  wish and it will work with `monad_event_ring_mmap`.
</Note>

### Convention 1: libhugetlbfs in the node setup guide

The
[official guide](https://validator-docs.vercel.app/docs/full_node/events-and-websockets)
for setting up a local Monad node for execution events recommends the use
of `libhugetlbfs`.

`libhugetlbfs` is both a C library and a set of admin tools using that
library that follow a particular configuration convention. The idea is to
standardize some rules for how mount points and permissions are managed for
hugetlbfs filesystems. There are three parts to the basic idea:

1. Each user (or group if you want to do it that way) gets its own
   separately-mounted hugetlbfs filesystem. The mount point is located in a
   well-defined place under `/var/lib/hugetlbfs/user/<user-name>`[^1]

2. `hugeadm`, a program that a system administrator runs, is a configuration
   front-end for tasks like listing hugetlbfs mounts, creating new mounts, etc.

3. The C library, `libhugetlbfs`, helps client programs "find" hugetlbfs mounts
   that the current user has permission to access

The setup guide for the Monad node tells the user to install the `libhugetlbfs`
command line tools and to set up a "user mount" for the `monad` user. The guide
also recommends that all users be given access to enter this directory, so that
data consumer applications that run as non-`monad` users can open the file.

[^1]: Other configuration schemes are possible too, see
    [`man hugeadm`](https://linux.die.net/man/8/hugeadm)

### Convention 2: "default" event ring directory

The event ring library introduces the concept of a "default event ring
directory."  This is the default directory where event ring files should be
created, and thus where reader applications should look for them. This default
can come from one of two places:

1. You can provide it manually OR

2. If you don't provide it, the library will use a conventional location

The conventional location is a subdirectory called `event-rings`, created
directly under whatever hugetlbfs mount point is returned by `libhugeltbfs`[^2],
i.e., it is:

```
<libhugeltbfs-computed-mount-point>/event-rings
```

If you follow the setup guide to the letter, this should be:

```
/var/lib/hugetlbfs/user/monad/pagesize-2MB/event-rings
```

But depending on how your system is setup, `libhugetlbfs` could return a
different path. For example, you might see something like this:

```
/dev/hugepages/event-rings
```

This is because `libhugeltbfs` scrapes the contents of `/proc/mounts` and
returns only one path that the current user has
[access](https://man7.org/linux/man-pages/man2/access.2.html)
to. What if the user has access to multiple hugetlbfs mounts? There is no
logic to prefer one flavor of path over another, it only depends on their
relative ordering in the `/proc/mounts` file.

[^2]: The exact path might be user-dependent, and is determined by the
    function `hugetlbfs_find_path_for_size`

#### Providing the default event ring directory manually

You may wish to use this "open from the default directory" configuration idiom
while by-passing libhugetlbfs. The two reasons to do that are:

1. If you don't want the event ring file to be present on a hugetlbfs file
   system at all; this is usually when you want to create an event ring file
   larger than the hugetlbfs mount point (or the system's underlying pool of
   huge pages) would allow

2. If you do not want to use libhugetlbfs as a library dependency of your
   project, in which case you will want to set the CMake
   `MONAD_EVENT_USE_LIBHUGETLBFS` option to `OFF`

### Convention 3: event ring filename resolution

The "default directory" concept is used in the final convention, which is a
"convenience" API call for turning user input for an event ring file into
the path where your program will attempt to open that file.

It allows users to specify a filename such as `xyz` and have it be translated
to a full (and ugly) path like this:

```
/var/lib/hugetlbfs/user/monad/pagesize-2MB/event-rings/xyz
```

while still allowing the user to be able to specify *any* file, including one
not in the default directory, if they wish.

Here is how event ring file inputs are resolved by the the C function
`monad_event_ring_resolve_file` and the Rust function `EventRingPath::resolve`:

* If a "pure" filename is provided (i.e., a filename with no `/` character),
  it is resolved relative to a provided `default_path` directory

* Otherwise (i.e., if the file contains any `/` character), it is resolved
  relative to the current working directory; if `/` is the first character,
  it is resolved as an absolute path

This is similar to how a UNIX shell resolves a command name. A "pure" name
with no path characters is resolved relative to the entries in the `$PATH`
environment variable (i.e., it searches the default command directories). The
presence of a path-separator character causes the input to be treated like a
specific path relative to the current directory, which disables this "search".
This familiar principal applies here.

Furthermore:

* In C you usually pass the sentinel value `MONAD_EVENT_DEFAULT_HUGETLBFS`
  (which is just an alias for `nullptr`) as the `default_path` parameter; this
  causes `libhugetlbfs` to figure out what the default hugetlbfs root path
  should be[^3]; in Rust this is just `EventRingPath::resolve`

* You can provide your own `default_path` value, which can be on any path on
  any filesystem; this is required if you don't want `libhugetlbfs` as a
  dependency; in Rust this is `EventRingPath::resolve_with_default_path`

<Note title="Resolution is only about _generating_ path names">
  Resolution does not try to open a file: it just standardizes the convention for
  how to build a path string from the two inputs. Namely, it does not check
  whether the computed file path exists or not.

  Remember that the event ring library itself only cares about file descriptors,
  and none of its APIs (even the "helper" APIs) attempt to
  [open(2)](https://man7.org/linux/man-pages/man2/open.2.html) a file. They just
  provide "reasonable default" ways of locating files that programs can opt into.
  If your host needs to set up your filesystem mounts differently, you are free to
  do that.
</Note>

#### Examples

The table below shows how the C function `monad_event_ring_resolve_file`
behaves. `<cwd>` is the process' current working directory and `<htlbfs>`
is the mount point returned by `libhugetlbfs`.

| `default_path` value              | `input` value         | resolve file returns...                    | Notes                                                         |
| --------------------------------- | --------------------- | ------------------------------------------ | ------------------------------------------------------------- |
| `MONAD_EVENT_DEFAULT_HUGETLBFS`   | `"xyz"`               | `"<htlbfs>/event-rings/xyz"`               |                                                               |
| `MONAD_EVENT_DEFAULT_HUGETLBFS`   | `"a/b/c"`             | `"<cwd>/a/b/c"`                            | `default_path` only affects "pure" file names                 |
| `MONAD_EVENT_DEFAULT_HUGETLBFS  ` | `"/d/e/f"`            | `"/d/e/f"`                                 | absolute paths always remain absolute                         |
| `MONAD_EVENT_DEFAULT_HUGETLBFS`   | `"monad-exec-events"` | `"<htlbfs>/event-rings/monad-exec-events"` | the default event ring file name used by the execution daemon |
| `"/tmp/my-event-ring-path"`       | `"xyz"`               | `"/tmp/my-event-ring-path/xyz"`            | intermediate directories will be created if not existing      |
| `"/tmp/my-event-ring-path"`       | `"a/b/c"`             | `"<cwd>/a/b/c"`                            |                                                               |
| `"/tmp/my-event-ring-path"`       | `"/d/e/f"`            | `"/d/e/f"`                                 |                                                               |

In Rust, `EventRingPath::resolve` behaves like the `MONAD_EVENT_DEFAULT_HUGETLBFS`
rows, and `EventRingPath::resolve_with_default_path` takes an explicit
`basepath` argument and behaves like the bottom three rows.

[^3]: The actual function used is the event ring library's utility function
    `monad_event_open_hugetlbfs_dir_fd`, which adds in the `event-rings`
    subdirectory path component and creates it if it does not already exist


# C API
Source: https://docs.monad.xyz/execution-events/c-api



## Core concepts

There are two central objects in the event ring C API. They are:

1. **struct `monad_event_ring`** - represents an event ring whose shared memory
   segments have been mapped into the address space of the current process;
   the primary thing the client does with this object is use it to initialize
   iterators that point into the event ring, using the
   `monad_event_ring_init_iterator` function
2. **struct `monad_event_iterator`** - the star of the show: this iterator
   object is used to read sequential events. The iterator's `try_next`
   operation copies the current event descriptor (if it is available) and
   if successful, advances the iterator. Conceptually, it behaves like the
   expression `descriptor = *i++`, if an event descriptor is ready immediately
   (it does nothing otherwise)

The easiest way to understand the API is to compile and run the included
`eventwatch` example program. This program dumps ASCII representations of
execution events to `stdout`, as they are written by a execution daemon
running on the same host.

In `eventwatch`, the event descriptors are fully decoded, but the event
payloads are only shown in hexdump form, because this simple program that does
not include pretty-printing logic for all event payload types. The program is
only 250 lines of code, and reading through it should explain how the various
API calls fit together.

The SDK also includes C++20
[`std::formatter`](https://en.cppreference.com/w/cpp/utility/format/formatter.html)
specializations which can fully decode event payloads into human-readable form.
These are used by the `monad-event-cli` utility program.

## Using the API in your project

`libmonad_event` is designed for third party integration, so it does not have
any library dependencies aside from a recent version of glibc. This also means
it has no dependency on the rest of the monad repository or on its build
system: the sole requirement is a C compiler supporting C23.

The "Getting start" guide to building the C example program
[discusses several ways](/execution-events/getting-started/c#how-can-my-code-use-libmonad_eventa)
to use the SDK library as a third-party dependency in your code. Alternatively,
the source files that make up the library target can be copied into your own
codebase. A Rust client library is [also available](/execution-events/rust-api).

## API overview

### Event ring APIs

| API                               | Purpose                                                                                                                                               |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `monad_event_ring_mmap`           | Given a file descriptor to an open event ring file, map its shared memory segments into the current process, initializing a `struct monad_event_ring` |
| `monad_event_ring_init_iterator`  | Given a pointer to a `struct monad_event_ring`, initialize an iterator that can read from the event ring                                              |
| `monad_event_ring_try_copy`       | Given a specific sequence number, try to copy the event descriptor for it, if it hasn't been overwritten                                              |
| `monad_event_ring_payload_peek`   | Get a zero-copy pointer to an event payload                                                                                                           |
| `monad_event_ring_payload_check`  | Check if an event payload referred to by a zero-copy pointer has been overwritten                                                                     |
| `monad_event_ring_memcpy`         | `memcpy` the event payload to a buffer, succeeding only if the payload is not expired                                                                 |
| `monad_event_ring_get_last_error` | Return a human-readable string describing the last error that occurred on this thread                                                                 |

All functions which can fail will return an `errno(3)` domain error code
diagnosing the reason for failure. The function
`monad_event_ring_get_last_error` can be called to provide a human-readable
string explanation of what failed.

### Event iterator APIs

| API                                        | Purpose                                                                                                                  |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `monad_event_iterator_try_next`            | If an event descriptor if is available, copy it and advance the iterator; behaves like `*i++`, but only if `*i` is ready |
| `monad_event_iterator_try_copy`            | Copy the event descriptor at the current iteration point, without advancing the iterator                                 |
| `monad_event_iterator_reset`               | Reset the iterator to point to the most recently produced event descriptor; used for gap recovery                        |
| `monad_exec_iter_consensus_prev`           | Rewinds an iterator to the previous consensus event (`BLOCK_START`, `BLOCK_QC`, `BLOCK_FINALIZED`, or `BLOCK_VERIFIED`)  |
| `monad_exec_iter_block_number_prev`        | Rewinds an iterator to the previous consensus event for the given block number                                           |
| `monad_exec_iter_block_id_prev`            | Rewinds an iterator to the previous consensus event for the given block ID                                               |
| `monad_exec_iter_rewind_for_simple_replay` | Rewinds an iterator to replay events you may have missed, based on the last finalized block you saw                      |

### Event ring utility APIs

| API                                     | Purpose                                                                                                                              |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `monad_event_ring_check_content_type`   | Check if the binary layouts of event definitions used by the library match what is recorded in a mapped event ring                   |
| `monad_event_ring_find_writer_pids`     | Find processes that have opened an event ring file descriptor for writing; used for detecting publisher exit                         |
| `monad_check_path_supports_map_hugetlb` | Check if a path is on a filesystem that allows its files to be mmap'ed with `MAP_HUGETLB`                                            |
| `monad_event_open_hugetlbfs_dir_fd`     | Open the default hugetlbfs directory where event ring files are created[^1]                                                          |
| `monad_event_resolve_ring_file`         | If a path contains no `/` character (i.e., if it is a "pure" filename), resolve it relative to some default event ring directory[^2] |
| `monad_event_is_snapshot_file`          | Check if a path refers to an event ring snapshot file                                                                                |
| `monad_event_decompress_snapshot_fd`    | Decompress the event ring snapshot contained in the given file descriptor                                                            |
| `monad_event_decompress_snapshot_mem`   | Decompress the event ring snapshot contained in the given memory buffer                                                              |

[^1]: By default, this returns the a path on a hugetlbfs mount, as computed by
    libhugetlbfs

[^2]: If compiling with `MONAD_EVENT_USE_LIBHUGETLBFS=OFF`, a default event
    ring directory must be specified; see
    [here](/execution-events/advanced#location-of-event-ring-files) for details

## Library organization

Event ring files in `libmonad_event`:

| File                      | Contains                                                                                                              |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `event_ring.{h,c}`        | Definitions of core shared memory structures for event rings, and the API that initializes and mmaps event ring files |
| `event_iterator.h`        | Defines the basic event iterator object and its API                                                                   |
| `event_iterator_inline.h` | Definitions of the `event_iterator.h` functions, all of which are inlined for performance reasons                     |
| `event_metadata.h`        | Structures that describe event metadata (string names of events, descriptions of events, etc.)                        |
| `exec_iter_help.h`        | API for rewinding the the iterator to point to block executions or consensus events                                   |

Execution event files in `libmonad_event`:

| File                           | Contains                                                                                                      |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `base_ctypes.h`                | Definitions of basic vocabulary types common in Ethereum data (e.g., 256 bit integer types, etc).             |
| `eth_ctypes.h`                 | Definitions of structures used in the Ethereum virtual machine                                                |
| `exec_event_ctypes.h`          | Definition of execution event payload structures, and the event type enumeration `enum monad_exec_event_type` |
| `exec_event_ctypes_metadata.c` | Defines static metadata about execution events, and the schema hash value array                               |
| `monad_ctypes.h`               | Definitions of Monad blockchain extensions to Ethereum                                                        |

Supporting files in `libmonad_event`:

| File                    | Contains                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| `event_ring_util.{h,c}` | Convenience functions that are useful in most event ring programs, but which are not part of the core API     |
| `format_err.{h,c}`      | Helper utility from the execution codebase used to implement the `monad_event_ring_get_last_error()` function |
| `srcloc.h`              | Helper utility used with the `format_err.h` API, for capturing source code locations in C                     |

Other files in the SDK:

| File              | Contents                                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `eventwatch.c`    | A sample program that shows how to use the API                                                                     |
| `*_fmt.hpp` files | Files ending in `_fmt.hpp` are used with C++ `<format>` and contain `std::formatter` specializations for SDK types |
| `hex.hpp`         | `<format>` hexdump utility used by the `_fmt.hpp` files to dump `uint8_t[]` values                                 |


# Consensus events
Source: https://docs.monad.xyz/execution-events/consensus-events



As explained [here](/monad-arch/consensus/asynchronous-execution),
Monad's consensus and execution services are decoupled, and execution is
asynchronous with the respect to consensus: the two don't have to move in
lock step, and can working on different blocks. Also, execution can
[speculatively execute](/monad-arch/consensus/asynchronous-execution#speculative-execution)
blocks whose consensus outcome is not yet known.

Execution events are "trace" information reported directly from the EVM during
execution, so they report real-time data on *speculative* basis: the event data
may relate to a block that is never finalized.

Dealing with real-time data on a speculative basis is discussed in detail on
[this page](/monad-arch/realtime-data/spec-realtime). The "takeaway"
from that part of the documentation is the following: if you consume
speculative real-time data, then you need to understand
[block commit states](/monad-arch/consensus/block-states) and how the
real-time data protocol you're using communicates the changes in block states.

For example, for the Monad WebSocket extension feeds,
[this section](/reference/websockets#monadnewheads-and-monadlogs)
explains how the block IDs and commit states are announced for the
`monadNewHeads` subscription. This documentation page explains how it
is done with execution events.

## Block tags

As explained
[here](/monad-arch/realtime-data/spec-realtime#block-numbers-and-block-ids),
blocks must be identified by their unique ID prior to finalization. Even so,
it is often useful to know what the proposed block number is, even before we
know if the block will committed with that number or not. The following
structure -- called a "block tag" -- appears as a field in several execution
event payload types, to communicate the block ID and the (proposed) block
number together.

```
struct monad_exec_block_tag
{
    monad_c_bytes32 id;    ///< Monad consensus unique ID for block
    uint64_t block_number; ///< Proposal is to become this block
};
```

## The four consensus events

The four [block commit states](/monad-arch/consensus/block-states)
correspond to four execution event types. Events of these types are published
to announce that a particular block is moving to a new commit state.

### First consensus event: **`BLOCK_START`** (*proposed* state)

```c theme={null}
/// Event recorded at the start of block execution
struct monad_exec_block_start
{
    struct monad_exec_block_tag
        block_tag;                      ///< Execution is for this block
    uint64_t block_round;               ///< Round when block was proposed
    uint64_t epoch;                     ///< Epoch when block was proposed
    monad_c_bytes32 parent_eth_hash;    ///< Hash of Ethereum parent block
    monad_c_uint256_ne chain_id;        ///< Block chain we're associated with
    struct monad_c_eth_block_exec_input
        exec_input;                     ///< Ethereum execution inputs
};
```

The first event recorded by the EVM is a `BLOCK_START` event, whose event
payload contains a `block_tag` field that introduces the unique ID for the
block and the block number it will eventually have, if it gets finalized.

Almost all execution events (transaction logs, call frames, receipts, etc.)
occur between the `BLOCK_START` and `BLOCK_END` events. In the current
implementation, block execution is never pipelined, so all events between
`BLOCK_START` and `BLOCK_END` pertain to a single block, and there will not
be another `BLOCK_START` until the current block is ended.

Unlike the other events in this list, `BLOCK_START` is both a "consensus
event" (it means the associated block is in proposed state) and an "EVM event,"
because execution information about the block is being made available to you.

The other events in this list are not like that. They are "pure" consensus
events: they tell you what happened to a proposed block in the consensus
algorithm, after you've already seen all of its EVM events.

To understand the implications of this state, see
[here](/monad-arch/realtime-data/spec-realtime#first-commit-state-proposed).

<Note>
  There's no reason why a block *has* to start in the proposed state. If
  execution is lagging behind consensus, it's possible that a block might have
  advanced to a later state in the consensus algorithm. For example, suppose
  consensus has been working on a block for a while, and by the time execution
  finally sees it, perhaps consensus knows that it has progressed to voted.

  In the current implementation, however, execution will not know this. It
  implicitly considers everything it executes to only be proposed. This is only
  literally true if execution is not lagging behind.
</Note>

### Second consensus event: **`BLOCK_QC`** (*voted* state)

```c theme={null}
/// Event recorded when a proposed block obtains a quorum certificate
struct monad_exec_block_qc
{
    struct monad_exec_block_tag
        block_tag;              ///< QC for proposal with this block
    uint64_t round;             ///< Round of proposal vote
    uint64_t epoch;             ///< Epoch of proposal vote
};
```

When a block with the given tag is voted, an event of this type is published
to announce it. To understand all the implications of seeing this event, see
[here](/monad-arch/realtime-data/spec-realtime#second-commit-state-voted).

### Third consensus event: **`BLOCK_FINALIZED`**

```c theme={null}
/// Event recorded when consensus finalizes a block
typedef struct monad_exec_block_tag monad_exec_block_finalized;
```

The finalized event payload does not have any information that isn't already
part of the block tag, so the payload is just the tag of the block that gets
finalized. To understand all the implications of seeing this event, see
[here](/monad-arch/realtime-data/spec-realtime#third-commit-state-finalized).

### Fourth consensus event: **`BLOCK_VERIFIED`**

```c theme={null}
/// Event recorded when consensus verifies the state root of a finalized block
struct monad_exec_block_verified
{
    uint64_t block_number; ///< Number of verified block
};
```

The consensus algorithm produces one last event for a block, called
`BLOCK_VERIFIED`. This time, it is sufficient to identify the block only by
its block number. Because verified blocks are already finalized, they are
part of the canonical blockchain and cannot be reverted without a hard fork.
Thus, we no longer need the block tag.

To understand all the implications of seeing this event, see
[here](/monad-arch/realtime-data/spec-realtime#fourth-commit-state-verified).


# Event rings in detail
Source: https://docs.monad.xyz/execution-events/event-ring



## Event ring files and content types

Event rings are made up of four shared memory segments. Two of these -- the
event descriptor array and payload buffer -- are described in the
[overview documentation](/execution-events/overview).
The third shared memory segment contains a header that describes metadata
about the event ring. The fourth (the "context area") is a special feature
that is not needed for execution events.

The shared memory segments are mapped into a process' address space using
[mmap(2)](https://man7.org/linux/man-pages/man2/mmap.2.html). This means
that the event ring's data structures live in a file somewhere, and that
shared access to it is obtained by creating shared memory mappings of that
file.

Most of the time an event ring is a regular file, created on a special
in-memory file system called
[hugetlbfs](https://lwn.net/Articles/375096/). hugetlbfs is similar to the
[tmpfs](https://man7.org/linux/man-pages/man5/tmpfs.5.html) in-memory
filesystem, but supports the creation of files backed by large page sizes.
The use of large pages is just an
[optimization](https://lwn.net/Articles/374424/): event ring files may be
created on any file system. If the execution daemon is told to create an
event ring file on a filesystem without hugetlb mmap support, it will log a
performance warning but will still create the file. To learn more about
hugetlbfs and how it is used, read
[this page](/execution-events/advanced#location-of-event-ring-files).

### Event ring configuration

To use execution events, the execution daemon must be started with the command
line parameter:

```
--exec-event-ring [<event-ring-configuration-string>]
```

Without this command line parameter, execution will not publish any events.
This command line parameter (and mounting a hugetlbfs filesystem, for that
matter) are not part of the default configuration instructions for the
execution daemon. A
[separate guide](https://validator-docs.vercel.app/docs/full_node/events-and-websockets)
covers mounting a hugetlbfs filesystem and modifying the command line in
the systemd unit configuration files.

Note that the configuration string is optional; if you pass `--exec-event-ring`
without an argument (which is the recommended thing to do), this is equivalent
to passing `--exec-event-ring monad-exec-events`, where `monad-exec-events` is
the default execution event ring file name.

The event ring configuration string has the form:

```
<ring-name-or-file-path>[:<descriptor-shift>:<payload-buffer-shift>]
```

In other words, the configuration string consists of three `:`-separated
fields; the first field is required but the second two are optional. Here
is an example of the command line parameter, with just the first field:

```
--exec-event-ring /var/lib/hugetlbfs/user/monad/pagesize-2MB/event-rings/monad-exec-events
```

and another example, with all three:

```
--exec-event-ring monad-exec-events:21:29
```

The first field is the name of the event ring file. The execution daemon
interprets this field in two different ways:

* If it is purely a file name -- i.e., if the path does not contain any `/`
  characters -- then it is interpreted as a file living in the default
  event ring file directory; this is the directory returned by the API
  function `monad_event_open_ring_dir_fd`; it uses
  [libhugetlbfs](https://github.com/libhugetlbfs/libhugetlbfs) to locate
  the most suitable mount point for a hugetlbfs file system, and automatically
  creates subdirectory called `event-rings` underneath that, if it does not
  already exist (see [here](/execution-events/advanced#location-of-event-ring-files) for
  more information); the event ring file will be created in that `event-rings`
  subdirectory

* If the path has multiple path components -- i.e., if it contains at least
  one `/` character -- then this path will be used as written *even if* it is
  not resident on a hugetlbfs file system; the rationale for why someone
  might want this is explained below

The "shift" parameters are power-of-two exponents that determine the event
ring's size.[^1] A `<descriptor-shift>` of 21 means there will be 2^21
descriptors in the ring's event descriptor array. This means approximately 2
million events can be written before the descriptor ring buffer wraps around
and overwrites older event descriptors.

A `<payload-buffer-shift>` of 29 means there will be 2^29 bytes in the payload
buffer array. This means 512 MiB worth of event payloads can be recorded before
the payload buffer wraps around and overwrites an older event's payload.

If the event ring size parameters are not specified, then default values are
used. Why might you increase these values from their defaults? If your reader
program crashes, but execution does not, then you will likely miss some events
during the time when your program is not running. Your application might not
care about lost events for old blocks, but if it does, you'll need to retrieve
them somehow.

If not much time has gone by, chances are good that the events you are missing
are still sitting there in the event ring memory, i.e., are not overwritten
yet. The default sizes are large enough to hold several minutes worth of
blocks at 10k TPS. Increasing these values allows you to rewind further back
in time.

Be aware that there is a fixed-size pool of huge pages. The pool size can be
changed by modifying the system's configuration, see the discussion of
`/proc/sys/vm/nr_hugepages`
[here](https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt).

If an event ring is created on a hugetlbfs mount, and its size exceeds the
number of available huge pages, then the execution daemon will exit with an
error message that reports a "no space left on device" error. For example,
here we tried to allocate an event ring with a one terabyte payload buffer:

```
LOG_ERROR  event library error -- monad_event_ring_init_simple@event_ring_util.c:78:
posix_fallocate failed for event ring file `/dev/hugepages/monad-exec-events`, size 1099647942656: No space left on device (28)
```

If you happen to have multiple terabytes of main memory available, you
could pass a file path containing a `/` character to a file on a tmpfs
mount and it would work, e.g., `--exec-event-ring /my-giant-tmpfs/monad-exec-events`.

If you need to rewind back especially far -- or if you are missing events
because execution itself has crashed -- then you will need to use alternative
recovery methods described elsewhere.[^2]

[^1]: They are called "shifts" because `1UL << x` is equal to `2^x`

[^2]: The alternative recovery methods are still in development and will be
    available in the next SDK release

### Event ring file format

The event ring file format is simple: all four sections are laid out
sequentially and aligned to a large page boundary, and the header describes
the size of each section.

```
╔═Event ring file══╗
║ ┌──────────────┐ ║
║ │              │ ║
║ │    Header    │ ║
║ │              │ ║
║ ├──────────────┤ ║
║ │              │ ║
║ │    Event     │ ║
║ │  Descriptor  │ ║
║ │    Array     │ ║
║ │              │ ║
║ ├──────────────┤ ║
║ │              │ ║
║ │              │ ║
║ │              │ ║
║ │              │ ║
║ │   Payload    │ ║
║ │    Buffer    │ ║
║ │              │ ║
║ │              │ ║
║ │              │ ║
║ │              │ ║
║ │              │ ║
║ ├──────────────┤ ║
║ │              │ ║
║ │   Context    │ ║
║ │     Area     │ ║
║ │              │ ║
║ └──────────────┘ ║
╚══════════════════╝
```

The descriptor array is a just an array of `struct monad_event_descriptor`
objects, and the payload buffer is a flat byte array (i.e., it has type
`uint8_t[]`). The header structure is defined this way:

```c theme={null}
/// Event ring shared memory files start with this header structure
struct monad_event_ring_header
{
    char magic[6];                           ///< 'RINGvv', vv = version number
    enum monad_event_content_type
        content_type;                        ///< Kind of events in this ring
    uint8_t schema_hash[32];                 ///< Ensure event definitions match
    struct monad_event_ring_size size;       ///< Size of following structures
    struct monad_event_ring_control control; ///< Tracks ring's state/status
};
```

### Event content types

The `content_type` header field is needed because the event ring library --
both the reader and writer APIs -- performs unstructured I/O: the functions
read and write raw `uint8_t[]` event payloads, and the event descriptors
contain plain `uint16_t` numerical event codes. Much like the UNIX `read(2)`
and `write(2)` file I/O system calls, the event ring API functions do not
inherently know the format of data they are working with. This is the
reason why the `event_type` field in the event descriptor is the generic
integer type `uint16_t` instead of `enum monad_exec_event_type`.

The assumption here is that the reader and writer know the binary format of
the data they're both working with, and they treat the raw data as if it has
this format by type-casting it when needed, e.g.,

```c theme={null}
const struct monad_exec_block_start *block_start = nullptr;

// We assume that the event ring file we opened contains execution events,
// and thus further assume that it makes sense to compare `event->event_type`
// to a value of type `enum monad_exec_event_type`
if (event->event_type == MONAD_EXEC_BLOCK_START) {
    // Since this is MONAD_EXEC_BLOCK_START, we can cast the `const void *`
    // payload to a `const struct monad_exec_block_start *` payload.
    // Note: implicit type-casting from `void *` is allowed in C, but not C++
    block_start = monad_event_ring_payload_peek(event_ring, event);
}
```

We need some kind of error-detection mechanism to ensure this is safe to do.
The event ring file header contains a "content type" enumeration constant
explaining what kind of event data it contains:

```c theme={null}
enum monad_event_content_type : uint16_t
{
    MONAD_EVENT_CONTENT_TYPE_NONE,  ///< An invalid value
    MONAD_EVENT_CONTENT_TYPE_TEST,  ///< Used in simple automated tests
    MONAD_EVENT_CONTENT_TYPE_EXEC,  ///< Core execution events
    MONAD_EVENT_CONTENT_TYPE_PERF,  ///< Performance tracer events
    MONAD_EVENT_CONTENT_TYPE_COUNT  ///< Total number of known event rings
};
```

The execution events are always recorded to a ring with `content_type`
equal to `MONAD_EVENT_CONTENT_TYPE_EXEC`.

### Binary schema versioning: the `schema_hash` field

If `content_type` is equal to `MONAD_EVENT_CONTENT_TYPE_EXEC`, then we know a
ring is supposed to execution events, but what if the event payload definitions
change? Or what if the enumeration constants in `enum monad_exec_event_type`
change?

Suppose that a user compiles their application with a particular version
of `exec_event_ctypes.h`, the file which defines the execution event payloads
and the event type enumeration.

Now imagine that some time later, the user deploys a new version of the
execution node, which was compiled with a different version of
`exec_event_ctypes.h`, causing the memory representation of the event payloads
to be different.

If the reader does not remember to recompile their application with the new
header, it could misinterpret the bytes in the event payloads, assuming they
have the old layout from their old (compile-time) version of
`exec_event_ctypes.h`.

To prevent these kinds of errors, the binary layout of all event payloads is
summarized by a hash value which changes any time a change is made to any event
payload for that content type. In addition to payload changes, any change to
`enum monad_exec_event_type` will also generate a new hash.

This mechanism is called the "schema hash", and the hash value is present as
a global, read-only byte array inside the library code (defined in
`exec_event_ctypes_metadata.c`).

If the hash value in this array does not match the hash value in the event ring
file header, then the binary formats are incompatible.

A helper function called `monad_event_ring_check_content_type` is used to
check that an event ring file has both the expected content type, and the
expected schema hash for that content type. Here is an example of it being
called in the `eventwatch.c` sample program:

```c theme={null}
struct monad_event_ring exec_ring;

/* initialization of `exec_ring` not shown */

if (monad_event_ring_check_content_type(
        &exec_ring,
        MONAD_EVENT_CONTENT_TYPE_EXEC,
        g_monad_exec_event_schema_hash) != 0) {
    errx(EX_SOFTWARE, "event library error -- %s",
         monad_event_ring_get_last_error());
}
```

If the type of event ring is not `MONAD_EVENT_CONTENT_TYPE_EXEC` or if the
`schema_hash` in the file header does not match the value contained in the
global array `uint8_t g_monad_exec_event_schema_hash[32]`, this function will
return the `errno(3)` domain code `EPROTO`.

## Event descriptors in detail

### Binary format

The event descriptor is defined this way:

```c theme={null}
struct monad_event_descriptor
{
    alignas(64) uint64_t seqno;  ///< Sequence number, for gap/liveness check
    uint16_t event_type;         ///< What kind of event this is
    uint16_t : 16;               ///< Unused tail padding
    uint32_t payload_size;       ///< Size of event payload
    uint64_t record_epoch_nanos; ///< Time event was recorded
    uint64_t payload_buf_offset; ///< Unwrapped offset of payload in p. buf
    uint64_t content_ext[4];     ///< Extensions for particular content types
};
```

### Flow tags: the `content_ext` fields in execution event rings

For each content type, we may want to publish additional data directly in the
event descriptor, e.g., if that data is common to every payload type or if it
would help the reader quickly filter out events they are not interested in,
without needing to examine the event payload. This additional data is stored
in the `content_ext` ("content extensions") array, and its meaning is defined
by the `content_type`.

For execution event rings, the first three values of the `content_ext` array
are sometimes filled in. The value at each index in the array has the semantic
meaning described by the following enumeration type, which is defined in
`exec_event_ctypes.h`:

```c theme={null}
/// Stored in event descriptor's `content_ext` array to tag the
/// block & transaction context of event
enum monad_exec_flow_type : uint8_t
{
    MONAD_FLOW_BLOCK_SEQNO = 0,
    MONAD_FLOW_TXN_ID = 1,
    MONAD_FLOW_ACCOUNT_INDEX = 2,
};
```

For example, if we have an event descriptor

```c theme={null}
struct monad_event_descriptor event;
```

And its contents are initialized by a call to `monad_event_iterator_try_next`,
then `event.content_ext[MONAD_FLOW_TXN_ID]` will contains the "transaction ID"
for that event. The transaction ID is equal to the transaction index plus one,
and it is zero if the event has no associated transaction (e.g., the start of
a new block).

The idea behind the "flow" tags is that they tag events with the context they
belong to. For example, when a transaction accesses a particular account
storage key, a `STORAGE_ACCESS` event is emitted.

By looking at the `content_ext` array for the `STORAGE_ACCESS` event descriptor,
the reader can tell it is a storage access made (1) by the transaction with
index `event.content_ext[MONAD_FLOW_TXN_ID] - 1` and (2) to the account with
index `event.content_ext[MONAD_FLOW_ACCOUNT_INDEX]` (this index is related to
an earlier `ACCOUNT_ACCESS` event series that will have already been seen).

Flow tags are used for two reasons:

1. **Fast filtering** - if we are processing 10,000 transactions per second,
   and there are at least a dozen events per transaction, then we only have
   about 10 microseconds to process each event or we'll eventually fall behind
   and gap. At timescales like these, even touching the memory containing the
   event payload is expensive, on a relative basis. The event payload lives on
   a different cache line -- one that is not yet warm in the reader's CPU --
   and the cache line ownership must first be changed in the cache coherence
   protocol (because it was recently exclusively owned by the writer, and now
   must be shared with the reading CPU, causing cross-core bus traffic). For
   most applications, the user can identify transactions IDs they are
   interested in at the time of the `TXN_HEADER_START` event, and then any
   event without an interesting ID can be ignored. Because the IDs are a dense
   set of integers, a simple array of type `bool[TXN_COUNT + 1]` can be
   used to efficiently look up whether subsequent events associated with that
   transaction are interesting (this can be made even more efficient using
   a single bit instead of a full `bool` per transaction)

2. **Compression** - the account of a `STORAGE_ACCESS` is referred to by an
   index (which refers to an earlier `ACCOUNT_ACCESS` event) because an
   account address is 20 bytes: large enough that it cannot fit in the two
   remaining `content_ext` array slots

The compression technique is also used for storing the block associated with
an event, in `event.content_ext[MONAD_FLOW_BLOCK_SEQNO]`. The flow tag in this
case is the *sequence number* of the `BLOCK_START` event that started the
associated block. A few things to note about this flow tag:

* Sometimes it is zero (an invalid sequence number), which means the event
  is not associated with any block; although most events are scoped to a
  block, the consensus state change events (`BLOCK_QC`, `BLOCK_FINALIZED`,
  and `BLOCK_VERIFIED`) do not occur inside a block

* Note that the block flow tag is *not* the block number. This is because
  at the time events are seen, the blocks are in the "proposed" state, and
  the consensus algorithm has not finished voting on whether or not the block
  will be included in the canonical blockchain (this is discussed extensively
  in the next section). Until a block becomes finalized, the only unambiguous
  way to refer to it is by its unique ID, which is 32-byte hash value (which
  can be read from the `BLOCK_START` payload); thus the block flow tag is also
  a form of compression

* Having the sequence number allows us to rewind the iterator to the start
  of the block, if we start observing the event sequence in the middle of
  a block (e.g., if the reader starts up after the execution daemon). An
  example of this (and a detailed explanation of it) can be found in the
  `eventwatch.c` example program, in the `find_initial_iteration_point`
  function


# Building the C example program
Source: https://docs.monad.xyz/execution-events/getting-started/c



The C and C++ languages do not have a standard package manager, so using a
third-party library requires the programmer to come up with their own
dependency management scheme.

Before we perform the first step of the guide, we'll discuss the options the
user has for integrating the SDK library dependency into their project. Then
we'll pick one of these options and build the example program using that
method. A second method will be briefly shown at the end.

<Info>
  If you are not familiar with CMake, you may want to read CMake's
  ["Using Dependencies Guide"](https://cmake.org/cmake/help/latest/guide/using-dependencies/index.html)
  first
</Info>

### Where is the SDK source code?

The execution event C SDK lives in the same source code repository as the
execution daemon ([here](https://github.com/category-labs/monad)), in the
subdirectory [`category/event`](https://github.com/category-labs/monad/tree/main/category/event).
It has a separate `CMakeLists.txt` file that can act as a top-level project
file, so that users do not need to build the full execution project in order
to compile it.

The SDK's build system produces a library called `libmonad_event.a`, or
`libmonad_event.so` if you prefer shared libraries. You will also need the
public header files.

### How can my code use `libmonad_event.a`?

Here are three different options:

1. **Precompiled library** - you could build the library yourself and store
   the library file (and its headers) somewhere, then import it into your
   build system manually. The SDK build system also creates a CMake "config"
   file for use with
   [`find_package`](https://cmake.org/cmake/help/latest/command/find_package.html)
   to help import it, if you are also using CMake

The other two options assume your project is also using CMake:

2. **CMake subproject integration** - your CMake project can include the SDK
   as a subproject. In this case, you download the source code of the execution
   repository as part of your own project, and call the CMake function:

   ```
   add_subdirectory(<path-to-monad-repo>/category/event)
   ```

   This will add the SDK's library target (called `monad_event`) into your
   parent CMake project. One way to add the SDK code to your build is to use a
   [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules).
   Another way is to use CMake's
   [`FetchContent`](https://cmake.org/cmake/help/latest/module/FetchContent.html)
   module. The three main differences between these approaches are:

   1. By default, `FetchContent` will clone a git repository into your CMake
      build tree at build configuration time, whereas a git submodule
      integrates into your source tree at the repository level
   2. With `FetchContent`, the version you check out is specified by the
      `GIT_TAG` you specify in a `CMakeLists.txt` file; for `git submodule`,
      it is managed via git commands
   3. If the content you are fetching has its own CMake buildsystem (as the
      C SDK does), `FetchContent` will automatically call `add_subdirectory`
      to add it to the current project; in the git submodule approach, you
      need to do this manually

3. **CMake `ExternalProject` integration** - CMake's
   [`ExternalProject`](https://cmake.org/cmake/help/latest/module/ExternalProject.html)
   module is similar to `FetchContent`, but is more isolated; this will build
   and install the SDK into a "staging" directory somewhere in your CMake build
   tree. This uses a completely separate CMake invocation, so it will not add
   the SDK's CMake project into your own. This means, for example, that you will
   not automatically have a `monad_event` library target in your own CMake
   project -- you would need to create one as an imported target.
   `ExternalProject` helps isolate your build system from the SDK's build
   system, ensuring that CMake configuration and variables from the SDK can't
   "leak" into your parent project

In this guide, we'll use the `FetchContent` approach. This encapsulates the
entire process as a simple, all-in-one `CMakeLists.txt` file, and we comment
that file to explain everything you need to know.

This is the clear best choice for our tiny "Getting started" example program,
but it might not be best for your real project. At the end of this guide, an
alternative method using `find_package` is briefly shown.

## Building the example program with `FetchContent`

### Step 1: install prerequisite development packages

In addition to CMake (at least version 3.23) and git, we will need a recent C
compiler and two third-party libraries. We will also use
[curl](https://curl.se/docs/manpage.html)
to download some files.

#### Required C compiler

The C SDK uses some recent features from C23, and requires either gcc-13 or
clang-19. If the default compiler found by CMake is too old, you will need
to specify an alternative C compiler by setting the `CC` environment variable
or using a CMake [toolchain file](https://cmake.org/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html).

The default compiler chosen by CMake is usually the one reported by the output
of the command `cc -v`. If you need to use a different one, you can use the
bash syntax `VAR=VALUE <command>` for setting an environment variable in the
scope of the following command, e.g.:

```shell theme={null}
$ CC=gcc-15 cmake <args>
```

#### Required C++ compiler

C++ is not used in this example, but there are some optional C++ components in
the CMake project. Consequently, you must have a C++ compiler installed or the
CMake configuration step will fail.

<Info title="C++ in the SDK">
  The SDK is written in pure C, except for some C++ header files that can be used
  to "pretty-print" event types using the `<format>` library. These are not part
  of the example program, and they require full C++23 support for formatting
  ranges  (the `__cpp_lib_format_ranges` feature test macro) which were added to
  libstdc++ in gcc version 15.2. This is a recent release: the first time gcc 15.2
  appeared in the Ubuntu package repositories was in Ubuntu 25.10.

  You can also use clang with libc++, the LLVM implementation of the C++ standard
  library, which has had range formatting support since version 19. An example of
  building a C++ program with clang-19 is shown as the optional last step of the
  "Getting started" guide, when we build the `monad-event-cli` utility.
</Info>

#### Required third-party libraries

| Requirement  | Ubuntu package name | What is it used for?                                                                                        |
| ------------ | ------------------- | ----------------------------------------------------------------------------------------------------------- |
| zstd library | libzstd-dev         | Snapshot event ring files are compressed with zstd; `libzstd` is needed to decompress them                  |
| libhugetlbfs | libhugetlbfs-dev    | `libhugetlbfs` is used to locate the optimal hugetlbfs mount point to create event ring shared memory files |

`libzstd` is a hard requirement; `libhugetlbfs` is optional but is expected
by default on Linux. It can be turned off manually by setting the CMake option
`MONAD_EVENT_USE_LIBHUGETLBFS` to `OFF`.

#### macOS compatiblity

Real-time data requires a Linux host (because the execution daemon itself
does), but you can compile and run the example program on historical data
using macOS. This allows you to "try before you buy" and explore the SDK
before going through the trouble of setting up a Monad node on Linux.

In this case, you do not need `libhugetlbfs` (which is a Linux-only library),
but you will need a recent XCode toolchain, the `libzstd` compression
library, and CMake. The last two are not included in the default XCode
development tools, so you'll probably want to use
[Homebrew](https://brew.sh/) or
[MacPorts](https://www.macports.org/)
to install these onto your system. As for XCode itself, any version since
16.3 should work, but it has only been tested with version 23.2 (the real
requirement is for Apple Clang 17).[^1]

[^1]: "Apple Clang" is based on, but different than, vanilla LLVM
    [Clang](https://clang.llvm.org/). Apple Clang 17 is based on LLVM/Clang 19,
    thus the discrepancy in the requirements table.

### Step 2: download the example program

First, create a new directory and download the example program source file
into it. We'll use the example directory `~/src/event-sdk-example-c`

```shell theme={null}
$ mkdir -p ~/src/event-sdk-example-c
$ cd ~/src/event-sdk-example-c
$ curl -O https://raw.githubusercontent.com/category-labs/monad/refs/tags/release/exec-events-sdk-v1.1/category/event/example/eventwatch.c
```

You should now have a file called `eventwatch.c` in your new directory.

### Step 3: add a `CMakeLists.txt` build file

Create a `CMakeLists.txt` file in the directory alongside `eventwatch.c` and
copy these contents into it:

```CMakeLists.txt theme={null}
cmake_minimum_required(VERSION 3.23)

project(eventwatch LANGUAGES C)

#
# SDK setup
#

include(FetchContent)

FetchContent_Declare(exec_events_c_sdk
    # The execution events C SDK is kept in the same git repository as the
    # execution daemon itself
    GIT_REPOSITORY https://github.com/category-labs/monad.git

    # The latest version of the SDK is available on a special release branch
    # of the execution repository
    GIT_TAG release/exec-events-sdk-v1.1

    # This will only download the SDK branch
    GIT_SHALLOW TRUE

    # This will disable the checkout of all git submodules; they are needed
    # for the full execution daemon to build, but not the SDK
    GIT_SUBMODULES ""

    # The top-level CMakeLists.txt builds the entire execution daemon; we don't
    # want that, so we specify SOURCE_SUBDIR to choose a CMakeLists.txt file
    # in a sudirectory to treat as the "top-level" file for the external
    # project; this only creates the monad_event library
    SOURCE_SUBDIR category/event)

# The SDK's build system also builds the same example we're building now, using
# the same target name ('eventwatch'). This is done as a CI check to ensure
# that the upstream project doesn't break the example program. We have to
# disable it, because it will conflict with the eventwatch target we're going
# to add below (CMake does not allow two targets with the same name)
set(MONAD_EVENT_BUILD_EXAMPLE OFF CACHE INTERNAL "")

# This will download the source code and call add_subdirectory, which will add
# the `monad_event` library target; this is the SDK target we need to link
FetchContent_MakeAvailable(exec_events_c_sdk)

#
# eventwatch example program target
#

add_executable(eventwatch eventwatch.c)
target_compile_options(eventwatch PRIVATE -Wall -Wextra -Wconversion -Werror)
target_link_libraries(eventwatch PRIVATE monad_event)
```

### Step 4: run CMake and build

#### CMake with `make` and the default compiler:

```shell theme={null}
$ cmake -S ~/src/event-sdk-example-c -B ~/src/event-sdk-example-c/build
$ cd ~/src/event-sdk-example-c/build
$ make
```

#### CMake with `ninja` and an alternate compiler:

Here is another possible invocation, which sets an alternative C compiler using
the `CC` environment variable and uses the [Ninja](https://ninja-build.org/)
build tool:

```shell theme={null}
$ CC=clang-19 cmake -S ~/src/event-sdk-example-c -B ~/src/event-sdk-example-c/build -G Ninja
$ cd ~/src/event-sdk-example-c/build
$ ninja
```

The compilation should produce an executable file called `eventwatch`. Try
running it with the `-h` flag to print the help.

```shell theme={null}
$ ./eventwatch -h
usage: eventwatch [-h] [<exec-event-ring>]

execution event observer example program

Options:
  -h | --help   print this message

Positional arguments:
  <exec-event-ring>   path of execution event ring shared memory file
                        [default: monad-exec-events]
```

If all was successful, continue on to the [next step in the guide](/execution-events/getting-started/snapshot)
or if you are also interested in Rust, build the
[Rust example program](/execution-events/getting-started/rust). The Rust example program prints more
interesting output than the C version, thanks to Rust's
[`#[derive(Debug)]`](https://doc.rust-lang.org/rust-by-example/hello/print/print_debug.html)
attribute, so the "Getting started" experience is better in Rust. You can do
an equivalent thing in C++ by using the aformentioned `std::formatter`
specializations, but they're not in the tutorial.

You can also continue on to the next section on this page, which shows a
different way of integrating with the C library.

## Alternative: install locally, find with `find_package`

Now that you have seen the "all-in-one" tutorial, which explains the source
code organization, where the SDK's `CMakeLists.txt` file is, etc., it is
easy to show an alternative kind of build system without as much commentary.
In this section we will:

* Install the SDK to the temporary directory `/tmp/sdk-install-demo`, which
  will have the traditional `include` and `lib` directory structure, but
  also a `lib/cmake/category-labs` directory containing the config files for
  CMake's `find_package`

* Compile `eventwatch.c` again, this time using `find_package` which will be
  instructed to look in `/tmp/sdk-install-demo`

### Step 1: build and install `libmonad_event.a`

```shell theme={null}
$ git clone -b release/exec-events-sdk-v1.1 https://github.com/category-labs/monad.git \
  ~/src/monad-exec-events-sdk
$ cmake -S ~/src/monad-exec-events-sdk/category/event \
  -B ~/build/monad-exec-events-sdk-v1-release \
  -DCMAKE_INSTALL_PREFIX=/tmp/sdk-install-demo -DCMAKE_BUILD_TYPE=RelWithDebInfo
$ cmake --build ~/build/monad-exec-events-sdk-v1-release
$ cmake --install ~/build/monad-exec-events-sdk-v1-release
```

If all is successful, you should have a populated `/tmp/sdk-install-demo`
directory.

### Step 2: create a new directory and download `eventwatch.c`

```shell theme={null}
$ mkdir -p ~/src/event-sdk-example-c-find-package
$ cd ~/src/event-sdk-example-c-find-package
$ curl -O https://raw.githubusercontent.com/category-labs/monad/refs/tags/release/exec-events-sdk-v1.1/category/event/example/eventwatch.c
```

### Step 3: create `CMakeLists.txt`

Add a `CMakeLists.txt` file with this content:

```CMakeLists.txt theme={null}
cmake_minimum_required(VERSION 3.23)

project(eventwatch LANGUAGES C)

find_package(monad_exec_events_sdk REQUIRED
             PATHS /tmp/sdk-install-demo/lib/cmake/category-labs)

add_executable(eventwatch eventwatch.c)
target_compile_options(eventwatch PRIVATE -Wall -Wextra -Wconversion -Werror)
target_link_libraries(eventwatch PRIVATE monad_event)
```

### Step 4: build and run

```shell theme={null}
$ cmake -S . -B build
$ cmake --build build
$ build/eventwatch -h
```


# Running the example program on live data, and next steps
Source: https://docs.monad.xyz/execution-events/getting-started/final



If you're following this guide in order, you should have already built one
of the example programs (in [C](/execution-events/getting-started/c) or [Rust](/execution-events/getting-started/rust)), ran it with a
[snapshot file](/execution-events/getting-started/snapshot), and installed your own local
[Monad node](/execution-events/getting-started/setup-node).

Now we'll run the example program again, but this time it will print the
real-time events published by our local Monad node.

## Running with live data

### Step 1: preparing the Monad node

Before running, make sure the execution daemon is running and that
[execution events are enabled](/node-ops/events-and-websockets).
in particular, make sure you have passed the command line argument
`--exec-event-ring` to the execution daemon

### Step 2: run the example program

In the snapshot example, we passed the name of the snapshot file to the
program as a command line argument. In both the C and Rust example programs,
if we do not pass any filename at all, it will use default filename used by
the execution daemon, connecting us to the live event stream.

* For C, run `eventwatch` with no arguments

* For Rust, run the command `cargo run -- -d`

You will see similar data to the snapshot case, but as it is being published
by execution. If you stop the execution daemon, the example program will
detect that the source of data is gone, and exit.

## Next steps

This completes the getting started guide! If you're interested in developing
your own real-time data processing software with the SDK, where should
you go from here?

Here is a recommended list of resources, in roughly the order that will be
most helpful in developing real applications:

1. If you haven't already, read the [overview](/execution-events/overview) and the
   source code for the example program you just ran

2. Once you understand the basic ideas in the example,
   [the rest of the SDK documentation](/execution-events#execution-events-documentation)
   should be easy to follow

3. Before using the SDK, make sure you understand the
   [consensus events](/execution-events/consensus-events) and what they
   mean

4. Try out a more sophisticated program and look at the source code for it

   * For Rust, try the "Block Explorer" TUI example in the upstream
     [`monad`](https://github.com/category-labs/monad/tree/release/exec-events-sdk-v1.1/rust/crates/monad-exec-events/examples/explorer.rs)
     repository. You can run it with
     `cargo run -p monad-exec-events --example explorer` and then browse the
     source code in `explorer.rs`

   * For C, look at the code for the `monad-event-cli` program in the upstream
     [`monad`](https://github.com/category-labs/monad/tree/release/exec-events-sdk-v1.1/category/event/tools/event-cli)
     repository; this program is the "tcpdump" of the execution event system,
     and shows several different uses of the API. You may also want to read
     the next section about compiling this program

## Optional: build the `monad-event-cli` tool

`monad-event-cli` is a useful utility for working with the event system. Like
the Rust `eventwatch` example, it can decode execution event payloads into
human-readable form. It does several other tasks which are useful in the
developer workflow, e.g., recording captures of events and creating snapshot
event ring files for test cases.

<Warning>
  `monad-event-cli` requires gcc 15.2 or higher, and will not build with gcc
  15.1. Currently, the only Ubuntu release that ships with gcc 15.2 in its package
  repositories is Ubuntu 25.10, which was recently released at the time this
  guide was written.

  If your Linux distribution does not provide gcc 15.2 and you do not want to
  install it manually, you can instead use clang-19 (or more recent) but *using
  libc++ instead of libstdc++*. The default on Linux is for clang to use the gcc
  C++ standard library (libstdc++).

  If you specify `-stdlib=libc++` it will use the LLVM standard library instead,
  which has the needed `<format>` support. You may have to install it, since in
  some distributions it is not part of the clang package. In Ubuntu, the clang-19
  libc++ runtime and development packages will be added when you install
  `libc++-19-dev`.

  When using libc++-19, you must also specify the `-fexperimental-library`
  compiler flag to enable C++20 time zone support in `<chrono>`; the event CLI
  tool uses this for printing the event timestamp in local time. In some future
  version of libc++ this will no longer be needed.
</Warning>

To build `monad-event-cli`, you will also need the
[CLI11](https://github.com/CLIUtils/CLI11)
C++ command-line parser library and the OpenSSL development files. Although it
is optional, you should also install the development files for
[GNU multiple-precision library](https://gmplib.org/)
so that `uint256` values print in decimal form.

The instructions also use the
[ninja](https://ninja-build.org/)
build tool. You can install everything on Ubuntu with:

```
$ sudo apt install libcli11-dev libssl-dev libgmp-dev ninja-build
```

Now clone the
[execution repository](https://github.com/category-labs/monad.git) and
check out the branch `release/exec-events-sdk-v1.1`, then build the CMake
project rooted at `category/event`.

Using clang-19 with libc++ and the above options:

```shell theme={null}
$ git clone -b release/exec-events-sdk-v1.1 https://github.com/category-labs/monad.git \
  ~/src/monad-event-cli
$ CC=clang-19 CFLAGS="-march=x86-64-v4" \
  CXX=clang++-19 CXXFLAGS="-stdlib=libc++ -fexperimental-library -march=x86-64-v4" cmake \
  -S ~/src/monad-event-cli/category/event -B ~/build/monad-event-cli-v1.1-release -G Ninja \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo -DMONAD_EVENT_BUILD_CLI=ON
$ cmake --build ~/build/monad-event-cli-v1.1-release
```

You should now be able to run:

```shell theme={null}
$ ~/build/monad-event-cli-v1.1-release/monad-event-cli --help
```

<Note>
  The `-march=x86-64-v4` is needed to enable certain atomic operations at the
  CPU instruction level, to avoid needing to link with libatomic.a; without this,
  a performance warning is emitted, which becomes a compilation error due to
  `-Werror`
</Note>

To simplify running cmake with all these settings, you might want to create a
CMake toolchain file instead of using environment variables. To do this, create
a file called `clang19-libcxx.cmake` with these contents:

```CMake theme={null}
set(CMAKE_C_COMPILER clang-19)
set(CMAKE_CXX_COMPILER clang++-19)
set(CMAKE_ASM_FLAGS_INIT -march=x86-64-v4)
set(CMAKE_C_FLAGS_INIT -march=x86-64-v4)
set(CMAKE_CXX_FLAGS_INIT "-march=x86-64-v4 -stdlib=libc++ -fexperimental-library")
```

Now can you run this slightly cleaner command:

```shell theme={null}
$ cmake --toolchain <path-to-toolchain-file> -S ~/src/monad-event-cli/category/event \
  -B ~/build/monad-event-cli-v1.1-release -G Ninja \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo -DMONAD_EVENT_BUILD_CLI=ON
```


# Getting started
Source: https://docs.monad.xyz/execution-events/getting-started/index



In this guide, we will:

1. Compile an example program, which will involve building code with the
   execution event SDK as a dependency. The SDK is offered for both the C
   and Rust programming languages. Each language has its own guide, so
   follow the instructions for your language of choice
   * [C guide](/execution-events/getting-started/c)
   * [Rust guide](/execution-events/getting-started/rust)
2. [Run the example program on some historical data](/execution-events/getting-started/snapshot),
   which prints ASCII representations of execution events to `stdout`
3. [Set up and run our own Monad node](/execution-events/getting-started/setup-node),
   so that we have a local execution process publishing real-time data
4. [Run the example program again, this time using our Monad node](/execution-events/getting-started/final);
   this will again print execution events to `stdout`, but this time the
   source will be real-time data from our local node

<Info title="Linux required, but with some macOS support">
  This guide has been tested on a clean Ubuntu 24.04 LTS install, but should
  work on any recent Linux distribution, although the names of the required
  packages might be different. The distribution will need to provide a recent
  enough C compiler, either `gcc-13` or `clang-19`.

  The first two steps of the guide, which involve looking at historical data
  instead of real-time data, will also work on a macOS installation that is
  configured for software development. This may make it easier for some developers
  to try out the SDK on a development workstation or laptop, without the need to
  set up a Linux host first.

  Unlike the SDK, the Monad node itself only runs on Linux so the later steps of
  the guide -- which actually consume real-time data -- require a full Linux host
  running your own Monad node.
</Info>


# Building the Rust example program
Source: https://docs.monad.xyz/execution-events/getting-started/rust



The execution event SDK is made up of two packages, called `monad-event-ring`
and `monad-exec-events`. These are described in more detail in the
[Rust API guide](/execution-events/rust-api),
but for now it's enough to just know their names.

In the future, Category Labs may publish these packages to
[crates.io](https://crates.io),
but that is not how the SDK is currently distributed.

Instead, the user's `Cargo.toml` file declares the upstream source of these
dependencies to be a particular release tag of the git repository where the
SDK source code is located. Dependencies which are sourced from git rather
than crates.io are explained in
[this section](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories)
of the Cargo Book.

## Where is the Rust SDK source code?

The execution event Rust SDK lives in same source code repository as the
execution daemon ([here](https://github.com/category-labs/monad)). Most
of the code in this repository in written in either C or C++, the languages
used by the execution daemon itself. The repository also contains a few Rust
wrapper APIs, one of which is the Rust execution events SDK. The top-level
`Cargo.toml` file for all the Rust components is located in the `rust/`
subdirectory.

Many of the functions in the execution events C SDK are reused by Rust, via
an FFI interface. The main way this affects you as a Rust user is that you
must ensure that a recent enough C compiler is selected when Cargo calls
CMake and bindgen from the SDK's
[`build.rs` build scripts](https://doc.rust-lang.org/cargo/reference/build-scripts.html).

The C SDK uses some recent C23 language features, and requires either gcc-13 or
clang-19. If you run `cc -v` and it reports an older compiler, you will need to
set the `CC` environment variable to tell CMake to select a newer compiler.

## Building the example program

### Step 1: install prerequisite development packages

You might already have some of these installed, but make sure you have at least
the minimum required version (newer versions will probably work, but are not
explicitly tested).

In addition to a Rust toolchain, you will need:

| Requirement  | Ubuntu package name | Minimum version   | What is it used for?                                                                                                                 |
| ------------ | ------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| C compiler   | gcc-13 or clang-19  | see package names | The core event library (`libmonad_event.a`) is written in C, and is used by the Rust library                                         |
| C++ compiler | g++-13 or clang-19  | see package names | The optional C++ components are not used by Rust, but the CMake configure step will report an error if it cannot find a C++ compiler |
| CMake        | cmake               | CMake 3.23        | `libmonad_event.a` is built with CMake, via `build.rs` integration with cargo                                                        |
| zstd library | libzstd-dev         | any               | Snapshot event ring files are compressed with zstd; this library is needed to decompress them                                        |
| libhugetlbfs | libhugetlbfs-dev    | any               | `libhugetlbfs` is used to locate the default hugetlbfs mount point that holds event ring shared memory files                         |
| libclang     | clang-19            | clang-19          | Rust's bindgen requires the a recent version of the libclang library                                                                 |

We will also need git and curl.

#### macOS compatiblity

Real-time data requires a Linux host (because the execution daemon itself
does), but you can compile and run the example program on historical data
using macOS. This allows you to "try before you buy" and explore the SDK
before going through the trouble of setting up a Monad node on Linux.

In this case, you do not need `libhugetlbfs` (which is a Linux-only library),
but you will need a recent XCode toolchain, the `libzstd` compression
library, and CMake. The last two are not included in the default XCode
development tools, so you'll probably want to use
[Homebrew](https://brew.sh/) or
[MacPorts](https://www.macports.org/)
to install these onto your system. As for XCode itself, any version since
16.3 should work, but it has only been tested with version 23.2 (the real
requirement is for Apple Clang 17).[^1]

[^1]: "Apple Clang" is based on, but different than, vanilla LLVM
    [Clang](https://clang.llvm.org/). Apple Clang 17 is based on LLVM/Clang 19,
    thus the discrepancy in the requirements table.

#### Dependencies quickstart

To install all of the dependenices in one shot on Ubuntu 24.04 or higher, run
this command (feel free to use more recent verions, e.g., `clang-20`):

```shell theme={null}
$ sudo apt install git curl gcc g++ cmake clang-19 libzstd-dev libhugetlbfs-dev
```

<Info title="`libclang` and clang versions">
  Even if you compile `libmonad_event.a` with gcc, the Rust
  [bindgen](https://rust-lang.github.io/rust-bindgen/) utility still uses the
  [libclang](https://clang.llvm.org/docs/Tooling.html#libclang) tool to
  programmatically generate Rust bindings to C code. Technically you should
  not need the full clang compiler, just the libclang package, but some users
  have reported trouble without installing it.

  The reason you need version 19 (or greater) is that clang-19 was the first
  version to support enough features from the C23 language standard to be able
  to compile the SDK. If you see errors that imply that bindgen cannot understand
  the `constexpr` keyword, then bindgen has automatically selected a libclang
  version that is too old.

  If you have multiple libclang versions on the system (the default clang is
  version 18 on Ubuntu 24.04), installing a newer version may not help, if the
  underlying problem is that bindgen is selecting the wrong one by default.
  Later on in this guide (during the `cargo build` step) we'll explain more
  about how to fix some common problems with libclang version selection.
</Info>

### Step 2: create a new package and copy the example code into it

First, create a new cargo package for the example program:

```shell theme={null}
$ cargo new --bin event-sdk-example-rust
$ cd event-sdk-example-rust
```

Next, we'll overwrite the default "Hello world" `main.rs` source file with the
example program code, downloaded from github:

```
$ curl https://raw.githubusercontent.com/category-labs/monad/refs/tags/release/exec-events-sdk-v1.1/rust/crates/monad-exec-events/examples/eventwatch.rs > src/main.rs
```

### Step 3: integrating with the SDK packages

Create the following `Cargo.toml` file:

```Cargo.toml theme={null}
[package]
name = "event-sdk-example-rust"
version = "0.1.0"
edition = "2021"

[dependencies]
chrono = "0.4.34"
clap = { version = "4.2", features = ["derive"] }
lazy_static = "1.5.0"

[dependencies.monad-event-ring]
git = "https://github.com/category-labs/monad"
tag = "release/exec-events-sdk-v1.1"

[dependencies.monad-exec-events]
git = "https://github.com/category-labs/monad"
tag = "release/exec-events-sdk-v1.1"
```

### Step 4: build the project

```shell theme={null}
cargo build
```

The first time you build will be *very* slow, because it will fetch the monad
repository and all transitive git submodules. None of them are needed for the
SDK, but cargo checks them out and there is currently no way to override this
(see [this issue](https://github.com/rust-lang/cargo/issues/4247)). Thankfully,
the git cache is usually shared by all Cargo projects (in `$HOME/.cargo/git`)
so this long download should only happen a single time, not once per project.

You may need to tell CMake to use a more recent C compiler than the default
one it detects, which you can do using the `CC` environment variable. The
example below uses the bash terse syntax for setting environment variables
in the scope of the next command to be run:

```shell theme={null}
CC=clang-19 cargo build
```

If you encounter any build errors, check out the "trouble-shooting" section
after this one. Otherwise, the build should produce a working executable file.
Try running it with the `-h` flag to print the help:

```shell theme={null}
cargo run -- -h
```

If all was successful, continue on to the [next step in the guide](/execution-events/getting-started/snapshot).

### Trouble-shooting common build errors

#### libclang errors

The most common source of errors when building is when bindgen selects an
outdated libclang version, as explained earlier. This typically appears
as either:

* An error explicitly mentioning `libclang` OR
* A message that includes the text "Unable to generate bindings"

Setting the environment variable `CC=clang-19` only influences the compiler
that CMake uses to build the C SDK library, `libmonad_event.a`. Namely, it
does not the affect the libclang version that is used by bindgen to generate
the bindings. `CC` specifies a particular binary program, whereas libclang
is a shared library that is dynamically loaded by a `build.rs` build script.
They are (for the most part) *not* affected by the same environment variables.

There are a number of environment variables that control the behavior of how
libclang is located and configured, and they're documented in the "Environment
Variables" section of the
[Rust libclang bindings library](https://crates.io/crates/clang-sys).

Some advice we have found works well:

* Setting `LLVM_CONFIG_PATH` to point to the full path to the `llvm-config`
  binary is the best option; this command bakes in a lot of details about
  how LLVM was built and installed on the system, to make it easier for
  users of LLVM (such as bindgen) to find the configuration they need

* In some unusual cases, you may select the right libclang but it may
  be configured strangely, so that it cannot find the basic libc header
  files anymore (typical symptoms are claims that `stddef.h`, `assert.h`,
  or `string.h` are missing); you can can figure out the location of these
  files on the system and pass them as system include directories (the
  `-isystem` clang option) to libclang through bindgen using the
  `BINDGEN_EXTRA_CLANG_ARGS` environment variable; on macOS this looks like:

  ```
  BINDGEN_EXTRA_CLANG_ARGS="-isystem $(xcrun --show-sdk-path)/usr/include"
  ```

  and in a typical Linux setup it looks like this:

  ```
  BINDGEN_EXTRA_CLANG_ARGS="-isystem /usr/include"
  ```

#### zstd library errors

A common error with MacPorts on macOS is the inability of the C compiler to
find the `zstd.h` header file, or the inability of the linker to find the
`libzstd` library. This is because the system C compiler will not search in
the `/opt/local` directory hierarchy by default. To fix this, export the
`CFLAGS` and `RUSTFLAGS` environment variables as follows:

```shell theme={null}
export CFLAGS=-I/opt/local/include
export RUSTFLAGS=-L/opt/local/lib
```

Alternatively, you can set `CC` to a MacPorts-provided C compiler, which will
know to search there.


# Setting up your Monad node
Source: https://docs.monad.xyz/execution-events/getting-started/setup-node



The execution events SDK relies on a shared memory communication system,
in which the node's EVM execution daemon acts a publisher. Thus, in order to
use it, you need to (i) run your own Monad node and (ii) run your data
processing application on the same host as the node, so it can read the
data from shared memory.

Follow the guides on the [node operations](/node-ops) page,
which cover how to install and configure a full node, and how to reset it
when problems occur. You will also need to follow some
[extra configuration steps](/node-ops/events-and-websockets)
to prepare the node for use with execution events.


# Running the example program on snapshot data
Source: https://docs.monad.xyz/execution-events/getting-started/snapshot



The easiest way to get acquainted with the execution event system is to
try out the example program and read the code, although you may want to
read the [quick overview](/execution-events/overview) explaining
the basic concepts first.

If you're following this guide in order you should have already built one
of the example programs. If you have not built one yet, choose the
appropriate guide for your language or choice (either
[C](/execution-events/getting-started/c) or
[Rust](/execution-events/getting-started/rust)), and then return to this page.

## Live event rings vs. snapshot event rings

The event ring's shared memory data structures typically live inside of a
regular file. Any process that wants shared access to an event ring, first
locates it via the filesystem, then maps a shared view of it into the
process' virtual memory map using the
[mmap(2)](https://man7.org/linux/man-pages/man2/mmap.2.html) system call.

Event ring files come in two flavors:

1. **"Live" event ring files** -- these are the "normal" event ring files that
   are the source of real-time data. The whole point of the SDK is to read
   real-time events from these files, but they're not very convenient for most
   day-to-day software development tasks. Suppose, for example, you wanted to
   write a test for your data processing program. The SDK is mostly designed
   around *reading* events, so to test it with a live event ring, you'd need
   to write some dummy event publishing code just to have events to read. For
   execution events, the live event ring file is populated by the execution
   daemon, which we have not even installed at this point in the tutorial!
   A lot of development headaches are solved by the second kind of event ring
   file.

2. **"Snapshot" event ring files** -- these are compressed snapshots taken of a
   live event ring file as it existed at a particular moment in time. Typically
   they are "rewound" to the oldest event in the circular event queue, and are
   used to replay a fixed set of historical execution events. Snapshot files are
   useful for testing and development workflows, because you do not need to be
   running an active publisher to use them. Because they're so useful for
   development, snapshots are the first data source we'll use, before trying the
   example program on a live node.

## Running the example program on a snapshot file

### Step 1: download a snapshot file

Run this command to download a snapshot:

```shell theme={null}
$ curl https://raw.githubusercontent.com/category-labs/monad/refs/tags/release/exec-events-sdk-v1.1/rust/crates/monad-exec-events/test/data/exec-events-emn-30b-15m/snapshot.zst > /tmp/exec-events-emn-30b-15m.zst
```

The `emn-30b-15m` part of the filename means "Ethereum mainnet replay for 30
blocks starting after block 15 million". In other words, this contains the
execution events emitted during a historical replay of the Ethereum blockchain
(chain ID 1), from block 15,000,001 to block 15,000,031.

The Category Labs execution daemon is able to execute blocks from Monad
blockchains (the EVM chain ID 143 or any of its test networks), but also from
other EVM-compatible networks. Historical replay of the Ethereum mainnet is
used as an execution "conformance test", to make sure the node software remains
as Ethereum compatible as possible.

We use an Ethereum chain snapshot in the tutorial under the assumption that
many developers are already familiar with the Ethereum ecosystem, but might be
new to Monad. You can check that all of the data captured in the snapshot file
matches the data published by your favorite Ethereum data provider. For example,
you'll be able to check that the data shown here matches what is reported by
websites like [Etherscan](https://etherscan.io/).

<Warning title="Why `/tmp`?">
  Our example `curl` command placed the snapshot file in `/tmp` for a reason.
  Although the file can be placed anywhere, we encourage users not to place it
  in the same directory they are already in, to ensure they won't encounter a
  confusing error the first time they run the program.

  If the file is placed in the current working directory, and you specified it as
  `exec-events-emn-30b-15m.zst`, an error would occur. That error would go away
  if you instead referred to the file as `./exec-events-emn-30b-15m.zst`. The
  leading `./` "fixes" the problem in a way you've seen before: when you want to
  run a command in your UNIX shell which is not on the `$PATH`, you often add a
  `./` to suppress the default automatic path search. Any `/` character marks the
  input as an actual file path and not a "command name" to be searched for.

  A similar thing happens with event ring files, where file inputs without `/` are
  translated in an automatic way. The file would not be "searched for" in the
  current directory unless the name contains a `./` to communicate that the input
  is a path. "Pure" filenames are only searched for in a special directory called
  the "default event ring directory." The rationale is explained fully in the
  ["Location of event ring files"](/execution-events/advanced#location-of-event-ring-files)
  section of the SDK.
</Warning>

### Step 2: run the SDK example program you built previously

The command is slightly different for each programming language.

For C, run:

```shell theme={null}
$ eventwatch /tmp/exec-events-emn-30b-15m.zst
```

For Rust, run:

```shell theme={null}
cargo run -- --event-ring-path /tmp/exec-events-emn-30b-15m.zst -d
```

The Rust example program output is more informative than the C output. Both
programs "pretty-print" the event descriptor information, but the C example
program can only hexdump the event payloads, whereas the Rust program is able
to debug-print them, thanks to Rust's `#[derive(Debug)]` feature. The `-d`
parameter in the Rust command line tells the program to print this "debug"
form.

<Note>
  Full pretty-printers *do* exist in the SDK for the C language family, but they
  are only available for C++ and are based on the standard C++ `<format>` library
</Note>

### Step 3: analyze the data (Rust only)

If you're running the Rust example program -- and this step of the guide
assumes you are -- you will see a text dump of all event data. We'll look
at a few specific events to give you a sense of what kind of data the SDK
produces, and what you can do with it.

The first two lines printed by the Rust example program look like this:

```
16:26:14.354056730 BLOCK_START [2 0x2] SEQ: 1 BLK: 15000001
Payload: BlockStart(monad_exec_block_start { <block-start-details> })
```

Let's break down the first line:

* `16:26:14.354056730` -- this is the nanosecond-resolution timestamp when the
  original event was recorded; since we're looking at a snapshot and not live
  data, this will always be the same number, and it's from a long time ago; the
  actual "date" portion of the timestamp is omitted when we print it, since the
  typical use-case for the SDK is for real-time data (where the date is usually
  "today")

* `BLOCK_START` - this is the type of the event that occurred inside of the
  EVM; a `BLOCK_START` event is recorded when a new block is first seen by
  the execution daemon, and its payload describes all the execution inputs
  that are known at the *start* of execution processing; this mostly corresponds
  to the fields in the Ethereum block header which are known prior to execution

* `[2 0x2]` - this is the numerical code that corresponds to the `BLOCK_START`
  event type, in both decimal and hexidecimal

* `SEQ: 1` - the sequence number (a monotonic counter of the number of
  events published so far) is 1; in a live event ring, these are used
  for gap / overwrite detection

* `BLK: 15000001` - this event is part of block number 15,000,001

The second line is produced by this Rust statement:

```rust theme={null}
println!("Payload: {exec_event:x?}");
```

Because it's a very long line (there is no line-wrapping in Rust's
`#[derive(Debug)]` output) it was abbreviated in our example output text. We'll
look at parts of it in a moment, but we'll pause here to explain some things
about this `println!("Payload: {exec_event:x?}")` statement.

`exec_event` is a value of Rust enum type `ExecEvent`. Here is how that
enum is defined:

```rust theme={null}
pub enum ExecEvent {
    RecordError(monad_event_record_error),
    BlockStart(monad_exec_block_start),
    BlockReject(monad_exec_block_reject),
    BlockPerfEvmEnter,
    BlockPerfEvmExit,
    BlockEnd(monad_exec_block_end),
    BlockQC(monad_exec_block_qc),
    BlockFinalized(monad_exec_block_finalized),
    BlockVerified(monad_exec_block_verified),
    TxnHeaderStart {
        txn_index: usize,
        txn_header_start: monad_exec_txn_header_start,
        data_bytes: Box<[u8]>,
        blob_bytes: Box<[u8]>,
    },
    // ... more enum variants follow, full definition not shown
}
```

* The debug output starts with `BlockStart(...)`, so `exec_event` has the
  `ExecEvent::BlockStart` enum variant

* It seems like we already knew that from the earlier `BLOCK_START [2 0x2]`
  print-out, but there's a subtle difference. The first line prints information
  found in the *event descriptor*, which is like a header containing the the
  common fields of an event. At the point in the program where the descriptor
  line is printed, it has not yet decoded the event payload to construct the
  `exec_event` variant. Suppose we were only interested in block 15,000,002.
  In that case, we could look at just the descriptor, notice it relates to
  block 15,000,001, and skip over this event (and all other events for that
  block), i.e., we would not bother decoding it

* The value associated with an `ExecEvent::BlockStart` variant if of type
  `struct monad_exec_block_start`; notice that this type does *not* follow the
  normal Rust code-formatting style: it uses `lower_case_snake_case` instead of
  `UpperCamelCase` and has a seemingly-unnecessary prefix (all the variant
  value types start with `monad_exec_`). This is because the payload types
  are defined as C language structures, and their Rust equivalents are
  generated using bindgen. The C-style spelling helps indicate that. The
  definition of `monad_exec_block_start` comes from the C header file
  `exec_event_ctypes.h`, where it is defined like this:

```c theme={null}
/// Event recorded at the start of EVM execution
struct monad_exec_block_start
{
    struct monad_exec_block_tag block_tag;          ///< Proposal is for this block
    uint64_t round;                                 ///< Round when block was proposed
    uint64_t epoch;                                 ///< Epoch when block was proposed
    __uint128_t proposal_epoch_nanos;               ///< UNIX epoch nanosecond timestamp
    monad_c_uint256_ne chain_id;                    ///< Blockchain we're associated with
    struct monad_c_secp256k1_pubkey author;         ///< Public key of block author
    monad_c_bytes32 parent_eth_hash;                ///< Hash of Ethereum parent block
    struct monad_c_eth_block_input eth_block_input; ///< Ethereum execution inputs
    struct monad_c_native_block_input monad_block_input; ///< Monad execution inputs
};
```

The Ethereum execution inputs field `eth_block_input` is the field that
corresponds to the parts of the Ethereum block header which are known at
the start of execution.

Some of this output is difficult to read, since Rust's `#[derive(Debug)]` is
meant for ease of debugging and doesn't always "pretty-print" data in the best
way for readability. Other fields are clear though, for example, the `gas_limit`
of the block is shown as a hexidecimal value:

```
monad_c_eth_block_input { <not shown...> gas_limit: 1c9c380 <...not shown> }
```

`0x1c9c380` corresponds to the decimal number `30,000,000`, a number we expect
to see for a mainnet Ethereum gas limit.

<Info>
  Real pretty-printing of events is done with a developer tool called
  `monad-event-cli`, which is part of the SDK. This example is meant to be as
  simple and short as possible, to help with learning the API. When debugging
  real event programs, you will probably prefer developer tools like the event
  CLI tool. The build instructions for it are in the final step of the
  "Getting start" guide [(here)](/execution-events/getting-started/final#optional-build-the-monad-event-cli-tool).
</Info>

Now let's look for something a little more interesting, to get a sense of a
what a real SDK consumer might do with this data.

If you search the output for the string `TXN_EVM_OUTPUT`, the first match
will be this event (with some formatting differences):

```
16:26:14.376725676 TXN_EVM_OUTPUT [17 0x11] SEQ: 236 BLK: 15000001 TXN: 0
Payload: TxnEvmOutput { txn_index: 0, output: monad_exec_txn_evm_output {
    receipt: monad_c_eth_txn_receipt { status: false, log_count: 0, gas_used: 765c },
    call_frame_count: 1
} }
```

This is the first event that describes the output of transaction zero in block
15,000,001 -- note the `TXN: 0` in the descriptor and `txn_index: 0` in the
payload. We say "first event" because the output for any particular transaction
usually spans *several* events: each log, call frame, state change, and state
access is recorded as a separate event.

The first event is always of type `TXN_EVM_OUTPUT`. It contains a basic summary
of what happened, and an indication of how many more output-related events will
follow. You can see that this particular transaction emitted zero logs, and one
call frame trace. The call frame information is recorded in the next event,
on the line below this one.

As it turns out, the very first transaction is also somewhat interesting: it
failed to execute after using 30,300 gas (0x765c). The transaction's failure is
recorded by `status` field. As you can see, it is set to `false`.

Why did it fail? To figure it out, we'll use the information in the
`TXN_CALL_FRAME` event that follows this one. The `evmc_status_code` field in
that event has the value `2`, which is the numeric value of the
[`EVMC_REVERT`](https://github.com/ipsilon/evmc/blob/496ce0f81058378b72d0b592d1c49b935bce3302/include/evmc/evmc.h#L298)
status code. This tells us that the revert was requested by the contract code
itself, i.e., it executed a
[`REVERT`](https://www.evm.codes/?fork=osaka#fd) instruction. In other words,
this was not a VM-initiated exceptional halt such as "out of gas" or "illegal
instruction, but something the contract itself decided to do.

Because this is a Solidity contract, we can decode richer error information
from the call frame. The `REVERT` instruction can pass arbitrary-length return
data back to the caller. This return data is recorded in the call frame, in the
`return_bytes` array.

Observe that the first 4 bytes of `return_bytes` are `0x8c379a0`. This is how
Solidity represents a revert that carries a string explanation. The details of
how this string is encoded is
[here](https://docs.soliditylang.org/en/v0.8.21/control-structures.html#revert),
but the upshot is that we can decode the last 32 bytes of this `return_bytes`
array as an ASCII string. If you try this yourself, you'll discover that it
says:

```
Ownable: caller is not the owner
```

This error string ultimately comes from
[here](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/release-v4.0/contracts/access/Ownable.sol#L43),
in OpenZeppelin's abstract "Ownable" contract. This was used as a third-party
library in the implementation of this smart contract, to provide some simple
access controls.

In an earlier event (called `TXN_HEADER_START`) we can find the transaction's
Keccak hash, which is
`0xaedb8ef26125d8ad6e0c5f19fc9cbdd7f4a42eb82de88686b39090b8abcfeb8f`. If
we look up information about this transaction on
[Etherscan](https://etherscan.io/tx/0xaedb8ef26125d8ad6e0c5f19fc9cbdd7f4a42eb82de88686b39090b8abcfeb8f),
using the hash, we can see that Etherscan agrees. The `Status:` field reads:

```
Fail with error 'Ownable: caller is not the owner'
```

Feel free to double-check this result using your favorite tool for exploring
Ethereum mainnet data!

### Step 4: Learn how it works

The source code for the example program you just ran has a lot of comments,
and it is designed to teach you how to use the API. The best way to learn about
the SDK is to read through it, but if you haven't read the
[overview](/execution-events/overview) yet, you may want to do that first.

You can either do that now, or continue on to the next step, where we'll
install our own local [Monad node](/execution-events/getting-started/setup-node). Once we have our own
node, we can run this same example program but make it consume real-time
Monad blockchain data instead of snapshot data.


# Execution Events
Source: https://docs.monad.xyz/execution-events/index



The **Execution Events** system allows developers to build high-performance
applications that receive lowest-latency event data from a Monad node via a
shared memory queue. In addition to low-latency applications, this system
is also needed by programs that process very large *volumes* of blockchain
data.

To consume this real-time data, you write some data processing software in C,
C++, or Rust using the software development kit described on this page, and
run it on a host running the
[Monad node software](/node-ops) built by Category Labs.

This would be overkill for simple data processing use cases; see the
[alternatives section](#alternatives-to-execution-events) for more convenient
ways to consume Monad blockchain data.

For comparisons to other systems such as Reth's ExEx or Solana Geyser, see
the [comparisons](#comparisons-with-other-data-systems) section.

## Do I need execution events?

If you're coming to Monad from other EVM blockchains, you might find your
data processing is "not able to keep up" with the rate of data generated
on Monad. This is because Monad is a fast blockchain, in two different
dimensions:

* New blocks are proposed every 400 milliseconds, or equivalently about 150
  blocks every minute.

* A single block can contain many more transactions compared to other
  blockchains; at peak processing rates, Monad can execute blocks containing
  thousands of transactions, and it was designed to sustain execution rates
  approaching 10,000 transactions per second (TPS).

The popular
[JSON-RPC data access APIs](/reference)
were designed for the original
Ethereum blockchain, which rarely exceeds 50 TPS. If you need a lot of data,
or you need the most recent data very quickly, JSON-RPC simply won't scale.
Data streaming over
[WebSockets](/reference/websockets) can sometimes help, but not all data
is published over WebSockets.

If you're not able to keep up, you have two options:

1. *Build more sophisticated processing yourself* - you can use the
   execution events SDK to build the lowest-latency, highest-throughput
   data consumer possible.

2. *Use a third-party data service* - if you are not comfortable with
   systems programming (low-level backend programming in the C, C++, or
   Rust programming langauges) or if you simply don't have the time or
   interest, there are many third-party providers which provide data
   services for Monad. Typically these services will use the execution
   events SDK themselves, and then somehow filter, digest, or enrich the
   data so that you can get what you need more efficiently than the
   traditional JSON-RPC. Check out the
   [Tooling and Infrastructure](/tooling-and-infra) page
   for links to popular providers, particularly the
   [indexers](/tooling-and-infra/indexers) section although
   other services like
   [block explorers](/tooling-and-infra/block-explorers) sometimes
   provide data access APIs that might offer you what you need.

## What are "execution events"?

The Category Labs
[execution daemon](https://github.com/category-labs/monad/blob/main/docs/overview.md)
contains a shared-memory communication
system that publishes data about most actions taken by the EVM during
transaction execution. The raw binary records of these EVM actions are
called "execution events".

Third-party applications that need the highest performance can run on the
same host as the node software, and directly consume the execution event
records from shared memory. To read this data, your third-party application
calls functions in the execution event SDK, our real-time data library.

<Note title="Monad execution events vs Solidity events">
  The Solidity programming language also has a feature called
  [events](https://docs.soliditylang.org/en/latest/contracts.html#events).
  These are not the same thing as execution events. Solidity events are a
  programming-language-level abstraction of the Ethereum Virtual Machine's
  [low-level logging opcodes](https://www.evm.codes/?fork=prague#a0).

  The execution events system *does* record all log events, but it also
  records information about other things that happen during transaction
  execution, such as calls to other contracts, a list of accounts that
  were accessed by a transaction, and more.
</Note>

## Execution events documentation

* [Release notes](/execution-events/release-notes) - see what's new in the latest
  release of the SDK
* [Getting started](/execution-events/getting-started) - describes
  how to build and run a simple example program
* [Events overview](/execution-events/overview) - explains the core
  concepts in the execution events system
* [Event rings in detail](/execution-events/event-ring) - documents
  event ring files and protocol versioning
* API documentation - overview of our programming libraries, which are
  provided for several programming languages
  * [C API](/execution-events/c-api)
  * [Rust API](/execution-events/rust-api)
* [Consensus events](/execution-events/consensus-events) - execution
  publishes some information from consensus that is essential for
  understanding real-time data
* [Advanced topics](/execution-events/advanced) - documentation for
  advanced users and for software developers who contribute to the execution
  source code

## Alternatives to execution events

Category Labs' node software includes an RPC server component. The RPC server
supports two easier ways to read blockchain data:

1. The typical [JSON RPC](/reference) endpoints supported by
   most EVM-compatible blockchain nodes (e.g., Geth)
2. The Geth [real-time events](https://geth.ethereum.org/docs/interacting-with-geth/rpc/pubsub)
   WebSocket protocol (i.e., `eth_subscribe`) is also supported, along with
   some Monad-specific extensions for better performance; see the
   [WebSocket guide](/reference/websockets) for more information

Both of these access methods are standardized across EVM-compatible blockchains
and are simpler to use than execution events. The execution events system is
designed for specialized applications, such as running an indexer platform or
applications that need the lowest latency possible (e.g., market making).
It is also where the RPC server itself gets its real-time data.

## Comparisons with other data systems

A brief comparison with low latency systems in other blockchain
software:

* **Geth Live Tracing**
  [(link)](https://geth.ethereum.org/docs/developers/evm-tracing/live-tracing) - "hook"
  based API: your code is loaded into the Geth node as a plugin, and is run synchronously
  (via callbacks) during execution
* **Reth ExEx** [(link)](https://www.paradigm.xyz/2024/05/reth-exex) and
  [(link)](https://reth.rs/exex/overview) - async function based API:
  your code is loaded into a Reth node; execution sees events after the fact
  rather than synchronously
* **Solana Geyser** [(link)](https://www.helius.dev/blog/solana-geyser-plugins-streaming-data-at-the-speed-of-light) - "hook" based API, a plugin that runs inside
  a Solana validator and invokes callbacks during execution

All three of these are different from the Execution Events approach. In our approach:

* You are seeing events "as-they-happen", as in the Geth Live Tracer and
  Solana Geyser. Unlike these approaches, your code is not running as a
  plugin inside the execution engine, but in parallel (about one
  microsecond later) in a separate process
* Like the Geth Live Tracer (but unlike Reth's ExEx) you see each "piece"
  of the transaction -- each log, each balance change, etc. -- as a
  separate event
* Unlike the Geth Live Tracer or Geyser, you do not install "hooks" and
  receive callbacks; instead you continuously poll for new event records,
  iterating through any new events that are returned to you (and ignoring
  events that you are not interested in)
* Because the system is based on shared memory ring buffers, you can lose
  data if your consumer is too slow -- you must keep up!


# Execution events overview
Source: https://docs.monad.xyz/execution-events/overview



The execution daemon includes a system for recording events that occur during
transaction processing. An "execution event" is a notification that the EVM has
performed some action, such as "an account balance has been updated" or "a new
block has started executing." These EVM events can be observed by external
third-party applications, using a high-performance inter-process communication
(IPC) channel.

The execution daemon publishes event data to shared memory, and external
applications read from this same shared memory region to observe the events.
Your application can read events using the C library `libmonad_event` or the
Rust package `monad-exec-events`.

This page provides an overview of the basic concepts used in both the C
and Rust APIs.

## Event rings vs. execution events

Although the real-time data system and its SDK are often called "execution
events," there are two different parts of the SDK:

1. **Event ring API** - "event ring" is the name of a shared memory data
   structure and the API for reading and writing to it. Event rings are a
   general purpose, IPC broadcast utility for publishing events to any number
   of reading processes. The event ring API works with *unstructured* I/O: like
   the UNIX
   [`read(2)`](https://pubs.opengroup.org/onlinepubs/009604599/functions/read.html)
   and
   [`write(2)`](https://pubs.opengroup.org/onlinepubs/009695099/functions/write.html)
   file I/O system calls, the event ring API sees all data as raw byte arrays

2. **Execution event definitions** - the actual "execution events" are the
   standardized binary formats that the execution daemons writes to represent
   particular EVM actions. It can be thought of as a protocol, a schema, or a
   serialization format. Continuing the analogy, if the event ring API is like
   the UNIX `read(2)` and `write(2)` file APIs, then "execution events" are
   like a "file format" that defines what a particular file contains

In the Rust SDK, these two parts are in different packages: `monad-event-ring`
and `monad-exec-events`.

The C SDK is a single library, but the header files for the two different
parts live in different directories: the event ring headers live in the
`category/core/event` subdirectory, and the execution event files live in
`category/execution/ethereum`.

## Event ring basics

### What is an event?

Events are made up of two components:

1. The *event descriptor* is a fixed-size (currently 64 byte) object describing
   the common fields of an event that has happened. It contains the event's
   type, a sequence number, a timestamp, and some internal book-keeping
   information
2. The *event payload* is a variably-sized piece of extra data about the event,
   which is specific to the event type. For example, a "transaction log" event
   describes a single EVM log record emitted by a transaction. While the
   descriptor tells us the event's type (i.e., that it is "log event"), the
   payload tells us all the details: the contract address, the log topics, and
   the log data. Some of the fields in the event descriptor not already
   mentioned are used to communicate where in shared memory the payload bytes
   are located, and the payload's length

<Note>
  Remember that at the event ring API level, an event payload is just an
  unstructured byte buffer; the reader must know the format of what they are
  reading, and interpret it accordingly
</Note>

### Where do events live?

When an event occurs, an event descriptor is written into a ring buffer that
lives in a shared memory segment. This ring buffer is the "event descriptor
array" in the diagram below.

Event payloads are stored in a different array (in a separate shared memory
segment) called the "payload buffer."

```
  ╔═Event descriptor array══════════════...═════════════════════════════════════╗
  ║                                                                             ║
  ║ ┌───────────────┐ ┌───────────────┐     ┌───────────────┐ ┌───────────────┐ ║
  ║ │     Event     │ │     Event     │     │     Event     │ │░░░░░░░░░░░░░░░│ ║
  ║ │  descriptor   │ │  descriptor   │     │  descriptor   │ │░░░░ empty ░░░░│ ║
  ║ │       1       │ │       2       │     │       N       │ │░░░░░░░░░░░░░░░│ ║
  ║ └┬──────────────┘ └┬──────────────┘     └┬──────────────┘ └───────────────┘ ║
  ╚══╬═════════════════╬════════════════...══╬══════════════════════════════════╝
     │                 │                     │
     │                 │                     │
     │         ┌───────┘                     └─┐
     │         │                               │
     │         │                               │
   ╔═╬═════════╬═══════════════════════════...═╬═══════════════════════════════╗
   ║ │         │                               │                               ║
   ║ ▼───────┐ ▼─────────────────────────┐     ▼─────────────┐ ┌─────────────┐ ║
   ║ │Event 1│ │         Event 2         │     │   Event N   │ │░░░░free░░░░░│ ║
   ║ │payload│ │         payload         │     │   payload   │ │░░░░space░░░░│ ║
   ║ └───────┘ └─────────────────────────┘     └─────────────┘ └─────────────┘ ║
   ╚═Payload buffer════════════════════════...═════════════════════════════════╝
```

Keep in mind that real event payloads are typically much larger (in terms of
number of bytes) than the event descriptors, even though they don't appear that
way in this simple diagram. The diagram is primarily trying to show that:

* Event descriptors are *fixed-size* and event payloads are *variably-sized*
* An event descriptor refers / "points to" the location of its payload
* Event descriptors and payloads live in different contiguous arrays of shared
  memory

Although there are two different ring buffers in this system -- the descriptor
array and payload byte buffer -- we call the entire combined data structure an
"event ring."

A few properties about the style of communication chosen:

* It supports *broadcast* semantics: multiple readers may read from the event
  ring simultaneously, and each reader maintains its own iterator position
  within the ring

* As in typical broadcast protocols, the writer is not aware of the readers --
  events are written regardless of whether anyone is reading them or not.
  Because the writer does not even know what the readers are doing, it cannot
  wait for a reader if it is slow. Readers must iterate through events quickly,
  or events will be lost: descriptor and payload memory can be overwritten by
  later events. Conceptually the event sequence is a *queue* (it has FIFO
  semantics) but is it called a *ring* to emphasize its overwrite-upon-overflow
  semantics

* A sequence number is included in the event descriptor to detect gaps (missing
  events due to slow readers), and a similar strategy is used to detect when
  payload buffer contents are overwritten

## Execution event basics

As mentioned, the event ring API works with unstructured I/O. This API does
not understand what the data means: it knows about bytes, but does not know
anything about blocks, transactions, etc.

When working with a particular event ring, the reader interprets the bytes
assuming they have some known format. The primary format used with the SDK are
the *execution* events: the binary format that records what is happening in
the EVM in real time, during the execution of proposed blocks on the Monad
blockchain. There are a few other kinds of formats (called "content types"),
but they are only used internally by Category Labs, mostly for performance
profiling.

For the remainder of the overview, we'll look at an example execution event.

### Example: the "transaction start" event

One particularly important kind of event is the "start of transaction header"
event, which is recorded shortly after a new transaction is decoded by the EVM.
It contains most of the transaction information (encoded as a C structure) as
its event payload. The payload structure is defined in `exec_event_ctypes.h`
as:

```c theme={null}
/// First event recorded when transaction processing starts
struct monad_exec_txn_header_start {
    monad_c_bytes32 txn_hash;     ///< Keccak hash of transaction RLP
    monad_c_address sender;       ///< Recovered sender address
    struct monad_c_eth_txn_header
        txn_header;               ///< Transaction header
};
```

The nested `monad_c_eth_txn_header` structure contains most of the interesting
information -- it is defined in `eth_ctypes.h` as follows:

```c theme={null}
/// Fields of an Ethereum transaction that are recognized by the monad EVM
/// implementation.
///
/// This type contains the fixed-size fields present in any supported
/// transaction type. If a transaction type does not support a particular field,
/// it will be zero-initialized.
struct monad_c_eth_txn_header {
    enum monad_c_transaction_type
        txn_type;                        ///< EIP-2718 transaction type
    monad_c_uint256_ne chain_id;         ///< T_c: EIP-155 blockchain identifier
    uint64_t nonce;                      ///< T_n: num txns sent by this sender
    uint64_t gas_limit;                  ///< T_g: max usable gas (upfront xfer)
    monad_c_uint256_ne max_fee_per_gas;  ///< T_m in EIP-1559 txns or T_p (gasPrice)
    monad_c_uint256_ne
        max_priority_fee_per_gas;        ///< T_f in EIP-1559 txns, 0 otherwise
    monad_c_uint256_ne value;            ///< T_v: wei xfered or contract endowment
    monad_c_address to;                  ///< T_t: recipient
    bool is_contract_creation;           ///< True -> interpret T_t == 0 as null
    monad_c_uint256_ne r;                ///< T_r: r value of ECDSA signature
    monad_c_uint256_ne s;                ///< T_s: s value of ECDSA signature
    bool y_parity;                       ///< Signature Y parity (see YP App. F)
    monad_c_uint256_ne
        max_fee_per_blob_gas;            ///< EIP-4844 contribution to max fee
    uint32_t data_length;                ///< Length of trailing `data` array
    uint32_t blob_versioned_hash_length; ///< Length of trailing `blob_versioned_hashes` array
    uint32_t access_list_count;          ///< # of EIP-2930 AccessList entries
    uint32_t auth_list_count;            ///< # of EIP-7702 AuthorizationList entries
};
```

The formal nomenclature in the comments (e.g., `T_n` and `T_c`) are references
to variable names in the
[Ethereum Yellow Paper](https://ethereum.github.io/yellowpaper/paper.pdf).

The type `monad_c_uint256_ne` ("native endian") is a 256-bit integer that is
stored as a `uint64_t[4]` in the
[limb format](https://gmplib.org/manual/Integer-Internals)
used by most "big integer" libraries that have good performance.

<Note title="Event payload types in Rust">
  If you are using the Rust SDK, `struct` types with the same names (and the same
  binary layouts, courtesy of a `#[repr(C)]` attribute) are generated by
  [bindgen](https://docs.rs/bindgen/latest/bindgen/) when the `monad-exec-events`
  package is built. The defining characteristic of the execution event payloads
  is that they rely on the "natural" interoperability of simple C data
  structures across programming languages.

  Most popular programming languages have a defined foreign function interface
  for working with C code, and this usually also entails some way to "naturally"
  work with C structure types. Although C's data representation is not portable,
  these objects live in shared memory, therefore both the reader and writer must
  be on the same host, and must follow the same C ABI.
</Note>

### Variable-length trailing arrays and subsequent events

For a particular "start of transaction" event, *most* of the event payload will
be the low-level byte representation of a `struct monad_exec_txn_header_start`
value. Almost always, there will be some extra data in the payload byte array
*following* this structure:

* The transaction's variably-sized `data` byte array, whose length is specified
  by the `data_length` field, is also part of the event payload and immediately
  follows the `struct monad_exec_txn_header_start` object

* If this is an EIP-4844 transaction, a `blob_versioned_hashes` array will
  immediately follow the `data` array

Both of these are examples of "variable-length trailing" (VLT) array payload
data; "trailing" means a simple variable-length array is recorded after the
fixed-size payload structure which (among other things) must contain a field
that describes length of that array; if there is more than VLT array, they
are recorded in the same order that their corresponding `_length` fields are
listed in the fixed-size structure.

The EIP-2930 and EIP-7702 lists are also variable-length items in a
transaction, but they are *not* recorded in the payload of the "start of
transaction header" event.

Instead of being recording in trailing arrays, a unique event will be recorded
for each EIP-2930 access list entry and each EIP-7702 authorization tuple. The
number of these events *is* published in the "start of transaction header"
event payload (see the `access_list_count` and `auth_list_count` fields), so
that the reader will know how many more events to expect.

### Execution event properties in the descriptor

So far we've talked about the payload for a "start of transaction" event, but
the common properties of the event are recorded directly in the event
descriptor. Most importantly, these include the numeric code that identifies
the type of event, so we know we're supposed to interpret the unstructured
payload bytes as a `struct monad_exec_txn_header_start` in the first place.

An event descriptor is defined this way:

```c theme={null}
struct monad_event_descriptor
{
    alignas(64) uint64_t seqno;  ///< Sequence number, for gap/liveness check
    uint16_t event_type;         ///< What kind of event this is
    uint16_t : 16;               ///< Unused tail padding
    uint32_t payload_size;       ///< Size of event payload
    uint64_t record_epoch_nanos; ///< Time event was recorded
    uint64_t payload_buf_offset; ///< Unwrapped offset of payload in p. buf
    uint64_t content_ext[4];     ///< Extensions for particular content types
};
```

For a "start of transaction header" event, the `event_type` field will be set
to the value of the C enumeration constant `MONAD_EXEC_TXN_HEADER_START`, a
value of type `enum monad_exec_event_type`. This tells the user that it is
appropriate to cast the `const uint8_t *` pointing to the start of the event
payload to a `const struct monad_event_txn_header_start *` (or to perform
the corresponding `unsafe` cast in Rust).

All the C enumeration constants start with a `MONAD_EXEC_` prefix, but
typically the documentation refers to event types without the prefix, e.g.,
`TXN_HEADER_START`.

Note that the transaction number is not included in the payload structure.
Because of their importance in the blockchain protocol, transaction numbers
are encoded directly in the event descriptor. At a low level (i.e., in the
C API) this information is encoded in the `context_ext[1]` field. In the Rust
API -- which is a bit more user friendly -- it is decoded and presented as the
structure field `ExecEventRingFlowInfo::txn_idx`.[^1]

[^1]: This encoding and the rationale for storing it in the descriptor is
    described elsewhere in the documentation, in the section describing
    [flow tags](/execution-events/event-ring#flow-tags-the-content_ext-fields-in-execution-event-rings)).

The potential presence of subsequent events with EIP-2930 and EIP-7702
information is why `TXN_HEADER_START` is called the *start* of the transaction
header. A corresponding event called `TXN_HEADER_END` is emitted after all the
transaction header information has been seen. `TXN_HEADER_END` has no payload,
and only serves to announce that all events related to the transaction input
have been recorded. Such an event is called a "marker event" in the
documentation.

Finally, the reason it is called a "header" in the first place, is that there
are many more events related to transactions. The various "transaction header"
events only describe all the inputs that were in the block. Most of the events
describe transaction *outputs*: the logs, the call frames, the state changes,
and the receipt.

### Example in-memory layout

The following diagram illustrates everything explained above about a
transaction header's variable-length trailing arrays, related subsequent
events, and its terminating marker event. This example transaction has two
accounts in its EIP-2930 access list, and no EIP-7702 entries. Each address in
an EIP-2930 list records a separate `TXN_ACCESS_LIST_ENTRY` event, with a
variable-length trailing array of potentially-accessed storage keys.

```
                                      ╔═Payload buffer══════════════════════════════╗
                                      ║                                             ║
                                      ║  ┏━━━━━━━TXN_HEADER_START payload━━━━━━━━┓  ║
                                      ║  ┃░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░┃  ║
                                  ┌───╬──╋─▶─monad_exec_txn_header_start───────┐░┃  ║
                                  │   ║  ┃░│                                   │░┃  ║
                                  │   ║  ┃░│ monad_c_bytes32 txn_hash;         │░┃  ║
                                  │   ║  ┃░│ monad_c_address sender;           │░┃  ║
                                  │   ║  ┃░│ struct monad_c_eth_txn_header     │░┃  ║
  ╔═Event descriptor array════╗   │   ║  ┃░│     txn_header;                   │░┃  ║
  ║                           ║   │   ║  ┃░├───────────────────────────────────┤░┃  ║
  ║ ┌───────────────────────┐ ║   │   ║  ┃░│                                   │░┃  ║
  ║ │ seqno: 1              □─╬───┘   ║  ┃░│     Transaction data variable     │░┃  ║
  ║ │ TXN_HEADER_START      │ ║       ║  ┃░│       length trailing array       │░┃  ║
  ║ └───────────────────────┘ ║       ║  ┃░│                                   │░┃  ║
  ║                           ║       ║  ┃░│                                   │░┃  ║
  ║ ┌───────────────────────┐ ║       ║  ┃░└───────────────────────────────────┘░┃  ║
  ║ │ seqno: 2              □─╬────┐  ║  ┃░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░┃  ║
  ║ │ TXN_ACCESS_LIST_ENTRY │ ║    │  ║  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛  ║
  ║ └───────────────────────┘ ║    │  ║                                             ║
  ║                           ║    │  ║  ┏━━━━━TXN_ACCESS_LIST_ENTRY payload━━━━━┓  ║
  ║ ┌───────────────────────┐ ║    │  ║  ┃░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░┃  ║
  ║ │ seqno: 3              │ ║    └──╬──╋─▶─monad_exec_txn_access_list_entry──┐░┃  ║
  ║ │ TXN_ACCESS_LIST_ENTRY □─╬────┐  ║  ┃░│                                   │░┃  ║
  ║ └───────────────────────┘ ║    │  ║  ┃░│ uint32_t index;                   │░┃  ║
  ║                           ║    │  ║  ┃░│ struct monad_c_access_list_entry  │░┃  ║
  ║ ┌───────────────────────┐ ║    │  ║  ┃░│     entry;                        │░┃  ║
  ║ │ seqno: 4              │ ║    │  ║  ┃░├───────────────────────────────────┤░┃  ║
  ║ │ TXN_HEADER_END        │ ║    │  ║  ┃░│       Storage key variable        │░┃  ║
  ║ └───────────────────────┘ ║    │  ║  ┃░│       length trailing array       │░┃  ║
  ║                           ║    │  ║  ┃░└───────────────────────────────────┘░┃  ║
  ║                           ║    │  ║  ┃░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░┃  ║
  ║                           ║    │  ║  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛  ║
  ║                           ║    │  ║                                             ║
  ║                           ║    │  ║  ┏━━━━━TXN_ACCESS_LIST_ENTRY payload━━━━━┓  ║
  ║                           ║    │  ║  ┃░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░┃  ║
  ║                           ║    └──╬──╋─▶─monad_exec_txn_access_list_entry──┐░┃  ║
  ║                           ║       ║  ┃░│                                   │░┃  ║
  ║                           ║       ║  ┃░│ uint32_t index;                   │░┃  ║
  ╚═══════════════════════════╝       ║  ┃░│ struct monad_c_access_list_entry  │░┃  ║
                                      ║  ┃░│     entry;                        │░┃  ║
                                      ║  ┃░├───────────────────────────────────┤░┃  ║
                                      ║  ┃░│                                   │░┃  ║
                                      ║  ┃░│       Storage key variable        │░┃  ║
                                      ║  ┃░│       length trailing array       │░┃  ║
                                      ║  ┃░│      (this has more storage       │░┃  ║
                                      ║  ┃░│        keys and is larger)        │░┃  ║
                                      ║  ┃░│                                   │░┃  ║
                                      ║  ┃░└───────────────────────────────────┘░┃  ║
                                      ║  ┃░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░┃  ║
                                      ║  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛  ║
                                      ║                                             ║
                                      .                                             .
                                      .                                             .
                                      .                                             .
                                      ║                                             ║
                                      ╚═════════════════════════════════════════════╝
```

### Patterns in execution event serialization

Why are EIP-2930 entries recorded as separate `TXN_ACCESS_LIST_ENTRY` events
instead of as variable-length trailing arrays in `TXN_HEADER_START`? Because
there are two levels of variable-length information involved. There are a
variable number of EIP-2930 accounts, and then for each account, a
variable-length number of associated storage keys.

The event serialization protocol tries to be very simple: the only time a
variable length trailing array will be recorded is when the array *element*
type is fixed size. In particular, data that is shaped like a
["jagged array"](https://en.wikipedia.org/wiki/Jagged_array)
is not permitted in an event payload.

Whenever there are multiple dimensions to the variability, they are "factored
out" by using more distinct events. The trade-off is between fewer events with
a more complex encoding, vs. more events which "unfold" the data into a
"flatter" shape. The latter choice fits better with the "zero-copy C ABI"
data model.[^2]

[^2]: The natural C encoding of jagged arrays requires an array of pointers.
    This can't work in a shared memory structure unless we explicitly control
    the address in virtual address space where the event ring file is mapped,
    e.g., with `MAP_FIXED`.

Technically, the EIP-7702 authorization list *could* be represented as a
variable-length trailing array, since the authorization tuples are fixed-size.
However, as a design decision, variable-length trailing arrays are only allowed
to have simple element types like `u8` or `uint256`, and there cannot be too
many of them.

The decoding logic of VLT arrays tends to be error prone; it looks confusing
because it is harder to "see" in the code exactly what the serialization rules
are. "Unfolding" the data into more events is more self-documenting: distinct
typed objects are created rather than relying on implicit parsing rules for
reinterpreting unstructured trailing data.

Consequently, VLT arrays are only used when their use seems "obvious", e.g.,
the storage key arrays in each `EIP-2930` access list entry.


# Release notes
Source: https://docs.monad.xyz/execution-events/release-notes



### v1.1

* The execution events Rust SDK was moved from the
  [consensus repository](https://github.com/category-labs/monad-bft)
  to the
  [execution repository](https://github.com/category-labs/monad)

* The `eventcap` program was renamed to `monad-event-cli`

* General improvements to the documentation

### v1.0

Initial release of the execution event SDK


# Rust API
Source: https://docs.monad.xyz/execution-events/rust-api



## Modules

The Rust execution events API is split across two library packages:

1. **`monad-event-ring`** - this package provides the core event ring
   functionality. Recall that event rings are a generic broadcast utility
   based on shared memory communication, and are agnostic about what kind
   of event data they contain. Consequently, this package does *not* include
   the definitions of the execution event types (nor any other event types)

2. **`monad-exec-events`** - the execution event data types are defined in this
   library, along with some helpful utilities for writing real-time data
   applications

These libraries fit together in a more structured way than they do in C.

In the C API, the event ring API works with unstructured data, e.g., event
numerical codes are `uint16_t` values and event payloads are raw byte arrays.
The reader performs unchecked type casts to reinterpret the meaning of those
bytes. There are some
[safety mechanisms](/execution-events/event-ring#binary-schema-versioning-the-schema_hash-field)
to check if an event ring file appears to contain the right kind of data,
but the content types are not strongly represented in the type system.

In the Rust API, the event ring is not just "generic" in the general sense
of the word; it is a literal generic type:

```rust theme={null}
struct EventRing<D: EventDecoder>
```

Event rings are explicitly parameterized by a "decoder". The decoder knows
how to interpret the raw bytes for a particular event content type, e.g.,
execution events.

## Core concepts

### Event enumeration type

Consider how decoding works in the C API: it's typically a "giant switch
statement" pattern, where we examine the numerical code of an event and
reinterpret the raw bytes as the appropriate payload type via an unchecked
type cast:

```c theme={null}
const void *payload = monad_event_ring_payload_peek(&exec_ring, &event);

switch (event.event_type) {
case BLOCK_START:
    handle_block_start((const struct monad_exec_block_start *)payload);
    break;

case BLOCK_END:
    handle_block_end((const struct monad_exec_block_end *)payload);
    break;

// ... more event types handled here
}
```

The Rust way of expressing this is to use an `enum` type: the different kinds
of event payloads become the enum's variants, and the `switch` logic is
replaced by a more-powerful `match`.

In Rust, decoding produces a value of enumeration type `ExecEvent`, which is
defined like this:

```rust theme={null}
#[derive(Clone, Debug)]
pub enum ExecEvent {
    BlockStart(monad_exec_block_start),
    BlockReject(monad_exec_block_reject),
    BlockEnd(monad_exec_block_end),
    // more variants follow
```

Notice that each variant of `ExecEvent` holds a value whose type name resembles
the C event payload structures. For example, `struct monad_exec_block_start` is
the event payload structure definition in the C API. It's recorded when a new
block starts, and is defined in the file `exec_event_ctypes.h`.

The use of these exact same C structure names -- including the `monad_exec`
prefix and  lower-case, snake-case spelling -- is designed to alert you to the
fact that the payload types have *exactly* the same in-memory representation
as their C API counterparts. They are generated by
[bindgen](https://rust-lang.github.io/rust-bindgen/) and are layout-compatible
(via a `#[repr(C)]` attribute) with the C types of the same names.

### Event rings and the `'ring` reference lifetime

`EventRing` is an RAII-handle type: when you create an `EventRing` instance,
new shared memory mapping are added to your process for that event ring file.
Likewise, when `EventRing::drop` is called, those shared memory mappings are
removed. Any pointers or references pointing into shared memory would need to
be invalidated at that point.

We rely on Rust's builtin reference lifetime analysis framework to express
this. References to data that lives in event ring shared memory always carries
a reference lifetime called `'ring`. This lifetime corresponds to the lifetime
of the `EventRing` object itself.  Since an `EventRing` pins the shared memory
mappings in place by being alive, the true meaning of `'ring` can usually be
thought of as the "shared memory lifetime", which is the same.

### Zero-copy APIs and the "event reference" enumeration type

In a previous section, we discussed the decoded execution event type,
`enum ExecEvent`. There is a second type with a similar design called
`enum ExecEventRef<'ring>`; it is used for the zero copy API.

To compare the two, here is the `ExecEvent` type:

```rust theme={null}
#[derive(Clone, Debug)]
pub enum ExecEvent {
    BlockStart(monad_exec_block_start),
    BlockReject(monad_exec_block_reject),
    BlockEnd(monad_exec_block_end),
    // more variants follow
```

And here is the `ExecEventRef<'ring>` type:

```rust theme={null}
#[derive(Clone, Debug)]
pub enum ExecEventRef<'ring> {
    BlockStart(&'ring monad_exec_block_start),
    BlockReject(&'ring monad_exec_block_reject),
    BlockEnd(&'ring monad_exec_block_end),
    // more variants follow
```

The former contains *copies* of event payloads, whereas the latter directly
references the bytes living in the shared memory payload buffer. By working
with `ExecEventRef<'ring>`, you avoid avoid copying a potentially large amount
of data, e.g., especially large EVM logs or call frames. This is valuable
if you are filtering out most events anyway.

The "event reference" enum type offers better performance, but it comes with
two drawbacks:

1. Because it has a reference lifetime as a generic parameter, it can be more
   difficult to work with (i.e., more running afoul of the borrow checker)

2. Data that lives directly in the payload buffer can be overwritten at any
   time, so you shouldn't rely on it still being there long after you first
   look at it

### Copying vs. zero-copy payload APIs

The copy vs. zero-copy decision only applies to event payloads; event
descriptors are small, and are always copied. There are two ways to read an
event's payload once you have its descriptor:

1. *Copying style* `EventDescriptor::try_read` - this will return an
   `EventPayloadResult` enum type, which either contains the "success" variant
   (`EventPayloadResult::Ready`) or the "failure" variant
   (`EventPayloadResult::Expired`); the former contains a `ExecEvent` payload
   value, and the latter indicates that the payload was lost

2. *Zero-copy style* `EventDescriptor::try_filter_map` - you pass a
   non-capturing closure to this method, and it is called back with an
   `ExecEventRef<'ring>` reference pointing to the event payload in shared
   memory; since your closure can't capture anything, the only way for you to
   react to the event payload is to return some value `v` of type `T`;
   `EventDescriptor::try_filter_map` itself returns an `Option<T>`, which is
   used in the following way:

   * If the payload has expired prior to calling your closure, then your
     closure is never called, and the `try_filter_map` returns `Option::None`

   * Otherwise your closure is run and its return value `v: T` is moved into
     the `try_filter_map` function

   * If the payload is still valid after your closure has run, then the value
     is transferred to the caller by returning `Option::Some(v)`, otherwise
     `Option::None` is returned

#### Why non-capturing closures?

The pattern of zero-copy APIs generally works like this:

* Create a reference to the data in the event ring payload buffer
  (`e: &'ring E`) and check for expiration; if not expired ...

* ... compute something based on the event payload value, i.e., compute
  `let v = f(&e)`

* Once `f` finishes, check again if the payload expired; if it is expired
  *now*, then it *may have* become expired sometime during the computation
  of `v = f(&e)`; the only safe thing we can do is discard the computed value
  `v`, since we have no way of knowing exactly when the expiration happened

If you were permitted to capture variables in the zero-copy closure, you could
"smuggle out" computations out-of-band from the library's payload expiration
detection checks. That is, if the library later detects that the payload was
overwritten sometime during when your closure was running, it would have no
guaranteed way to "poison" your smuggled out value. It could only *advise* you
not to trust it, but that is error prone.

Idiomatic Rust tends to follow a "correct by default" style, and guards against
these kinds of unsafe patterns. In the zero-copy API, you can communicate only
through return values since you cannot capture anything. This way, the library
can decide not to propagate the return value back to you at all, if it later
discovers that the payload it gave you as input has expired.

## Important types in the Rust API

There are six core types in the API:

1. **Event ring** `EventRing<D: EventDecoder>` - given a path to an event
   ring file, you create one of these to gain access to the shared memory
   segments of the event ring in that file; you typically use the type alias
   `ExecEventRing`, which is syntactic sugar for `EventRing<ExecEventDecoder>`

2. **Event reader** `EventReader<'ring, D: EventDecoder>` - this is the
   iterator-like type that is used to read events; it's called a "reader" rather
   than an "iterator" because [Iterator](https://doc.rust-lang.org/std/iter/trait.Iterator.html)
   already has a specific meaning in Rust; the event reader has a more complex
   return type than a Rust iterator because it has a "polling" style: its
   equivalent  of `next()` -- called `next_descriptor()` -- can return an
   event descriptor, report a gap, or indicate that no new event is ready
   yet

3. **Event descriptor** `EventDescriptor<'ring, D: EventDecoder>` - the event
   reader produces one of these if the next event is read successfully; recall
   that the event descriptor contains the common fields of the event, and stores
   the necessary data to read the event payload and check if it's expired; in
   the Rust API, reading payloads is done using methods defined on the event
   descriptor

4. **Event decoder** `trait EventDecoder` - you don't use this directly, but
   a type that implements this trait -- `ExecEventDecoder` in the case of an
   execution event ring -- contains all the logic for how to decode event
   payloads

5. **Event enumeration types** (associated types `EventDecoder::Event` and
   `EventDecoder::EventRef`) - these give the "copy" and "zero-copy" decoded
   forms of events; in the case of the `ExecEventDecoder`, `ExecEvent` is the
   "copy" type and `ExecEventRef<'ring>` is the zero-copy (shared-memory
   reference) type

6. **Execution event payload types** (`monad_exec_block_start`, and others) -
   these are bindgen-generated, `#[repr(C)]` event payload types that match
   their C API counterparts

## Block-level utilities

### `ExecutedBlockBuilder`

Execution events are granular: most actions taken by the EVM will publish a
single event describing that one action, e.g., every EVM log emitted is
published as as a separate `ExecEvent::TxnLog` event. The events are streamed
to consumers almost as soon as they are available, so the real-time data of a
block comes in "a piece at a time."

A utility called the `ExecutedBlockBuilder` will aggregate these events back
into a single, block-oriented update, if the user prefers working with complete
blocks. The data types in the block representation are also
[alloy\_primitives types](https://docs.rs/alloy-primitives/latest/alloy_primitives/)
which are more ergonomic to work with in Rust.

### `CommitStateBlockBuilder`

As explained in the section on
[speculative real-time data](/monad-arch/realtime-data/spec-realtime),
the EVM publishes execution events as soon as it is able to, which means it
is usually publishing data about blocks that are speculatively executed.
We do not know if these blocks will be appended to the blockchain or not,
since the consensus decision is occurring in parallel with (and will finish
later than) the block's execution.

`CommitStateBlockBuilder` builds on the `ExecutedBlockBuilder` by also
tracking the commit state of the block as it moves through the consensus
life cycle. The block update itself is passed around via an
`Arc<ExecutedBlock>`, so that it is cheap to copy references to it. As the
block commit state changes, you receive updates describing the new state,
along with another reference to the `Arc<ExecutedBlock>` itself.

The speculative real-time data guide often points out that block abandonment
is not explicitly communicated by the event system (e.g.,
[here](/monad-arch/realtime-data/spec-realtime#third-commit-state-finalized) and
[here](/reference/websockets#monadnewheads-and-monadlogs)).
The `CommitStateBlockBuilder` however, *does* report explicit abandonment of
failed proposals, because it is a higher level, user-friendly utility.


# Frequently Asked Questions
Source: https://docs.monad.xyz/faq



## Execution

<Accordion title="Are there any differences in opcode pricing?">
  A few opcodes and precompiles have been repriced to more correclty account for their relative
  cost. See details [here](/developer-essentials/opcode-pricing).
</Accordion>

<Accordion title="How does Monad's optimistic parallel execution manage interdependent transactions?">
  In Monad, like in Ethereum, transactions are ordered linearly within a block. The guarantee
  that Monad provides is that the result at the end of each block will be as if the transactions
  were executed serially, even though under the hood there was work done in parallel.

  Monad handles interdependent transactions gracefully by separating the concerns of
  **computation** (which can be done in parallel) from **commitment** (which is still done
  serially).

  Transactions are computed in parallel optimistically (i.e. assuming that any storage slots read
  in during execution are correct), generating a **pending result** for each transaction. A pending
  result consists of the set of input storage slots (and their values) and output storage slots
  (and their values).

  Pending results are committed **serially** in the original order of the transactions, checking
  each input for correctness at the time of commitment. (An input will be incorrect if it was
  mutated by one of the previously-committed pending results.) If a pending result has any
  incorrect inputs, it will be re-executed; no other pending results can be committed until
  that completes.

  Committing pending results serially ensures that correctness is always preserved.

  <Note>
    An example illustrates this best. Suppose that at the start of a block, Alice, Bob, and
    Charlie each have a balance of 100 USDC. These are the first two transactions:

    | Transaction # | What happens              |
    | ------------- | ------------------------- |
    | 0             | Alice sends Bob 5 USDC    |
    | 1             | Bob sends Charlie 10 USDC |

    When transactions 0 and 1 are executed in parallel, they produce the following pending results:

    | Pending Result # | Inputs                      | Outputs                    |
    | ---------------- | --------------------------- | -------------------------- |
    | 0                | Alice: 100<br /> Bob: 100   | Alice: 95<br /> Bob: 105   |
    | 1                | Bob: 100<br /> Charlie: 100 | Bob: 90<br /> Charlie: 110 |

    Now we commit the pending results serially. Pending result 0 gets committed. When we try to
    commit pending result 1, we notice that one of the inputs is wrong - Bob's balance was expected
    to be 100, but it is actually 105. This re-triggers execution for transaction 1. No other
    transactions can be committed until transaction 1 is re-executed.
  </Note>
</Accordion>

<Accordion title="In optimistic parallel execution, transactions get re-executed if their first execution was done with inputs that subsequently were mutated. What if there is a long list of serially dependent transactions?">
  *(Note: This question is asking about re-execution as discussed [here](/monad-arch/execution/parallel-execution#optimistic-execution).)*

  While it's true that having to re-execute a pending result is slower than immediately committing
  it, re-execution is also typically much faster than the original execution because inputs are
  stored in cache (RAM). Also note that every transaction will be executed at most twice: once
  initially, and once on re-execution.

  More generally, you can think of optimistic parallel execution as a two-pass strategy. The first
  pass begins executing many transactions in parallel, thus surfacing many storage slot
  dependencies in parallel and pulling them all into cache. The second pass iterates over the
  transactions serially, either committing the pending result immediately or re-executing it (but
  from a position where most storage slots are cached). This strategy, combined with efficient SSD
  lookups from [MonadDb](/monad-arch/execution/monaddb), delivers a workload that uses the full
  SSD throughput more efficiently.
</Accordion>

<Accordion title="Do I need to change my code to take advantage of Monad’s parallelism? Would it make sense to split my contract into many contracts to reduce the probability of two transactions touching the same contract?">
  No, no need! Transactions interacting with your smart contract behave as if every transaction
  is being executed serially. Parallel execution is strictly an implementation detail.

  Also, it is important to note that all state contention is evaluated on a slot-by-slot basis.
  So for example, suppose that transaction 1 involves Alice sending USDC to Bob, and transaction
  2 involves Charlie sending USDC to David. It doesn't matter that both transactions involve the
  same smart contract (the USDC ERC-20 contract); the two affected storage slots in transaction
  1 are completely independent from the two affected storage slots in transaction 2.
</Accordion>

<Accordion title="What specific optimizations does MonadDB introduce over traditional databases for EVM state storage?">
  MonadDb stores Merkle Patricia Trie data natively, rather than embedding the trie inside a
  generic database (like LevelDB or RocksDB) which have their own logic for mapping database
  entries to locations on disk. This eliminates a level of indirection and substantially reduces
  the number of IOPS and page reads to look up one value. Trie operations such as recomputing the
  merkle root at the end of each block are much more efficient.

  MonadDb further reduces latency and increases throughput by implementing asynchronous I/O using
  `io_uring` and by bypassing the filesystem.  `io_uring` is a new linux kernel technology that
  allows execution threads to issue I/O requests without stalling or tieing up threads. This allows
  many I/O requests to be issued in parallel, sequenced by the kernel, and serviced by the first
  available thread on return.

  Finally, in MonadDb, each node in the trie is versioned, allowing for intuitive maintenance of
  the merkle trie and efficient state synchronization algorithms. Only the necessary trie
  components are sent during statesync, making bootstrapping and recovery faster.
</Accordion>

<Accordion title="Why doesn't Monad make EIP-2930 access lists mandatory? Wouldn’t it make execution more efficient?">
  1. Usage of access lists generally increases the size of transactions; long-term we think that
     bandwidth is the biggest bottleneck

  2. In Ethereum, the workflow for a user to submit using access lists is: simulate the
     transaction, note which storage slots are accessed, then submit the transaction with these
     slots mentioned in the access list. However, the state of the world may change between
     simulation and the real execution; we feel that it's the job of the system to handle this
     gracefully under the hood.

  3. It would break integrations with existing wallets which don't support EIP-2930.

  4. Note that EIP-2930 access lists are actually underspecified, at least from the perspective
     of anticipating state contention. If two transactions both read from the same storage slot
     (but neither writes to it) then, with respect to that storage slot, there is no state
     contention - neither transaction can invalidate the other's computation. Contention only
     occurs when an earlier transaction writes to a storage slot that a later transaction will
     read. EIP-2930 access lists mention which storage slots are accessed, but don't make note
     of whether the transaction will read from or write to that storage slot.
</Accordion>

## Consensus

<Accordion title="How are leaders selected?">
  The leader schedule is constructed by a deterministic, stake-weighted process that is computed
  once per epoch:

  * An epoch occurs roughly every 5.5 hours (50000 blocks). Validator stake weights are locked in
    one epoch ahead (i.e. any changes for epoch N+1 must be registered prior to the start of epoch N).
  * At the start of each epoch, each validator computes the leader schedule based on running a
    deterministic pseudorandom function on the stake weights. Since the function is deterministic,
    everyone arrives at the same leader schedule.
</Accordion>

<Accordion title="How many nodes can participate in consensus? Is participation permissionless?">
  The client codebase has a parameter called [`ACTIVE_VALSET_SIZE`](/monad-arch/consensus/staking#constants)
  which is currently set to 200.
  Thus, the top 200 validators (ordered by stake weight) can participate directly in consensus.
  This parameter is likely to change over time.

  Participation is permissionless; one simply needs to be in the top `ACTIVE_VALSET_SIZE`
  validators.
</Accordion>

### Raptorcast

<Accordion title="Where can I find a detailed description of RaptorCast?">
  Check [this](https://www.category.xyz/blogs/raptorcast-designing-a-messaging-layer) blog post!
</Accordion>

<Accordion title="Why was UDP chosen instead of TCP in RaptorCast?">
  See the discussion in [this](https://www.category.xyz/blogs/raptorcast-designing-a-messaging-layer)
  blog post. UDP was selected, accepting  lossyness but alleviating it by adding additional data
  integrity (Raptor codes) and message authentication (signatures over merkle roots), because the
  combination of those strategies over UDP is substantially more efficient than using TCP.
</Accordion>

<Accordion title="What is the difference between Raptorcast and the propagation methods in Ethereum, Solana, or L2s?">
  Ethereum is using [libp2p](https://blog.libp2p.io/libp2p-and-ethereum/). It is gossip based
  (each node propagates its message to a set of peers) which is a lot less efficient (more
  duplicate messages and a more meandering process for getting the word out). As a result,
  Ethereum budgets several seconds for the block to propagate throughout the network.

  Solana uses [Turbine](https://www.helius.dev/blog/turbine-block-propagation-on-solana).
  Turbine and RaptorCast are similar in the sense that they both use erasure coding, cut packets
  into MTU-sized chunks, and send transactions through a broadcast tree for efficiency. Some of
  the differences include:

  * Monad uses Raptor codes while Turbine uses Reed-Solomon
  * Monad uses a 2-level broadcast tree with every other validator as a level-1 node while Solana
    uses a deeper, less structured broadcast tree with fewer level-1 nodes and more complex logic
    for determining the broadcast tree. There aren't BFT guarantees on block delivery the way that
    there are for Monad.

  In L2s there's only 1 sequencer so there isn't a notion of block propagation for consensus.
  The sequencer just pushes transaction batches occasionally to L1.
</Accordion>

### Mempool

<Accordion title="If there is a gap in nonces, will transactions after the gap be preserved in the mempool?">
  For example, if my EOA currently has nonce 0, and I send a transaction with nonce 3, then I
  send transactions with nonce 0, 1, and 2. Will the transaction with nonce 3 be executed or
  dropped?

  Answer: Transaction 3 will be executed.
</Accordion>

## Block States and Finality

<Accordion title="When can a node start executing a block?">
  A node can start executing [speculatively](/monad-arch/consensus/asynchronous-execution#speculative-execution)
  as soon as a new block proposal is received. Executing a block just generates new states and a
  new merkle trie root - but the official pointer is still to the old one. This is like receiving
  a possible piece of homework from your teacher which will be finalized soon - you can start
  working on it on a new piece of paper, and just throw it away if it turns out that the homework
  isn't needed.
</Accordion>

<Accordion title="When can a node be sure about the state?">
  As soon as a block enters the [Finalized](/monad-arch/consensus/block-states) state, the
  merkle root for the speculative execution of that block becomes the official local merkle root
  for that block. That merkle root won't be verified by consensus for another `D=3` blocks, but
  it is still known locally because state is deterministic given a fixed ordering of transactions.

  If you want to be certain that your local node did not make a computation error (e.g. due to
  cosmic rays), you may wait `D=3` blocks for the delayed merkle root, which makes the block in
  question enter the [Verified](/monad-arch/consensus/block-states) state.
</Accordion>

## RPC

<Accordion title="When calling `eth_call` with an old block number, I received this response: `Block requested not found. Request might be querying historical state that is not available. If possible, reformulate query to point to more recent blocks`. What's going on?">
  Due to Monad's high throughput, full nodes do not provide access to arbitrarily old state,
  as this would require too much storage. See
  [Historical Data](/developer-essentials/historical-data) for a fuller discussion.

  When writing smart contracts, it is recommended to use events to log any state that will
  be needed later, or use a [smart contract indexer](/tooling-and-infra/indexers/indexing-frameworks)
  to compute it off-chain.
</Accordion>

## Features

<Accordion title="Is EIP-7702 supported?">
  Yes, EIP-7702 is supported.

  Note that when accounts are delegated under EIP-7702, their treatment under Monad's
  [Reserve Balance](/developer-essentials/reserve-balance) rules changes slightly.
  You can learn more about it [here](/developer-essentials/eip-7702).
</Accordion>

<Accordion title="Is EIP-7951 (or RIP-7212) supported?">
  Yes, it is the precompile at `0x0100` following EIP-7951. This enables on-chain verification
  of WebAuthn/passkey signatures using the P256 curve. See
  [Precompiles](/developer-essentials/precompiles#p256-signature-verification) for
  usage details and a Solidity example.
</Accordion>

## Miscellaneous

<Accordion title="What is the point of low validator hardware requirements (32 GB RAM, 2x 2TB SSD, 16-core CPU), if there will only be 100-200 voting nodes?">
  Monad's north star is decentralization. If it's really expensive to run a node, only professional
  validation companies with a large amount of stake will be able to justify the cost. Making nodes
  economical is crucial to making it feasible for anyone to run a full node, as well as to
  supporting a large validator set - the Day-1 mainnet target of 100-200 nodes is just a starting
  point.
</Accordion>

<Accordion title="Why was rust chosen for the consensus client and C++ for execution?">
  Rust and C++ are both great high-performance languages. C++ was selected for the database and
  execution system to get finer control over the filesystem and to use libraries like `io_uring`
  and `boost::fibers`. Rust was selected for consensus to take advantage of stricter memory safety
  given that consensus concerns itself with slightly higher-level systems engineering problems.
</Accordion>


# Add Monad to Wallet
Source: https://docs.monad.xyz/guides/add-monad-to-wallet/index



<CardGroup>
  <Card title="Mainnet" href="/guides/add-monad-to-wallet/mainnet">
    Add Monad Mainnet
  </Card>

  <Card title="Testnet" href="/guides/add-monad-to-wallet/testnet">
    Add Monad Testnet
  </Card>
</CardGroup>


# Add Monad Mainnet to Wallet
Source: https://docs.monad.xyz/guides/add-monad-to-wallet/mainnet



Follow this quick guide to add Monad Mainnet to your wallet.

<Tabs>
  <Tab title="Add Monad Mainnet automatically">
    Click the button below to automatically add Monad Mainnet to your wallet:

    <AddNetworkButton />
  </Tab>

  <Tab title="Add Monad Mainnet manually">
    To manually add Monad Mainnet to your wallet, navigate to your wallet's network settings and add
    a custom network with the following details:

    <div>
      <p><strong>Network Details:</strong></p>

      <ul>
        <li>
          <CopyToClipboard><strong>RPC URL:</strong> `https://rpc.monad.xyz`</CopyToClipboard>
        </li>

        <li>
          <CopyToClipboard><strong>Chain ID:</strong> `143`</CopyToClipboard>
        </li>

        <li>
          <CopyToClipboard><strong>Currency Symbol:</strong> `MON`</CopyToClipboard>
        </li>

        <li>
          <CopyToClipboard><strong>Block Explorer:</strong> `https://monadvision.com`</CopyToClipboard>
        </li>
      </ul>
    </div>
  </Tab>
</Tabs>


# Add Monad Testnet to Wallet
Source: https://docs.monad.xyz/guides/add-monad-to-wallet/testnet



Follow this quick guide to add Monad Testnet to your wallet.

<Tabs>
  <Tab title="Add Monad Testnet automatically">
    Click the button below to automatically add Monad Testnet to your wallet:

    <AddNetworkButton />
  </Tab>

  <Tab title="Add Monad Testnet manually">
    To manually add Monad Testnet to your wallet, navigate to your wallet's network settings and add a custom network with the following details:

    <div>
      <p><strong>Network Details:</strong></p>

      <ul>
        <li>
          <CopyToClipboard><strong>RPC URL:</strong> `https://testnet-rpc.monad.xyz`</CopyToClipboard>
        </li>

        <li>
          <CopyToClipboard><strong>Chain ID:</strong> `10143`</CopyToClipboard>
        </li>

        <li>
          <CopyToClipboard><strong>Currency Symbol:</strong> `MON`</CopyToClipboard>
        </li>

        <li>
          <CopyToClipboard><strong>Block Explorer:</strong> `https://testnet.monadvision.com`</CopyToClipboard>
        </li>
      </ul>
    </div>
  </Tab>
</Tabs>


# How to build a donation blink
Source: https://docs.monad.xyz/guides/blinks



In this guide, you will learn how to build a [Blink](https://www.dialect.to/) that allows people to donate MON with a single click.

## Prerequisites

* Code Editor of your choice ([Cursor](https://www.cursor.com/) or [Visual Studio Code](https://code.visualstudio.com/) recommended).
* [Node](https://nodejs.org/en/download) 18.x.x or above.
* Basic TypeScript knowledge.
* Testnet MON ([Faucet](https://testnet.monad.xyz)).

## Initial setup

### Initialize the project

```bash theme={null}
npx create-next-app@14 blink-starter-monad && cd blink-starter-monad
```

**When prompted, configure your project with these settings:**

* ✓ Ok to proceed? → Yes
* ✓ Would you like to use TypeScript? → Yes
* ✓ Would you like to use ESLint? → Yes
* ✓ Would you like to use Tailwind CSS? → Yes
* ✓ Would you like your code inside a `src/` directory? → Yes
* ✓ Would you like to use App Router? → Yes
* ✓ Would you like to customize the import alias (`@/*` by default)? → No

### Install dependencies

```bash theme={null}
npm install @solana/actions wagmi viem@2.x
```

### Start development server

The development server is used to start a local test environment that runs on your computer. It is perfect to test and develop your blink, before you ship it to production.

```bash theme={null}
npm run dev
```

## Building the Blink

Now that we have our basic setup finished, it is time to start building the blink.

### Create an endpoint

To write a blink provider, you have to create an endpoint. Thanks to NextJS, this all works pretty straightforward. All you have to do is to create the following folder structure:

```
src/
└── app/
    └── api/
            └── actions/
                └── donate-mon/
                    └── route.ts
```

### Create actions.json

Create a route in `app` folder for the `actions.json` file which will be hosted in the root directory of our application. This file is needed to tell other applications which blink providers are available on your website. **Think of it as a sitemap for blinks.**

You can read more about the [actions.json](https://docs.dialect.to/documentation/actions/specification/actions.json) in the official [Dialect documentation](https://docs.dialect.to/documentation/actions/specification/actions.json).

```
src/
└── app/
    └── actions.json/
        └── route.ts
```

```js lines title="src/app/actions.json/route.ts" theme={null}
import { ACTIONS_CORS_HEADERS, ActionsJson } from "@solana/actions";

export const GET = async () => {
  const payload: ActionsJson = {
    rules: [
      // map all root level routes to an action
      {
        pathPattern: "/*",
        apiPath: "/api/actions/*",
      },
      // idempotent rule as the fallback
      {
        pathPattern: "/api/actions/**",
        apiPath: "/api/actions/**",
      },
    ],
  };

  return Response.json(payload, {
    headers: ACTIONS_CORS_HEADERS,
  });
};

// DO NOT FORGET TO INCLUDE THE `OPTIONS` HTTP METHOD
// THIS WILL ENSURE CORS WORKS FOR BLINKS
export const OPTIONS = GET;
```

### Add an image for the blink

Every blink has an image that is rendered on top. If you have your image already hosted somewhere, you can skip this step but if you haven't you can just create a `public` folder in your `NextJS` project and paste an image there.

In our example we will paste a file called `donate-mon.png` into this public folder. You can right-click and save the image below.

<img alt="donate-mon" />

<img alt="image" />

### OPTIONS endpoint and headers

This enables CORS for cross-origin requests and standard headers for the API endpoints. This is standard configuration you do for every Blink.

```js lines title="src/app/api/actions/donate-mon/route.ts" theme={null}
// CAIP-2 format for Monad
const blockchain = `eip155:10143`;

// Create headers with CAIP blockchain ID
const headers = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
  "Access-Control-Allow-Headers":
  "Content-Type, x-blockchain-ids, x-action-version",
  "Content-Type": "application/json",
  "x-blockchain-ids": blockchain,
  "x-action-version": "2.0",
};

// OPTIONS endpoint is required for CORS preflight requests
// Your Blink won't render if you don't add this
export const OPTIONS = async () => {
  return new Response(null, { headers });
};
```

### GET endpoint

`GET` returns the Blink metadata and UI configuration.

It describes:

* How the Action appears in Blink clients
* What parameters users need to provide
* How the Action should be executed

```js lines title="src/app/api/actions/donate-mon/route.ts"   theme={null}
import {
  ActionGetResponse,
} from "@solana/actions";

// GET endpoint returns the Blink metadata (JSON) and UI configuration
export const GET = async (req: Request) => {
  // This JSON is used to render the Blink UI
  const response: ActionGetResponse = {
    type: "action",
    icon: `${new URL("/donate-mon.png", req.url).toString()}`,
    label: "1 MON",
    title: "Donate MON",
    description:
      "This Blink demonstrates how to donate MON on the Monad blockchain. It is a part of the official Blink Starter Guides by Dialect Labs.  \n\nLearn how to build this Blink: https://dialect.to/docs/guides/donate-mon",
    // Links is used if you have multiple actions or if you need more than one params
    links: {
      actions: [
        {
          // Defines this as a blockchain transaction
          type: "transaction",
          label: "0.01 MON",
          // This is the endpoint for the POST request
          href: `/api/actions/donate-mon?amount=0.01`,
        },
        {
          type: "transaction",
          label: "0.05 MON",
          href: `/api/actions/donate-mon?amount=0.05`,
        },
        {
          type: "transaction",
          label: "0.1 MON",
          href: `/api/actions/donate-mon?amount=0.1`,
        },
        {
          // Example for a custom input field
          type: "transaction",
          href: `/api/actions/donate-mon?amount={amount}`,
          label: "Donate",
          parameters: [
            {
              name: "amount",
              label: "Enter a custom MON amount",
              type: "number",
            },
          ],
        },
      ],
    },
  };

  // Return the response with proper headers
  return new Response(JSON.stringify(response), {
    status: 200,
    headers,
  });
};
```

### Testing the Blink

Visit [dial.to](https://dial.to) and type in the link to your blink to see if it works. If your server runs on localhost:3000 the url should be like this: `http://localhost:3000/api/actions/donate-mon`

<Info>
  [dial.to](https://dial.to) currently supports only GET previews for EVM. To test your POST endpoint, we need to build a Blink Client.
</Info>

<img alt="testing blink" />

### POST endpoint

`POST` handles the actual MON transfer transaction.

#### POST request to the endpoint

Create the post request structure and add the necessary imports as well as the `donationWallet` on top of the file.

```js lines title="src/app/api/actions/donate-mon/route.ts" theme={null}
// Update the imports
import { ActionGetResponse, ActionPostResponse } from "@solana/actions";
import { serialize } from "wagmi";
import { parseEther } from "viem";

// Wallet address that will receive the donations
const donationWallet = `<RECEIVER_ADDRESS>`;


// POST endpoint handles the actual transaction creation
export const POST = async (req: Request) => {
  try {
  
  // Code that goes here is in the next step
  
  } catch (error) {
    // Log and return an error response
    console.error("Error processing request:", error);
    return new Response(JSON.stringify({ error: "Internal server error" }), {
      status: 500,
      headers,
    });
  }
};
```

#### Extract data from request

The request contains the URL and the account (PublicKey) from the payer.

```js lines title="src/app/api/actions/donate-mon/route.ts" theme={null}
// POST endpoint handles the actual transaction creation
export const POST = async (req: Request) => {
  try {
    // Step 1
    // Extract amount from URL
    const url = new URL(req.url);
    const amount = url.searchParams.get("amount");

    if (!amount) {
        throw new Error("Amount is required");
    }

  } catch (error) {
    // Error handling
  }
}
```

#### Create the transaction

Create a new transaction with all the necessary data and add it below in the `POST` request.

```js lines title="src/app/api/actions/donate-mon/route.ts" theme={null}
// POST endpoint handles the actual transaction creation
export const POST = async (req: Request) => {
  try {

    // ... previous code from step
    
    // Build the transaction
    const transaction = {
        to: donationWallet,
        value: parseEther(amount).toString(),
        chainId: 10143,
    };

    const transactionJson = serialize(transaction);
  
  } catch (error) {
    // Error handling
  }
}
```

#### Return the transaction in response.

Create `ActionPostResponse` and return it to the client.

```ts lines title="src/app/api/actions/donate-mon/route.ts" theme={null}
export const POST = async (req: Request) => {
  try {
    // ... previous code from step 1 and 2
    
    // Build ActionPostResponse
    const response: ActionPostResponse = {
        type: "transaction",
        transaction: transactionJson,
        message: "Donate MON",
    };

    // Return the response with proper headers
    return new Response(JSON.stringify(response), {
        status: 200,
        headers,
    });

  } catch (error) {
    // Error handling
  }
}
```

### Full code in `route.ts`

```ts lines title="src/app/api/actions/donate-mon/route.ts" theme={null}
import { ActionGetResponse, ActionPostResponse } from "@solana/actions";
import { serialize } from "wagmi";
import { parseEther } from "viem";

// CAIP-2 format for Monad
const blockchain = `eip155:10143`;

// Wallet address that will receive the donations
const donationWallet = `<RECEIVER_ADDRESS>`;

// Create headers with CAIP blockchain ID
const headers = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
  "Access-Control-Allow-Headers":
  "Content-Type, x-blockchain-ids, x-action-version",
  "Content-Type": "application/json",
  "x-blockchain-ids": blockchain,
  "x-action-version": "2.0",
};

// OPTIONS endpoint is required for CORS preflight requests
// Your Blink won't render if you don't add this
export const OPTIONS = async () => {
  return new Response(null, { headers });
};

// GET endpoint returns the Blink metadata (JSON) and UI configuration
export const GET = async (req: Request) => {
  // This JSON is used to render the Blink UI
  const response: ActionGetResponse = {
    type: "action",
    icon: `${new URL("/donate-mon.png", req.url).toString()}`,
    label: "1 MON",
    title: "Donate MON",
    description:
      "This Blink demonstrates how to donate MON on the Monad blockchain. It is a part of the official Blink Starter Guides by Dialect Labs.  \n\nLearn how to build this Blink: https://dialect.to/docs/guides/donate-mon",
    // Links is used if you have multiple actions or if you need more than one params
    links: {
      actions: [
        {
          // Defines this as a blockchain transaction
          type: "transaction",
          label: "0.01 MON",
          // This is the endpoint for the POST request
          href: `/api/actions/donate-mon?amount=0.01`,
        },
        {
          type: "transaction",
          label: "0.05 MON",
          href: `/api/actions/donate-mon?amount=0.05`,
        },
        {
          type: "transaction",
          label: "0.1 MON",
          href: `/api/actions/donate-mon?amount=0.1`,
        },
        {
          // Example for a custom input field
          type: "transaction",
          href: `/api/actions/donate-mon?amount={amount}`,
          label: "Donate",
          parameters: [
            {
              name: "amount",
              label: "Enter a custom MON amount",
              type: "number",
            },
          ],
        },
      ],
    },
  };

  // Return the response with proper headers
  return new Response(JSON.stringify(response), {
    status: 200,
    headers,
  });
};

// POST endpoint handles the actual transaction creation
export const POST = async (req: Request) => {
    try {
      // Extract amount from URL
      const url = new URL(req.url);
      const amount = url.searchParams.get("amount");

      if (!amount) {
          throw new Error("Amount is required");
      }

      // Build the transaction
      const transaction = {
          to: donationWallet,
          value: parseEther(amount).toString(),
          chainId: 10143,
      };

      const transactionJson = serialize(transaction);

      // Build ActionPostResponse
      const response: ActionPostResponse = {
          type: "transaction",
          transaction: transactionJson,
          message: "Donate MON",
      };

      // Return the response with proper headers
      return new Response(JSON.stringify(response), {
          status: 200,
          headers,
      });
    } catch (error) {
      // Log and return an error response
      console.error("Error processing request:", error);
      return new Response(JSON.stringify({ error: "Internal server error" }), {
        status: 500,
        headers,
      });
  }
};
```

At this point the Blink is ready, but we need a Blink client since [dial.to](https://dial.to) does not support EVM wallets.

## Implementing the Blink client

In this step you will learn to implement the blink client, which is the visual representation of a blink.

### Install dependencies

```bash theme={null}
npm install connectkit @tanstack/react-query @dialectlabs/blinks
```

### Implement the provider

The provider is necessary to trigger wallet actions in the blink.

### Create config for `WagmiProvider`

This file is used to set the proper configurations for the `WagmiProvider` in the next step.

```ts lines title="src/config.ts" theme={null}
import { http, createConfig } from "wagmi";
import { monadTestnet } from "wagmi/chains";

export const config = createConfig({
  chains: [monadTestnet],
  transports: {
    [monadTestnet.id]: http(),
  },
});
```

### Create the wallet connection context providers

Create the provider that we can use to wrap around our app. Don't forget to use the `“use client”;` at the top of the file if you are in a NextJS project.

<Info>
  In this project, we are using [ConnectKit](https://docs.family.co/connectkit) but you can use other alternatives as well (Eg: [RainbowKit](https://www.rainbowkit.com/))
</Info>

```tsx lines title="src/provider.tsx" theme={null}
"use client";

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ConnectKitProvider } from "connectkit";
import { type PropsWithChildren } from "react";
import { WagmiProvider } from "wagmi";
import { config } from "@/config";

const queryClient = new QueryClient();

export const Providers = ({ children }: PropsWithChildren) => {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <ConnectKitProvider>{children}</ConnectKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
};
```

### Wrap the app with context provider

If you want your provider to be accessible throughout your app, it is recommended to wrap it around the `children` element in your `layout.tsx`.

```tsx lines title="src/app/layout.tsx" theme={null}
// additional import
import { Providers } from "@/provider";

// other code in the file ...

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body
      className={`${geistSans.variable} ${geistMono.variable} antialiased`}
      >
          <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

### Using the `Blink` component

Now that we have everything wrapped, we can start with the implementation of the blink renderer.
To do so open the `page.tsx` file in your `/src/app` folder.

```tsx lines title="src/app/page.tsx" theme={null}
"use client";

import {
  Blink,
  useBlink,
  useActionsRegistryInterval,
} from "@dialectlabs/blinks";

import "@dialectlabs/blinks/index.css";

import { useEvmWagmiAdapter } from "@dialectlabs/blinks/hooks/evm";

import { ConnectKitButton, useModal } from "connectkit";

export default function Home() {
  // Actions registry interval
  useActionsRegistryInterval();

  // ConnectKit modal
  const { setOpen } = useModal();

  // Wagmi adapter, used to connect to the wallet
  const { adapter } = useEvmWagmiAdapter({
    onConnectWalletRequest: async () => {
      setOpen(true);
    },
  });

  // Action we want to execute in the Blink
  const { blink, isLoading } = useBlink({
    url: "evm-action:http://localhost:3000/api/actions/donate-mon",
  });

  return (
    <main className="flex flex-col items-center justify-center">
      <ConnectKitButton />
      <div className="w-1/2 lg:px-4 lg:p-8">
        {isLoading || !blink ? (
          <span>Loading</span>
        ) : (
          // Blink component, used to execute the action
          <Blink blink={blink} adapter={adapter} securityLevel="all" />
        )}
      </div>
    </main>
  );
}
```

### Make a transaction

That's it. To test it, visit [localhost:3000](http://localhost:3000) and click on a button or enter a custom amount that you want to donate.

<img alt="blink client" />

## Conclusion

In this tutorial, you learned how you can create a blink that sends MON to another wallet from scratch using a `NextJS` project. Besides the basic project setup there were two important things that we built.

The first thing was the blink provider. This provider works as an API for the blink and handles how the blink is rendered in the fronend (`GET` request) and executes the blockchain transaction (`POST` request).

The second implementation was the blink client. This client serves as the visual representation of the blink and is what the user sees and uses to interact with the blink provider.

These are two separate parts, which means you can build a blink without worrying about the client implementation and you can implement clients for existing blinks without the need to build your own blink.


# Custom Stablecoins on Monad with Brale
Source: https://docs.monad.xyz/guides/brale



Deploy regulated, fully-backed USD stablecoins on Monad and integrate them into your application with onramps, offramps, and custody.

## Overview

Monad's high-performance EVM, with 10,000+ tx/s and sub-second time-to-finality, makes it well-suited for stablecoin-powered applications. Brale lets businesses create their own stablecoins and then access them programmatically through a single API for money movements.

## What You'll Build

By the end of this guide, you'll have:

* A custom stablecoin launched on Monad
* API credentials for programmatic control
* Working integrations for onramps, transfers, swaps, and offramps

## Why Custom Stablecoins?

| Use Case              | Benefit                                                              |
| --------------------- | -------------------------------------------------------------------- |
| Branded experience    | Your token, your identity—build user trust                           |
| Direct fiat rails     | Connect to ACH, wire, and RTP through a single orchestration layer   |
| Cross-chain liquidity | Move value across supported chains through a unified transfers model |
| Compliance built-in   | Brale handles the regulated issuance and orchestration layer         |

***

## Prerequisites

Before starting, ensure you have:

* A registered business entity for KYB verification
* A [Brale account](https://app.brale.xyz/)
* Monad network and wallet access:
  * [Mainnet network info](https://docs.monad.xyz/developer-essentials/network-information)
  * [Testnet network info](https://docs.monad.xyz/developer-essentials/testnets)
  * [Add Monad to your wallet](https://docs.monad.xyz/guides/add-monad-to-wallet)

## Choose Your Environment

Use Brale testnet while developing and switch to mainnet for production. In testnet, use `monad_testnet` as the `transfer_type` and in mainnet, use `monad`. Brale's testnet supports testnet networks only and skips the real fiat leg on mint and redemption flows.

***

## Part 1: Launch Your Stablecoin in Brale

Stablecoin issuance is a dashboard workflow. API integration begins after your stablecoin has been launched. Once issued, the stablecoin is available via the API.

### Step 1: Complete Business Verification

1. Log in to the Brale Dashboard
2. Complete KYB (Know Your Business) verification:
   * Business name and EIN
   * Beneficial ownership information

### Step 2: Launch Your Stablecoin

In the Brale Dashboard, create your stablecoin and configure:

* **Name:** Your stablecoin's display name (for example, Acme Dollar)
* **Symbol:** Token ticker (for example, ACME)
* **Chains:** Select Monad
* **Branding:** Add your token logo

Then fund it via Wire, ACH, or USDC.

Once your stablecoin is live, continue with the API setup below.

***

## Part 2: Integrate with the Brale API

Brale's API uses OAuth 2.0 client credentials, environment-specific applications, and `address_id` values as the source/destination primitive for transfers.

### Step 1: Create API Credentials

1. Sign in to your Brale account
2. Navigate to **Settings → API**
3. Click **Create Application**
4. Give the application a name and choose **Mainnet** or **Testnet**
5. Copy the generated `CLIENT_ID` and `CLIENT_SECRET`

Brale API applications are environment-specific, and the same application credentials can be used for direct API access and the hosted Brale API MCP server.

### Step 2: Authenticate

Exchange your credentials for a bearer token:

```bash theme={null}
export CLIENT_ID="your_client_id"
export CLIENT_SECRET="your_client_secret"

CLIENT_CREDENTIALS=$(
  printf "%s:%s" "${CLIENT_ID}" "${CLIENT_SECRET}" | base64 | tr -d '\n'
)

curl --request POST \
  --url "https://auth.brale.xyz/oauth2/token" \
  --header "Authorization: Basic ${CLIENT_CREDENTIALS}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data grant_type=client_credentials
```

**Response**

```json theme={null}
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

Use the returned token in subsequent requests:

```bash theme={null}
export AUTH_TOKEN="your_access_token"
```

### Step 3: Set Your Working Variables

```bash theme={null}
export ACCOUNT_ID="your_account_id"
export TOKEN_SYMBOL="ACME"

# Use testnet while developing
export MONAD_TRANSFER_TYPE="monad_testnet"

# Switch to mainnet for production
# export MONAD_TRANSFER_TYPE="monad"
```

### Step 4: Retrieve Your `account_id`

List your accounts and identify the account you want to operate on:

```bash theme={null}
curl --request GET \
  --url "https://api.brale.xyz/accounts" \
  --header "Authorization: Bearer ${AUTH_TOKEN}"
```

### Step 5: Get Your Internal Monad `address_id`

Brale automatically generates internal custodial addresses on supported chains for onboarded accounts. Retrieve the internal Monad address you want to use for custodial flows:

```bash theme={null}
curl --request GET \
  --url "https://api.brale.xyz/accounts/${ACCOUNT_ID}/addresses?type=internal&transfer_type=${MONAD_TRANSFER_TYPE}" \
  --header "Authorization: Bearer ${AUTH_TOKEN}"
```

Store the returned internal Monad `address_id`:

```bash theme={null}
export MONAD_ADDRESS_ID="your_internal_monad_address_id"
```

### Step 6: Register an External Monad Wallet (Optional)

If you want to send to or receive from a self-custody Monad wallet, register it as an external address first. In Brale, addresses can be `type=internal` or `type=external`, and both are represented by `address_id` values used in transfers.

```bash theme={null}
curl --request POST \
  --url "https://api.brale.xyz/accounts/${ACCOUNT_ID}/addresses/external" \
  --header "Authorization: Bearer ${AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "name": "User Monad Wallet",
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "transfer_types": ["'"${MONAD_TRANSFER_TYPE}"'"]
  }'
```

**Response**

```json theme={null}
{
  "id": "2VcUIIsgARwVbEGlIYbhg6fGG57"
}
```

Store the returned `id` as the wallet's Brale `address_id`:

```bash theme={null}
export EXTERNAL_MONAD_ADDRESS_ID="your_external_monad_address_id"
```

***

## Alternative: Brale API MCP Server

Brale offers a hosted API MCP server for live API access from MCP-compatible clients. The remote server URL is `https://mcp.brale.xyz/`.

### Setup for Claude Desktop

1. Open **Settings → Connectors**
2. Click **Add custom connector**
3. Enter the remote MCP server URL: `https://mcp.brale.xyz/`
4. Open **Advanced settings** and enter your OAuth Client ID and Client Secret
5. Save the connector

Once added, enable it from the Search and Tools menu in chat.

<Info>
  Custom connectors are available on Pro, Max, Team, and Enterprise plans.
</Info>

### Setup for Cursor

Add a server entry in **Settings → MCP**:

```json theme={null}
{
  "name": "Brale API MCP",
  "url": "https://mcp.brale.xyz/",
  "env": {
    "CLIENT_ID": "your_client_id",
    "CLIENT_SECRET": "your_client_secret"
  }
}
```

### Setup for Windsurf

Edit `~/.codeium/windsurf/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "Brale API MCP": {
      "url": "https://mcp.brale.xyz/",
      "env": {
        "CLIENT_ID": "your_client_id",
        "CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

Restart Windsurf after saving.

***

## Move Value with Transfers

All stablecoin movement is handled through the Transfers API. Every transfer is scoped to an `account_id`, references `address_id` values where applicable, and uses `transfer_type` plus `value_type` to define the rail/chain and asset being moved.

### Base URL

```
https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers
```

### Required Headers

```
Authorization: Bearer ${AUTH_TOKEN}
Content-Type: application/json
Idempotency-Key: $(uuidgen)
```

<Tip>
  Always include a fresh `Idempotency-Key` on create requests.
</Tip>

***

## Onramps: Fiat to Stablecoin

Convert USD to your stablecoin on Monad.

### Option A: Wire Onramp

```bash theme={null}
curl --request POST \
  --url "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers" \
  --header "Authorization: Bearer ${AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "amount": {
      "value": "1000.00",
      "currency": "USD"
    },
    "source": {
      "value_type": "usd",
      "transfer_type": "wire"
    },
    "destination": {
      "address_id": "'"${MONAD_ADDRESS_ID}"'",
      "value_type": "'"${TOKEN_SYMBOL}"'",
      "transfer_type": "'"${MONAD_TRANSFER_TYPE}"'"
    }
  }'
```

### Option B: ACH Onramp

If you are funding from a linked bank account, use an ACH funding address and mint to your Monad destination address:

```bash theme={null}
export FUNDING_ADDRESS_ID="your_ach_funding_address_id"

curl --request POST \
  --url "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers" \
  --header "Authorization: Bearer ${AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "amount": {
      "value": "1000.00",
      "currency": "USD"
    },
    "source": {
      "address_id": "'"${FUNDING_ADDRESS_ID}"'",
      "value_type": "usd",
      "transfer_type": "ach_debit"
    },
    "destination": {
      "address_id": "'"${MONAD_ADDRESS_ID}"'",
      "value_type": "'"${TOKEN_SYMBOL}"'",
      "transfer_type": "'"${MONAD_TRANSFER_TYPE}"'"
    }
  }'
```

### Option C: Automated Onramps

For recurring flows, create an Automation that mints stablecoins automatically when USD arrives:

1. In the Dashboard, navigate to **Automations**
2. Create an automation that listens for inbound ACH or wire funding
3. Set the destination to your Monad address
4. Save the automation

***

## Transfers: Move Stablecoins

Transfer your stablecoin between addresses on Monad or across chains.

### On-Chain Transfer (Monad)

```bash theme={null}
export SOURCE_ADDRESS_ID="your_source_monad_address_id"
export DESTINATION_ADDRESS_ID="your_destination_monad_address_id"

curl --request POST \
  --url "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers" \
  --header "Authorization: Bearer ${AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "amount": {
      "value": "500.00",
      "currency": "USD"
    },
    "source": {
      "address_id": "'"${SOURCE_ADDRESS_ID}"'",
      "value_type": "'"${TOKEN_SYMBOL}"'",
      "transfer_type": "'"${MONAD_TRANSFER_TYPE}"'"
    },
    "destination": {
      "address_id": "'"${DESTINATION_ADDRESS_ID}"'",
      "value_type": "'"${TOKEN_SYMBOL}"'",
      "transfer_type": "'"${MONAD_TRANSFER_TYPE}"'"
    }
  }'
```

### Cross-Chain Transfer

Move your stablecoin from Monad to another supported chain:

```bash theme={null}
export BASE_ADDRESS_ID="your_base_address_id"

curl --request POST \
  --url "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers" \
  --header "Authorization: Bearer ${AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "amount": {
      "value": "500.00",
      "currency": "USD"
    },
    "source": {
      "address_id": "'"${MONAD_ADDRESS_ID}"'",
      "value_type": "'"${TOKEN_SYMBOL}"'",
      "transfer_type": "'"${MONAD_TRANSFER_TYPE}"'"
    },
    "destination": {
      "address_id": "'"${BASE_ADDRESS_ID}"'",
      "value_type": "'"${TOKEN_SYMBOL}"'",
      "transfer_type": "base"
    }
  }'
```

***

## Swaps: Exchange Stablecoins

Swap between supported stablecoins at 1:1 with no slippage.

<Info>
  Confirm the specific `value_type` and `transfer_type` combination you plan to use before production.
</Info>

### Example: Swap Your Token for USDC

```bash theme={null}
export USDC_DESTINATION_ADDRESS_ID="your_usdc_destination_address_id"

curl --request POST \
  --url "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers" \
  --header "Authorization: Bearer ${AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "amount": {
      "value": "250.00",
      "currency": "USD"
    },
    "source": {
      "address_id": "'"${MONAD_ADDRESS_ID}"'",
      "value_type": "'"${TOKEN_SYMBOL}"'",
      "transfer_type": "'"${MONAD_TRANSFER_TYPE}"'"
    },
    "destination": {
      "address_id": "'"${USDC_DESTINATION_ADDRESS_ID}"'",
      "value_type": "USDC",
      "transfer_type": "base"
    }
  }'
```

***

## Offramps: Stablecoin to Fiat

Convert your stablecoin back to USD via wire or ACH.

### Offramp to Wire

```bash theme={null}
export USD_DESTINATION_ADDRESS_ID="your_wire_destination_address_id"

curl --request POST \
  --url "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers" \
  --header "Authorization: Bearer ${AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "amount": {
      "value": "1000.00",
      "currency": "USD"
    },
    "source": {
      "address_id": "'"${MONAD_ADDRESS_ID}"'",
      "value_type": "'"${TOKEN_SYMBOL}"'",
      "transfer_type": "'"${MONAD_TRANSFER_TYPE}"'"
    },
    "destination": {
      "address_id": "'"${USD_DESTINATION_ADDRESS_ID}"'",
      "value_type": "usd",
      "transfer_type": "wire"
    }
  }'
```

### Offramp to ACH

For ACH payouts, use `ach_credit` or `same_day_ach_credit` on the destination address instead of `wire`.

***

## Monitoring Transfers

Check transfer status by querying the transfer ID:

```bash theme={null}
export TRANSFER_ID="your_transfer_id"

curl --request GET \
  --url "https://api.brale.xyz/accounts/${ACCOUNT_ID}/transfers/${TRANSFER_ID}" \
  --header "Authorization: Bearer ${AUTH_TOKEN}"
```

### Transfer States

| Status       | Description                                                  |
| ------------ | ------------------------------------------------------------ |
| `pending`    | Transfer submitted but not yet in progress                   |
| `processing` | Transfer is in progress                                      |
| `complete`   | Transfer finalized and funds have arrived at the destination |
| `canceled`   | Transfer has been canceled                                   |
| `failed`     | Transfer could not be completed                              |

***

## Best Practices

### Security

* Store API credentials in environment variables or a secrets manager
* Use a fresh idempotency key for each new transfer request
* Refresh bearer tokens when they expire

### Testing

* Use testnet credentials during development
* Use `monad_testnet` while testing and `monad` in production
* Do not mix testnet credentials/resources with mainnet flows

### Addressing

* Use internal addresses for Brale-custodied wallets
* Register self-custody Monad wallets as external addresses before using them in transfers
* Store returned `address_id` values and reuse them across workflows

***

## Next Steps

* Explore the [Brale docs](https://docs.brale.xyz/)
* Review the [Brale API MCP guide](https://docs.brale.xyz/mcp/api)
* Confirm [supported transfer types and value types](https://docs.brale.xyz/coverage/transfer-types) before shipping production flows


# How to build custom deep links in an Expo-based mobile app
Source: https://docs.monad.xyz/guides/deeplinks-using-expo



Deep links are URLs that take users directly to specific content within a mobile app or website, rather than just launching the app's home screen. They work like shortcuts, enabling smoother navigation and improving user experience.

In this guide, you will learn the basics of adding deep links into your [Expo](https://docs.expo.dev/)-based mobile app.

## What are deep links?

Deep link is constructed by three parts:

* **Scheme**: The URL scheme that identifies the app that should open the URL (example: myapp\://). It can also be https or http for non-standard deep links.
* **Host**: The domain name of the app that should open the URL (example: web-app.com).
* **Path**: The path to the screen that should be opened (example: /product). If the path isn't specified, the user is taken to the home screen of the app.

Deep links can also have params just like web links!

Example:

```
rnwalletapp://swap?from={token}&to={token}&amount={amount}
```

## Building a deep link

<Note>
  If you'd like to try a deep link demo you can do by cloning [this](https://github.com/monad-developers/expo-swap-template/tree/branch/deeplink?tab=readme-ov-file) repo and switching to the `branch/deeplink` branch:

  ```bash theme={null}
  git clone https://github.com/monad-developers/expo-swap-template.git
  ```

  ```bash theme={null}
  git checkout branch/deeplink
  ```
</Note>

### Defining the scheme

The first step is to define a scheme; you can do so by editing the `app.json` file in the Expo project.

```json title="app.json" theme={null}
{
  "expo": {
    "scheme": "myapp" // or your preferred scheme
  }
}
```

<Warning>
  Custom schemes like `myapp://` are not unique across Android or iOS.
  If two apps register the same scheme, the system won’t know which one to launch, or it might launch the wrong one.
  Use something app-specific and hard to accidentally duplicate.
</Warning>

### Listening for deep link events

In your app entrypoint (e.g., `_layout.tsx` or a provider), add logic to:

* Handle initial deep link
* Listen for deep link changes

A good practice is to create a `DeepLinkHandler` and wrap the entire app with it.

Example (in an Expo project using File-based routing):

```tsx lines title="app/_layout.tsx" theme={null}
...

// Function to parse the deep link and get the hostname and queryParams
function parseSwapDeeplink(url: string): SwapDeeplinkParams | null {
  try {
    const { hostname, queryParams } = Linking.parse(url);
    
    if (hostname !== 'swap' || !queryParams) {
      return null;
    }

    return {
      from: queryParams.from as string | undefined,
      to: queryParams.to as string | undefined,
      amount: queryParams.amount as string | undefined,
    };
  } catch (error) {
    console.error('Error parsing deeplink:', error);
    return null;
  }
}

function DeeplinkHandler({ children }: { children: React.ReactNode }) {
  const router = useRouter();
  
  useEffect(() => {
    
    const handleDeeplink = (url: string) => {
      // Parse the deep link and get the params (host, path, params etc...)
      const params = parseSwapDeeplink(url);
      if (params) {
        // The example here makes the params globally accessible in the app, however you can use React Context or similar to make the params accessible from anywhere in the app.
        (global as any).swapDeeplinkParams = params;
        // Based on the path or host you can redirect the user to the respective screen in the app 
        router.replace('/');
      }
    };

    // Handle initial URL
    Linking.getInitialURL().then(url => url && handleDeeplink(url));

    // Create an event listener and handle URL changes while app is open
    const subscription = Linking.addEventListener('url', event => handleDeeplink(event.url));

    // Removes the event listener when the component is destroyed (avoids memory leaks)
    return () => subscription.remove();
  }, [router]);

  return <>{children}</>;
}


export default function Layout() {
    ...

    return (
        <DeeplinkHandler>
            <App />
        </DeeplinkHandler>
    );
 }
```

That's it, your app is ready to handle deep links based on the `hostname` and `queryParams` you can redirect the user to the respective screens.

Additionally if you make the `queryParams` accessible globally (via context or some other way) you can prefill input values too!

**Example: Prefilling token swap amounts!**

## Testing the deep link

Here's a demo of how deep links work in a mobile app:

<iframe title="YouTube video player" />

### Testing on iOS simulator

```bash theme={null}
xcrun simctl openurl booted [deeplink]
```

Example:

```bash theme={null}
xcrun simctl openurl booted "rnwalletapp://swap?from=MON&to=USDC&amount=100"
```

### Testing on Android emulator

```bash theme={null}
adb shell am start -W -a android.intent.action.VIEW -d [deeplink]
```

Example:

```bash theme={null}
# Important: Use single quotes to wrap the entire command to prevent shell from parsing & symbols
adb shell 'am start -W -a android.intent.action.VIEW -d "rnwalletapp://swap?from=MON&to=USDC&amount=100"'
```

<Warning>
  If you don't use single quotes, the shell will interpret `&` as a command separator, and only the first parameter will be passed to the app.
</Warning>

### Testing on a physical device

You can create a simple HTML page with links.

Example:

```html theme={null}
<a href="rnwalletapp://swap?from=MON&to=USDC&amount=100">Swap MON to USDC</a>
```

## Try out the demo

If you'd like to try a deep link demo you can do by setting up [this](https://github.com/monad-developers/expo-swap-template/tree/branch/deeplink?tab=readme-ov-file) repo and switch to the `branch/deeplink` branch.

```bash theme={null}
git clone https://github.com/monad-developers/expo-swap-template.git
```

```bash theme={null}
git checkout branch/deeplink
```

Here are some deep links you can try:

1. Swap MON to USDC

```
rnwalletapp://swap?from=MON&to=USDC
```

2. Swap 100 MON to USDC

```
rnwalletapp://swap?from=MON&to=USDC&amount=100
```

3. Swap USDC to WMON

```
rnwalletapp://swap?from=USDC&to=WMON&amount=1000
```


# Deploy a smart contract on Monad using Monad Foundry
Source: https://docs.monad.xyz/guides/deploy-smart-contract/foundry



[Monad Foundry](/tooling-and-infra/toolkits/monad-foundry) is a custom fork of [Foundry](https://book.getfoundry.sh/) with Monad-native EVM execution, staking precompile support, and human-readable trace decoding.

## 1. Installing Monad Foundry

Install the Monad Foundry installer:

```sh theme={null}
curl -L https://foundry.category.xyz | bash
```

Then install the binaries:

```sh theme={null}
foundryup --network monad
```

This installs `forge`, `cast`, `anvil`, and `chisel` with Monad support.

<Note>
  If you're on Windows, you'll need to use WSL, since Foundry currently doesn't work natively on Windows. Please follow [this link](https://learn.microsoft.com/en-us/windows/wsl/install) to learn more about WSL.
</Note>

## 2. Create a new foundry project

<Tip>
  You can use `foundry-monad` template to create a new project.

  *[Foundry-Monad](https://github.com/monad-developers/foundry-monad) is a Foundry template with Monad configuration.*
</Tip>

The below command uses `foundry-monad` to create a new foundry project:

```sh theme={null}
forge init --template monad-developers/foundry-monad [project_name]
```

Alternatively, you can create a foundry project using the command below:

```sh theme={null}
forge init [project_name]
```

## 3. Modify Foundry configuration

Update the `foundry.toml` file to add Monad Testnet configuration.

```toml lines title="foundry.toml" theme={null}
[profile.default]
src = "src"
out = "out"
libs = ["lib"]
# Monad Testnet Configuration
eth-rpc-url = "https://testnet-rpc.monad.xyz"
chain_id = 10143
```

## 4. Write a smart contract

You can write your smart contracts under the `src` folder. There is already a `Counter` contract in the project located at `src/Counter.sol`.

```solidity lines title="src/Counter.sol" theme={null}
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.13;

contract Counter {
    uint256 public number;

    function setNumber(uint256 newNumber) public {
        number = newNumber;
    }

    function increment() public {
        number++;
    }
}
```

## 5. Compile the smart contract

```sh theme={null}
forge compile
```

Compilation process output can be found in the newly created `out` directory, which includes contract ABI and bytecode.

## 6. Deploy the smart contract

<Note>
  For deploying contracts, we recommend using keystores instead of private keys.
</Note>

### Get testnet funds

Deploying smart contracts requires testnet funds. Claim testnet funds via a [faucet](https://testnet.monad.xyz).

### Deploy smart contract

<Tabs>
  <Tab title="Using a Keystore (Recommended)">
    Using a keystore is much safer than using a private key because keystore encrypts the private key and can later be referenced in any commands that require a private key.

    Create a new keystore by importing a newly generated private key with the command below.

    ```sh theme={null}
    cast wallet import monad-deployer --private-key $(cast wallet new | grep 'Private key:' | awk '{print $3}')
    ```

    Here is what the command above does, step by step:

    * Generates a new private key
    * Imports the private key into a keystore file named `monad-deployer`
    * Prints the address of the newly created wallet to the console

    After creating the keystore, you can read its address using:

    ```sh theme={null}
    cast wallet address --account monad-deployer
    ```

    Provide a password to encrypt the keystore file when prompted and do not forget it.

    Run the below command to deploy your smart contracts

    ```sh theme={null}
    forge create src/Counter.sol:Counter --account monad-deployer --broadcast
    ```
  </Tab>

  <Tab title="Using a Private Key (Not Recommended)">
    Use the below command to deploy a smart contract by directly pasting the private key in the terminal.

    <Warning>
      Using a private key is not recommended. You should not be copying and pasting private keys into your terminal. Please use a keystore instead.
    </Warning>

    ```sh theme={null}
    forge create --private-key <your_private_key> src/Counter.sol:Counter --broadcast
    ```
  </Tab>
</Tabs>

On successful deployment of the smart contract, the output should be similar to the following:

```sh theme={null}
[⠊] Compiling...
Deployer: 0xB1aB62fdFC104512F594fCa0EF6ddd93FcEAF67b
Deployed to: 0x67329e4dc233512f06c16cF362EC3D44Cdc800e0
Transaction hash: 0xa0a40c299170c9077d321a93ec20c71e91b8aff54dd9fa33f08d6b61f8953ee0
```

### Next Steps

Check out [how to verify the deployed smart contract on MonadVision](/guides/verify-smart-contract/foundry).


# Deploy a smart contract on Monad using Hardhat
Source: https://docs.monad.xyz/guides/deploy-smart-contract/hardhat



[Hardhat](https://hardhat.org/docs) is a comprehensive development environment consisting of different components for editing, compiling, debugging, and deploying your smart contracts.

## Requirements

Before you begin, you need to install the following dependencies:

* Node.js v18.0.0 or later

<Note>
  If you are on Windows, we strongly recommend using [WSL 2](https://learn.microsoft.com/en-us/windows/wsl/about) when following this guide.
</Note>

<Warning>
  When deploying to Monad, set `evmVersion: "prague"` in your Hardhat Solidity compiler settings. For example:

  ```ts theme={null}
  solidity: {
    version: "0.8.28",
    settings: {
      evmVersion: "prague",
    },
  },
  ```
</Warning>

<Tabs>
  <Tab title="Hardhat 2">
    ## 1. Create a new Hardhat project

    <Tip>
      You can use the `hardhat-monad` template to create a new project with Monad configuration already set up.

      *[hardhat-monad](https://github.com/monad-developers/hardhat-monad) is a Hardhat template with Monad configuration.*
    </Tip>

    Clone the repository to your machine using the command below:

    ```sh theme={null}
    git clone https://github.com/monad-developers/hardhat-monad.git
    cd hardhat-monad
    ```

    ## 2. Install dependencies

    ```sh theme={null}
    npm install
    ```

    ## 3. Create an .env file

    ```sh theme={null}
    cp .env.example .env
    ```

    Edit the `.env` file with your private key:

    ```
    PRIVATE_KEY=your_private_key_here
    ```

    <Warning>
      Protect your private key carefully. Never commit it to version control, share it in public repositories, or expose it in client-side code. Your private key provides full access to your funds.
    </Warning>

    ## 4. Deploy the smart contract

    The following commands use [Hardhat Ignition](https://hardhat.org/ignition/docs/getting-started#overview):

    ### Deploying to the local hardhat node

    Run hardhat node by running:

    ```bash theme={null}
    npx hardhat node
    ```

    To deploy the example contract to the local hardhat node, run the following command in a separate terminal:

    ```bash theme={null}
    npx hardhat ignition deploy ignition/modules/Counter.ts
    ```

    ### Deploying to Monad Testnet

    Ensure your private key is set in the `.env` file.

    Deploy the contract to Monad Testnet:

    ```bash theme={null}
    npx hardhat ignition deploy ignition/modules/Counter.ts --network monadTestnet
    ```

    Redeploy the same code to a different address:

    ```bash theme={null}
    npx hardhat ignition deploy ignition/modules/Counter.ts --network monadTestnet --reset
    ```

    ### Deploying to Monad Mainnet

    Ensure your private key is set in the `.env` file.

    Deploy the contract to Monad Mainnet:

    ```bash theme={null}
    npx hardhat ignition deploy ignition/modules/Counter.ts --network monadMainnet
    ```

    Redeploy the same code to a different address:

    ```bash theme={null}
    npx hardhat ignition deploy ignition/modules/Counter.ts --network monadMainnet --reset
    ```
  </Tab>

  <Tab title="Hardhat3">
    ## 1. Create a new Hardhat3 project

    <Tip>
      You can use the `hardhat3-monad` template to create a new project with Monad configuration already set up for Hardhat3.

      *[hardhat3-monad](https://github.com/monad-developers/hardhat3-monad) is a Hardhat3 template with Monad configuration.*

      To learn more about Hardhat3, please visit the [Getting Started guide](https://hardhat.org/docs/getting-started#getting-started-with-hardhat-3).
    </Tip>

    Clone the repository to your machine using the command below:

    ```sh theme={null}
    git clone https://github.com/monad-developers/hardhat3-monad.git
    cd hardhat3-monad
    ```

    ## 2. Install dependencies

    ```sh theme={null}
    npm install
    ```

    ## 3. Set up your private key

    Create a `.env` file in the project root:

    ```sh theme={null}
    PRIVATE_KEY=your_private_key_here
    ETHERSCAN_API_KEY=your_etherscan_api_key_here
    ```

    <Warning>
      Protect your private key carefully. Never commit your `.env` file or expose your private key. Your private key provides full access to your funds.
    </Warning>

    ## 4. Deploy the smart contract

    The following commands use [Hardhat Ignition](https://hardhat.org/ignition/docs/getting-started#overview):

    ### Deploying to a local chain

    ```bash theme={null}
    npx hardhat ignition deploy ignition/modules/Counter.ts
    ```

    ### Deploying to Monad Testnet

    Ensure your `.env` file is set up with your private key.

    ```bash theme={null}
    npx hardhat ignition deploy ignition/modules/Counter.ts --network monadTestnet
    ```

    ### Deploying to Monad Mainnet

    Ensure your `.env` file is set up with your private key.

    ```bash theme={null}
    npx hardhat ignition deploy ignition/modules/Counter.ts --network monadMainnet
    ```
  </Tab>
</Tabs>

## Next Steps

Check out [how to verify the deployed smart contract on MonadVision](/guides/verify-smart-contract/hardhat).


# Deploy a Contract
Source: https://docs.monad.xyz/guides/deploy-smart-contract/index



<CardGroup>
  <Card title="Foundry" href="/guides/deploy-smart-contract/foundry">
    Deploy a smart contract on Monad using Foundry
  </Card>

  <Card title="Hardhat" href="/guides/deploy-smart-contract/hardhat">
    Deploy a smart contract on Monad using Hardhat
  </Card>

  <Card title="Remix" href="/guides/deploy-smart-contract/remix">
    Deploy a smart contract on Monad using Remix
  </Card>
</CardGroup>


# Deploy a smart contract on Monad using Remix
Source: https://docs.monad.xyz/guides/deploy-smart-contract/remix



[Remix IDE](https://remix.ethereum.org/) is a browser-based IDE that can be used for the entire journey of smart contract development by users at every knowledge level. It requires no setup, fosters a fast development cycle, and has a rich set of plugins with intuitive GUIs.

In this guide you will learn how to deploy and interact with a simple Greeting smart contract on Monad Testnet using [Remix IDE](https://remix.ethereum.org/).

## Requirements

* You need to have the Monad Testnet network added to your wallet.

## Deploying the smart contract

Head over to [Remix IDE](https://remix.ethereum.org/) in your browser. Click 'Start Coding' to create a new project template.

<img alt="remix-ide" />

Make sure the 'contracts' folder is selected, then create a new file using the "Create new file" button on top left corner.

<img alt="create-file" />

Name the new file "Gmonad.sol" and add the following code to it

```solidity lines title="src/Gmonad.sol" theme={null}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

contract Gmonad { 
    string public greeting;

    constructor(string memory _greeting) {
        greeting = _greeting;
    }

    function setGreeting(string calldata _greeting) external {
        greeting = _greeting;
    }
}
```

**Note:** You may see a red squiggly line underneath the `pragma solidity...` line; this is because the default compiler version is outside of the range specified in the contract. We'll fix that in the next step.

<img alt="code" />

Let's compile the smart contract. Navigate to the compiler view by clicking the "Solidity compiler" tab on the far left. Then select the right compiler version (0.8.24).

<img alt="compiler" />

Once you have the right compiler version selected, click on the "Compile Gmonad.sol" button. If succesful, you will see a green check mark on the "Solidity compiler" tab icon.

<img alt="compile" />

Now we can deploy the smart contract! Navigate to the deploy view using the "Deploy & run transactions" tab on the far left.

<img alt="deploy" />

Using the "Environment" dropdown, select "Injected Provider" to connect to your wallet.

The screenshot below says "Injected Provider - Metamask"; in case you are using some wallet other than Metamask you may see an appropriate option.

<img alt="environment" />

Your wallet should pop up asking for permission to connect to Remix, click "Connect".

<img alt="connect" />

Once connected you should be able to see your address with your balance in the "Account" dropdown.

Make sure you also see the correct chain id under the "Environment" dropdown.

Now let's deploy the contract. `Gmonad.sol` requires a greeting message to be passed to the constructor before it can be deployed; choose the greeting message of your choice (in this example it is "gmonad").

Now you can deploy the smart contract by clicking the "Deploy" button.

<img alt="deploy" />

You should see a wallet popup asking for confirmation to deploy the smart contract. Click "Confirm".

<img alt="confirm" />

Once the transaction is confirmed you will see the smart contract address in the "Deployed Contracts" section on the bottom left.

<img alt="deployed" />

## Interacting with the smart contract

You can expand the smart contract to see the functions available.

There you will find a `greeting` button which can be used to read the current greeting message stored in the smart contract.

Click the "greeting" button to call the `greeting()` method (which outputs the current greeting message). You'll need to click the expand arrow in the terminal output to see the decoded output.

<Info>
  This "greeting" button is a getter function which is automatically created for the *public* `greeting` state variable in the smart contract.
</Info>

<img alt="expand" />

You can change the greeting message by using the `setGreeting` function.

In this example, we will change the greeting message to "gmonad molandak".

Once again, click the "transact" button to initiate the transaction.

You should see a wallet popup asking for confirmation to change the greeting message. Click "Confirm".

<img alt="transact" />

Once the transaction is confirmed you can view the updated greeting message using the `greeting` button.

<img alt="updated" />

Congratulations! You have successfully deployed and interacted with a smart contract on Monad  Testnet using Remix IDE.


# How to register and build with ERC-8004 (Trustless Agents) on Monad
Source: https://docs.monad.xyz/guides/erc-8004



This guide shows how to register AI agents and build trustless agent interactions using ERC-8004 on Monad.

## What is ERC-8004?

[ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) is an Ethereum standard for Trustless Agents that provides three on-chain registries for agent identity, reputation, and validation. It gives AI agents and agentic services (MCPs, APIs, etc) portable identity, verifiable track records, and cryptographic validation so they can operate as accountable economic actors.

The standard enables:

* **Identity Registry**: Agents register with an ERC-721 NFT and agent card
* **Reputation Registry**: Immutable feedback system for agent interactions
* **Validation Registry**: Third-party verification of agent work

### Key Benefits

* **Portable Identity**: Agents have persistent, transferable identities across platforms via ERC-721 tokens.
* **Verifiable Reputation**: Immutable on-chain feedback creates auditable track records for agents.
* **Trust Without Intermediaries**: Cryptographic validation enables trustless agent-to-agent interactions without any central entity.
* **Economic Interoperability**: Agents can discover, verify, and pay each other autonomously using x402.

## Core Components

### 1. Identity Registry

Each agent mints an ERC-721 token. The token ID is the agent's unique identifier, and the token URI points to an "agent card" with:

* Name and description
* API endpoints (A2A Protocol, MCP, HTTP, etc.)
* Supported trust models
* DID/ENS identifiers
* Agent wallet address for payments, if available

### 2. Reputation Registry

After interacting with an agent, clients submit structured feedback on-chain:

* Values measuring properties (e.g., uptime, success rate, quality)
* Tags for categorization (e.g., "fast", "accurate", "DeFi")
* Optional `feedbackURI` for detailed off-chain reviews
* Content hash for data integrity

Feedback is **permanent and immutable** - creating an auditable track record.

### 3. Validation Registry (coming soon)

For high-stakes tasks, third-party validators can verify agent work on-chain. The registry is unopinionated about validation models (TEE, zkML, fraud proofs, etc.).

## Interaction Flow

```mermaid theme={null}
sequenceDiagram
    box Agent A
        participant Service as Service
    end
    box ERC-8004
        participant Registries as Registries
    end
    box Agent B
        participant Client as Client
    end

    Service->>Registries: 1. Register identity
    Client->>Registries: 2. Discover agents
    Client->>Registries: 3. Check reputation
    Client->>Service: 4. Service request + x402 payment
    Service->>Client: 5. Service response
    Client->>Registries: 6. Submit feedback
```

## Use Cases

### Agentic Services Marketplace

* **Oracles**: Agents provide real-time data feeds (e.g., price feeds, weather, sports scores) that are discoverable via reputation.
* **Market ratings & analytics**: Specialized agents offer services such as risk assessment, credit scoring, and sentiment analysis.
* **APIs as agents**: Any API—such as weather, translation, or image processing—can register as an agent, making them both discoverable and payable.
* **Reputation-gated access**: Services can filter or restrict clients based on their on-chain reputation histories.

### Agent Routing Systems

Instead of implementing services natively, agents call routing systems that dynamically select the best service provider based on:

* **Latency**: Route to the fastest available agent for time-sensitive tasks
* **Price**: Find the most cost-effective provider for bulk operations
* **Reputation**: Select highly-rated agents for critical operations
* **Specialization**: Match task requirements to agent capabilities

### AI Agent Marketplaces

* Agents register services with pricing
* Clients discover agents via reputation
* Automated service discovery and payment

### Autonomous Service Networks

* Agents hire other agents for subtasks
* Reputation-based trust decisions
* Automatic feedback loops

### DeFi Agent Protocols

* Portfolio management agents
* Trading strategy agents
* Yield optimization agents

### Enterprise Agent Ecosystems

* Internal agent directories
* Cross-organization agent collaboration
* Compliance and audit trails

## Best Practices

### Registration

* Use descriptive agent names and thorough documentation.
* Provide multiple endpoint types for improved flexibility.
* Keep agent cards updated as capabilities change.
* Use ENS names for easier discovery.

### Reputation Management

* Submit honest feedback after every interaction
* Use consistent tag taxonomies
* Include detailed reviews for significant interactions
* Respond to feedback on your agents

### Security

* Verify agent signatures before payments
* Check reputation before high-value transactions
* Use validation registry for critical operations
* Monitor feedback for your agents

You can find more [here](https://github.com/erc-8004/best-practices).

## Advanced Features

### Cross-Chain Agent Discovery

```ts theme={null}
// Bridge agent identity across chains
import { CCIPRouter } from "@chainlink/ccip";

async function bridgeAgentToMonad(agentId: string, sourceChain: string) {
  // Query agent card from source chain
  // Register mirror on Monad
  // Link reputation data
}
```

### Reputation Aggregation

```ts theme={null}
// Build custom reputation scoring
function calculateTrustScore(feedback: Feedback[]): number {
  const recentWeight = 0.7;
  const historicalWeight = 0.3;
  
  const recent = feedback.slice(0, 10);
  const historical = feedback.slice(10);
  
  const recentScore = average(recent.map(f => f.value));

  const historicalScore = average(historical.map(f => f.value));
  
  return recentScore * recentWeight + historicalScore * historicalWeight;
}
```

### Validation Integration

```ts theme={null}
// TEE-based validation (coming soon)
async function validateWithTEE(
  agentId: string,
  task: any,
  proof: any
) {
  // Submit to validation registry
  // TEE verifies execution
  // On-chain proof recorded
}
```

## Resources

* [ERC-8004 Specification](https://www.8004.org/learn)
* [ERC-8004 GitHub](https://github.com/erc-8004)
* [agent0 SDK](https://sdk.ag0.xyz/) - TypeScript and Python SDKs, with guides
* [8004scan.io](https://8004scan.io) -  Browse agents and reputation
* [Agentscan.info](http://Agentscan.info) - Browse agents and reputation
* [8004agents.ai](http://8004agents.ai) - Browse agents and reputation
* [Monad Developer Discord](https://discord.gg/monaddev)

## Contract Addresses

<ul>
  <li>
    <strong>Identity Registry</strong>:

    <CopyToClipboard>
      [`0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`](https://monadvision.com/address/0x8004A169FB4a3325136EB29fA0ceB6D2e539a432)
    </CopyToClipboard>
  </li>

  <li>
    <strong>Reputation Registry</strong>:

    <CopyToClipboard>
      [`0x8004BAa17C55a88189AE136b182e5fdA19dE9b63`](https://monadvision.com/address/0x8004BAa17C55a88189AE136b182e5fdA19dE9b63)
    </CopyToClipboard>
  </li>

  <li>
    <strong>Validation Registry</strong>: (coming soon)
  </li>
</ul>

## Need Help?

Join the [Monad Developer Discord](https://discord.gg/monaddev) or reach out to [team@8004.org](mailto:team@8004.org)

Happy building! 🤖


# EVM Behavior
Source: https://docs.monad.xyz/guides/evm-resources/evm-behavior



## EVM Behavioral Specification

* [Notes on the EVM](https://github.com/CoinCulture/evm-tools/blob/master/analysis/guide.md): straightforward technical specification of the EVM plus some behavioral examples
* [EVM: From Solidity to bytecode, memory and storage](https://www.youtube.com/watch?v=RxL_1AfV7N4): a 90-minute talk from Peter Robinson and David Hyland-Wood
* [EVM illustrated](https://takenobu-hs.github.io/downloads/ethereum_evm_illustrated.pdf): an excellent set of diagrams for confirming your mental model
* [EVM Deep Dives: The Path to Shadowy Super-Coder](https://noxx.substack.com/p/evm-deep-dives-the-path-to-shadowy)

## Opcode Reference

<Note>
  Opcode pricing on Monad has been changed to reflect their relative costs in execution, learn more about it [here](/developer-essentials/opcode-pricing)
</Note>

[evm.codes](https://www.evm.codes/): opcode reference and an interactive sandbox for stepping through bytecode execution

## Solidity Storage Layout

The EVM allows smart contracts to store data in 32-byte words ("storage slots"), however the details of how complex datastructures such as lists or mappings is left as an implementation detail to the higher-level language.  Solidity has a specific way of assigning variables to storage slots, described below:

* [Official docs on storage layout](https://docs.soliditylang.org/en/latest/internals/layout_in_storage.html)
* [Storage patterns in Solidity](https://programtheblockchain.com/posts/2018/03/09/understanding-ethereum-smart-contract-storage/)


# EVM Resources
Source: https://docs.monad.xyz/guides/evm-resources/index



Resources for learning about EVM development, from Solidity basics to low-level assembly languages.

<CardGroup>
  <Card title="Solidity Resources" href="/guides/evm-resources/solidity-resources">
    A comprehensive guide to learning Solidity, from beginner to advanced
  </Card>

  <Card title="EVM Behavior" href="/guides/evm-resources/evm-behavior">
    EVM behavioral specification, opcode reference, and storage layout
  </Card>

  <Card title="Other Languages" href="/guides/evm-resources/other-languages">
    Resources for Vyper, Huff, and Yul
  </Card>
</CardGroup>


# Huff
Source: https://docs.monad.xyz/guides/evm-resources/other-languages/huff



[Huff](https://docs.huff.sh/) is most closely described as EVM assembly. Unlike Yul, Huff does not provide control flow constructs or abstract away the inner working of the program stack. Only the most upmost performance sensitive applications take advantage of Huff, however it is a great educational tool to learn how the EVM interprets instructions its lowest level.

* [Huff resources](https://docs.huff.sh/resources/overview/) provides additional resources


# Other Languages
Source: https://docs.monad.xyz/guides/evm-resources/other-languages/index



Alternative smart contract languages for the EVM beyond Solidity.

<CardGroup>
  <Card title="Vyper" href="/guides/evm-resources/other-languages/vyper">
    A Python-like language for EVM smart contracts
  </Card>

  <Card title="Huff" href="/guides/evm-resources/other-languages/huff">
    Low-level EVM assembly language
  </Card>

  <Card title="Yul" href="/guides/evm-resources/other-languages/yul">
    Intermediate assembly language for the EVM
  </Card>
</CardGroup>


# Vyper
Source: https://docs.monad.xyz/guides/evm-resources/other-languages/vyper



[Vyper](https://www.quicknode.com/guides/ethereum-development/smart-contracts/how-to-write-an-ethereum-smart-contract-using-vyper) is a popular programming language for the EVM that is logically similar to Solidity and syntactically similar with Python.

The [Vyper documentation](https://docs.vyperlang.org/en/stable/index.html) covers installing the Vyper language, language syntax, coding examples, compilation.

A typical EVM developer looking for a Python-like experience is encouraged to use Vyper as the programming language and [ApeWorx](https://docs.apeworx.io/ape/stable/userguides/quickstart.html), which leverages the Python language, as the testing and deployment framework. ApeWorx also allows for the use of typical Python libraries in analysis of testing results such as Pandas.

Vyper and ApeWorx can be used with [Jupyter](https://jupyter.org/), which offers an interactive environment using a web browser.  A quick setup guide for working with Vyper and Jupyter for smart contract development for the EVM can be found [here](https://medium.com/deepyr/interacting-with-ethereum-using-web3-py-and-jupyter-notebooks-e4207afa0085).

## Resources

* [Vyper by Example](https://vyper-by-example.org/)
* [Snekmate](https://github.com/pcaversaccio/snekmate): a Vyper library of gas-optimized smart contract building blocks
* [Curve contracts](https://github.com/curvefi/curve-contract): the most prominent example usage of Vyper


# Yul
Source: https://docs.monad.xyz/guides/evm-resources/other-languages/yul



[Yul](https://docs.soliditylang.org/en/latest/yul.html) is a intermediate language for Solidity that can generally be thought of as inline assembly for the EVM. It is not quite pure assembly, providing control flow constructs and abstracting away the inner working of the stack while still exposing the raw memory backend to developers. Yul is targeted at developers needing exposure to the EVM's raw memory backend to build high performance gas optimized EVM code.


# Solidity Resources
Source: https://docs.monad.xyz/guides/evm-resources/solidity-resources



Monad is fully EVM bytecode-compatible, with all supported opcodes and precompiles as of the [Osaka fork](https://www.evm.codes/?fork=osaka). Monad also preserves the standard Ethereum JSON-RPC interfaces.

As such, most development resources for Ethereum Mainnet apply to development on Monad.

This page suggests a **minimal** set of resources for getting started with building a decentralized app for Ethereum. Child pages provide additional detail or options.&#x20;

As [Solidity](https://docs.soliditylang.org/) is the most popular language for Ethereum smart contracts, the resources on this page focus on Solidity; alternatively see resources on [Vyper](/guides/evm-resources/other-languages/vyper) or [Huff](/guides/evm-resources/other-languages/huff). Note that since smart contracts are composable, contracts originally written in one language can still make calls to contracts in another language.

## **IDEs**

* [Remix](https://remix.ethereum.org/#lang=en\&optimize=false\&runs=200\&evmVersion=null) is an interactive Solidity IDE. It is the easiest and fastest way to get started coding and compiling Solidity smart contracts without the need for additional tool installations.
* [VSCode](https://code.visualstudio.com/) + [Solidity extension](https://marketplace.visualstudio.com/items?itemName=NomicFoundation.hardhat-solidity)

## **Basic Solidity**

* [CryptoZombies](https://cryptozombies.io/en/course) is a great end-to-end introduction to building dApps on the EVM. It provides resources and lessons for anyone from someone who has never coded before, to experienced developers in other disciplines looking to explore blockchain development.
* [Solidity by Example](https://solidity-by-example.org/) introduces concepts progressively through simple examples; best for developers who already have basic experience with other languages.
* [Blockchain Basics course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/blockchain-basics) teaches the fundamentals of blockchain, DeFi, and smart contracts.
* [Solidity Smart Contract Development by Cyfrin Updraft](https://updraft.cyfrin.io/courses/solidity) will teach you how to become a smart contract developer. Learn to build with projects and get hands-on experience.
* [Ethereum Developer Degree by LearnWeb3](https://learnweb3.io/degrees/ethereum-developer-degree/) is the a good course to go from no background knowledge in web3 to being able to build multiple applications and understanding several key protocols, frameworks, and concepts in the web3 space.

## **Intermediate Solidity**

* [The Solidity Language](https://docs.soliditylang.org/en/v0.8.21/introduction-to-smart-contracts.html) official documentation is an end-to-end description of Smart Contracts and blockchain basics centered on EVM environments. In addition to Solidity Language documentation, it covers the basics of compiling your code for deployment on an EVM as well as the basic components relevant to deploying a Smart Contract on an EVM.
* [Solidity Patterns](https://github.com/fravoll/solidity-patterns) repository provides a library of code templates and explanation of their usage.&#x20;
* The [Uniswap V2](https://github.com/Uniswap/v2-core) contract is a professional yet easy to digest smart contract that provides a great overview of an in-production Solidity dApp. A guided walkthrough of the contract can be found [here](https://ethereum.org/en/developers/tutorials/uniswap-v2-annotated-code/).
* [Cookbook.dev](https://www.cookbook.dev/search?q=cookbook\&categories=Contracts\&sort=popular\&filter=\&page=1) provides a set of interactive example template contracts with live editing, one-click deploy, and an AI chat integration to help with code questions.&#x20;
* [OpenZeppelin](https://www.openzeppelin.com/contracts) provides customizable template contract library for common Ethereum token deployments such as ERC20, ERC712, and ERC1155. Note, they are not gas optimized.
* [Rareskills Blog](https://www.rareskills.io/category/solidity) has some great in-depth articles on various concepts in Solidity.
* [Foundry Fundamentals course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/foundry) is a comprehensive web3 development course designed to teach you about Foundry the industry-standard framework to build, deploy, and test your smart contracts.
* [Smart Contract Programmer YT channel](https://www.youtube.com/@smartcontractprogrammer) has a plenty of in-depth videos about various Solidity concepts like ABI encoding, EVM memory, and many more.

## **Advanced Solidity**

* The [Solmate repository](https://github.com/transmissions11/solmate) and [Solady repository](https://github.com/Vectorized/solady/tree/main) provide gas-optimized contracts utilizing Solidity or Yul.
* [Yul](https://docs.soliditylang.org/en/latest/yul.html) is a intermediate language for Solidity that can generally be thought of as inline assembly for the EVM. It is not quite pure assembly, providing control flow constructs and abstracting away the inner working of the stack while still exposing the raw memory backend to developers. Yul is targeted at developers needing exposure to the EVM's raw memory backend to build high performance gas optimized EVM code.&#x20;
* [Huff](https://docs.huff.sh/get-started/overview/) is most closely described as EVM assembly. Unlike Yul, Huff does not provide control flow constructs or abstract away the inner working of the program stack. Only the most upmost performance sensitive applications take advantage of Huff, however it is a great educational tool to learn how the EVM interprets instructions its lowest level.
* [Advanced Foundry course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/advanced-foundry) teaches you about Foundry, how to develop a DeFi protocol and a stablecoin, how to develop a DAO, advanced smart contract development, advanced smart contracts testing and fuzzing and manual verification.
* [Smart Contract Security course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/security) will teach you everything you need to know to get started auditing and writing secure protocols.
* [Assembly and Formal Verification course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/formal-verification) teaches you about Assembly, writing smart contracts using Huff and Yul, Ethereum Virtual Machine OPCodes, Formal verification testing, Smart contract invariant testing and tools like Halmos, Certora, Kontrol.
* [Smart Contract DevOps course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/wallets) teaches about access control best practices when working with wallets, post-deployment security, smart contract and web3 devOps and live protocols maintenance and monitoring.
* [Secureum YT Channel](https://www.youtube.com/@SecureumVideos/videos) has plenty videos about Solidity from Solidity Basics to all the way to advanced concepts like Fuzzing and Solidity auditing.

## Tutorials

* [Ethernaut](https://ethernaut.openzeppelin.com/): learn by solving puzzles
* [Damn Vulnerable DeFi](https://www.damnvulnerabledefi.xyz): DVD is a series of smart contract challenges which consists of vulnerable contracts and you are supposed to be able to hack it. These challenges are a good way to practice and apply the Solidity skills you have acquired.

## Best practices/patterns

* [DeFi developer roadmap](https://github.com/OffcierCia/DeFi-Developer-Road-Map)
* [RareSkills Book of Gas Optimization](https://www.rareskills.io/post/gas-optimization)

## Testing

* [Echidna](https://github.com/crytic/echidna): fuzz testing
* [Slither](https://github.com/crytic/slither): static analysis for vulnerability detection
* [solidity-coverage](https://github.com/sc-forks/solidity-coverage/tree/master): code coverage for Solidity testing

## Smart contract archives

* [Smart contract sanctuary](https://github.com/tintinweb/smart-contract-sanctuary) - contracts verified on Etherscan
* [EVM function signature database](https://www.4byte.directory/)


# How to Consume Execution Events in Rust
Source: https://docs.monad.xyz/guides/execution-events/consume-rust



# How to Consume Execution Events in Rust: A Basic Example

This guide walks through building a minimal Rust application that reads execution events from a live Monad node. By the end of this guide, you'll have a working event consumer that prints each EVM action as it happens.

<iframe title="YouTube video player" />

## Prerequisites

This guide assumes you have:

* A running Monad node with execution events enabled ([setup guide](/guides/execution-events/setup))

## Project Setup

Here is the [repo with the code](https://github.com/portdeveloper/simple-execution-events).

Create a new Rust project:

```bash theme={null}
cargo new --bin exec-events-demo
cd exec-events-demo
```

Replace `Cargo.toml` with:

```toml theme={null}
[package]
name = "exec-events-demo"
version = "0.1.0"
edition = "2021"

[dependencies]
monad-exec-events = { git = "https://github.com/category-labs/monad-bft", tag = "release/exec-events-sdk-v1.0" }
monad-event-ring = { git = "https://github.com/category-labs/monad-bft", tag = "release/exec-events-sdk-v1.0" }
```

## The Code

Replace `src/main.rs` with:

```rust title="src/main.rs" theme={null}
use std::time::Duration;

use monad_event_ring::{DecodedEventRing, EventNextResult, EventPayloadResult, EventRingPath};
use monad_exec_events::{ExecEvent, ExecEventReaderExt, ExecEventRing, ExecEventType};

/// Default path for the execution event ring
const EVENT_RING_PATH: &str =
    "/var/lib/hugetlbfs/user/monad/pagesize-2MB/event-rings/monad-exec-events";

fn main() {
    // Resolve the event ring path (full path bypasses hugetlbfs lookup)
    let event_ring_path =
        EventRingPath::resolve(EVENT_RING_PATH).expect("Failed to resolve path");

    // Open the live event ring
    let ring = ExecEventRing::new(&event_ring_path).expect("Failed to open event ring");

    println!("Connected to event ring");
    println!("Waiting for events...\n");

    // Create a reader and rewind to the start of the current block
    let mut reader = ring.create_reader();
    reader.consensus_prev(Some(ExecEventType::BlockStart));

    loop {
        match reader.next_descriptor() {
            EventNextResult::Ready(event) => {
                let seqno = event.info().seqno;

                // Try to read the event payload
                match event.try_read() {
                    EventPayloadResult::Ready(exec_event) => {
                        print_event(&exec_event, seqno);
                    }
                    EventPayloadResult::Expired => {
                        eprintln!("[{}] Payload expired!", seqno);
                        reader.reset();
                    }
                }
            }
            EventNextResult::Gap => {
                eprintln!("Warning: event gap occurred (reader too slow)");
                reader.reset();
            }
            EventNextResult::NotReady => {
                // No events available, wait briefly
                std::thread::sleep(Duration::from_millis(10));
            }
        }
    }
}

fn print_event(event: &ExecEvent, seqno: u64) {
    match event {
        ExecEvent::BlockStart(block) => {
            println!(
                "[{}] BLOCK_START: number={}",
                seqno, block.block_tag.block_number
            );
        }
        ExecEvent::BlockEnd(_) => {
            println!("[{}] BLOCK_END", seqno);
        }
        ExecEvent::TxnHeaderStart { txn_index, .. } => {
            println!("[{}] TXN_START: index={}", seqno, txn_index);
        }
        ExecEvent::TxnEvmOutput { txn_index, output } => {
            println!(
                "[{}] TXN_OUTPUT: index={} gas_used={}",
                seqno, txn_index, output.receipt.gas_used
            );
        }
        ExecEvent::TxnLog { txn_index, txn_log, .. } => {
            println!(
                "[{}] LOG: txn={} topics={}",
                seqno, txn_index, txn_log.topic_count
            );
        }
        ExecEvent::TxnEnd => {
            println!("[{}] TXN_END", seqno);
        }
        // Silently ignore other events (call frames, storage access, etc.)
        _ => {}
    }
}
```

## Build and Run

```bash theme={null}
cargo build --release
./target/release/exec-events-demo
```

## Expected Output

You'll see a stream of events as your node processes transactions:

```
Connected to event ring
Waiting for events...

[508183802] BLOCK_START: number=45199825
[508183811] TXN_START: index=0
[508183822] TXN_OUTPUT: index=0 gas_used=0
[508183823] LOG: txn=0 topics=3
[508183838] TXN_END
[508183942] BLOCK_END
```

## Key Concepts

### Event Ring

The event ring is a shared memory buffer where the execution daemon writes events. Multiple readers can consume from it simultaneously, each maintaining their own position.

### EventNextResult

* **Ready**: An event is available to process
* **NotReady**: No new events yet (daemon hasn't written any)
* **Gap**: Reader fell behind and events were overwritten - call `reset()` to recover

### Event Types

Common events you'll see:

* `BlockStart` / `BlockEnd` - Block boundaries
* `TxnHeaderStart` / `TxnEnd` - Transaction boundaries
* `TxnEvmOutput` - Transaction execution result (contains receipt with gas\_used)
* `TxnLog` - EVM log emission (Solidity events)
* `AccountAccess` - Account touched during execution
* `StorageAccess` - Contract storage read/write

## Next Steps

* See the full [eventwatch.rs](https://github.com/category-labs/monad-bft/blob/release/exec-events-sdk-v1.0/monad-exec-events/examples/eventwatch.rs) example for production patterns (timestamps, timeout detection, CLI args)
* Read the [Rust API docs](/execution-events/rust-api) for detailed type information
* Explore the [event ring internals](/execution-events/event-ring) to understand the shared memory protocol


# How to accelerate your app with Execution Events
Source: https://docs.monad.xyz/guides/execution-events/index



<CardGroup>
  <Card title="Set up Execution Events" href="/guides/execution-events/setup">
    Configure your Monad node to enable execution events
  </Card>

  <Card title="Consume Events in Rust" href="/guides/execution-events/consume-rust">
    Build a Rust application to read execution events
  </Card>
</CardGroup>


# Set up Execution Events
Source: https://docs.monad.xyz/guides/execution-events/setup



This guide walks you through configuring your Monad node to enable the Execution Events system, which allows you to build high-performance applications that receive lowest-latency event data via shared memory.

## Prerequisites

* A running Monad full node ([full node installation guide](/node-ops/full-node-installation))
* A stable way to access the node

<Info title="Why execution events?">
  Monad produces blocks every 400 milliseconds and can process thousands of transactions per block. Traditional JSON-RPC and WebSocket APIs may not keep up with this data volume. Execution events provide the highest-throughput, lowest-latency option for consuming real-time blockchain data.

  For more details, see the [Execution Events documentation](/execution-events/).
</Info>

## Step 1: Install required packages

Install the `hugeadm` utility for managing huge pages:

```bash theme={null}
sudo apt install libhugetlbfs-bin
```

<Accordion title="Behind the scenes">
  Installs the `libhugetlbfs-bin` package, which provides the `hugeadm` command-line tool. This tool manages "huge pages" - large memory pages (2MB instead of the standard 4KB) that reduce memory management overhead and improve performance for applications that need to share large amounts of data quickly, like execution events.
</Accordion>

If you plan to write applications using the Execution Events SDK (C, C++, or Rust), also install these development packages:

```bash theme={null}
sudo apt install libhugetlbfs-dev libhugetlbfs0 libzstd-dev
```

<Accordion title="Behind the scenes">
  * **libhugetlbfs-dev**: Header files for developing applications that use huge pages
  * **libhugetlbfs0**: Runtime library for huge page support
  * **libzstd-dev**: Zstandard compression library, used for efficient data encoding in the SDK
</Accordion>

## Step 2: Set up the `hugetlbfs` mount

The execution events system uses huge pages for high-performance shared memory communication. You need to create a persistent `hugetlbfs` mount.

### Create a systemd service for persistent mounts

Create the service file:

```bash theme={null}
sudo nano /etc/systemd/system/events-hugepages-mounts.service
```

Paste the following contents (replace `monad` with your user if different):

```ini theme={null}
[Unit]
Description=Create hugepage mounts for monad
After=local-fs.target

[Service]
Type=oneshot
ExecStart=/usr/bin/hugeadm --create-user-mounts monad
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
```

<Accordion title="Behind the scenes">
  This systemd service runs `hugeadm --create-user-mounts monad` at boot time, which:

  * Creates a `hugetlbfs` filesystem mount at `/var/lib/hugetlbfs/user/monad/`
  * Sets up separate directories for different page sizes (2MB and 1GB)
  * Ensures the `monad` user has permission to create files in these directories

  The `Type=oneshot` means it runs once at startup, and `RemainAfterExit=yes` keeps the service marked as "active" so systemd knows the mount is still needed.
</Accordion>

Save and exit (`Ctrl+O`, `Enter`, `Ctrl+X`).

Enable and start the service:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl enable --now events-hugepages-mounts
```

<Accordion title="Behind the scenes">
  * **daemon-reload**: Tells systemd to re-read all service files, picking up your new service
  * **enable --now**: Enables the service to start at boot AND starts it immediately

  After this, the hugepage mount will be available now and on every reboot.
</Accordion>

## Step 3: Create the event-rings directory

The execution daemon writes event data to files in this directory:

```bash theme={null}
sudo mkdir -p /var/lib/hugetlbfs/user/monad/pagesize-2MB/event-rings
sudo chown monad:monad /var/lib/hugetlbfs/user/monad/pagesize-2MB/event-rings
```

<Accordion title="Behind the scenes">
  * **mkdir -p**: Creates the `event-rings` directory (and any parent directories if needed)
  * **chown monad:monad**: Changes ownership to the `monad` user so the execution daemon can write event ring files here

  The path `/var/lib/hugetlbfs/user/monad/pagesize-2MB/` is where `hugeadm` created the 2MB huge page mount. The execution daemon will create shared memory files in `event-rings/` that your consumer applications can read.
</Accordion>

<Note>
  Replace `monad` with your actual user if you're running the node as a different user.
</Note>

## Step 4: Configure the Execution daemon

Create a systemd override to enable execution events output.

Open the override editor:

```bash theme={null}
sudo systemctl edit monad-execution
```

<Accordion title="Behind the scenes">
  Opens a text editor to create an "override" file for the `monad-execution` service. Overrides let you modify service settings without editing the original unit file (which would be overwritten on package updates). The override file is saved at `/etc/systemd/system/monad-execution.service.d/override.conf`.
</Accordion>

Add the following configuration:

```ini theme={null}
[Service]
ExecStart=
ExecStart=/usr/local/bin/monad \
    --chain "$CHAIN" \
    --db /dev/triedb \
    --block_db /home/monad/monad-bft/ledger \
    --statesync /home/monad/monad-bft/statesync.sock \
    --exec-event-ring /var/lib/hugetlbfs/user/monad/pagesize-2MB/event-rings/monad-exec-events \
    --sq_thread_cpu 1 \
    --log_level INFO
```

<Accordion title="Behind the scenes">
  * **ExecStart=** (empty): Clears the original command from the base unit file (required for overrides)
  * **ExecStart=/usr/local/bin/monad ...**: Sets the new command with all flags
  * **--exec-event-ring**: The key flag that enables execution events output. It specifies the path where the daemon will create the shared memory event ring file

  The other flags are standard execution daemon options copied from the default configuration.
</Accordion>

<Warning>
  Both `ExecStart=` lines are required. The first clears the original value, and the second sets the new value with the `--exec-event-ring` flag.
</Warning>

Reload and restart the Execution daemon:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl restart monad-execution
```

<Accordion title="Behind the scenes">
  * **daemon-reload**: Tells systemd to re-read all service files, including your new override
  * **restart monad-execution**: Stops and starts the execution daemon with the new configuration

  After restart, the daemon will begin writing execution events to the shared memory ring buffer.
</Accordion>

## Step 5: Configure the RPC daemon for WebSocket support

This step enables WebSocket support in the RPC server, allowing you to use `eth_subscribe` for real-time data.

<Warning>
  RPC with WebSocket enabled has a hard dependency on Execution running with events enabled. If you start RPC with `--ws-enabled` before completing Step 4, RPC will crash.
</Warning>

Open the RPC override editor:

```bash theme={null}
sudo systemctl edit monad-rpc
```

<Accordion title="Behind the scenes">
  Creates an override file at `/etc/systemd/system/monad-rpc.service.d/override.conf` to customize the RPC service configuration.
</Accordion>

Add the following configuration:

```ini theme={null}
[Service]
ExecStart=
ExecStart=/usr/local/bin/monad-rpc \
    --ipc-path /home/monad/monad-bft/mempool.sock \
    --triedb-path /dev/triedb \
    --otel-endpoint "http://0.0.0.0:4317" \
    --allow-unprotected-txs \
    --node-config /home/monad/monad-bft/config/node.toml \
    --exec-event-path /var/lib/hugetlbfs/user/monad/pagesize-2MB/event-rings/monad-exec-events \
    --ws-enabled
```

<Accordion title="Behind the scenes">
  * **ExecStart=** (empty): Clears the original command from the base unit file (required for overrides)
  * **--exec-event-path**: Points to the same event ring file that the Execution daemon writes to
  * **--ws-enabled**: Enables WebSocket support on port 8081 (default)
</Accordion>

Reload and restart the RPC daemon:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl restart monad-rpc
```

<Accordion title="Behind the scenes">
  * **daemon-reload**: Tells systemd to re-read all service files, including your new override
  * **restart monad-rpc**: Stops and starts the RPC daemon with WebSocket support enabled
</Accordion>

## Step 6: Verify the setup

Check that the event ring file has been created:

```bash theme={null}
ls -la /var/lib/hugetlbfs/user/monad/pagesize-2MB/event-rings/
```

<Accordion title="Behind the scenes">
  Lists the contents of the event-rings directory. You should see a file named `monad-exec-events`. This is the shared memory file that the execution daemon writes to and your consumer applications read from.
</Accordion>

You should see a file named `monad-exec-events` (or similar).

Check the Execution daemon status:

```bash theme={null}
sudo systemctl status monad-execution
```

<Accordion title="Behind the scenes">
  Shows the current status of the execution daemon service. Look for:

  * **Active: active (running)** - the service is running
  * No error messages in the recent log output

  If you see errors related to the event ring or hugepages, check the Troubleshooting section below.
</Accordion>

The service should be active and running without errors.

### Check WebSocket connectivity

A quick way to check if WebSocket connectivity is working is to use [`websocat`](https://github.com/vi/websocat), a command-line WebSocket client. It can be installed via `cargo install websocat` or by downloading precompiled binaries.

Run it in verbose mode with the WebSocket service on default port 8081:

```bash theme={null}
websocat -v ws://localhost:8081
```

You should see output like:

```
[INFO  websocat::lints] Auto-inserting the line mode
[INFO  websocat::stdio_threaded_peer] get_stdio_peer (threaded)
[INFO  websocat::ws_client_peer] get_ws_client_peer
[INFO  websocat::net_peer] Connected to TCP 127.0.0.1:8081
[INFO  websocat::ws_client_peer] Connected to ws
[INFO  websocat::ws_peer] Received WebSocket ping
```

To subscribe to new block headers, type this JSON-RPC call and press enter:

```json theme={null}
{ "id": 1, "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newHeads"] }
```

Every half-second or so, you should see updates about new blocks.

## Next steps

With execution events and WebSocket support enabled, you can now:

* **Build your own data consumer**: Write high-performance applications in C, C++, or Rust using the Execution Events SDK. See the [Getting Started guide](/execution-events/getting-started/) for examples.

* **Learn more about WebSocket subscriptions**: See the [WebSocket Guide](/reference/websockets) for all available subscription types.

## Troubleshooting

### Event ring file not created

Ensure the hugepage mount is active:

```bash theme={null}
mount | grep hugetlbfs
```

<Accordion title="Behind the scenes">
  Lists all mounted filesystems and filters for `hugetlbfs` mounts. You should see output like:

  ```
  hugetlbfs on /var/lib/hugetlbfs/user/monad/pagesize-2MB type hugetlbfs (rw,relatime,...)
  ```

  If there's no output, the hugepage mount isn't active.
</Accordion>

You should see a mount point like `/var/lib/hugetlbfs/user/monad/pagesize-2MB`.

If not, restart the hugepages service:

```bash theme={null}
sudo systemctl restart events-hugepages-mounts
```

<Accordion title="Behind the scenes">
  Re-runs the hugepage mount service, which will recreate the `hugetlbfs` mount points. After this, run the `mount | grep hugetlbfs` command again to verify.
</Accordion>

### Execution daemon fails to start

Check the logs for errors:

```bash theme={null}
sudo journalctl -u monad-execution -f
```

<Accordion title="Behind the scenes">
  * **journalctl -u monad-execution**: Shows logs for the execution daemon service
  * **-f**: Follows the log in real-time (like `tail -f`)

  Press `Ctrl+C` to stop following. Look for error messages mentioning the event ring path, permissions, or hugepages.
</Accordion>

Common issues:

* The `event-rings` directory doesn't exist or has wrong permissions
* The hugepage mount is not available
* Incorrect paths in the systemd override

### Permission denied errors

Ensure the `event-rings` directory is owned by the correct user:

```bash theme={null}
sudo chown -R monad:monad /var/lib/hugetlbfs/user/monad/
```

<Accordion title="Behind the scenes">
  Recursively changes ownership of the entire hugepage directory tree to the `monad` user. The `-R` flag ensures all subdirectories and files are updated.
</Accordion>

## Further resources

* [Execution Events documentation](/execution-events/) - Comprehensive documentation on the execution events system
* [Execution Events overview](/execution-events/overview) - Core concepts and event types
* [C API reference](/execution-events/c-api) - C library documentation
* [Rust API reference](/execution-events/rust-api) - Rust crate documentation
* [Execution Events and WebSocket Setup](/node-ops/events-and-websockets) - Enable WebSocket support in RPC


# Guides
Source: https://docs.monad.xyz/guides/index



Start building smart contracts and applications on Monad with our quickstart guides.

## Get a wallet

<CardGroup>
  <Card title="Phantom" href="https://phantom.com/download" />

  <Card title="Metamask" href="https://metamask.io/download/" />
</CardGroup>

## Deploy Smart Contract

<CardGroup>
  <Card title="Foundry" href="/guides/deploy-smart-contract/foundry">
    Deploy a smart contract on Monad using Foundry
  </Card>

  <Card title="Hardhat" href="/guides/deploy-smart-contract/hardhat">
    Deploy a smart contract on Monad using Hardhat
  </Card>

  <Card title="Remix" href="/guides/deploy-smart-contract/remix">
    Deploy a smart contract on Monad using Remix
  </Card>
</CardGroup>

## Verify Smart Contract

<CardGroup>
  <Card title="Foundry" href="/guides/verify-smart-contract/foundry">
    Verify a smart contract on Monad using Foundry
  </Card>

  <Card title="Hardhat" href="/guides/verify-smart-contract/hardhat">
    Verify a smart contract on Monad using Hardhat
  </Card>
</CardGroup>

## Indexing

<CardGroup>
  <Card title="GhostGraph" href="/guides/indexers/ghost">
    Index transfers with GhostGraph
  </Card>

  <Card title="Envio" href="/guides/indexers/tg-bot-using-envio">
    Index transfers for a telegram bot using Envio
  </Card>

  <Card title="QuickNode Streams" href="/guides/indexers/quicknode-streams">
    Index transfers using QuickNode Streams
  </Card>
</CardGroup>

## Connectivity

<CardGroup>
  <Card title="Reown AppKit" href="/guides/reown-guide">
    Connect a wallet to your app with Reown AppKit
  </Card>

  <Card title="Blinks" href="/guides/blinks-guide">
    Build a donation blink
  </Card>
</CardGroup>

## AI

<CardGroup>
  <Card title="MCP Server" href="/guides/monad-mcp">
    Build an MCP server to interact with Monad Testnet
  </Card>

  <Card title="x402 on Monad" href="/guides/x402-guide">
    How to setup x402-enabled endpoints with Monad support
  </Card>
</CardGroup>

## Execution Events

<CardGroup>
  <Card title="Set up Execution Events" href="/guides/execution-events/setup">
    Configure your Monad node to enable execution events
  </Card>

  <Card title="Consume Events in Rust" href="/guides/execution-events/consume-rust">
    Build a Rust application to read execution events
  </Card>
</CardGroup>


# How to index token transfers with GhostGraph
Source: https://docs.monad.xyz/guides/indexers/ghost



## Introduction

In this guide, you will create an ERC20 token on Monad Testnet and index its transfers with [GhostGraph](https://docs.tryghost.xyz/). You'll learn how to:

* Deploy a basic ERC20 token contract
* Test the contract locally
* Deploy to Monad Testnet
* Set up event tracking with GhostGraph

## Prerequisites

Before starting, ensure you have:

* Node.js installed (v16 or later)
* Git installed
* [Foundry](https://github.com/foundry-rs/foundry) installed
* Some MONAD testnet tokens (for gas fees)
* Basic knowledge of Solidity and ERC20 tokens

## Project Setup

First, clone the starter repository:

```sh theme={null}
git clone https://github.com/chrischang/cat-token-tutorial.git
cd cat-token-tutorial
```

## CatToken Contract Implementation

The `src/CatToken.sol` contract implements a basic ERC20 token with a fixed supply. Here's the code:

```solidity lines title="src/CatToken.sol" theme={null}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract CatToken is ERC20 {
    /**
     * @dev Constructor that gives msg.sender all existing tokens.
     * Initial supply is 1 billion tokens.
     */
    constructor() ERC20("CatToken", "CAT") {
        // Mint initial supply of 1 billion tokens to deployer
        // This will emit a Transfer event that GhostGraph   can index
        _mint(msg.sender, 1_000_000_000 * 10 ** decimals());
    }
}
```

This implementation:

* Creates a token with name "CatToken" and symbol "CAT"
* Mints 1 billion tokens to the deployer's address
* Uses OpenZeppelin's battle-tested ERC20 implementation

## Testing the Contract

Navigate to the test file `test/CatToken.t.sol`:

```solidity lines title="test/CatToken.t.sol" theme={null}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import "forge-std/Test.sol";
import "../src/CatToken.sol";

contract CatTokenTest is Test {
    CatToken public token;
    address public owner;
    address public user;

    function setUp() public {
        owner = address(this);
        user = address(0x1);

        token = new CatToken();
    }

    function testInitialSupply() public view {
        assertEq(token.totalSupply(), 1_000_000_000 * 10**18);
        assertEq(token.balanceOf(owner), 1_000_000_000 * 10**18);
    }

    function testTransfer() public {
        uint256 amount = 1_000_000 * 10**18;
        token.transfer(user, amount);
        assertEq(token.balanceOf(user), amount);
        assertEq(token.balanceOf(owner), 999_000_000 * 10**18);
    }
}
```

Run the tests:

```sh theme={null}
forge test -vv
```

## Deployment Setup

### 1. Create a `.env` file:

```sh theme={null}
cp .env.example .env
```

### 2. Add your credentials to `.env` file:

```sh theme={null}
PRIVATE_KEY=your_private_key_here
MONAD_TESTNET_RPC=https://testnet-rpc.monad.xyz
```

### 3. Create deployment script `script/DeployCatToken.s.sol`:

```solidity lines title="script/DeployCatToken.s.sol" theme={null}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import "forge-std/Script.sol";
import "../src/CatToken.sol";

contract DeployCatToken is Script {
    function run() external {
        // Retrieve private key from environment
        uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");

        vm.startBroadcast(deployerPrivateKey);
        CatToken token = new CatToken();
        vm.stopBroadcast();

        // Log the token address - this will be needed for GhostGraph indexing and submit transactions
        console.log("CatToken deployed to:", address(token));
    }
}
```

## Deploying CatToken on Monad Testnet

### 1. Load environment variables:

```sh theme={null}
source .env
```

### 2. Deploy the contract:

```sh theme={null}
forge script script/DeployCatToken.s.sol \
--rpc-url $MONAD_TESTNET_RPC \
--broadcast
```

Save the deployed contract address for the next steps.

Remember to add `TOKEN_ADDRESS` into your `.env` file

You should now have

```sh theme={null}
PRIVATE_KEY=your_private_key_here
MONAD_TESTNET_RPC=https://testnet-rpc.monad.xyz
TOKEN_ADDRESS=0x...
```

## Verify Smart Contract

### 1. Load environment variables:

```sh theme={null}
source .env
```

### 2. Verify the contract:

```sh theme={null}
forge verify-contract \
  --rpc-url $MONAD_TESTNET_RPC \
  --verifier sourcify \
  --verifier-url 'https://sourcify-api-monad.blockvision.org/' \
  $TOKEN_ADDRESS \
  src/CatToken.sol:CatToken
```

After verification, you should see the contract verified on the [MonadVision](https://testnet.monadvision.com). You should see a checkmark and the banner stating the contract source code verified.

<img alt="Verified Contract" />

## Script for Token Transfers Transactions Onchain

We perform some token transfer transactions onchain to trigger the `Transfer` event that GhostGraph will index.

View the transfer script `script/TransferCatTokens.s.sol`:

```solidity lines title="script/TransferCatTokens.s.sol" theme={null}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import "forge-std/Script.sol";
import "../src/CatToken.sol";

contract TransferCatTokens is Script {
    function run() external {
        uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");
        address token = vm.envAddress("TOKEN_ADDRESS");

        vm.startBroadcast(deployerPrivateKey);

        // Send tokens to test addresses
        CatToken(token).transfer(address(0x1), 1000 * 10**18);
        CatToken(token).transfer(address(0x2), 2000 * 10**18);
        CatToken(token).transfer(address(0x3), 3000 * 10**18);

        vm.stopBroadcast();
    }
}
```

Run the below command to execute transfers:

```sh theme={null}
forge script script/TransferCatTokens.s.sol \
--rpc-url $MONAD_TESTNET_RPC \
--broadcast
```

You have now deployed your ERC-20 contract and submitted transactions on the Monad testnet. Let’s track these onchain events with GhostGraph.

## Setting Up GhostGraph Indexing

1. Visit [GhostGraph](https://tryghost.xyz/) and click sign up for an account

2. Create a new GhostGraph

<img alt="create_ghost_graph" />

3. Copy and paste this into `events.sol` file. We are interested in tracking token flow. Let’s insert this event here. To learn more about events: [https://docs.tryghost.xyz/ghostgraph/getting-started/define-events](https://docs.tryghost.xyz/ghostgraph/getting-started/define-events)

```solidity lines title="events.sol" theme={null}
interface Events {
    event Transfer(address indexed from, address indexed to, uint256 value);
}
```

4. Copy and paste this into `schema.sol` file. In this case, we are creating a few struct which we will use to save entity into the Ghost database. To learn more about schema: [https://docs.tryghost.xyz/ghostgraph/getting-started/define-schema](https://docs.tryghost.xyz/ghostgraph/getting-started/define-schema)

```solidity lines title="schema.sol" theme={null}
struct Global {
    string id;
    uint256 totalHolders;
}

struct User {
    address id;
    uint256 balance;
}

struct Transfer {
    string id;
    address from;
    address to;
    uint256 amount;

    uint64 block;
    address emitter;
    uint32 logIndex;
    bytes32 transactionHash;
    uint32 txIndex;
    uint32 timestamp;
}
```

5. Click on `generate code` button to generate `indexer.sol` file along with some other readonly files. This file will be where the logic and transformations resides.

6. Copy and paste this into `indexer.sol` be sure to insert your token address to the `CAT_TESTNET_TOKEN_CONTRACT_ADDRESS` variable.

```solidity lines title="indexer.sol" theme={null}
// SPDX-License-Identifier: MIT
pragma solidity 0.8.19;

import "./gen_schema.sol";
import "./gen_events.sol";
import "./gen_base.sol";
import "./gen_helpers.sol";

contract MyIndex is GhostGraph {
    using StringHelpers for EventDetails;
    using StringHelpers for uint256;
    using StringHelpers for address;

    address constant CAT_TESTNET_TOKEN_CONTRACT_ADDRESS = <INSERT YOUR TOKEN ADDRESS>;

    function registerHandles() external {
        graph.registerHandle(CAT_TESTNET_TOKEN_CONTRACT_ADDRESS);
    }

    function onTransfer(EventDetails memory details, TransferEvent memory ev) external {
        // Get global state to track holder count
        Global memory global = graph.getGlobal("1");

        // Handle sender balance
        if (ev.from != address(0)) {
            // Skip if minting
            User memory sender = graph.getUser(ev.from);
            if (sender.balance == ev.value) {
                // User is transferring their entire balance
                global.totalHolders -= 1; // Decrease holder count
            }
            sender.balance -= ev.value;
            graph.saveUser(sender);
        }

        // Handle receiver balance
        User memory receiver = graph.getUser(ev.to);
        if (receiver.balance == 0 && ev.value > 0) {
            // New holder
            global.totalHolders += 1; // Increase holder count
        }
        receiver.balance += ev.value;
        graph.saveUser(receiver);

        // Save global state
        graph.saveGlobal(global);

        // Create and save transfer record
        Transfer memory transfer = graph.getTransfer(details.uniqueId());
        transfer.from = ev.from;
        transfer.to = ev.to;
        transfer.amount = ev.value;
        
        // Store transaction metadata
        transfer.block = details.block;
        transfer.emitter = details.emitter;
        transfer.logIndex = details.logIndex;
        transfer.transactionHash = details.transactionHash;
        transfer.txIndex = details.txIndex;
        transfer.timestamp = details.timestamp;
        
        graph.saveTransfer(transfer);
    }
}
```

7. Compile and deploy your GhostGraph. After a few seconds, you should see GhostGraph has successfully indexed your contract.

<img alt="ghostgraph_playground" />

8. Clicking on the playground will take you to the GraphQL playground, where you can ensure the data is indexed correctly. Let’s copy and paste this into our playground and click the play button to fetch the data from GhostGraph.

```graphql lines title="GraphQL Playground" theme={null}
query FetchRecentTransfers {
  transfers(
    orderBy: "block", 
    orderDirection: "desc"
    limit: 50
  ) {
    items {
      amount
      block
      emitter
      from
      id
      logIndex
      timestamp
      to
      transactionHash
      txIndex
    }
  }
}
```

<img alt="graphql_playground" />

<Tip>
  Try submitting additional transactions by running the transfer script again. You should see that GhostGraph automatically indexes the new transactions.
</Tip>

## Conclusion

You have now successfully created a GhostGraph to track onchain data for your contract. The next step is to connect it to your frontend.

The Ghost team has created end-to-end tutorials on how to do just that [here](https://docs.tryghost.xyz/blog/connect_ghost_graph_to_frontend/)


# Use an Indexer
Source: https://docs.monad.xyz/guides/indexers/index



<CardGroup>
  <Card title="GhostGraph" href="/guides/indexers/ghost">
    Index transfers with GhostGraph
  </Card>

  <Card title="Envio" href="/guides/indexers/tg-bot-using-envio">
    Index transfers for a telegram bot using Envio
  </Card>

  <Card title="Envio HyperSync" href="/guides/indexers/token-snapshot-hypersync">
    Query token data with Envio HyperSync
  </Card>

  <Card title="QuickNode Streams" href="/guides/indexers/quicknode-streams">
    Index transfers using QuickNode Streams
  </Card>
</CardGroup>


# How to index every WMON transfer using QuickNode Streams
Source: https://docs.monad.xyz/guides/indexers/quicknode-streams



In this guide, you will learn how to use QuickNode Streams to index every [WMON](https://testnet.monadvision.com/token/0xFb8bf4c1CC7a94c73D209a149eA2AbEa852BC541) transfer, including internal transactions, on Monad Testnet.

## What is QuickNode Streams?

[QuickNode Streams](https://www.quicknode.com/docs/streams/getting-started) is a web3 data streaming solution supporting real-time and historical Monad data that offers:

* **Reliable Data Delivery** - Exactly-once, guaranteed delivery, seamlessly integrating with your data lake. Streams ensures every block, receipt, or trace is delivered exactly-once in the order of dataset finality, preventing issues like corrupt or missing data
* **Real-Time Data Consistency** - Consistent, live data streaming
* **Efficient Historical Data Handling** - Configurable date ranges and destinations for streamlined historical data management
* **Easy Integration** - Simple setup through a user-friendly interface
* **Transparent User Experience** - Clear logging, metrics, and usage tracking

## Setup Guide

### 1. Initial setup

1. Sign up for [QuickNode](https://dashboard.quicknode.com/?prompt=signup) and log into your dashboard.

2. Click on "Streams" in the left sidebar.

<img alt="QuickNode Dashboard" />

3. Click on "Create Stream".

<img alt="Create Stream Button" />

### 2. Configure Stream range

1. Give your stream a name. In this example we will name it `monad-quicknode-stream`.

2. In the "Network" section, select `Monad` from the dropdown.

3. In the "Stream Start" section you can choose to start the stream from the latest block or from a specific block number.

<img alt="Stream Configuration" />

4. In the "Stream End" section you can choose to end the stream until manually paused or at a specific block number.

5. In the "Latest block delay" section, you can set a block number as a delay in receiving data. For this guide we will receive data as soon as it is available.<br /><br />For example: If the block delay is `3`, you will receive data only when there is **new data available** for `3` blocks including latest block, this helps in case there is a reorg.

6. In the "Restream on reorg" section you can decide if you would like to get updated data restreamed in case of a reorg. For this guide we will keep this off.

7. Once done click "Next".

<img alt="Additional Settings" />

### 3. Set up dataset

1. In the "Dataset" dropdown you can select the dataset of your choice according to the use case. For this guide we will select `Block with Receipts` since we want to filter logs with events emitted by WMON contract.

* Optional: Enable "Batch messages" to receive multiple blocks in a single message. This can be useful when the stream is not starting from the latest block.

<img alt="Dataset Selection" />

2. Feel free to test it out by entering a block number and clicking "Fetch payload".

<img alt="Raw Payload Example" />

### 4. Create WMON Transfer filter

1. In the "Modify the stream payload" section, you can define filters by clicking **"Customize your payload"**. For this guide, we will filter to only retrieve receipts involving WMON transfers.

<img alt="modify stream image" />

2. QuickNode has a set of filter templates. Select the **Decoded ERC20 transfers** template:

<img alt="image for filter" />

3. The editor will appear:

<img alt="image of filter editor" />

The current filter allows all ERC20 transfers through. Replace the filter code with:

```js lines theme={null}
function main(stream) {  
  const erc20Abi = `[{
    "anonymous": false,
    "inputs": [
      {"indexed": true, "type": "address", "name": "from"},
      {"indexed": true, "type": "address", "name": "to"},
      {"indexed": false, "type": "uint256", "name": "value"}
    ],
    "name": "Transfer",
    "type": "event"
  }]`;
  
  const data = stream.data ? stream.data : stream;
  
  // Decodes logs from the receipts that match the Transfer event ABI
  var result = decodeEVMReceipts(data[0].receipts, [erc20Abi]);
  
  // Filter for receipts with decoded logs
  result = result.filter(receipt => {
        // Check if there are any ERC20 transfers
        if(receipt.decodedLogs) {
            // Check if there are any WMON transfers
            receipt.decodedLogs = receipt.decodedLogs.filter(log => log.address == "0xFb8bf4c1CC7a94c73D209a149eA2AbEa852BC541");
            
            // Return receipt if there logs which indicate a WMON transfer.
            return receipt.decodedLogs.length > 0;
        }

        // Return nothing if there are no ERC20 transfers.
        return false;
    });
  
  return { result };
}
```

4. Test the filter with "Run test"

<img alt="run test image" />

5. "Save & close" to save the filter.

<img alt="save & close image" />

6. Click "Next"

### 5. Set up Stream destination

For this guide we will keep the stream destination simple and use `Webhook` as the "Destination Type".

1. Let's use a site like [Svix Play](https://www.svix.com/play/) to quickly get a webhook and test the stream.

<img alt="svix play image" />

2. Copy the webhook url from Svix Play:

<img alt="svix play copy url image" />

3. In QuickNode:

* Select `Webhook` as destination type
* Paste your webhook URL
* We can keep the rest of the settings as default

<img alt="webhook dropdown image" />

4. Click on "Check Connection" to test the webhook url. Check if you received the "PING" message in the Svix Play dashboard.

<img alt="check connection image" />

<img alt="ping message image" />

5. Click "Send Payload" to send a test payload to the webhook.

<img alt="add send payload image" />

<img alt="svix payload image" />

6. Finally click "Create a Stream" to create the stream.

<img alt="create stream image" />

### 6. Launch and Monitor

You should now be able to see the stream delivering the messages to the webhook!

<img alt="stream delivering image" />

<img alt="svix streaming receiving message video" />

You can pause the stream by clicking the switch in the top right corner.

<img alt="pause switch image" />

## Next Steps

* Monitor your stream's performance in the QuickNode dashboard
* Adjust filter parameters as needed
* Connect to your production webhook endpoint when ready

Your stream will now track all WMON transfers until manually paused or until reaching your specified end block.


# How to build a transfer notification bot with Envio HyperIndex
Source: https://docs.monad.xyz/guides/indexers/tg-bot-using-envio



In this guide, you will learn how to use [Envio](https://envio.dev/) HyperIndex to create a Telegram bot that sends notifications whenever WMON tokens are transferred on the Monad Testnet. We'll walk through setting up both the indexer and the Telegram bot.

Envio HyperIndex is an open development framework for building blockchain application backends. It offers real-time indexing, automatic indexer generation from contract addresses, and triggers for external API calls.

## Prerequisites

You'll need the following installed:

* Node.js v18 or newer
* pnpm v8 or newer
* Docker Desktop (required for running the Envio indexer locally)

## Setting up the project

First, create and enter a new directory:

```shell theme={null}
mkdir envio-mon && cd envio-mon
```

### Get the contract ABI

1. Create an `abi.json` file:

```shell theme={null}
touch abi.json
```

2. Copy the [WrappedMonad](https://testnet.monadvision.com/token/0xFb8bf4c1CC7a94c73D209a149eA2AbEa852BC541?tab=Contract) ABI from the explorer

<img alt="image of explorer" />

3. Paste the ABI into your `abi.json` file

### Initialize the project

Run the initialization command:

```shell theme={null}
pnpx envio init
```

Follow the prompts:

1. Press Enter when asked for a folder name (to use current directory)
2. Select `TypeScript` as your language
3. Choose `Evm` as the blockchain ecosystem
4. Select `Contract Import` for initialization
5. Choose `Local ABI` as the import method
6. Enter `./abi.json` as the path to your ABI file
7. Select only the `Transfer` event to index
8. Choose `<Enter Network Id>` and input `10143` (Monad Testnet chain ID)
9. Enter `WrappedMonad` as the contract name
10. Input the contract address: `0xFb8bf4c1CC7a94c73D209a149eA2AbEa852BC541`
11. Select `I'm finished` since we're only indexing one contract
12. Choose whether to create or add an existing API token. If you choose to create a new token, you'll be taken to a page that looks like this:

<img alt="new API token view" />

Once the project is initialized, you should see the following project structure in your project directory.

<img alt="envio dashboard" />

Add the following code to `config.yaml` file, to make transaction hash available in event handler:

```yaml lines title="config.yaml" theme={null}
# default config...
field_selection:
    transaction_fields:
      - hash
```

*More details about the `field_selection` config [here](https://docs.envio.dev/docs/HyperIndex/configuration-file#field-selection)*

## Starting the indexer

Start Docker Desktop.

To start the indexer run the following command in the project directory:

```shell theme={null}
pnpx envio dev
```

You should see something similar to the below image in your terminal; this means that the indexer is syncing and will eventually reach the tip of the chain.

<img alt="envio indexer syncing" />

You will also see this page open in your browser automatically, the password is `testing`.

<img alt="hasura local page" />

We can use this interface to query the indexer using GraphQL. Results will depend on the sync progress:

<img alt="query interface" />

Currently, the indexer is catching up to the tip of the chain. Once syncing is complete the indexer will be able to identify latest WMON transfers.

We can shut down the indexer for now, so we can proceed with Telegram integration.

## Creating the Telegram bot

1. Visit [BotFather](https://t.me/botfather) to create your bot and get an API token
2. Add these environment variables to your `.env` file:

```
ENVIO_BOT_TOKEN=<your_bot_token>
ENVIO_TELEGRAM_CHAT_ID=<your_chat_id>
```

To get your chat ID:

1. Create a Telegram group and add your bot
2. Send `/start` to the bot: `@YourBot /start`
3. Visit `https://api.telegram.org/bot<YourBOTToken>/getUpdates`
4. Look for the channel chat ID (it should start with "-")

<Note>
  If you don't see the chat ID, try removing and re-adding the bot to the group.
</Note>

The Telegram bot is now ready.

## Integrating Telegram API to HyperIndex Event Handler

Create a folder `libs` inside `src` folder in the project directory, create a file inside it `telegram.ts` and add the following code

```ts lines title="src/libs/telegram.ts" theme={null}
import axios from "axios";
import { CHAT_ID, BOT_TOKEN } from "../constants";

export const sendMessageToTelegram = async (message: string): Promise<void> => {
  try {
    const apiUrl = `https://api.telegram.org/bot${BOT_TOKEN}/sendMessage`;

    await axios.post(apiUrl, {
      chat_id: CHAT_ID,
      text: message,
      parse_mode: "HTML",
    });
  } catch (error) {
    console.error("Error sending message:", error);
  }
};
```

You will come across some errors, let's fix them.

Install `axios` package

```bash theme={null}
pnpm i axios
```

Create a file in `src` folder called `constants.ts` and add the following code:

```ts lines title="src/constants.ts" theme={null}
export const EXPLORER_URL_MONAD = "https://testnet.monadvision.com/";

// Threshold for WMON transfer amount above which the bot sends a notification
export const THRESHOLD_WEI: string = process.env.ENVIO_THRESHOLD_WEI ?? "1000000000000000000"; // in wei

export const BOT_TOKEN = process.env.ENVIO_BOT_TOKEN; // Telegram bot token
export const CHAT_ID = process.env.ENVIO_TELEGRAM_CHAT_ID; // WMON Transfers Notification Channel ID

// Function to get explorer url for the provided address
export const explorerUrlAddress = (address: string) =>
  EXPLORER_URL_MONAD + "address/" + address;

// Function to get explorer url for the provided transaction hash
export const explorerUrlTx = (txHash: string) =>
  EXPLORER_URL_MONAD + "tx/" + txHash;
```

We can now edit the `EventHandlers.ts` in `src` folder, to add the code for sending the telegram message:

```ts lines title="src/EventHandlers.ts" theme={null}
import {
  WrappedMonad,
} from "generated";
import { isIndexingAtHead, weiToEth } from "./libs/helpers";
import { sendMessageToTelegram } from "./libs/telegram";
import { THRESHOLD_WEI, explorerUrlAddress, explorerUrlTx } from "./constants";

// Other event handlers can be removed...

WrappedMonad.Transfer.handler(async ({ event, context }) => {
    const from_address = event.params.src;
    const to_address = event.params.dst;

  if (isIndexingAtHead(event.block.timestamp) && event.params.wad >= BigInt(THRESHOLD_WEI)) {
    // Only send a message when the indexer is indexing event from the time it was started and not historical transfers, and only message if the transfer amount is greater than or equal to THRESHOLD_WEI.

    // Example message
    // WMON Transfer ALERT: A new transfer has been made by 0x65C3564f1DD63eA81C11D8FE9a93F8FFb5615233 to 0xBA5Cf1c0c1238F60832618Ec49FC81e8C7C0CF01 for 2.0000 WMON! 🔥 - View on Explorer

    const msg = `WMON Transfer ALERT: A new transfer has been made by <a href="${explorerUrlAddress(from_address)}">${from_address}</a> to <a href="${explorerUrlAddress(to_address)}">${to_address}</a> for ${weiToEth(event.params.wad)} WMON! 🔥 - <a href="${explorerUrlTx(
      event.transaction.hash
    )}">View on Explorer</a>`;

    await sendMessageToTelegram(msg);
  }
});
```

Let us now fix the import error.

Create a file called `helpers.ts` in `src/libs` folder, paste the following code in it:

```ts lines title="src/libs/helpers.ts" theme={null}
// Used to ensure notifications are only sent while indexing at the head and not historical sync
const INDEXER_START_TIMESTAMP = Math.floor(new Date().getTime() / 1000);

export const isIndexingAtHead = (timestamp: number): boolean => {
    return timestamp >= INDEXER_START_TIMESTAMP;
}

// Convert wei to ether for human readability
export const weiToEth = (bigIntNumber: bigint): string => {
  // Convert BigInt to string
  const numberString = bigIntNumber.toString();

  const decimalPointsInEth = 18;

  // Extract integer part and decimal part
  const integerPart = numberString.substring(
    0,
    numberString.length - decimalPointsInEth
  );

  const decimalPart = numberString.slice(-decimalPointsInEth);

  // Insert decimal point
  const decimalString =
    (integerPart ? integerPart : "0") +
    "." +
    decimalPart.padStart(decimalPointsInEth, "0");

  // Add negative sign if necessary
  return decimalString.slice(0, -14);
};
```

That's it! We can now run the indexer, and the telegram bot will start sending messages in the telegram channel when the indexer detects a WMON transfer!

<img alt="example bot message" />

*Note: Screenshot was taken before message format was changed. The message will be slightly different if you followed the guide.*

<Note>
  You may not immediately start seeing messages because the indexer take some time to catch up to the tip of the the recent blocks.

  The bot will only send notifications for transfers when the indexer detects a WMON transfer in finalized blocks, with timestamp greater than or equal to the indexer start time.
</Note>


# How to query token data with Envio HyperSync
Source: https://docs.monad.xyz/guides/indexers/token-snapshot-hypersync



In this guide, you will learn how to efficiently compute token ownership for ERC-721, ERC-20, and ERC-1155 contracts on Monad, using Envio HyperSync to accelerate the process.

## Background

A common problem for EVM developers is the "historical balance problem" - recovering the full mapping of accounts to balances for an ERC-20, ERC-721, or ERC-1155 token. Solidity doesn't keep track of the keys in a mapping; values are stored in the appropriate storage slot after hashing the key. Therefore, to recover the balances, a typical strategy is to replay all transfer events for that token and compute the rolling sum.

Envio HyperSync is an indexer that allows developers to query millions of blockchain events in seconds. In this guide, we'll use data from HyperSync to reconstruct the historical balances for a token.

## Prerequisites

* Node.js 18+
* Free HyperSync API key from [envio.dev/app/api-tokens](https://envio.dev/app/api-tokens)

## HyperSync Endpoints

<div>
  <table>
    <thead>
      <tr>
        <th>Network</th>
        <th>URL</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Testnet</td>

        <td>
          <CopyToClipboard>`https://monad-testnet.hypersync.xyz`</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Mainnet</td>

        <td>
          <CopyToClipboard>`https://monad.hypersync.xyz`</CopyToClipboard>
        </td>
      </tr>
    </tbody>
  </table>
</div>

## Ingredients

This guide surveys how to reconstruct balances for all three of the most popular token standards - ERC-20, ERC-721, and ERC-1155. Each uses some common ingredients, while requiring different logic to assemble the end reuslt.

### Querying Transfer Events

First, let's write some code to query **all** of the Transfer events for our contract,
filtering for the appropriate signature.

ERC-20 and ERC-721 use the `Transfer` event below, while ERC-1155 uses the `TransferSingle` and `TransferBatch` events:

| Event                                                        | Signature                                                            |
| ------------------------------------------------------------ | -------------------------------------------------------------------- |
| `Transfer(address,address,uint256)`                          | `0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef` |
| `TransferSingle(address,address,address,uint256,uint256)`    | `0xc3d58168c5ae7397731d063d5bbf3d657854427343f4c083240f7aacaa2d0f62` |
| `TransferBatch(address,address,address,uint256[],uint256[])` | `0x4a39dc06d4c0dbc64b70af90fd698a233a518aa5d07e595d983b8c0526c8f7fb` |

```typescript lines title="lib/signatures.ts" theme={null}
// ERC-20 and ERC-721 share the same Transfer signature
const TRANSFER_EVENT = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";

// ERC-1155 events
const TRANSFER_SINGLE = "0xc3d58168c5ae7397731d063d5bbf3d657854427343f4c083240f7aacaa2d0f62";
const TRANSFER_BATCH = "0x4a39dc06d4c0dbc64b70af90fd698a233a518aa5d07e595d983b8c0526c8f7fb";
```

Here is code for querying the events for an ERC-20 contract:

```typescript lines title="lib/hypersync.ts" theme={null}
const HYPERSYNC_URL = "https://monad-testnet.hypersync.xyz";

// keccak256("Transfer(address,address,uint256)") - same for ERC-20 and ERC-721
const TRANSFER_SIGNATURE = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";

async function queryTransfers(contractAddress: string, apiKey: string) {
  const response = await fetch(`${HYPERSYNC_URL}/query`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      from_block: 0,
      logs: [
        {
          address: [contractAddress],
          topics: [[TRANSFER_SIGNATURE]],
        },
      ],
      field_selection: {
        log: ["topic0", "topic1", "topic2", "topic3", "data"],
      },
    }),
  });

  return response.json();
}
```

### Field Selection

To optimize our queries, we should only request the fields we actually need. This reduces response size and speeds up queries significantly. Different token standards encode data in different topics:

**ERC-721** (tokenId in topic3):

```json theme={null}
{ "log": ["topic0", "topic2", "topic3"] }
```

**ERC-20** (value in data):

```json theme={null}
{ "log": ["topic0", "topic1", "topic2", "data"] }
```

**ERC-1155** (id and value in data):

```json theme={null}
{ "log": ["topic0", "topic1", "topic2", "topic3", "data"] }
```

### Parsing Log Data

Now that we have the raw event data, we need to parse it into usable values. Topics are 32-byte hex strings where addresses are left-padded with zeros, occupying the last 20 bytes:

```typescript lines title="lib/parse.ts" theme={null}
function parseAddress(topic: string): string {
  return "0x" + topic.slice(-40).toLowerCase();
}

function parseTokenId(topic: string): string {
  return BigInt(topic).toString();
}

function parseValue(data: string): bigint | null {
  if (!data || data === "0x") return null;
  return BigInt(data);
}
```

> **Note:** `parseValue` returns the raw token value as a `bigint`. ERC-20 tokens have a `decimals` property (typically 18) — divide by `10n ** BigInt(decimals)` to convert to a human-readable amount.

### Pagination

HyperSync returns paginated results to handle large datasets efficiently. We need to continue querying until `next_block` is undefined to get all transfers:

```typescript lines title="lib/paginate.ts" theme={null}
async function fetchAllTransfers(contractAddress: string, apiKey: string) {
  const ownership = new Map<string, string>();
  let fromBlock = 0;
  let hasMore = true;

  while (hasMore) {
    const response = await queryHypersync(contractAddress, fromBlock, apiKey);

    // Process logs
    for (const block of response.data) {
      for (const log of block.logs) {
        const to = parseAddress(log.topic2);
        const tokenId = parseTokenId(log.topic3);
        ownership.set(tokenId, to);
      }
    }

    // Check for more pages
    if (response.next_block && response.next_block > fromBlock) {
      fromBlock = response.next_block;
    } else {
      hasMore = false;
    }
  }

  return ownership;
}
```

Now we can start putting it all together.

## ERC-721 Balance Snapshot

For ERC-721, we will reconstruct the current ownership state by replaying all Transfer events. For NFTs, the last transfer for each token ID determines the current owner:

```typescript lines title="app/api/snapshot/route.ts" theme={null}
import { NextRequest, NextResponse } from "next/server";

const HYPERSYNC_URL = "https://monad-testnet.hypersync.xyz";

// keccak256("Transfer(address,address,uint256)") - same for ERC-20 and ERC-721
const TRANSFER_SIGNATURE = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";

const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";

function parseAddress(topic: string): string {
  return "0x" + topic.slice(-40).toLowerCase();
}

function parseTokenId(topic: string): string {
  return BigInt(topic).toString();
}

interface HypersyncLog {
  topic0: string;
  topic2: string;
  topic3: string;
}

interface HypersyncResponse {
  data: { logs: HypersyncLog[] }[];
  next_block?: number;
}

async function queryHypersync(
  contractAddress: string,
  fromBlock: number,
  apiKey: string
): Promise<HypersyncResponse> {
  const response = await fetch(`${HYPERSYNC_URL}/query`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      from_block: fromBlock,
      logs: [{ address: [contractAddress], topics: [[TRANSFER_SIGNATURE]] }],
      field_selection: { log: ["topic0", "topic2", "topic3"] },
    }),
  });

  if (!response.ok) {
    throw new Error(`HyperSync error: ${response.status}`);
  }

  return response.json();
}

export async function GET(request: NextRequest) {
  const contract = request.nextUrl.searchParams.get("contract");
  const apiKey = process.env.HYPERSYNC_BEARER_TOKEN;

  if (!contract || !apiKey) {
    return NextResponse.json({ error: "Missing parameters" }, { status: 400 });
  }

  // Track current owner for each tokenId
  const ownership = new Map<string, string>();
  let fromBlock = 0;
  let hasMore = true;

  while (hasMore) {
    const response = await queryHypersync(contract, fromBlock, apiKey);

    for (const block of response.data) {
      for (const log of block.logs) {
        const to = parseAddress(log.topic2);
        const tokenId = parseTokenId(log.topic3);
        ownership.set(tokenId, to); // Last transfer wins
      }
    }

    if (response.next_block && response.next_block > fromBlock) {
      fromBlock = response.next_block;
    } else {
      hasMore = false;
    }
  }

  // Filter out burned tokens
  const snapshot = Array.from(ownership.entries())
    .filter(([, owner]) => owner !== ZERO_ADDRESS)
    .map(([tokenId, owner]) => ({ tokenId, owner }));

  return NextResponse.json({ snapshot });
}
```

## ERC-20 Balance Snapshot

For ERC-20 tokens, we need to sum all transfers to calculate current balances. Unlike NFTs where we track ownership, ERC-20 balances require summing all incoming and outgoing transfers for each address.

First, query ERC-20 transfers with the right field selection (topic1 for `from`, topic2 for `to`, and `data` for the value):

```typescript lines title="lib/erc20.ts" theme={null}
async function queryERC20Transfers(
  contractAddress: string,
  fromBlock: number,
  apiKey: string
): Promise<HypersyncResponse> {
  const response = await fetch(`${HYPERSYNC_URL}/query`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      from_block: fromBlock,
      logs: [{ address: [contractAddress], topics: [[TRANSFER_SIGNATURE]] }],
      field_selection: { log: ["topic0", "topic1", "topic2", "data"] },
    }),
  });

  if (!response.ok) {
    throw new Error(`HyperSync error: ${response.status}`);
  }

  return response.json();
}
```

Then reconstruct balances by summing all transfers:

```typescript lines title="lib/erc20.ts" theme={null}
async function getERC20Balances(contractAddress: string, apiKey: string) {
  const balances = new Map<string, bigint>();
  let fromBlock = 0;
  let hasMore = true;

  while (hasMore) {
    const response = await queryERC20Transfers(contractAddress, fromBlock, apiKey);

    for (const block of response.data) {
      for (const log of block.logs) {
        const from = parseAddress(log.topic1);
        const to = parseAddress(log.topic2);
        const value = parseValue(log.data);

        if (value === null) continue;

        // Subtract from sender
        if (from !== ZERO_ADDRESS) {
          const current = balances.get(from) || 0n;
          balances.set(from, current - value);
        }

        // Add to receiver
        if (to !== ZERO_ADDRESS) {
          const current = balances.get(to) || 0n;
          balances.set(to, current + value);
        }
      }
    }

    if (response.next_block && response.next_block > fromBlock) {
      fromBlock = response.next_block;
    } else {
      hasMore = false;
    }
  }

  // Filter positive balances, sort descending
  return Array.from(balances.entries())
    .filter(([, balance]) => balance > 0n)
    .sort((a, b) => (b[1] > a[1] ? 1 : -1))
    .map(([address, balance]) => ({ address, balance: balance.toString() }));
}
```

## ERC-1155 Balance Snapshot

ERC-1155 tokens work differently from ERC-20 and ERC-721. They store `id` and `value` in the data field rather than topics, requiring more complex parsing:

```typescript lines title="lib/erc1155.ts" theme={null}
// TransferSingle: data = id (32 bytes) + value (32 bytes)
function parseTransferSingle(data: string): { tokenId: string; value: bigint } | null {
  if (!data || data.length < 130) return null;
  const tokenId = BigInt("0x" + data.slice(2, 66)).toString();
  const value = BigInt("0x" + data.slice(66, 130));
  return { tokenId, value };
}

// TransferBatch: ABI-encoded arrays
function parseTransferBatch(data: string): { tokenId: string; value: bigint }[] | null {
  if (!data || data.length < 258) return null;

  // Decode offsets
  const idsOffset = Number(BigInt("0x" + data.slice(2, 66)));
  const valuesOffset = Number(BigInt("0x" + data.slice(66, 130)));

  // Read array lengths
  const idsLengthStart = 2 + idsOffset * 2;
  const idsLength = Number(BigInt("0x" + data.slice(idsLengthStart, idsLengthStart + 64)));

  const valuesLengthStart = 2 + valuesOffset * 2;
  const valuesLength = Number(BigInt("0x" + data.slice(valuesLengthStart, valuesLengthStart + 64)));

  if (idsLength !== valuesLength || idsLength === 0) return null;

  // Parse each id/value pair
  const results: { tokenId: string; value: bigint }[] = [];
  for (let i = 0; i < idsLength; i++) {
    const idStart = idsLengthStart + 64 + i * 64;
    const valueStart = valuesLengthStart + 64 + i * 64;
    const tokenId = BigInt("0x" + data.slice(idStart, idStart + 64)).toString();
    const value = BigInt("0x" + data.slice(valueStart, valueStart + 64));
    results.push({ tokenId, value });
  }

  return results;
}
```

### Querying Multiple Event Types

When working with ERC-1155 tokens, we can optimize by querying both TransferSingle and TransferBatch events in a single request:

```typescript lines title="lib/multi-event.ts" theme={null}
const query = {
  from_block: 0,
  logs: [
    {
      address: [contractAddress],
      topics: [[TRANSFER_SINGLE, TRANSFER_BATCH]], // Both ERC-1155 events
    },
  ],
  field_selection: {
    log: ["topic0", "topic1", "topic2", "topic3", "data"],
  },
};
```

Then route based on `topic0`:

```typescript lines theme={null}
for (const log of block.logs) {
  if (log.topic0 === TRANSFER_SINGLE) {
    const parsed = parseTransferSingle(log.data);
    // handle single transfer...
  } else if (log.topic0 === TRANSFER_BATCH) {
    const parsed = parseTransferBatch(log.data);
    // handle batch transfer...
  }
}
```

## Get Latest Block

To verify you've synced all available data, you can check the current chain height:

```typescript lines title="lib/height.ts" theme={null}
async function getLatestBlock(apiKey: string): Promise<number> {
  const response = await fetch(`${HYPERSYNC_URL}/height`, {
    headers: { "Authorization": `Bearer ${apiKey}` },
  });
  const data = await response.json();
  return data.height;
}
```

## Common Mistakes

### 1. Forgetting pagination

HyperSync returns partial results. Always check `next_block`:

```typescript theme={null}
// Wrong - only gets first page
const response = await queryHypersync(contract, 0);

// Right - loop until done
while (response.next_block) {
  // continue querying...
}
```

### 2. Requesting unused fields

Every field adds to response size. Be explicit:

```typescript theme={null}
// Wrong - fetches everything
field_selection: { log: ["*"] }

// Right - only what you need
field_selection: { log: ["topic0", "topic2", "topic3"] }
```

### 3. Using libraries for simple parsing

HyperSync returns raw hex. Native BigInt handles it:

```typescript theme={null}
// Unnecessary - adds dependency
import { decodeAbiParameters } from "viem";

// Sufficient - native JS
const value = BigInt("0x" + data.slice(2, 66));
```

### 4. Not filtering burned tokens

Address `0x000...000` means burned:

```typescript theme={null}
const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";

// Filter them out
const active = ownership.filter(([, owner]) => owner !== ZERO_ADDRESS);
```

## API Reference

### POST /query

Query event logs.

**Request body:**

| Field                 | Type         | Description                                        |
| --------------------- | ------------ | -------------------------------------------------- |
| `from_block`          | number       | Starting block (inclusive)                         |
| `to_block`            | number       | Ending block (optional)                            |
| `logs`                | array        | Log filters                                        |
| `logs[].address`      | string\[]    | Contract addresses to filter                       |
| `logs[].topics`       | string\[]\[] | Topic filters (OR within array, AND across arrays) |
| `field_selection.log` | string\[]    | Fields to return                                   |

**Response:**

| Field         | Type   | Description                      |
| ------------- | ------ | -------------------------------- |
| `data`        | array  | Blocks containing matching logs  |
| `data[].logs` | array  | Matching logs in block           |
| `next_block`  | number | Next block to query (pagination) |

### GET /height

Get current chain height.

**Response:**

| Field    | Type   | Description         |
| -------- | ------ | ------------------- |
| `height` | number | Latest block number |

## Summary

Envio HyperSync lets you query any contract's event history across Monad with a single paginated API — no node to run, no indexer to maintain.

The `/query` endpoint accepts topic and address filters, and `/height` gives you the current chain tip. Check out the [full HyperSync documentation](https://docs.envio.dev/docs/HyperSync/overview) for additional query types and options.

From here, you could extend this pattern to build airdrop eligibility checkers, governance voting power snapshots, or multi-token portfolio trackers.

## Next Steps

* [Envio docs](https://docs.envio.dev/docs/HyperSync/overview) - Full HyperSync documentation
* [API tokens](https://envio.dev/app/api-tokens) - Get your free API key


# How to add swaps to your app using Kuru Flow
Source: https://docs.monad.xyz/guides/kuru-flow



Your application may need to allow users to swap between two assets. You want your users
to get the best price available across the ecosystem.

Aggregators check many liquidity sources and find the best price. Integrating an aggregator API
can thus be a convenient and efficient means of enabling swapping in your app.

In this guide, we will examine integrating one such aggregator,
[Kuru Flow](https://docs.kuru.io/kuru-flow/flow-overview). You'll learn how to integrate Kuru
Flow into a frontend application—from authentication to fetching quotes and executing swaps.

## Requirements

Before you begin, ensure you have the following:

* A frontend framework with wallet connection (React, Next.js, etc.)
* [wagmi](https://wagmi.sh) and [viem](https://viem.sh) for wallet interactions
* User wallet connected to Monad mainnet (chain ID `143`)

## 1. Configure Authentication

We first need to get credentials to access the Kuru Flow API.
Kuru Flow uses JWT tokens for API authentication.

```typescript lines title="lib/kuru-flow.ts" theme={null}
const KURU_FLOW_API = "https://ws.kuru.io";

async function generateToken(userAddress: string) {
  const response = await fetch(`${KURU_FLOW_API}/api/generate-token`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ user_address: userAddress }),
  });

  return response.json();
  // Returns: { token: string, expires_at: number, rate_limit: { rps: number, burst: number } }
}
```

## 2. Get a Swap Quote

The `/api/quote` endpoint calculates the best swap path and returns transaction data.

The following parameters are supported:

| Parameter           | Required | Description                                      |
| ------------------- | -------- | ------------------------------------------------ |
| `userAddress`       | Yes      | User's wallet address                            |
| `tokenIn`           | Yes      | Token address (`0x0` for native MON)             |
| `tokenOut`          | Yes      | Token address (`0x0` for native MON)             |
| `amount`            | Yes      | Amount in smallest token units                   |
| `autoSlippage`      | No\*     | Set to `true` for automatic slippage calculation |
| `slippageTolerance` | No\*     | Manual slippage in basis points (1-10000)        |
| `referrerAddress`   | No       | Your address to receive referral fees            |
| `referrerFeeBps`    | No       | Referral fee in basis points (0-10000)           |

\*Either `autoSlippage: true` OR `slippageTolerance` must be provided.

We can write a small function to interact with the `quote` API:

```typescript lines title="lib/kuru-flow.ts" theme={null}
const KURU_FLOW_API = "https://ws.kuru.io";

// Your wallet address to receive referral fees
const REFERRER_ADDRESS = "0xYOUR_WALLET_ADDRESS_HERE";
const REFERRER_FEE_BPS = 50; // 0.5%

async function getQuote(
  userAddress: string,
  tokenIn: string,
  tokenOut: string,
  amount: string,
  token: string
) {
  const response = await fetch(`${KURU_FLOW_API}/api/quote`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({
      userAddress,
      tokenIn,
      tokenOut,
      amount,
      autoSlippage: true,
      referrerAddress: REFERRER_ADDRESS,
      referrerFeeBps: REFERRER_FEE_BPS,
    }),
  });

  return response.json();
}
```

### Response Structure

```typescript lines title="lib/kuru-flow.ts" theme={null}
export interface QuoteResponse {
  type: string;
  status: "success" | "error";
  output: string;           // Expected output amount (in wei)
  minOut: string;           // Minimum output with slippage
  transaction: {
    to: string;             // Router contract address
    calldata: string;       // Transaction calldata (WITHOUT 0x prefix!)
    value: string;          // Native MON amount (non-zero when swapping native MON)
  };
  gasPrices: {
    slow: string;
    standard: string;
    fast: string;
    rapid: string;
    extreme: string;
  };
  message?: string;         // Error message if status is "error"
}
```

<Note>
  The `calldata` field does NOT include the `0x` prefix. You must add it before sending the transaction.
</Note>

## 3. Check Token Allowance (ERC20 Only)

Before executing a swap with ERC20 tokens, we should verify that the router has permission to
spend the user's tokens.

<Tip>
  **Native MON does not require approval.** Skip this step when swapping native MON.
</Tip>

```typescript lines title="components/SwapCard.tsx" theme={null}
import { useState } from "react";
import { useAccount, useReadContract } from "wagmi";
import { parseUnits } from "viem";
import type { QuoteResponse } from "@/lib/kuru-flow";

// Token addresses
const NATIVE_MON = "0x0000000000000000000000000000000000000000" as const;
const USDC = "0x754704Bc059F8C67012fEd69BC8A327a5aafb603" as const;

const ERC20_ABI = [
  {
    name: "allowance",
    type: "function",
    stateMutability: "view",
    inputs: [
      { name: "owner", type: "address" },
      { name: "spender", type: "address" },
    ],
    outputs: [{ name: "", type: "uint256" }],
  },
] as const;

// Inside your component:
const { address } = useAccount();
const [amount, setAmount] = useState("");
const [quote, setQuote] = useState<QuoteResponse | null>(null);

const tokenIn = USDC; // Example: swapping USDC
const isNativeToken = tokenIn === NATIVE_MON;
const amountWei = amount ? parseUnits(amount, 6) : BigInt(0);

// Check allowance against router address from quote (skip for native MON)
const { data: allowance } = useReadContract({
  address: tokenIn,
  abi: ERC20_ABI,
  functionName: "allowance",
  args: address && quote?.transaction?.to
    ? [address, quote.transaction.to as `0x${string}`]
    : undefined,
  query: {
    enabled: !isNativeToken, // Don't check allowance for native token
  },
});

// Native tokens don't need approval
const needsApproval = !isNativeToken && allowance !== undefined && amountWei > allowance;
```

## 4. Approve Token Spending (ERC20 Only)

If allowance is insufficient for an ERC20 token, we should request approval before swapping.

```typescript lines title="components/SwapCard.tsx" theme={null}
import { encodeFunctionData } from "viem";
import { useSendTransaction } from "wagmi";

const APPROVE_ABI = [
  {
    name: "approve",
    type: "function",
    stateMutability: "nonpayable",
    inputs: [
      { name: "spender", type: "address" },
      { name: "amount", type: "uint256" },
    ],
    outputs: [{ name: "", type: "bool" }],
  },
] as const;

// Inside your component:
const { sendTransaction: sendApproveTx } = useSendTransaction();

const handleApprove = () => {
  if (!quote?.transaction?.to) return;

  const data = encodeFunctionData({
    abi: APPROVE_ABI,
    functionName: "approve",
    args: [quote.transaction.to as `0x${string}`, amountWei],
  });

  sendApproveTx({
    to: tokenIn,
    data,
  });
};
```

<Tip>
  Use viem's `encodeFunctionData` instead of manual hex string manipulation for reliable ABI encoding.
</Tip>

## 5. Execute the Swap

To submit the swap, we should use the transaction data from the quote response:

```typescript lines title="components/SwapCard.tsx" theme={null}
// Inside your component:
const { sendTransaction: sendSwapTx } = useSendTransaction();

const handleSwap = () => {
  if (!quote || quote.status !== "success") return;

  // IMPORTANT: Add 0x prefix to calldata
  const calldata = quote.transaction.calldata.startsWith("0x")
    ? quote.transaction.calldata
    : `0x${quote.transaction.calldata}`;

  sendSwapTx({
    to: quote.transaction.to as `0x${string}`,
    data: calldata as `0x${string}`,
    value: BigInt(quote.transaction.value || "0"),
  });
};
```

## Token Addresses and Decimals (Mainnet)

| Token        | Address                                      | Decimals | Notes              |
| ------------ | -------------------------------------------- | -------- | ------------------ |
| MON (native) | `0x0000000000000000000000000000000000000000` | 18       | No approval needed |
| USDC         | `0x754704Bc059F8C67012fEd69BC8A327a5aafb603` | 6        | Requires approval  |

<Warning>
  Be careful with token decimals when formatting output. USDC uses 6 decimals, not 18.

  ```typescript theme={null}
  import { formatEther, formatUnits } from "viem";

  // WRONG - assumes 18 decimals
  formatEther(BigInt(quote.output))  // Shows 0.000000002301622011

  // CORRECT - use actual token decimals
  formatUnits(BigInt(quote.output), 6)  // Shows 2301.62
  ```
</Warning>

## Referral Fee System

Kuru features a referral system. As the referrer, we can earn fees on every swap by including your referrer details in quote requests.

```typescript lines title="lib/kuru-flow.ts" theme={null}
// Replace with YOUR wallet address to receive referral fees
export const REFERRER_ADDRESS = "0xYOUR_WALLET_ADDRESS_HERE";

// Fee in basis points (50 = 0.5%, 100 = 1%)
export const REFERRER_FEE_BPS = 50;
```

**Example fee calculations at 50 bps (0.5%):**

| Swap Output | Fee Amount |
| ----------- | ---------- |
| 100 USDC    | 0.5 USDC   |
| 500 USDC    | 2.5 USDC   |
| 1000 USDC   | 5 USDC     |

<Warning>
  Replace `0xYOUR_WALLET_ADDRESS_HERE` with your actual wallet address before deploying. The `referrerAddress` must be a valid Ethereum address or transactions will fail.
</Warning>

## Error Handling

Along the way, we might run into errors. Here is how to interpret them:

| Status Code | Meaning                                 |
| ----------- | --------------------------------------- |
| 400         | Bad request - check parameters          |
| 401         | Unauthorized - invalid or expired token |
| 429         | Rate limited - wait before retrying     |
| 500         | Server error - retry later              |

## Common Mistakes

1. **Missing 0x prefix** - Add `0x` prefix to calldata before sending
2. **Invalid referrer address** - Must be a valid Ethereum address
3. **Skipping approval for ERC20** - ERC20 tokens require approval before swap (native MON does not)
4. **Wrong decimals** - USDC has 6 decimals, MON has 18
5. **Zero value for native MON swaps** - When swapping native MON, the transaction `value` must be set to the swap amount

## Next Steps

* Try the [Live Demo](https://kuru-flow-api-example-one.vercel.app/) to see Kuru Flow in action
* Clone the [Example Repository](https://github.com/monad-developers/kuru-flow-api-example) for a complete working implementation
* Read the [Kuru Flow Overview](https://docs.kuru.io/kuru-flow/flow-overview) for more details
* See [Monad Network Information](/developer-essentials/network-information) for RPC endpoints and chain configuration


# How to build an MCP server that can interact with Monad Testnet
Source: https://docs.monad.xyz/guides/monad-mcp



In this guide, you will learn how to build a [Model Context Protocol](https://github.com/modelcontextprotocol) (MCP) server that allows an MCP Client (Claude Desktop) to query Monad Testnet to check the MON balance of an account.

## What is MCP?

The [Model Context Protocol](https://github.com/modelcontextprotocol) (MCP) is a standard that allows AI models to interact with external tools and services.

## Prerequisites

* Node.js (v16 or later)
* `npm` or `yarn`
* Claude Desktop

## Getting started

1. Clone the [`monad-mcp-tutorial`](https://github.com/monad-developers/monad-mcp-tutorial) repository. This repository has some code that can help you get started quickly.

```shell theme={null}
git clone https://github.com/monad-developers/monad-mcp-tutorial.git
```

2. Install dependencies:

```
npm install
```

## Building the MCP server

Monad Testnet-related configuration is already added to `index.ts` in the `src` folder.

### Define the server instance

```ts lines title="src/index.ts" theme={null}
// Create a new MCP server instance
const server = new McpServer({
  name: "monad-mcp-tutorial",
  version: "0.0.1",
  // Array of supported tool names that clients can call
  capabilities: ["get-mon-balance"]
});
```

### Define the MON balance tool

Below is the scaffold of the `get-mon-balance` tool:

```ts lines title="src/index.ts" theme={null}
server.tool(
    // Tool ID 
    "get-mon-balance",
    // Description of what the tool does
    "Get MON balance for an address on Monad testnet",
    // Input schema
    {
        address: z.string().describe("Monad testnet address to check balance for"),
    },
    // Tool implementation
    async ({ address }) => {
        // code to check MON balance
    }
);
```

Let's add the MON balance check implementation to the tool:

```ts lines title="src/index.ts" theme={null}
server.tool(
    // Tool ID 
    "get-mon-balance",
    // Description of what the tool does
    "Get MON balance for an address on Monad testnet",
    // Input schema
    {
        address: z.string().describe("Monad testnet address to check balance for"),
    },
    // Tool implementation
    async ({ address }) => {
        try {
            // Check MON balance for the input address
            const balance = await publicClient.getBalance({
                address: address as `0x${string}`,
            });

            // Return a human friendly message indicating the balance.
            return {
                content: [
                    {
                        type: "text",
                        text: `Balance for ${address}: ${formatUnits(balance, 18)} MON`,
                    },
                ],
            };
        } catch (error) {
            // If the balance check process fails, return a graceful message back to the MCP client indicating a failure.
            return {
                content: [
                    {
                        type: "text",
                        text: `Failed to retrieve balance for address: ${address}. Error: ${
                        error instanceof Error ? error.message : String(error)
                        }`,
                    },
                ],
            };
        }
    }
);
```

### Initialize the transport and server from the `main` function

```ts lines title="src/index.ts" theme={null}
async function main() {
    // Create a transport layer using standard input/output
    const transport = new StdioServerTransport();
    
    // Connect the server to the transport
    await server.connect(transport);
}
```

### Build the project

```shell theme={null}
npm run build
```

The server is now ready to use!

### Add the MCP server to Claude Desktop

1. Open "Claude Desktop"

![claude desktop](https://github.com/monad-developers/monad-mcp-tutorial/blob/main/static/1.png?raw=true)

2. Open Settings

Claude > Settings > Developer

![claude settings](https://github.com/monad-developers/monad-mcp-tutorial/blob/main/static/claude_settings.gif?raw=true)

3. Open `claude_desktop_config.json`

![claude config](https://github.com/monad-developers/monad-mcp-tutorial/blob/main/static/config.gif?raw=true)

4. Add details about the MCP server and save the file.

```json lines title="claude_desktop_config.json" theme={null}
{
  "mcpServers": {
    ...
    "monad-mcp": {
      "command": "node",
      "args": [
        "/<path-to-project>/build/index.js"
      ]
    }
  }
}
```

5. Restart "Claude Desktop"

### Use the MCP server

You should now be able to see the tools in Claude!

![tools](https://github.com/monad-developers/monad-mcp-tutorial/blob/main/static/tools.gif?raw=true)

Here's the final result

![final result](https://github.com/monad-developers/monad-mcp-tutorial/blob/main/static/final_result.gif?raw=true)

## Further resources

* [Model Context Protocol Documentation](https://modelcontextprotocol.io/introduction)
* [Monad Documentation](https://docs.monad.xyz/)
* [Viem Documentation](https://viem.sh/)


# How to build a portfolio viewer using Moralis API
Source: https://docs.monad.xyz/guides/moralis-api



When building a web3 app, it is essentially for the app to show some information about the connected wallet like ERC20 token balances, ERC721 token balances, transaction history etc...

Moralis has a wide range of out-of-the-box APIs for the most popular features like wallet native balance, fetch all NFTs and collections, wallet age and activity, and many more...

In this guide, you will learn how to build a simple ERC20 token balances view for the connected wallet using Moralis API and NextJS.

<Note>
  If you wish to try the portfolio viewer before building it, you can do so [here](https://portfolio-dashboard-example.vercel.app)
</Note>

<img alt="portfolio view" />

## Requirements

Before you begin, you'll need:

1. **Moralis API Key**: Get it from [Moralis Dashboard](https://admin.moralis.io/)
2. **Reown Project ID**: Get it from [Reown Cloud](https://cloud.reown.com/)
   * You can also check out the [Reown AppKit guide for Monad](http://docs.monad.xyz/guides/reown-guide)

## Step 1: Initializing the project

### Create Nextjs app

```
npx create-next-app@latest portfolio-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
```

### Install ShadCN components

```
npx shadcn@latest add button card tabs
```

### Install Tanstack React Query (for better async state management)

```
npm install @tanstack/react-query
```

## Step 2: Environment Setup

Add your Moralis API key and Reown Project ID to `.env.local`:

```bash theme={null}
MORALIS_API_KEY=
NEXT_PUBLIC_PROJECT_ID=
```

## Step 3: Connect Wallet functionality

### Create the `ContextProvider` component

Create a folder named `context` in the `src` directory, inside the folder create a file named `index.ts`

```ts title="src/context/index.ts" theme={null}
"use client";

import { wagmiAdapter, projectId } from "@/config";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { createAppKit } from "@reown/appkit/react";
import { monad } from "@reown/appkit/networks";
import React, { type ReactNode } from "react";
import { WagmiProvider, type Config } from "wagmi";

// Set up queryClient
const queryClient = new QueryClient();

if (!projectId) {
  throw new Error("NEXT_PUBLIC_PROJECT_ID is not set");
}

// Set up metadata
const metadata = {
  name: "Portfolio Viewer",
  description: "View your crypto portfolio on Monad blockchain",
  url: "your-app-url",
  icons: ["your-app-icon"],
};

// Create the modal
const modal = createAppKit({
  adapters: [wagmiAdapter],
  projectId,
  networks: [monad],
  defaultNetwork: monad,
  metadata: metadata,
  features: {
    analytics: true,
  },
});

export function ContextProvider({ children }: { children: ReactNode }) {
  return (
    <WagmiProvider config={wagmiAdapter.wagmiConfig as Config}>
      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
    </WagmiProvider>
  );
}
```

### Wrap the app with `ContextProvider` component in `layout.tsx`

```tsx title="src/app/layout.tsx" theme={null}
// imports

export const metadata: Metadata = {
  title: "Monad Portfolio App",
  description: "View your crypto portfolio on Monad blockchain",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en" className={GeistSans.variable} style={{
      // @ts-ignore
      '--font-geist-sans': GeistSans.style.fontFamily,
      '--font-geist-mono': GeistMono.style.fontFamily,
    }}>
      <body className="font-sans min-h-screen flex flex-col bg-dot-pattern">
        <ContextProvider>
          <main className="flex-1 pb-6">{children}</main>
        </ContextProvider>
      </body>
    </html>
  );
}
```

### Create a custom `ConnectButton`

Create a file in `components/wallet` folder named `ConnectButton.tsx`

```tsx title="src/components/wallet/ConnectButton.tsx" theme={null}
"use client";

import { useAppKit, useAppKitAccount, useDisconnect } from "@reown/appkit/react";
import { Button } from "@/components/ui/Button";
import { ConnectIcon, type ConnectIconHandle } from "@/components/ui/ConnectIcon";

export function ConnectButton() {
  const { open } = useAppKit();
  const { address, isConnected } = useAppKitAccount();
  const { disconnect } = useDisconnect();

  if (isConnected && address) {
    return (
      <div className="inline-flex rounded-md shadow-sm">
        <a
          href={`https://monadvision.com/address/${address}`}
          target="_blank"
          rel="noopener noreferrer"
          className="inline-flex items-center px-8 h-10 bg-primary text-primary-foreground rounded-l-md font-semibold text-sm hover:bg-primary/90 transition-colors"
        >
          {formatAddress(address)}
        </a>
        <Button
          onClick={() => disconnect()}
          size="icon"
          className="h-10 w-10 rounded-l-none border-l border-primary-foreground/20"
        >
          <ConnectIcon size={16} />
        </Button>
      </div>
    );
  }

  return (
    <Button
      onClick={() => open()}
      size="lg"
      className="font-semibold shadow-sm gap-2"
    >
      <ConnectIcon ref={connectIconRef} size={20} />
      Connect Wallet
    </Button>
  );
}
```

We are using the `useAppKit` and `useAppKitAccount` hook for creating a custom connect button instead of the standard one provided by Reown AppKit.

### Create a `Header` component with custom `ConnectButton`

<img alt="header" />

Create a file named `Header.tsx` in `src/components/layout` folder and import the newly created `ConnectButton` component into it.

```tsx title="src/components/layout/Header.tsx" theme={null}
"use client";

import { ConnectButton } from "../wallet/ConnectButton";
import { ExternalLink } from "lucide-react";

export function Header() {
  return (
    <header className="sticky top-0 z-50 w-full border-b border-border bg-card/80 backdrop-blur supports-[backdrop-filter]:bg-card/60">
        <div className="flex h-16 items-center justify-between">
          <div className="flex items-center gap-3">
            <h1 className="text-xl font-bold text-foreground">
              Portfolio App
            </h1>
          </div>
          <div className="flex items-center gap-6">
            <ConnectButton />
          </div>
        </div>
    </header>
  );
}
```

Import the `Header` component in `layout.tsx`

```tsx title="src/app/layout.tsx" theme={null}
import { Header } from "@/components/layout/Header";

// rest of the code

<ContextProvider>
    <Header />
    <main className="flex-1 pb-6">{children}</main>
</ContextProvider>

// rest of the code
```

You should now be able to see a custom Connect Wallet button!

## Step 4: Fetching connected wallet token balances

### Creating a `/api/wallet/balances` route

Create a file named `route.ts` in the folder `src/app/api/wallet/balances/`

We are using the "Get Native & ERC20 Token Balances by Wallet" Moralis API endpoint to get the token balances. You can find the endpoint docs [here](https://docs.moralis.com/web3-data-api/evm/reference/wallet-api/get-wallet-token-balances-price?address=0xcB1C1FdE09f811B294172696404e88E658659905\&chain=0x8f\&token_addresses=\[]\&limit=25).

It takes in an address and a chain id and returns a list of ERC20 tokens (including Logo, Name, Symbol) and native balance of the address.

```ts title="src/app/api/wallet/balances/route.ts" theme={null}
import { NextRequest, NextResponse } from "next/server";

const MORALIS_API_BASE = "https://deep-index.moralis.io/api/v2.2";

export async function GET(request: NextRequest) {
  try {
    const { searchParams } = request.nextUrl;
    const address = searchParams.get("address");
    const chain = "0x8f"; // 0x8f = 143 (Monad chain ID in hex)

    if (!address) {
      return NextResponse.json(
        { error: "Address is required" },
        { status: 400 }
      );
    }

    // Fetch ERC20 token balances with price data from Moralis
    const data = await moralisRequest({
      endpoint: `/wallets/${address}/tokens`,
      params: {
        chain,
      },
    });

    return NextResponse.json(data);
  } catch (error) {
    console.error("Error fetching token balances:", error);

    const errorMessage = error instanceof Error ? error.message : "Failed to fetch token balances";

    return NextResponse.json(
      {
        error: errorMessage,
      },
      { status: 500 }
    );
  }
}

async function moralisRequest({
  endpoint,
  params,
}) {
  const apiKey = process.env.MORALIS_API_KEY;

  if (!apiKey) {
    throw new Error("MORALIS_API_KEY is not set");
  }

  const url = new URL(`${MORALIS_API_BASE}${endpoint}`);

  if (params) {
    Object.entries(params).forEach(([key, value]) => {
      url.searchParams.append(key, String(value));
    });
  }

  const response = await fetch(url.toString(), {
    method: "GET",
    headers: {
      "X-API-Key": apiKey,
      "Content-Type": "application/json",
    },
    next: {
      revalidate: 30, // Cache for 30 seconds
    },
  });

  if (!response.ok) {
    const errorData = await response.json().catch(() => ({}));
    const errorMessage = errorData.message || `Moralis API error: ${response.status}`;

    console.error("Moralis API Error:", {
      status: response.status,
      url: url.toString(),
      error: errorData,
    });

    throw new Error(errorMessage);
  }

  return response.json();
}
```

### Create a react hook called `useTokenBalances`

This react hook calls the `/api/wallet/balances/` endpoint that you created and gets the token balances data, formats it into a proper list and makes it available to consume in the frontend.

```ts title="src/hooks/useTokenBalances.ts" theme={null}
"use client";

import { useQuery } from "@tanstack/react-query";

async function fetchTokenBalances(
  address: string,
) {
  const response = await fetch(
    `/api/wallet/balances?address=${address}`
  );

  if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new Error(error.error || "Failed to fetch token balances");
  }

  const data = await response.json();

  // Check if data exists
  if (!data) {
    return [];
  }

  // Handle both response formats: direct array or object with result property
  const tokens = Array.isArray(data) ? data : data.result;

  if (!tokens || !Array.isArray(tokens)) {
    return [];
  }

  // Transform Moralis data to our Token type
  return tokens.map((token) => {
    const balanceFormatted = parseFloat(
      formatTokenBalance(token.balance, token.decimals)
    );

    // Calculate USD value if we have price but not value
    const usdValue = token.usd_value !== undefined
      ? token.usd_value
      : token.usd_price !== undefined
        ? token.usd_price * balanceFormatted
        : undefined;

    return {
      address: token.token_address,
      name: token.name,
      symbol: token.symbol,
      logo: token.logo || token.thumbnail,
      decimals: token.decimals,
      balance: token.balance,
      balanceFormatted,
      usdPrice: token.usd_price,
      usdValue,
      isNative: token.native_token || false,
      isSpam: token.possible_spam,
      verified: token.verified_contract,
    };
  });
}

export function useTokenBalances(address?: string, enabled: boolean = true) {
  return useQuery({
    queryKey: ["tokenBalances", address],
    queryFn: () => fetchTokenBalances(address!),
    enabled: enabled && !!address,
    staleTime: 30000, // 30 seconds
  });
}

function formatTokenBalance(
  balance: string | number,
  decimals: number = 18
): string {
  const balanceNum = typeof balance === "string" ? parseFloat(balance) : balance;
  const divisor = Math.pow(10, decimals);
  const formattedBalance = balanceNum / divisor;

  // Show more decimals for small amounts
  if (formattedBalance < 0.01) {
    return formattedBalance.toFixed(6);
  } else if (formattedBalance < 1) {
    return formattedBalance.toFixed(4);
  } else {
    return formattedBalance.toFixed(2);
  }
}
```

We will later use this hook in the UI components

## Step 5: Creating the UI

### Create a `TokenRow` component

<img alt="token-row" />

`TokenRow` component will display token details like name, symbol, logo, usd price, amount of tokens in connected wallet and the usd value.

Create a file named `TokenRow.tsx` in the folder `src/components/portfolio/tokens/`

```tsx title="src/components/portfolio/tokens/TokenRow.tsx" theme={null}
import Image from "next/image";

export function TokenRow({ token }) {
  return (
    <div className="grid grid-cols-12 gap-4 px-6 py-4 hover:bg-muted/30 transition-colors">
      {/* Token Info */}
      <div className="col-span-4 flex items-center gap-3">
        {token.logo ? (
          <Image
            src={token.logo}
            alt={token.name}
            width={40}
            height={40}
            className="rounded-full"
            onError={(e) => {
              e.currentTarget.style.display = "none";
            }}
          />
        ) : (
          <div className="w-10 h-10 rounded-full bg-primary/10 flex items-center justify-center text-primary font-bold border border-primary/20">
            {token.symbol.charAt(0)}
          </div>
        )}
        <div className="min-w-0">
          <div className="flex items-center gap-2">
            <p className="font-semibold truncate">{token.symbol}</p>
          </div>
          <p className="text-sm text-muted-foreground truncate">
            {token.name}
          </p>
        </div>
      </div>

      {/* Price */}
      <div className="col-span-2 flex items-center justify-end">
        {token.usdPrice !== undefined && token.usdPrice > 0 ? (
          <p className="text-sm font-medium">
            ${formatCurrency(token.usdPrice, 4)}
          </p>
        ) : (
          <p className="text-sm text-muted-foreground">-</p>
        )}
      </div>

      {/* Amount */}
      <div className="col-span-3 flex items-center justify-end">
        <p className="font-medium">{formatCurrency(token.balanceFormatted, 2)}</p>
      </div>

      {/* USD Value */}
      <div className="col-span-3 flex items-center justify-end">
        {token.usdValue !== undefined && token.usdValue > 0 ? (
          <p className="font-semibold text-primary">
            {formatUSD(token.usdValue)}
          </p>
        ) : (
          <p className="text-sm text-muted-foreground">-</p>
        )}
      </div>
    </div>
  );
}

// Helper function to format values in the UI

function formatUSD(value: number): string {
  if (value === 0) return "$0.00";
  if (value < 0.01) return "< $0.01";
  if (value < 1) return `$${value.toFixed(4)}`;
  if (value < 1000) return `$${value.toFixed(2)}`;
  if (value < 1000000) return `$${(value / 1000).toFixed(2)}K`;
  return `$${(value / 1000000).toFixed(2)}M`;
}

function formatCurrency(value: number, decimals: number = 2): string {
  return value.toLocaleString("en-US", {
    minimumFractionDigits: decimals,
    maximumFractionDigits: decimals,
  });
}
```

### Create a `TokenList` component

<img alt="token-list" />

Create a `TokenList.tsx` file in `src/components/portfolio` folder and import the newly created `TokenRow.tsx` component in it.

```tsx title="src/components/portfolio/TokenList.tsx" theme={null}
import { TokenRow } from "./tokens/TokenRow";

export function TokenList({
  tokens,
  isLoading,
  error,
  showLowValueTokens = false,
}) {

  if (isLoading) {
    return (
      // Loading state
    );
  }

  if (error) {
    return (
      // Error state
    );
  }

  
  if (tokens.length === 0) {
    return (
        // Empty state 
    );
  }

  return (
    <div className="divide-y divide-border">
        {tokens.map((token) => (
            <TokenRow key={token.address} token={token} />
        ))}
    </div>
  );
}
```

### Create a `PortfolioDashboard` component

<img alt="dashboard" />

The `PortfolioDashboard` component will display the `TokenList` and can be further modified to have more components presenting information that you would like your user to see.

```tsx title="src/components/portfolio/PortfolioDashboard.tsx" theme={null}
"use client";

import { useState, useEffect } from "react";
import { useAccount } from "wagmi";
import { useTokenBalances } from "@/hooks/useTokenBalances";
import { TokenList } from "./TokenList";

export function PortfolioDashboard() {
  const { address, isConnected } = useAccount();
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  const {
    data: tokens = [],
    isLoading,
    error,
    refetch,
    isFetching,
  } = useTokenBalances(address, isConnected);

  // Prevent hydration mismatch - don't render until mounted
  if (!mounted) {
    return null;
  }

  // Not connected state
  if (!isConnected) {
    return (
       // UI for wallet not connected state
    );
  }

  return (
    <div className="space-y-8">
        <TokenList
            tokens={tokens}
            isLoading={isLoading}
            error={error?.message}
            showLowValueTokens={showLowValueTokens}
        />
    </div>
  );
}
```

<Tip>
  Check out the other [Moralis API endpoints](https://docs.moralis.com/web3-data-api/evm/api-reference) and create visual components for the same!
</Tip>

## Conclusion

In this guide you learned how to use Moralis API to get wallet token balances and presenting them in a UI.

It is highly recommended you check out the other API endpoints and add more features to this project you created!

You can find a complete portfolio dashboard project [here](https://github.com/monad-developers/portfolio-dashboard-example) for inspiration.

## Useful links

* [Live portfolio app](https://portfolio-dashboard-example.vercel.app)
* [Moralis API reference](https://docs.moralis.com/web3-data-api/evm/api-reference)
* [Portfolio dashboard project](https://github.com/monad-developers/portfolio-dashboard-example)
* [Reown AppKit Docs](https://docs.reown.com/appkit/next/core/installation)


# How to connect a wallet to your app with Reown AppKit
Source: https://docs.monad.xyz/guides/reown



This guide shows you how to use [Reown AppKit](https://reown.com/appkit) to enable wallet connections and interact with the Monad network. AppKit provides seamless wallet connections, including email/social logins, smart accounts, one-click authentication, and wallet notifications.

For this tutorial, we'll be using Next.js, though you can use any other framework compatible
with AppKit.

<Note>
  AppKit is available on eight frameworks, including React, Next.js, Vue, JavaScript, React
  Native, Flutter, Android, iOS, and Unity.
</Note>

**What you'll learn:**

* Set up a new project using AppKit CLI
* Configure the project for Monad Testnet
* Connect wallets to your application

**Time to complete:** \~5 minutes

## Prerequisites

* Node.js installed on your system

## Step 1: Create a New Project

Run the AppKit CLI to create a new project configured with Reown AppKit:

```bash theme={null}
npx @reown/appkit-cli
```

When prompted, provide:

1. **Project Name**: Choose a name (e.g., `my-monad-appkit-app`)
2. **Framework**: Select `Next.js` (or your preferred framework)
3. **Blockchain Library**: Choose whether you want to install Wagmi, Ethers, Solana,
   or Multichain (EVM + Solana). In this case, you need to either pick `Wagmi` or `Ethers` since
   Monad is an EVM compatible blockchain. We will be choosing `Wagmi` for the sake of this
   tutorial.

The CLI will create a minimal AppKit example with your selected configuration.

## Step 2: Set Up the Project

Navigate to your project directory and install dependencies:

```bash theme={null}
cd my-monad-appkit-app
npm install
```

<Note>
  You can also use other package managers such as `yarn`, `bun`, `pnpm`, etc.
</Note>

## Step 3: Get Your Project ID

The example is pre-configured with a `projectId` that will only work on `localhost`. To fully configure your project, you will need to get a `projectId` from the [Reown Dashboard](https://dashboard.reown.com/?utm_source=monad\&utm_medium=docs\&utm_campaign=backlinks), as described below:

1. Go to [dashboard.reown.com](https://dashboard.reown.com/?utm_source=monad\&utm_medium=docs\&utm_campaign=backlinks) and sign in
2. Navigate to your team's Cloud Dashboard
3. Click "+ Project"

<img alt="Create Project" />

4. If prompted to choose a product type, select "AppKit" (otherwise ignore this step)

<img alt="Enter Project Name" />

5. Choose a project name
6. Click "Create"

<img alt="Select Framework" />

7. Copy the generated Project ID from the bottom of the page

<img alt="Project ID" />

## Step 4: Configure Environment Variables

Create a `.env` file in your project root:

```js title=".env" theme={null}
NEXT_PUBLIC_PROJECT_ID="YOUR_PROJECT_ID_HERE"
```

Replace `YOUR_PROJECT_ID_HERE` with the Project ID you copied in the previous step.

<Warning>
  Environment variables starting with `NEXT_PUBLIC_` are exposed to the client. Only include non-sensitive configuration data.
</Warning>

## Step 5: Configure for Monad Testnet

Update `/src/config/index.ts` to use Monad Testnet:

```ts lines title="/src/config/index.ts" theme={null}
import { mainnet, monadTestnet } from '@reown/appkit/networks'

export const networks = [monadTestnet] as [AppKitNetwork, ...AppKitNetwork[]]
```

This configures your app to use Monad Testnet instead of the default networks.

## Step 6: Run Your Application

Start the development server:

```bash theme={null}
npm run dev
```

Your app will be available at `http://localhost:3000`.

<Note>
  If you are using alternative package managers, you can try either of these commands - `yarn dev`, `pnpm dev`, or `bun dev`.
</Note>

## Conclusion

You have now learned how to create a simple app using AppKit CLI that allows users to connect their wallet and interact with Monad Testnet.

**Reown AppKit** is a powerful solution for developers looking to integrate wallet connections and other Web3 functionalities into their apps on any EVM chain. In just a few simple steps, you can provide your users with seamless wallet access, one-click authentication, social logins, and notifications—streamlining their experience while enabling advanced features like on-ramp functionality and smart accounts.

## What's Next?

* Explore the [Reown blog](https://reown.com/blog)
* Check out the complete example: [Reown AppKit EVM](https://github.com/rohit-710/reown-appkit-evm)


# How to build a basic dApp with Scaffold-ETH
Source: https://docs.monad.xyz/guides/scaffold-eth



In this guide, you will learn how to use Scaffold-ETH 2 to quickly build a new dapp project.

## Requirements

Before you begin, you need to install the following tools:

* Node (>= v18.18)
* Yarn (v1 or v2+)
* Git

### Get funds on Monad Testnet

You will need funds on Monad Testnet in order to deploy smart contracts, you can get funds from the [Monad Faucet](https://testnet.monad.xyz).

## Working with Scaffold-ETH

Scaffold-ETH can have two different solidity development frameworks: Foundry and Hardhat.

In this guide you can choose between Foundry and Hardhat.

<Tabs>
  <Tab title="Foundry">
    ### Clone the scaffold-monad-foundry repo

    ```sh theme={null}
    git clone https://github.com/monad-developers/scaffold-monad-foundry.git
    ```

    ### Open the project directory and install dependencies

    ```sh theme={null}
    cd scaffold-monad-foundry && yarn install
    ```

    ### Start your local blockchain node

    ```sh theme={null}
    yarn chain
    ```

    ### Deploy your smart contract to your local blockchain node

    ```sh theme={null}
    yarn deploy
    ```

    This command deploys `YourContract.sol` to your local blockchain node. The contract is located in `packages/foundry/contracts` and can be modified to suit your needs.

    The `yarn deploy` command uses the deploy script located in `packages/foundry/deploy` to deploy the contract to the network. You can also customize the deploy script.

    ### Start your NextJS app

    ```sh theme={null}
    yarn start
    ```

    Visit your app on: `http://localhost:3000`.

    You can interact with your smart contract using the Debug Contracts page. You can tweak the app config in `packages/nextjs/scaffold.config.ts`.

    ### Deploy your smart contract to Monad Testnet

    ```sh theme={null}
    yarn deploy --network monadTestnet
    ```

    This command deploys `YourContract.sol` to Monad Testnet. The contract is located in `packages/foundry/contracts` and can be modified to suit your needs.

    ### Verify your smart contract on Monad Testnet

    ```sh theme={null}
    yarn verify --network monadTestnet
    ```

    This command verifies `YourContract.sol` on Monad Testnet.
  </Tab>

  <Tab title="Hardhat">
    ### Clone the scaffold-monad-hardhat repo

    ```sh theme={null}
    git clone https://github.com/monad-developers/scaffold-monad-hardhat.git
    ```

    ### Open the project directory and install dependencies

    ```sh theme={null}
    cd scaffold-monad-hardhat && yarn install
    ```

    ### Start your local blockchain node

    ```sh theme={null}
    yarn chain
    ```

    ### Deploy your smart contract to your local blockchain node

    ```sh theme={null}
    yarn deploy
    ```

    This command deploys `YourContract.sol` to your local blockchain node. The contract is located in `packages/hardhat/contracts` and can be modified to suit your needs.

    The `yarn deploy` command uses the deploy script located in `packages/hardhat/deploy` to deploy the contract to the network. You can also customize the deploy script.

    ### Start your NextJS app

    ```sh theme={null}
    yarn start
    ```

    Visit your app on: `http://localhost:3000`.

    You can interact with your smart contract using the Debug Contracts page. You can tweak the app config in `packages/nextjs/scaffold.config.ts`.

    ### Generate a deployer account

    ```sh theme={null}
    yarn generate
    ```

    This command will create a new deployer account. **Remember the password you create** as you'll need it for deployments.

    ### Deploy your smart contract to Monad Testnet

    ```sh theme={null}
    yarn deploy --network monadTestnet
    ```

    This command deploys `YourContract.sol` to Monad Testnet. The contract is located in `packages/hardhat/contracts` and can be modified to suit your needs.

    ### Verify your smart contract on Monad Testnet

    ```sh theme={null}
    yarn verify --network monadTestnet
    ```

    This command verifies `YourContract.sol` on Monad Testnet.
  </Tab>
</Tabs>

## Next steps

* Explore the Debug Contracts page to interact with your deployed contract.
* Modify `YourContract.sol` to build your own functionality.
* Learn more about [Scaffold-ETH](https://docs.scaffoldeth.io/).


# Verify a smart contract on Monad using Foundry
Source: https://docs.monad.xyz/guides/verify-smart-contract/foundry



Once your contract is deployed to a live network, the next step is to verify its source code on the block explorer.

Verifying a contract means uploading its source code, along with the settings used to compile the code, to a
repository (typically maintained by a block explorer). This allows anyone to compile it and compare the generated
bytecode with what is deployed on chain. Doing this is extremely important in an open platform like Monad.

In this guide we'll explain how to do this using [Monad Foundry](/tooling-and-infra/toolkits/monad-foundry).

<Tip>
  This guide assumes you have Monad Foundry installed. See the [installation instructions](/tooling-and-infra/toolkits/monad-foundry#installation) if you haven't set it up yet.
</Tip>

<Tabs>
  <Tab title="Mainnet">
    <Tabs>
      <Tab title="Foundry Monad template (Recommended)">
        <Note>
          The [`foundry-monad`](https://github.com/monad-developers/foundry-monad) template is configured for testnet by default. To use mainnet, update your `foundry.toml` file:

          * Change `eth-rpc-url="https://testnet-rpc.monad.xyz"` to your mainnet RPC URL
          * Change `chain_id = 10143` to `143`
        </Note>

        If you are using [`foundry-monad`](https://github.com/monad-developers/foundry-monad) template, you can use the commands below based on your preferred block explorer:

        <Tabs>
          <Tab title="MonadVision">
            ```sh theme={null}
            forge verify-contract \
                <contract_address> \
                <contract_name> \
                --chain 143 \
                --verifier sourcify \
                --verifier-url https://sourcify-api-monad.blockvision.org/
            ```

            **Example:**

            ```sh theme={null}
            forge verify-contract \
                0x8fEc29BdEd7A618ab6E3CD945456A79163995769 \
                Counter \
                --chain 143 \
                --verifier sourcify \
                --verifier-url https://sourcify-api-monad.blockvision.org/
            ```

            On successful verification of smart contract, you should get a similar output in your terminal:

            ```sh theme={null}
            Start verifying contract `0x8fEc29BdEd7A618ab6E3CD945456A79163995769` deployed on monad-mainnet
            Attempting to verify on Sourcify. Pass the --etherscan-api-key <API_KEY> to verify on Etherscan, or use the --verifier flag to verify on another provider.

            Submitting verification for [Counter] "0x8fEc29BdEd7A618ab6E3CD945456A79163995769".
            Contract successfully verified
            ```

            Now check the contract on MonadVision.
          </Tab>

          <Tab title="Monadscan">
            ```sh theme={null}
            forge verify-contract \
                <contract_address> \
                <contract_name> \
                --chain 143 \
                --verifier etherscan \
                --etherscan-api-key YourApiKeyToken \
                --watch
            ```

            **Example:**

            ```sh theme={null}
            forge verify-contract \
                0x8fEc29BdEd7A618ab6E3CD945456A79163995769 \
                Counter \
                --chain 143 \
                --verifier etherscan \
                --etherscan-api-key YourApiKeyToken \
                --watch
            ```

            On successful verification of smart contract, you should get a similar output in your terminal:

            ```sh theme={null}
            Start verifying contract `0x8fEc29BdEd7A618ab6E3CD945456A79163995769` deployed on monad-mainnet

            Submitting verification for [src/Counter.sol:Counter] 0x8fEc29BdEd7A618ab6E3CD945456A79163995769.
            Submitted contract for verification:
                    Response: `OK`
                    GUID: `fhxxx4wsub68jce24ejvhe68fqabgtpmpzheqpdqvencgph1za`
                    URL: https://monadscan.com/address/0x8fec29bded7a618ab6e3cd945456a79163995769
            Contract verification status:
            Response: `NOTOK`
            Details: `Pending in queue`
            Warning: Verification is still pending...; waiting 15 seconds before trying again (7 tries remaining)
            Contract verification status:
            Response: `OK`
            Details: `Pass - Verified`
            Contract successfully verified
            ```

            Now check the contract on Monadscan.
          </Tab>

          <Tab title="Socialscan">
            ```sh theme={null}
            forge verify-contract \
                <contract_address> \
                <contract_name> \
                --chain 143 \
                --watch \
                --etherscan-api-key <your_api_key> \
                --verifier-url https://api.socialscan.io/monad-mainnet/v1/explorer/command_api/contract \
                --verifier etherscan
            ```

            **Example:**

            ```sh theme={null}
            forge verify-contract \
                0x8fEc29BdEd7A618ab6E3CD945456A79163995769 \
                Counter \
                --chain 143 \
                --watch \
                --etherscan-api-key test \
                --verifier-url https://api.socialscan.io/monad-mainnet/v1/explorer/command_api/contract \
                --verifier etherscan
            ```

            On successful verification of smart contract, you should get a similar output in your terminal:

            ```sh theme={null}
            Start verifying contract `0x8fEc29BdEd7A618ab6E3CD945456A79163995769` deployed on monad-mainnet

            Submitting verification for [src/Counter.sol:Counter] 0x8fEc29BdEd7A618ab6E3CD945456A79163995769.
            Submitted contract for verification:
                    Response: `Contract successfully verified`
                    GUID: `33588004868f0677a3c23734da00fc42895a63542f61b1ed0dbfd2eb6893d7f4`
                    URL: https://monad.socialscan.io/address/0x8fec29bded7a618ab6e3cd945456a79163995769
            Contract verification status:
            Response: `OK`
            Details: `Pass - Verified`
            Contract successfully verified
            ```

            Now check the contract on Socialscan.
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Default Foundry Project">
        ## 1. Update `foundry.toml` with Monad Configuration

        ```toml lines title="foundry.toml" theme={null}
        [profile.default]
        src = "src"
        out = "out"
        libs = ["lib"]
        metadata = true
        metadata_hash = "none"  # disable ipfs
        use_literal_content = true # use source code

        # Monad Configuration
        eth-rpc-url="https://rpc.monad.xyz"
        chain_id = 143
        ```

        ## 2. Verify the contract using one of the following block explorers:

        <Tabs>
          <Tab title="MonadVision">
            <Note>
              If you are using MonadVision, you can use
              [this guide](https://docs.blockvision.org/reference/verify-smart-contract-on-monad-explorer#/).
              In particular, the [Verify Contract](https://monadvision.com/verify-contract)
              page provides a convenient way to verify your contract.
            </Note>

            ```sh theme={null}
            forge verify-contract \
                <contract_address> \
                <contract_name> \
                --chain 143 \
                --verifier sourcify \
                --verifier-url https://sourcify-api-monad.blockvision.org/
            ```

            **Example:**

            ```sh theme={null}
            forge verify-contract \
                0x8fEc29BdEd7A618ab6E3CD945456A79163995769 \
                Counter \
                --chain 143 \
                --verifier sourcify \
                --verifier-url https://sourcify-api-monad.blockvision.org/
            ```

            On successful verification of smart contract, you should get a similar output in your terminal:

            ```sh theme={null}
            Start verifying contract `0x8fEc29BdEd7A618ab6E3CD945456A79163995769` deployed on monad-mainnet
            Attempting to verify on Sourcify. Pass the --etherscan-api-key <API_KEY> to verify on Etherscan, or use the --verifier flag to verify on another provider.

            Submitting verification for [Counter] "0x8fEc29BdEd7A618ab6E3CD945456A79163995769".
            Contract successfully verified
            ```

            Now check the contract on MonadVision.
          </Tab>

          <Tab title="Monadscan">
            ```sh theme={null}
            forge verify-contract \
                <contract_address> \
                <contract_name> \
                --chain 143 \
                --verifier etherscan \
                --etherscan-api-key YourApiKeyToken \
                --watch
            ```

            **Example:**

            ```sh theme={null}
            forge verify-contract \
                0x8fEc29BdEd7A618ab6E3CD945456A79163995769 \
                Counter \
                --chain 143 \
                --verifier etherscan \
                --etherscan-api-key YourApiKeyToken \
                --watch
            ```

            On successful verification of smart contract, you should get a similar output in your terminal:

            ```sh theme={null}
            Start verifying contract `0x8fEc29BdEd7A618ab6E3CD945456A79163995769` deployed on monad-mainnet

            Submitting verification for [src/Counter.sol:Counter] 0x8fEc29BdEd7A618ab6E3CD945456A79163995769.
            Submitted contract for verification:
                    Response: `OK`
                    GUID: `fhxxx4wsub68jce24ejvhe68fqabgtpmpzheqpdqvencgph1za`
                    URL: https://monadscan.com/address/0x8fec29bded7a618ab6e3cd945456a79163995769
            Contract verification status:
            Response: `NOTOK`
            Details: `Pending in queue`
            Warning: Verification is still pending...; waiting 15 seconds before trying again (7 tries remaining)
            Contract verification status:
            Response: `OK`
            Details: `Pass - Verified`
            Contract successfully verified
            ```

            Now check the contract on Monadscan.
          </Tab>

          <Tab title="Socialscan">
            ```sh theme={null}
            forge verify-contract \
                <contract_address> \
                <contract_name> \
                --chain 143 \
                --watch \
                --etherscan-api-key <your_api_key> \
                --verifier-url https://api.socialscan.io/monad-mainnet/v1/explorer/command_api/contract \
                --verifier etherscan
            ```

            **Example:**

            ```sh theme={null}
            forge verify-contract \
                0x8fEc29BdEd7A618ab6E3CD945456A79163995769 \
                Counter \
                --chain 143 \
                --watch \
                --etherscan-api-key test \
                --verifier-url https://api.socialscan.io/monad-mainnet/v1/explorer/command_api/contract \
                --verifier etherscan
            ```

            On successful verification of smart contract, you should get a similar output in your terminal:

            ```sh theme={null}
            Start verifying contract `0x8fEc29BdEd7A618ab6E3CD945456A79163995769` deployed on monad-mainnet

            Submitting verification for [src/Counter.sol:Counter] 0x8fEc29BdEd7A618ab6E3CD945456A79163995769.
            Submitted contract for verification:
                    Response: `Contract successfully verified`
                    GUID: `33588004868f0677a3c23734da00fc42895a63542f61b1ed0dbfd2eb6893d7f4`
                    URL: https://monad.socialscan.io/address/0x8fec29bded7a618ab6e3cd945456a79163995769
            Contract verification status:
            Response: `OK`
            Details: `Pass - Verified`
            Contract successfully verified
            ```

            Now check the contract on Socialscan.
          </Tab>
        </Tabs>
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Testnet">
    <Tabs>
      <Tab title="Foundry Monad template (Recommended)">
        If you are using [`foundry-monad`](https://github.com/monad-developers/foundry-monad) template, you can use the commands below based on your preferred block explorer:

        <Tabs>
          <Tab title="MonadVision">
            ```sh theme={null}
            forge verify-contract \
                <contract_address> \
                <contract_name> \
                --chain 10143 \
                --verifier sourcify \
                --verifier-url https://sourcify-api-monad.blockvision.org/
            ```

            **Example:**

            ```sh theme={null}
            forge verify-contract \
                0x8fEc29BdEd7A618ab6E3CD945456A79163995769 \
                Counter \
                --chain 10143 \
                --verifier sourcify \
                --verifier-url https://sourcify-api-monad.blockvision.org/
            ```

            On successful verification of smart contract, you should get a similar output in your terminal:

            ```sh theme={null}
            Start verifying contract `0x8fEc29BdEd7A618ab6E3CD945456A79163995769` deployed on monad-testnet
            Attempting to verify on Sourcify. Pass the --etherscan-api-key <API_KEY> to verify on Etherscan, or use the --verifier flag to verify on another provider.

            Submitting verification for [Counter] "0x8fEc29BdEd7A618ab6E3CD945456A79163995769".
            Contract successfully verified
            ```

            Now check the contract on [MonadVision](https://testnet.monadvision.com/).
          </Tab>

          <Tab title="Monadscan">
            ```sh theme={null}
            forge verify-contract \
                <contract_address> \
                <contract_name> \
                --chain 10143 \
                --verifier etherscan \
                --etherscan-api-key YourApiKeyToken \
                --watch
            ```

            **Example:**

            ```sh theme={null}
            forge verify-contract \
                0x8fEc29BdEd7A618ab6E3CD945456A79163995769 \
                Counter \
                --chain 10143 \
                --verifier etherscan \
                --etherscan-api-key YourApiKeyToken \
                --watch
            ```

            On successful verification of smart contract, you should get a similar output in your terminal:

            ```sh theme={null}
            Start verifying contract `0x8fEc29BdEd7A618ab6E3CD945456A79163995769` deployed on monad-testnet

            Submitting verification for [src/Counter.sol:Counter] 0x8fEc29BdEd7A618ab6E3CD945456A79163995769.
            Submitted contract for verification:
                    Response: `OK`
                    GUID: `fhxxx4wsub68jce24ejvhe68fqabgtpmpzheqpdqvencgph1za`
                    URL: https://testnet.monadscan.com/address/0x8fec29bded7a618ab6e3cd945456a79163995769
            Contract verification status:
            Response: `NOTOK`
            Details: `Pending in queue`
            Warning: Verification is still pending...; waiting 15 seconds before trying again (7 tries remaining)
            Contract verification status:
            Response: `OK`
            Details: `Pass - Verified`
            Contract successfully verified
            ```

            Now check the contract on [Monadscan](https://testnet.monadscan.com/).
          </Tab>

          <Tab title="Socialscan">
            ```sh theme={null}
            forge verify-contract \
                <contract_address> \
                <contract_name> \
                --chain 10143 \
                --watch \
                --etherscan-api-key <your_api_key> \
                --verifier-url https://api.socialscan.io/monad-testnet/v1/explorer/command_api/contract \
                --verifier etherscan
            ```

            **Example:**

            ```sh theme={null}
            forge verify-contract \
                0x8fEc29BdEd7A618ab6E3CD945456A79163995769 \
                Counter \
                --chain 10143 \
                --watch \
                --etherscan-api-key test \
                --verifier-url https://api.socialscan.io/monad-testnet/v1/explorer/command_api/contract \
                --verifier etherscan
            ```

            On successful verification of smart contract, you should get a similar output in your terminal:

            ```sh theme={null}
            Start verifying contract `0x8fEc29BdEd7A618ab6E3CD945456A79163995769` deployed on monad-testnet

            Submitting verification for [src/Counter.sol:Counter] 0x8fEc29BdEd7A618ab6E3CD945456A79163995769.
            Submitted contract for verification:
                    Response: `Contract successfully verified`
                    GUID: `33588004868f0677a3c23734da00fc42895a63542f61b1ed0dbfd2eb6893d7f4`
                    URL: https://api.socialscan.io/monad-testnet/v1/explorer/command_api/address/0x8fec29bded7a618ab6e3cd945456a79163995769
            Contract verification status:
            Response: `OK`
            Details: `Pass - Verified`
            Contract successfully verified
            ```

            Now check the contract on [Socialscan](https://testnet.socialscan.io/).
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Default Foundry Project">
        <Tip>
          If you use [`foundry-monad`](https://github.com/monad-developers/foundry-monad) you can skip the configuration step
        </Tip>

        ## 1. Update `foundry.toml` with Monad Configuration

        ```toml lines title="foundry.toml" theme={null}
        [profile.default]
        src = "src"
        out = "out"
        libs = ["lib"]  
        metadata = true
        metadata_hash = "none"  # disable ipfs
        use_literal_content = true # use source code

        # Monad Configuration
        eth-rpc-url="https://testnet-rpc.monad.xyz"
        chain_id = 10143
        ```

        ## 2. Verify the contract using one of the following block explorers:

        <Tabs>
          <Tab title="MonadVision">
            ```sh theme={null}
            forge verify-contract \
                <contract_address> \
                <contract_name> \
                --chain 10143 \
                --verifier sourcify \
                --verifier-url https://sourcify-api-monad.blockvision.org/
            ```

            **Example:**

            ```sh theme={null}
            forge verify-contract \
                0x8fEc29BdEd7A618ab6E3CD945456A79163995769 \
                Counter \
                --chain 10143 \
                --verifier sourcify \
                --verifier-url https://sourcify-api-monad.blockvision.org/
            ```

            On successful verification of smart contract, you should get a similar output in your terminal:

            ```sh theme={null}
            Start verifying contract `0x8fEc29BdEd7A618ab6E3CD945456A79163995769` deployed on monad-testnet
            Attempting to verify on Sourcify. Pass the --etherscan-api-key <API_KEY> to verify on Etherscan, or use the --verifier flag to verify on another provider.

            Submitting verification for [Counter] "0x8fEc29BdEd7A618ab6E3CD945456A79163995769".
            Contract successfully verified
            ```

            Now check the contract on [MonadVision](https://testnet.monadvision.com/).
          </Tab>

          <Tab title="Monadscan">
            ```sh theme={null}
            forge verify-contract \
                <contract_address> \
                <contract_name> \
                --chain 10143 \
                --verifier etherscan \
                --etherscan-api-key YourApiKeyToken \
                --watch
            ```

            **Example:**

            ```sh theme={null}
            forge verify-contract \
                0x8fEc29BdEd7A618ab6E3CD945456A79163995769 \
                Counter \
                --chain 10143 \
                --verifier etherscan \
                --etherscan-api-key YourApiKeyToken \
                --watch
            ```

            On successful verification of smart contract, you should get a similar output in your terminal:

            ```sh theme={null}
            Start verifying contract `0x8fEc29BdEd7A618ab6E3CD945456A79163995769` deployed on monad-testnet

            Submitting verification for [src/Counter.sol:Counter] 0x8fEc29BdEd7A618ab6E3CD945456A79163995769.
            Submitted contract for verification:
                    Response: `OK`
                    GUID: `fhxxx4wsub68jce24ejvhe68fqabgtpmpzheqpdqvencgph1za`
                    URL: https://testnet.monadvision.com/address/0x8fec29bded7a618ab6e3cd945456a79163995769
            Contract verification status:
            Response: `NOTOK`
            Details: `Pending in queue`
            Warning: Verification is still pending...; waiting 15 seconds before trying again (7 tries remaining)
            Contract verification status:
            Response: `OK`
            Details: `Pass - Verified`
            Contract successfully verified
            ```

            Now check the contract on [Monadscan](https://testnet.monadscan.com/).
          </Tab>

          <Tab title="Socialscan">
            ```sh theme={null}
            forge verify-contract \
                <contract_address> \
                <contract_name> \
                --chain 10143 \
                --watch \
                --etherscan-api-key <your_api_key> \
                --verifier-url https://api.socialscan.io/monad-testnet/v1/explorer/command_api/contract \
                --verifier etherscan
            ```

            **Example:**

            ```sh theme={null}
            forge verify-contract \
                0x8fEc29BdEd7A618ab6E3CD945456A79163995769 \
                Counter \
                --chain 10143 \
                --watch \
                --etherscan-api-key test \
                --verifier-url https://api.socialscan.io/monad-testnet/v1/explorer/command_api/contract \
                --verifier etherscan
            ```

            On successful verification of smart contract, you should get a similar output in your terminal:

            ```sh theme={null}
            Start verifying contract `0x8fEc29BdEd7A618ab6E3CD945456A79163995769` deployed on monad-testnet

            Submitting verification for [src/Counter.sol:Counter] 0x8fEc29BdEd7A618ab6E3CD945456A79163995769.
            Submitted contract for verification:
                    Response: `Contract successfully verified`
                    GUID: `33588004868f0677a3c23734da00fc42895a63542f61b1ed0dbfd2eb6893d7f4`
                    URL: https://testnet.monadvision.com/address/0x8fec29bded7a618ab6e3cd945456a79163995769
            Contract verification status:
            Response: `OK`
            Details: `Pass - Verified`
            Contract successfully verified
            ```

            Now check the contract on [Socialscan](https://testnet.socialscan.io/).
          </Tab>
        </Tabs>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>


# Verify a smart contract on Monad using Hardhat
Source: https://docs.monad.xyz/guides/verify-smart-contract/hardhat



Once your contract is deployed to a live network, the next step is to verify its source code on the block explorer.

Verifying a contract means uploading its source code, along with the settings used to compile the code, to a
repository (typically maintained by a block explorer). This allows anyone to compile it and compare the generated
bytecode with what is deployed on chain. Doing this is extremely important in an open platform like Monad.

In this guide we'll explain how to do this using [Hardhat](https://hardhat.org/).

<Tip>
  The verification command may show an error message, but this is often misleading - the contract is usually verified successfully on both Sourcify and MonadScan. Check the explorer links to confirm verification.
</Tip>

<Tabs>
  <Tab title="Hardhat 2">
    ## Hardhat 2 Verification

    The `hardhat-monad` template is pre-configured to verify contracts on both MonadVision (Sourcify) and Monadscan (Etherscan) simultaneously.

    If you're using the template, your `hardhat.config.ts` should already have:

    ```ts theme={null}
    import type { HardhatUserConfig } from "hardhat/config";
    import "@nomicfoundation/hardhat-toolbox-viem";
    import "@nomicfoundation/hardhat-ignition-viem";
    import "dotenv/config";

    const PRIVATE_KEY = process.env.PRIVATE_KEY || "";
    const ETHERSCAN_API_KEY = process.env.ETHERSCAN_API_KEY || "";

    const config: HardhatUserConfig = {
      solidity: {
        version: "0.8.28",
        settings: {
          metadata: {
            bytecodeHash: "ipfs", // Required for Sourcify verification
          },
        },
      },
      networks: {
        monadTestnet: {
          url: "https://testnet-rpc.monad.xyz",
          accounts: [PRIVATE_KEY],
          chainId: 10143,
        },
        monadMainnet: {
          url: "https://rpc.monad.xyz",
          accounts: [PRIVATE_KEY],
          chainId: 143,
        },
      },
      sourcify: {
        enabled: true,
        apiUrl: "https://sourcify-api-monad.blockvision.org",
        browserUrl: "https://monadvision.com",
      },
      etherscan: {
        enabled: true,
        apiKey: {
          monadMainnet: ETHERSCAN_API_KEY,
          monadTestnet: ETHERSCAN_API_KEY,
        },
        customChains: [
          {
            network: "monadMainnet",
            chainId: 143,
            urls: {
              apiURL: "https://api.etherscan.io/v2/api?chainid=143",
              browserURL: "https://monadscan.com",
            },
          },
          {
            network: "monadTestnet",
            chainId: 10143,
            urls: {
              apiURL: "https://api.etherscan.io/v2/api?chainid=10143",
              browserURL: "https://testnet.monadscan.com",
            },
          },
        ],
      },
    };

    export default config;
    ```

    **Verify on Mainnet:**

    ```sh theme={null}
    npx hardhat verify <contract_address> --network monadMainnet
    ```

    **Verify on Testnet:**

    ```sh theme={null}
    npx hardhat verify <contract_address> --network monadTestnet
    ```

    This will verify your contract on both MonadVision and Monadscan. Once verified, you can view your contract on the respective explorers.
  </Tab>

  <Tab title="Hardhat 3">
    ## Hardhat 3 Verification

    <Tip>
      The verification command may show an error message, but this is often misleading - the contract is usually verified successfully on both Sourcify and MonadScan. Check the explorer links to confirm verification.
    </Tip>

    The `hardhat3-monad` template is pre-configured to verify contracts on both MonadVision (Sourcify) and Monadscan (Etherscan). Hardhat 3 uses a different configuration structure with the `verify` key and `chainDescriptors`.

    If you're using the template, your `hardhat.config.ts` should already have:

    ```ts theme={null}
    import hardhatToolboxViemPlugin from "@nomicfoundation/hardhat-toolbox-viem";
    import { defineConfig } from "hardhat/config";
    import "dotenv/config";

    const PRIVATE_KEY = process.env.PRIVATE_KEY || "";
    const ETHERSCAN_API_KEY = process.env.ETHERSCAN_API_KEY || "";

    export default defineConfig({
      plugins: [hardhatToolboxViemPlugin],
      solidity: {
        version: "0.8.28",
        settings: {
          optimizer: {
            enabled: true,
            runs: 200,
          },
        },
      },
      networks: {
        hardhat: {
          type: "edr-simulated",
        },
        monadTestnet: {
          type: "http",
          url: "https://testnet-rpc.monad.xyz",
          accounts: [PRIVATE_KEY],
          chainId: 10143,
        },
        monadMainnet: {
          type: "http",
          url: "https://rpc.monad.xyz",
          accounts: [PRIVATE_KEY],
          chainId: 143,
        },
      },
      verify: {
        blockscout: {
          enabled: false,
        },
        etherscan: {
          enabled: true,
          apiKey: ETHERSCAN_API_KEY,
        },
        sourcify: {
          enabled: true,
          apiUrl: "https://sourcify-api-monad.blockvision.org",
        },
      },
      chainDescriptors: {
        143: {
          name: "MonadMainnet",
          blockExplorers: {
            etherscan: {
              name: "Monadscan",
              url: "https://monadscan.com",
              apiUrl: "https://api.etherscan.io/v2/api",
            },
          },
        },
      },
    });
    ```

    **Verify on Mainnet:**

    ```sh theme={null}
    npx hardhat verify <contract_address> --network monadMainnet
    ```

    **Verify on Testnet:**

    ```sh theme={null}
    npx hardhat verify <contract_address> --network monadTestnet
    ```

    This will verify your contract on both MonadVision and Monadscan. Once verified, you can view your contract on the respective explorers.
  </Tab>
</Tabs>


# Verify a Contract
Source: https://docs.monad.xyz/guides/verify-smart-contract/index



<CardGroup>
  <Card title="Foundry" href="/guides/verify-smart-contract/foundry">
    Verify a smart contract on Monad using Foundry
  </Card>

  <Card title="Hardhat" href="/guides/verify-smart-contract/hardhat">
    Verify a smart contract on Monad using Hardhat
  </Card>
</CardGroup>


# How to set up an x402-enabled endpoint with Monad support
Source: https://docs.monad.xyz/guides/x402



This guide shows how to set up payable endpoints using x402 payments and Monad's facilitator. It works on Monad testnet/mainnet.

## What is x402?

x402 is the HTTP 402 "Payment Required" status code reborn as a minimal protocol for internet‑native micropayments.

Instead of subscriptions or paywalls that require accounts, x402 lets any HTTP endpoint become instantly payable:

1. Client requests a resource
2. Server responds 402 with a small JSON payment requirement
3. Client signs a payment authorization and resends the request
4. Server verifies and serves the content

### Beyond legacy limitations

x402 is designed for a modern internet economy, solving key limitations of legacy systems:

* **Reduce fees and friction:** Direct onchain payments without intermediaries, high fees, or manual setup.
* **Micropayments & usage-based billing:** Charge per call or feature with simple, programmable pay-as-you-go flows.
* **Machine-to-machine transactions:** Let AI agents pay and access services autonomously with no keys or human input needed.

## Why x402 on Monad?

Monad is a fully EVM‑compatible Layer 1 with:

* 10,000 TPS
* \~0.4s block times
* Single‑slot finality
* Parallel execution
* Extremely low fees

These properties make Monad an ideal environment for **true micropayments and agent-to-agent commerce**. Payments **settle instantly at low cost and avoid mempool congestion**, perfect when many AI agents pay per API call.

### Core Flow (Direct Payment)

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Server
    participant Monad Chain

    Client->>Server: GET /premium-content
    Server-->>Client: 402 Payment Required + requirements JSON
    Note over Client: Sign authorization<br/>(local, no tx)
    Client->>Server: GET /premium-content<br/>(PAYMENT-SIGNATURE header)
    Server->>Monad Chain: transferWithAuthorization()
    Monad Chain-->>Server: tx confirmed
    Server-->>Client: 200 OK + content
```

### Facilitator Flow (Recommended for Production)

A facilitator service is optional but recommended in production. Facilitators can batch transactions, cover gas, handle refunds, and simplify client logic.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Server
    participant Facilitator
    participant Monad Chain

    Note over Facilitator: Facilitator is optional but solves gas,<br/>refunds, batching, and replay protection

    Client->>Server: GET /premium-content
    Server-->>Client: 402 + requirements
    Note over Client: Sign authorization<br/>(local, no tx)
    Client->>Server: GET /premium-content<br/>(PAYMENT-SIGNATURE header)
    Server->>Facilitator: POST /verify
    Facilitator-->>Server: { isValid: true }
    Server-->>Client: 200 + resource
    Server->>Facilitator: POST /settle
    Facilitator->>Monad Chain: transferWithAuthorization()
    Monad Chain-->>Facilitator: tx confirmed
    Facilitator-->>Server: { success, txHash }
```

## Building an x402-based app using Monad x402 facilitator

### Prerequisites

* Node.js 18+
* An EVM wallet
* Access to Monad testnet funds (USDC test tokens below)

<Note>
  Monad Facilitator only supports x402 version 2 and above.

  Migration guide that explains the differences: [https://docs.x402.org/guides/migration-v1-to-v2](https://docs.x402.org/guides/migration-v1-to-v2)
</Note>

<Accordion title="How to get USDC tokens on Monad testnet">
  You can get USDC tokens for Monad testnet using Circle's faucet:

  1. Visit [https://faucet.circle.com](https://faucet.circle.com)
  2. Select **USDC** as the token
  3. Select **Monad Testnet** from the Network dropdown
  4. Enter your wallet address
  5. Click **Send 1 USDC**

  **Limit:** One request per (stablecoin, testnet) pair every 2 hours

  <img alt="circle_faucet" />

  You'll also need testnet MON tokens for gas fees. Get them from the [Monad faucet](https://faucet.monad.xyz).
</Accordion>

### Step 1: Initialize a Next.js App

Create a new Next.js project:

```bash theme={null}
npx create-next-app@latest my-x402-app
```

When prompted, select the following options:

* ✅ TypeScript
* ✅ ESLint
* ✅ Tailwind CSS
* ✅ `src/` directory
* ✅ App Router
* ✅ Customize default import alias: `@/*` (default)

Navigate to your project:

```bash theme={null}
cd my-x402-app
```

Install the x402 packages:

<Note>
  Install x402 packages with version `2.2.0` and above.
</Note>

```bash theme={null}
npm install @x402/core @x402/evm @x402/fetch @x402/next
```

Create a `.env.local` file for your environment variables:

```bash theme={null}
touch .env.local
```

### Step 2: Create a `payTo` address

A `payTo` address is used to receive payments and interact with the blockchain from your backend.

Copy the wallet address and add it to your `.env.local` file as `PAY_TO_ADDRESS`

```
PAY_TO_ADDRESS=0xYourWallet
```

### Step 3: Create a server side payable endpoint

```ts lines title="src/app/api/premium/route.ts" theme={null}
import { NextResponse } from "next/server";
import { withX402, type RouteConfig } from "@x402/next";
import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import type { Network } from "@x402/core/types";

// Monad Testnet configuration
const MONAD_NETWORK: Network = "eip155:10143";
const MONAD_USDC_TESTNET = "0x534b2f3A21130d7a60830c2Df862319e593943A3";

// Monad Facilitator URL
const FACILITATOR_URL = "https://x402-facilitator.molandak.org"; 

if (!process.env.PAY_TO_ADDRESS) {
  throw new Error("PAY_TO_ADDRESS environment variable is required");
}
const PAY_TO = process.env.PAY_TO_ADDRESS;

// Create facilitator client for Monad
const facilitatorClient = new HTTPFacilitatorClient({ url: FACILITATOR_URL });

// Create and configure x402 resource server
const server = new x402ResourceServer(facilitatorClient);

// Create Exact EVM Scheme with custom money parser for Monad USDC
const monadScheme = new ExactEvmScheme();
monadScheme.registerMoneyParser(async (amount: number, network: string) => {
  if (network === MONAD_NETWORK) {
    // Convert decimal amount to USDC smallest units (6 decimals)
    const tokenAmount = Math.floor(amount * 1_000_000).toString();
    return {
      amount: tokenAmount,
      asset: MONAD_USDC_TESTNET, // Raw address for EIP-712 verifyingContract
      extra: {
        name: "USDC",
        version: "2",
      },
    };
  }
  return null; // Use default parser for other networks
});

// Register Monad network with custom scheme
server.register(MONAD_NETWORK, monadScheme);

// Route configuration
const routeConfig: RouteConfig = {
  accepts: {
    scheme: "exact",
    network: MONAD_NETWORK,
    payTo: PAY_TO,
    price: "$0.001",
  },
  resource: "http://localhost:3000/api/premium", // Use relative path to avoid host mismatch
};

// Handler that returns full article content
async function handler(request: NextRequest) {
  return NextResponse.json({
    content: "Return premium content",
    unlockedAt: new Date().toISOString(),
  });
}

// Export GET method wrapped with x402 payment protection
export const GET = withX402(handler, routeConfig, server);
```

### Step 4: Client-side setup (consuming paid endpoint)

Below is an example of consuming the paid endpoint using a Next.js app, however the endpoint can be consumed via an agent script as well.

```tsx lines title="src/app/page.tsx" theme={null}
"use client";

import { useState, useCallback, useEffect } from "react";
import { useAccount, useWalletClient } from "wagmi";
import { wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { x402Client } from "@x402/core/client";

// x402 configuration
const x402Config = {
  chainId: "eip155:10143" as const,
  usdcAddress: "0x534b2f3A21130d7a60830c2Df862319e593943A3", // MONAD USDC TESTNET
  facilitator: "https://x402-facilitator.molandak.org", // MONAD FACILITATOR URL
  price: "0.001", // USDC
};

export default function Home() {
  const { isConnected, address } = useAccount();
  const { data: walletClient } = useWalletClient();
  const [message, setMessage] = useState("Pay $0.001 USDC to unlock premium content");
  const [status, setStatus] = useState<"idle" | "loading" | "success" | "error">("idle");

  // This function allows signing a message, and pay USDC gaslessly. 
  const handleUnlock = useCallback(async () => {
    if (!walletClient || !address) {
      setError("Please connect your wallet first");
      return;
    }

    setIsLoading(true);
    setError(null);

    try {
      // Create EVM signer compatible with x402 ClientEvmSigner interface
      const evmSigner = {
        address: address as `0x${string}`,
        signTypedData: async (message: {
          domain: Record<string, unknown>;
          types: Record<string, unknown>;
          primaryType: string;
          message: Record<string, unknown>;
        }) => {
          return walletClient.signTypedData({
            domain: message.domain as Parameters<typeof walletClient.signTypedData>[0]["domain"],
            types: message.types as Parameters<typeof walletClient.signTypedData>[0]["types"],
            primaryType: message.primaryType,
            message: message.message,
          });
        },
      };

      // Create the Exact EVM scheme for signing
      const exactScheme = new ExactEvmScheme(evmSigner);

      // Create x402 client and register the scheme
      const client = new x402Client()
        .register(x402Config.chainId, exactScheme);

      console.log("x402 client configured for network:", x402Config.chainId);

      // Wrap fetch with x402 payment capability
      const paymentFetch = wrapFetchWithPayment(fetch, client);

      console.log("Making payment request to /api/article...");

      // Make request to protected endpoint
      const response = await paymentFetch("/api/premium", {
        method: "GET",
        headers: {
          "Content-Type": "application/json",
        },
      });

      if (!response.ok) {
        // Try to parse x402 payment-required header for detailed error
        const paymentHeader = response.headers.get("payment-required");

        if (paymentHeader && response.status === 402) {
          try {
            const paymentData = JSON.parse(atob(paymentHeader));
            console.error("Payment error details:", paymentData);

            // Extract user-friendly error message
            if (paymentData.error?.includes("insufficient_funds")) {
              throw new Error("INSUFFICIENT_FUNDS");
            }
            if (paymentData.error?.includes("unexpected_error")) {
              throw new Error("UNEXPECTED_ERROR");
            }
            if (paymentData.error) {
              throw new Error(paymentData.error);
            }
          } catch (e) {
            if (e instanceof Error && e.message === "INSUFFICIENT_FUNDS") {
              throw e;
            }
            // Failed to parse header, continue to generic error
          }
        }

        const errorText = await response.text().catch(() => "");
        let errorData: Record<string, unknown> = {};
        try {
          errorData = JSON.parse(errorText);
        } catch {
          // Not JSON
        }
        throw new Error(
          errorData.error as string ||
          errorData.details as string ||
          `Request failed: ${response.status}`
        );
      }

      const data = await response.json();

      // Cache the unlocked content in LocalStorage
      localStorage.setItem(
        "premimum_content_unlocked",
        JSON.stringify({
          content: data.content,
          timestamp: Date.now(),
        })
      );
    } catch (err) {
      console.error("Unlock error:", err);
      const message = err instanceof Error ? err.message : "Failed to unlock article";

      // Map technical errors to user-friendly messages
      if (
        message.includes("User rejected") ||
        message.includes("User denied") ||
        message.includes("user rejected")
      ) {
        setError("CANCELLED");
      } else if (message === "INSUFFICIENT_FUNDS" || message.includes("insufficient_funds")) {
        setError("INSUFFICIENT_FUNDS");
      } else if (message === "UNEXPECTED_ERROR" || message.includes("unexpected_error")) {
        setError("UNEXPECTED_ERROR");
      } else {
        setError(message);
      }
    } finally {
      setIsLoading(false);
    }
  }, [walletClient, address]);

  return (
    <main className="min-h-screen bg-zinc-950 flex items-center justify-center p-6">
      <div className="max-w-md w-full space-y-6">
        <div className="text-center space-y-2">
          <h1 className="text-2xl font-bold text-white">x402 on Monad</h1>
          <p className="text-zinc-400 text-sm">
            Micropayments via Thirdweb facilitator.{" "}
            <a href="https://docs.monad.xyz/guides/x402-guide" className="text-violet-400 hover:underline">
              Docs
            </a>
          </p>
        </div>

        <button
          onClick={handleUnlock}
          disabled={status === "loading"}
          className="w-full py-3 px-4 bg-violet-600 hover:bg-violet-500 disabled:bg-violet-800 disabled:cursor-wait text-white font-medium rounded-lg transition-colors"
        >
          {status === "loading" ? "Processing..." : "Pay & Unlock Content"}
        </button>

        <div className={`p-4 rounded-lg text-sm ${
          status === "error" ? "bg-red-950 text-red-300" :
          status === "success" ? "bg-green-950 text-green-300" :
          "bg-zinc-900 text-zinc-300"
        }`}>
          {message}
        </div>
      </div>
    </main>
  );
}
```

## Running Your x402 App

Now you're ready to test your x402 payment flow:

1. Start your development server:

   ```bash theme={null}
   npm run dev
   ```

2. Open [http://localhost:3000](http://localhost:3000) in your browser

3. Click "Pay & Unlock Content"

4. Connect your wallet

5. Approve the USDC payment

6. See the content unlock instantly!

## Facilitator API

For developers who are interested in using the barebones Facilitator API, here are the supported endpoints with examples.

Facilitator URL: `https://x402-facilitator.molandak.org`
Network support: Mainnet and Testnet.

### GET `/supported`

Returns supported networks, schemes, and signer addresses.

```ts theme={null}
const FACILITATOR_URL = "https://x402-facilitator.molandak.org";

async function testSupported(): Promise<void> {
  console.log("\n--- GET /supported ---");

  const response = await fetch(`${FACILITATOR_URL}/supported`);
  if (!response.ok) throw new Error(`Failed: ${response.status}`);

  const data = await response.json();
  console.log(JSON.stringify(data, null, 2));
  return data;
}
```

### POST `/verify`

Verify a payment signature.

```ts theme={null}
interface NetworkConfig {
  chainId: Network;
  name: string;
  rpcUrl: string;
  explorerUrl: string;
  usdcAddress: `0x${string}`;
  usdcDecimals: number;
  chainIdNumber: number;
}

/**
 * This function manually constructs and signs the EIP-712 typed data that
 * the x402 client library handles automatically.
 */
async function testVerify(
  account: ReturnType<typeof privateKeyToAccount>,
  networkConfig: NetworkConfig
): Promise<{ isValid: boolean; payload: any }> {
  console.log("\n--- POST /verify ---");
  const now = Math.floor(Date.now() / 1000);
  const nonce = keccak256(toHex(Math.random().toString()));
  const ACCOUNT_ADDRESS = "0x0000000000000000000000000000000000000000";

  // TransferWithAuthorization parameters (ERC-3009)
  const authorization = {
    from: ACCOUNT_ADDRESS, // Account that is paying
    to: PAY_TO_ADDRESS, // Receiver address
    value: "1000", // 0.001 USDC (6 decimals)
    validAfter: (now - 60).toString(), // Start validity 60s in the past to handle clock skew
    validBefore: (now + 900).toString(), // 15 minutes
    nonce,
  };

  // EIP-712 domain - must match USDC contract's DOMAIN_SEPARATOR
  const domain = {
    name: "USDC",  // Monad USDC uses "USDC" (not "USD Coin")
    version: "2",
    chainId: BigInt(networkConfig.chainIdNumber),
    verifyingContract: networkConfig.usdcAddress,
  };

  // EIP-712 type definition for TransferWithAuthorization
  const types = {
    TransferWithAuthorization: [
      { name: "from", type: "address" },
      { name: "to", type: "address" },
      { name: "value", type: "uint256" },
      { name: "validAfter", type: "uint256" },
      { name: "validBefore", type: "uint256" },
      { name: "nonce", type: "bytes32" },
    ],
  };

  const message = {
    from: authorization.from,
    to: authorization.to,
    value: BigInt(authorization.value),
    validAfter: BigInt(authorization.validAfter),
    validBefore: BigInt(authorization.validBefore),
    nonce: authorization.nonce as `0x${string}`,
  };

  const signature = await account.signTypedData({
    domain,
    types,
    primaryType: "TransferWithAuthorization",
    message,
  });

  const requestBody = {
    x402Version: 2,
    payload: {
      authorization,
      signature,
    },
    resource: {
      url: "http://test/resource",
      description: "Test resource",
      mimeType: "application/json",
    },
    accepted: {
      scheme: "exact",
      network: networkConfig.chainId,
      amount: authorization.value,
      asset: networkConfig.usdcAddress,
      payTo: authorization.to,
      maxTimeoutSeconds: 300,
      extra: {
        name: "USDC",
        version: "2",
      },
    },
  };

  const response = await fetch(`${FACILITATOR_URL}/verify`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(requestBody),
  });

  const data = await response.json();
  console.log(JSON.stringify(data, null, 2));

  return { isValid: data.isValid, payload: requestBody };
}
```

### POST `/settle`

Execute the payment on-chain. Facilitator pays gas.

```ts theme={null}
interface NetworkConfig {
  chainId: Network;
  name: string;
  rpcUrl: string;
  explorerUrl: string;
  usdcAddress: `0x${string}`;
  usdcDecimals: number;
  chainIdNumber: number;
}

/** POST /settle - Execute the payment on-chain. Facilitator pays gas. */
async function testSettle(
  payload: any,
  networkConfig: NetworkConfig
): Promise<void> {
  console.log("\n--- POST /settle ---");

  const response = await fetch(`${FACILITATOR_URL}/settle`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });

  const data = await response.json();
  console.log(JSON.stringify(data, null, 2));

  if (data.success && data.transaction) {
    // Transaction success
  } else if (data.errorReason) {
    console.log(`Failed: ${data.errorReason}`);
  }
}
```

## What's Next?

You've successfully built an x402 payment-enabled app on Monad! Here are some ideas to extend your implementation:

* **Add more payable endpoints** - Create different pricing tiers for various content or API calls
* **Build AI agent integrations** - Enable autonomous agents to pay for and access your APIs

## Resources

* [x402 Protocol Specification](https://www.x402.org/)
* [Monad Developer Discord](https://discord.gg/monaddev)
* [Migration Guide: V1 to V2](https://docs.x402.org/guides/migration-v1-to-v2)

## Need Help?

If you run into issues or have questions, join the [Monad Developer Discord](https://discord.gg/monaddev)

Happy building!


# Introduction
Source: https://docs.monad.xyz/index

Monad is a Layer-1 blockchain delivering high performance, true decentralization, and EVM compatibility.

<Note>
  **Quick hits**

  * [Network Information](/developer-essentials/network-information)
  * [Deployment Summary for Developers](/developer-essentials/summary)
</Note>

Monad is a Layer-1 blockchain delivering high performance, true decentralization, and EVM
compatibility.

Monad's north star is making decentralization more powerful, and eliminating the perceived
tradeoff between decentralization and performance.

Monad supports a large globally distributed network
(see the [validator map](https://www.gmonads.com/)), with intentionally minimal
[hardware requirements](/node-ops/hardware-requirements) so that anyone may run a node.
Performance comes from software architecture improvements rather than reliance on heavy hardware
or node colocation.

Monad's codebase is fully open source ([consensus](https://github.com/category-labs/monad-bft),
[execution](https://github.com/category-labs/monad)) and is built for extreme performance in
C++ and rust.

Monad introduces novel architectures in five major areas:

* [MonadBFT](/monad-arch/consensus/monad-bft), a frontier BFT consensus mechanism solving the
  [tail-forking](https://www.category.xyz/blogs/monadbft-fast-responsive-fork-resistant-streamlined-consensus) problem
* [RaptorCast](/monad-arch/consensus/raptorcast) for efficient block transmission
* [Asynchronous Execution](/monad-arch/consensus/asynchronous-execution) for pipelining
  consensus and execution to raise the time budget for execution
* [Parallel Execution](/monad-arch/execution/parallel-execution) and [JIT Compilation](/monad-arch/execution/native-compilation) for efficient transaction
  execution
* [MonadDb](/monad-arch/execution/monaddb) for efficient storage of Ethereum state

Monad's improvements address existing bottlenecks while preserving seamless compatibility for
application developers (full EVM bytecode compatibility) and users (Ethereum
[RPC API](/reference/json-rpc) compatibility).

The result is an Ethereum-compatible Layer-1 blockchain with 10,000 tps of throughput,
400ms block frequency, and 800ms finality.

Select a level of detail by visiting either [Monad for Users](/introduction/monad-for-users) or
[Monad for Developers](/introduction/monad-for-developers).

## Deploying on Monad

See [Deployment Summary for Developers](/developer-essentials/summary) for everything you need to
know as a developer deploying on Monad.

Monad features first-class support for many leading Ethereum developer tools and infra providers.
See [Tooling and Infrastructure](/tooling-and-infra) for a summary.

## Architecture

Monad is designed with a focus on performance and scalability with commodity hardware.
The subsequent pages survey the major [architectural changes](/monad-arch) in Monad as well as the
interface for users.

The first Monad client is built by
[Category Labs](https://www.category.xyz) and is written from scratch in C++ and Rust.

[`monad-bft`](https://github.com/category-labs/monad-bft), Category Labs's implementation of
a Monad consensus client, and
[`monad`](https://github.com/category-labs/monad), Category Labs's implementation of a Monad
execution client, are both open-source under `GPL-3.0`.

## Mainnet

Public mainnet launched on Nov 24, 2025.

See [Network Information](/developer-essentials/network-information) for access, or check out the
[MonadVision](https://monadvision.com/) block explorer, the [gmonads.com](https://gmonads.com)
network visualization, or [app.monad.xyz](https://app.monad.xyz).


# Monad for Developers
Source: https://docs.monad.xyz/introduction/monad-for-developers

Technical one-pager on Monad for developers

<Note>
  This page summarizes "Why Monad" for developers. For a summary of what you need to know in order
  to develop or redeploy on Monad, see
  [Deployment Summary for Developers](/developer-essentials/summary).
</Note>

Monad is an Ethereum-compatible Layer-1 blockchain with 10,000 tps of throughput, 400ms block frequency, and 800ms finality.

Monad's implementation of the Ethereum Virtual Machine complies with the Fusaka fork.

The Monad client has been simulated with historical Ethereum transactions and produces
identical merkle roots.

Monad also offers full Ethereum RPC compatibility so that users can interact with Monad using
familiar tools like Etherscan, Phantom, or MetaMask.

Monad accomplishes these performance improvements, while preserving backward compatibility, through
the introduction of several major innovations:

* [MonadBFT](/monad-arch/consensus/monad-bft), a frontier BFT consensus mechanism solving the
  [tail-forking](https://www.category.xyz/blogs/monadbft-fast-responsive-fork-resistant-streamlined-consensus) problem
* [RaptorCast](/monad-arch/consensus/raptorcast) for efficient block transmission
* [Asynchronous Execution](/monad-arch/consensus/asynchronous-execution) for pipelining
  consensus and execution to raise the time budget for execution
* [Parallel Execution](/monad-arch/execution/parallel-execution) and [JIT Compilation](/monad-arch/execution/native-compilation) for efficient transaction
  execution
* [MonadDb](/monad-arch/execution/monaddb) for efficient storage of Ethereum state

Although Monad features parallel execution and pipelining, it's important to note that blocks in Monad are linear, and transactions are linearly ordered within each block.

The first Monad client is built by
[Category Labs](https://www.category.xyz) and is written from scratch in C++ and Rust. The code
is open-source under `GPL-3.0` here:

* [`monad-bft`](https://github.com/category-labs/monad-bft)
* [`monad`](https://github.com/category-labs/monad)

## Transactions

|                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Address space             | Same address space as Ethereum (20-byte addresses using ECDSA)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Transaction format/types  | [Same as Ethereum](https://ethereum.org/en/developers/docs/transactions/). Monad transactions use the same typed transaction envelope introduced in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718), encoded with [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/). Transaction type 0 ("legacy"), 1 ("EIP-2930"), 2 ("EIP-1559"; now the default in Ethereum), and 4 ("EIP-7702") are supported. See [transaction type reference](https://ethereum.org/en/developers/docs/transactions/#typed-transaction-envelope). See [Transactions](/developer-essentials/transactions) for more details. |
| EIP-7702                  | Supported. See [EIP-7702 on Monad](/developer-essentials/eip-7702)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| EIP-155 replay protection | Note that pre [EIP-155](https://eips.ethereum.org/EIPS/eip-155) transactions are allowed on the protocol level on Monad, therefore it's discouraged to use an Ethereum account that had previously made pre EIP-155 transactions. [Discussion](/developer-essentials/transactions#transactions-without-a-chain_id)                                                                                                                                                                                                                                                                                                                 |
| Wallet compatibility      | Monad is compatible with standard Ethereum wallets such as Phantom or MetaMask. The only change required is to alter the RPC URL and chain id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Gas pricing               | Monad is EIP-1559-compatible; base fee and priority fee work as in Ethereum. Base fee follows a dynamic controller, similar to the EIP-1559 controller but with slower increases and faster decreases. [Details](/developer-essentials/gas-pricing#base_price_per_gas-controller). **Transactions are charged based on gas limit rather than gas usage**, i.e. total tokens deducted from the sender's balance is `value + gas_price * gas_limit`. This is a DOS-prevention measure for asynchronous execution. See [Gas in Monad](/developer-essentials/gas-pricing) for more details.                                            |

## Smart contracts

|                   |                                                                                                                                                                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Opcodes           | Monad is bytecode-compatible with Ethereum (Fusaka fork). All [opcodes](https://www.evm.codes/) as of the Fusaka fork are supported.                                                                                                                               |
| Opcode pricing    | Opcode pricing is the same as Ethereum, except for a few repricings needed to reweight relative scarcities of resources due to optimizations. [Details](/developer-essentials/opcode-pricing)                                                                      |
| Precompiles       | All Ethereum precompiles as of the Fusaka fork (`0x01` to `0x11`), plus P256 signature verification at `0x0100` ([EIP-7951](https://eips.ethereum.org/EIPS/eip-7951)) and the staking precompile at `0x1000`. See [Precompiles](/developer-essentials/precompiles) |
| Max contract size | 128 kb (up from 24.5 kb in Ethereum)                                                                                                                                                                                                                               |

## Consensus

|                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Sybil resistance mechanism  | Proof-of-Stake (PoS)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Delegation                  | Allowed (in-protocol)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Consensus mechanism         | Monad's consensus mechanism, [MonadBFT](/monad-arch/consensus/monad-bft), represents a major leap in Byzantine Fault-Tolerant (BFT) consensus. It is the first BFT consensus mechanism to address the critical problem of [tail forking](https://www.category.xyz/blogs/monadbft-fast-responsive-fork-resistant-streamlined-consensus) in pipelined HotStuff-style consensus. Accomplishing this allows MonadBFT to achieve high throughput (10,000+ tps), frequent block times (400 ms), fast finality (800 ms), linear messaging complexity, and large validator sets (200+) without being susceptible to tail forking, a critical weakness in prior protocols where a leader can fork away its predecessor's block.                                                                                                                                                                                                   |
| Block propagation mechanism | [RaptorCast](/monad-arch/consensus/raptorcast)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Block frequency             | 400 ms                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Finality                    | [Speculative finality](/monad-arch/consensus/monad-bft) at 400 ms; full finality at 800 ms                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Mempool                     | Leaders maintain a [local mempool](/monad-arch/consensus/local-mempool). When an RPC receives a transaction, it [forwards](/monad-arch/consensus/local-mempool#transaction-lifecycle-in-monad) it to the next 3 leaders who keep it in their local mempool. If the RPC node doesn't observe the transaction getting included, it repeats this process of forwarding to the next 3 leaders 2 more times. Additional forwarding may be added at a later time.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Consensus participants      | Direct consensus participants vote on block proposals and serve as leaders. To serve as a direct participant, a node must have at least `MinStake` staked and be in the top `MaxConsensusNodes` participants by stake weight. These parameters are set in code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Asynchronous execution      | In Monad, consensus and execution occur in a pipelined fashion. Nodes come to consensus on the official transaction order *prior* to executing that ordering ([Asynchronous Execution](/monad-arch/consensus/asynchronous-execution)); the outcome of execution is *not* a prerequisite to consensus. In blockchains where execution *is* a prerequisite to consensus, the time budget for execution is a small fraction of the block time. Pipelining consensus and execution allows Monad to expend the full block time on *both* consensus and execution. Block proposals consist of an ordered list of transactions and a delayed state merkle root from `k=3` blocks ago. Monad introduces the [Reserve Balance](/developer-essentials/reserve-balance) system to ensure that nodes at consensus time only include (or vote to include) transactions whose senders have sufficient balance to fund their execution. |
| State determinism           | Finality occurs at consensus time; the official ordering of transactions is enshrined at this point, and the outcome is fully deterministic for any full node, who will generally execute the transactions for that new block in under 800 ms. The `D`-block delay for state merkle roots is only for state root verification, for example for allowing a node to ensure that it didn't make a computation error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

## Execution

The execution phase for each block begins after consensus is reached on that block, allowing the node to proceed with consensus on subsequent blocks.

### Parallel Execution

Transactions are linearly ordered; the job of execution is to arrive at the state that results from executing that list of transactions serially. The naive approach is just to execute the transactions one after another. Can we do better? Yes we can!

Monad implements [parallel execution](/monad-arch/execution/parallel-execution):

* An executor is a virtual machine for executing transactions. Monad runs many executors in parallel.
* An executor takes a transaction and produces a **result**. A result is a list of **inputs** to and **outputs** of the transactions, where inputs are (ContractAddress, Slot, Value) tuples that were SLOADed in the course of execution, and outputs are (ContractAddress, Slot, Value) tuples that were SSTOREd as a result of the transaction.
* Results are initially produced in a pending state; they are then committed in the original order of the transactions. When a result is committed, its outputs update the current state. When it is a result's turn to be committed, Monad checks that its inputs still match the current state; if they don't, Monad reschedules the transaction. As a result of this concurrency control, Monad's execution is guaranteed to produce the same result as if transactions were run serially.
* When transactions are rescheduled, many or all of the required inputs are cached, so re-execution is generally relatively inexpensive. Note that upon re-execution, a transaction may produce a different set of Inputs than the previous execution did;

### MonadDb: high-performance state backend

All active state is stored in [MonadDb](/monad-arch/execution/monaddb), a storage backend for solid-state drives (SSDs) that is optimized for storing merkle trie data. Updates are batched so that the merkle root can be updated efficiently.

MonadDb implements in-memory caching and uses [asio](https://think-async.com/Asio/) for efficient asynchronous reads and writes. Nodes should have 32 GB of RAM for optimal performance.

## Comparison to Ethereum: User's Perspective

| Attribute                                                    | Ethereum                                                                                                         | Monad                                                                                                                                                                                 |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Transactions/second** (smart contract calls and transfers) | \~10                                                                                                             | \~10,000                                                                                                                                                                              |
| **Block Frequency**                                          | 12 seconds                                                                                                       | 400 ms                                                                                                                                                                                |
| **Finality**                                                 | [2 epochs](https://hackmd.io/@prysmaticlabs/finality) (12-18 min)                                                | 800 ms                                                                                                                                                                                |
| **Bytecode standard**                                        | EVM ([Fusaka fork](https://www.evm.codes))                                                                       | EVM ([Fusaka fork](https://www.evm.codes))                                                                                                                                            |
| **Precompiles**                                              | `0x01` to `0x11` (Fusaka fork)                                                                                   | `0x01` to `0x11` (Fusaka fork) plus `0x0100` (P256, [EIP-7951](https://eips.ethereum.org/EIPS/eip-7951)) and `0x1000` (staking). See [Precompiles](/developer-essentials/precompiles) |
| **Max contract size**                                        | 24.5 kb                                                                                                          | 128 kb                                                                                                                                                                                |
| **RPC API**                                                  | [Ethereum RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/)                                       | [Monad RPC API](/reference/json-rpc) (generally identical to Ethereum RPC API, see [differences](/reference/rpc-differences))                                                         |
| **Cryptography**                                             | ECDSA                                                                                                            | ECDSA                                                                                                                                                                                 |
| **Accounts**                                                 | Last 20 bytes of keccak-256 of public key under ECDSA                                                            | Last 20 bytes of keccak-256 of public key under ECDSA                                                                                                                                 |
| **Consensus mechanism**                                      | Gasper (Casper-FFG finality gadget + LMD-GHOST fork-choice rule)                                                 | [MonadBFT](/monad-arch/consensus/monad-bft) (tail-fork-resistant pipelined consensus with linear messaging complexity in the common case)                                             |
| **Mempool**                                                  | Global                                                                                                           | [Local](/monad-arch/consensus/local-mempool)                                                                                                                                          |
| **Transaction ordering**                                     | Leader's discretion (in practice, PBS)                                                                           | Leader's discretion (default behavior: priority gas auction)                                                                                                                          |
| **Sybil-resistance mechanism**                               | PoS                                                                                                              | PoS                                                                                                                                                                                   |
| **Delegation allowed**                                       | No; pseudo-delegation through LSTs                                                                               | Yes; see [Staking](/monad-arch/consensus/staking)                                                                                                                                     |
| **Hardware Requirements** (full node)                        | 4-core CPU, 32 GB RAM, 4 TB SSD NVMe, 25 Mbit/s bandwidth ([reference](https://eips.ethereum.org/EIPS/eip-7870)) | 16-core CPU, 32 GB RAM, 2 x 2 TB SSD NVMe, 100 Mbit/s bandwidth ([more info](/node-ops/hardware-requirements))                                                                        |

## Tooling and Infrastructure

Many leading Ethereum developer tools support Monad testnet. See
[Tooling and Infrastructure](/tooling-and-infra)
for a list of supported providers by category.

## Next Steps

Monad's public testnet is live. Head to [Network Information](/developer-essentials/network-information) to get started.

Now that you are familiar with Monad's architecture and features, head to
[Deployment Summary for Developers](/developer-essentials/summary)
for everything you need to know to deploy.


# Monad for Users
Source: https://docs.monad.xyz/introduction/monad-for-users

One-pager on Monad for users

Monad is a high-performance Ethereum-compatible L1, offering users the best of both worlds:
**portability** and **performance**.

From a portability perspective, Monad offers **full bytecode compatibility** for the Ethereum Virtual
Machine (EVM), so that applications built for Ethereum can be ported to Monad without code changes,
and **full Ethereum RPC compatibility**, so that infrastructure like Etherscan or The Graph can be
used seamlessly.

From a performance perspective, Monad offers **10,000 tps** of throughput, i.e. 1 billion
transactions per day, while offering **400ms block frequency** and **800ms finality**. This allows
Monad to support many more users and far more interactive experiences than existing blockchains,
while offering far cheaper per-transaction costs.

## What's familiar about Monad?

From a user perspective, Monad behaves very similarly to Ethereum. You can use the same wallets
(e.g. Phantom, MetaMask) or block explorers (e.g. Etherscan) to sign or view transactions. The same
apps built for Ethereum can be ported to Monad without code changes, so it is expected that you'll
be able to use many of your favorite apps from Ethereum on Monad. The address space in Monad is the
same as in Ethereum, so you can reuse your existing keys.

Like Ethereum, Monad features linear blocks, and linear ordering of transactions within a block.

Like Ethereum, Monad is a proof-of-stake network maintained by a decentralized set of validators.
Anyone can run a node to independently verify transaction execution, and significant care has been
taken to keep hardware requirements minimal.

## What's different about Monad?

Monad makes exceptional performance possible by introducing **parallel execution** and **superscalar
pipelining** to the Ethereum Virtual Machine.

**Parallel execution** is the practice of utilizing multiple cores and threads to strategically
execute work in parallel while still committing the results in the original order. Although
transactions are executed in parallel "under the hood", from the user and developer perspective they
are executed serially; the result of a series of transactions is always the same as if the
transactions had been executed one after another.

**Superscalar pipelining** is the practice of creating stages of work and executing the stages in
parallel. A simple diagram tells the story:

<img alt="Pipelining, Laundry Day" />

<p>Pipelining laundry day. Top: Naive; Bottom: Pipelined. Credit: Prof. Lois Hawkes, FSU</p>

When doing four loads of laundry, the naive strategy is to wash, dry, fold, and store the first load
of laundry before starting on the second one. The pipelined strategy is to start washing load 2 when
load 1 goes into the dryer. Pipelining gets work done more efficiently by utilizing multiple
resources simultaneously.

**Monad** introduces pipelining to address existing bottlenecks in state storage, transaction
processing, and distributed consensus. In particular, Monad introduces pipelining and other
optimizations in five major areas:

* [MonadBFT](/monad-arch/consensus/monad-bft) for performant, tail-fork-resistant BFT consensus
* [RaptorCast](/monad-arch/consensus/raptorcast) for efficient block transmission
* [Asynchronous Execution](/monad-arch/consensus/asynchronous-execution) for pipelining
  consensus and execution to raise the time budget for execution
* [Parallel Execution](/monad-arch/execution/parallel-execution) and
  [JIT Compilation](/monad-arch/execution/native-compilation) for efficient transaction
  execution
* [MonadDb](/monad-arch/execution/monaddb) for efficient state access

Monad's client, which was written from scratch in C++ and Rust, reflect these architectural
improvements and result in a platform for decentralized apps that can truly scale to world adoption.

## Why should I care?

Decentralized apps are replacements for centralized services with several significant advantages:

* **Open APIs / composability**: decentralized apps can be called atomically by other decentralized
  apps, allowing developers to build more complex functionality by stacking existing components.
* **Transparency**: app logic is expressed purely through code, so anyone can review the logic for
  side effects. State is transparent and auditable; proof of reserves in DeFi is the default.
* **Censorship-resistance and credible neutrality:** anyone can submit transactions or upload
  applications to a permissionless network.
* **Global reach**: anyone with access to the internet can access crucial financial services,
  including unbanked/underbanked users.

However, decentralized apps need cheap, performant infrastructure to reach their intended level of
impact. A single app with 1 million daily active users (DAUs) and 10 transactions per user per day
would require 10 million transactions per day, or 100 tps. A quick glance at
[L2Beat](https://l2beat.com/scaling/activity) - a useful website summarizing the throughput and
decentralization of existing EVM-compatible L1s and L2s - shows that no EVM blockchain supports even
close to that level of throughput right now.

Monad materially improves on the performance of an EVM-compatible blockchain network, pioneering
several innovations that will hopefully become standard in Ethereum in the years to come.

With Monad, developers, users, and researchers can reuse the wealth of existing applications,
libraries, and applied cryptography research that have all been built for the EVM.

## Testnet

Monad's public testnet is live. Head to
[Network Information](/developer-essentials/network-information) to get started.


# Why Blockchain?
Source: https://docs.monad.xyz/introduction/why-blockchain

A simple mental model for the 'what' and 'why'.

A blockchain is decentralized agreement among a diverse set of participants about two things:

1. An official **ordering** (ledger) of transactions
2. An official **state of the world**, including balances of accounts and the state of various programs.

In modern blockchains such as Ethereum, transactions consist of balance transfers, creation of new programs, and function calls against existing programs. The aggregate result of all transactions up to now produces the current state, which is why *agreement about (1) above implies agreement about (2).*

A blockchain system has a set of protocol rules, also known as a consensus mechanism, which describe how a distributed set of nodes which are currently in sync will communicate with each other to agree upon additional transactions to add to the ledger. ([MonadBFT](/monad-arch/consensus/monad-bft) is an example of a consensus mechanism.)

Induction keeps the nodes in sync: they start with the same state and apply the same transactions, so at the end of applying a new list of transactions, they still have consistent state.

Shared global state enables the development of decentralized apps - apps that live "on the blockchain", i.e. on each of the nodes in the blockchain system. A decentralized app is a chunk of code (as well as persistent, app-specific state) that can get invoked by any user, who does so by submitting a transaction pointing to a function on that app. Each of the nodes in the blockchain is responsible for correctly executing the bytecode being called; duplication keeps each node honest.

## An example app

Decentralized apps can implement functionality that we might otherwise expect to be implemented in a centralized fashion. For example, a very simple example of a decentralized app is a *Virtual Bank* (typically referred to in crypto as a Lending Protocol).

In the physical world, a bank is a business that takes deposits and loans them out at a higher rate. The bank makes the spread between the high rate and the low rate; the borrower gets a loan to do something economically productive; and you earn interest on your deposits. Everyone wins!

A Virtual Bank is simply an app with four major methods: `deposit`, `withdraw`, `borrow`, and `repay`. The logic for each of those methods is mostly bookkeeping to ensure that deposits and loans are being tracked correctly:

```python theme={null}
class VirtualBank:
  def deposit(sender, amount):
    # transfer amount from sender to myself (the bank)
    # do internal bookkeeping to credit the sender

  def withdraw(sender, amount):
    # ensure the sender had enough on deposit
    # do internal bookkeeping to debit the sender
    # transfer amount from myself (the bank) to sender

  def borrow(sender, amount):
    # ...

  def repay(sender, amount);
    # ...
```

In Ethereum, or in Monad, someone can write code for this Virtual Bank and upload it; then anyone can utilize it for borrowing and lending, potentially far more easily than when trying to get access to banking services in their home country.

This simple example shows the power of decentralized apps. Here are a few other benefits to call out:

* **Open APIs / composability**: decentralized apps can be called atomically by other decentralized apps, allowing developers to build more complex functionality by stacking existing components.
* **Transparency**: app logic is expressed purely through code, so anyone can review the logic for side effects. State is transparent and auditable; proof of reserves in DeFi is the default.
* **Censorship-resistance and credible neutrality:** anyone can submit transactions or upload applications to a permissionless network.
* **Global reach**: anyone with access to the internet can access crucial financial services, including unbanked/underbanked users.


# Why Monad: Decentralization + Performance
Source: https://docs.monad.xyz/introduction/why-monad

Monad addresses today's performance bottlenecks through optimization while preserving decentralization.

## Decentralization matters

A blockchain has several major components:

* Consensus mechanism for achieving agreement on transactions to append to the ledger
* Execution/storage system for maintaining the active state

In increasing the performance of these components, one could cut corners, for example by requiring all
of the nodes to be physically close to each other (to save on the overhead of consensus), or by
requiring a huge amount of RAM (to keep much or all of the state in memory), but it would be at a
significant cost to decentralization.

And decentralization is the whole point!

As discussed in [Why Blockchain?](/introduction/why-blockchain), decentralized shared global state
allows many parties to coordinate while relying on a single, shared, objective source of truth.
Decentralization is key to the matter; a blockchain maintained by a small group of node operators (or
in the extreme case, a single operator!) would not offer benefits such as trustlessness, credible
neutrality, and censorship-resistance.

For any blockchain network, decentralization should be the principal concern. Performance improvements
should not come at the expense of decentralization.

## Today's performance bottlenecks

Ethereum's current execution limits (2.5M gas per second) are set conservatively, but for several
good reasons:

* Inefficient storage access patterns
* Single-threaded execution
* Very limited execution budget, because consensus can't proceed without execution
* Concerns about state growth, and the effect of state growth on future state access costs

Monad addresses these limitations through algorithmic improvements and architectural changes,
pioneering several innovations that will hopefully become standard in Ethereum in the years to come.
Maintaining a high degree of decentralization, while making material performance improvements, is the
key consideration.

## Addressing these bottlenecks through optimization

Monad enables pipelining and other optimizations in four major areas to enable exceptional Ethereum
Virtual Machine performance and materially advance the decentralization/scalability tradeoff.
Subsequent pages describe these major areas of improvement:

* [MonadBFT](/monad-arch/consensus/monad-bft), a frontier BFT consensus mechanism solving the
  [tail-forking](https://www.category.xyz/blogs/monadbft-fast-responsive-fork-resistant-streamlined-consensus) problem
* [RaptorCast](/monad-arch/consensus/raptorcast) for efficient block transmission
* [Asynchronous Execution](/monad-arch/consensus/asynchronous-execution) for pipelining
  consensus and execution to raise the time budget for execution
* [Parallel Execution](/monad-arch/execution/parallel-execution) and [JIT Compilation](/monad-arch/execution/native-compilation) for efficient transaction
  execution
* [MonadDb](/monad-arch/execution/monaddb) for efficient storage of Ethereum state


# Asynchronous I/O
Source: https://docs.monad.xyz/monad-arch/concepts/asynchronous-io



*Asynchronous I/O* is a form of input/output processing that allows the CPU to continue executing concurrently while communication is in progress.

Disk and network are orders of magnitude slower than the CPU.  Rather than initiating an I/O operation and waiting for the result, the CPU can initiate the I/O operation as soon as it's known that the data will be needed, and continue executing other instructions which do not depend on the result of the I/O operation.

Some rough comparisons for illustration purposes:

<div>
  <table>
    <thead>
      <tr>
        <th>Device</th>
        <th>Latency</th>
        <th>Bandwidth</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>CPU L3 Cache</td>
        <td>10 ns</td>
        <td>>400 GB/s</td>
      </tr>

      <tr>
        <td>Memory</td>
        <td>100 ns</td>
        <td>100 GB/s</td>
      </tr>

      <tr>
        <td>Disk (NVMe SSD)</td>
        <td>400 us</td>
        <td>380 MB/s</td>
      </tr>

      <tr>
        <td>Network</td>
        <td>50 - 200 ms</td>
        <td>1 Gb/s (125 MB/s)</td>
      </tr>
    </tbody>
  </table>
</div>

(actual disk stats as reported by fio for random reads of size 2KB - \~190k IOPS)

Fortunately, SSD drives can perform operations concurrently, so the CPU can initiate several requests at the same time, continue executing, and then receive the results of multiple operations around the same time.

Some databases (such as lmdb / mdbx) use memory-mapped storage to read and write to disk. Unfortunately, memory-mapped storage is implemented by the kernel (mmap) and is not asynchronous, so execution is blocked while waiting for the operation to complete.

More about asynchronous I/O can be read [here](https://en.wikipedia.org/wiki/Asynchronous_I/O).


# Concepts
Source: https://docs.monad.xyz/monad-arch/concepts/index



Key concepts that underpin Monad's architecture.

<CardGroup>
  <Card title="Asynchronous I/O" href="/monad-arch/concepts/asynchronous-io">
    How Monad uses async I/O to keep the CPU productive while communication is in progress
  </Card>

  <Card title="Pipelining" href="/monad-arch/concepts/pipelining">
    Dividing tasks into smaller stages that can be processed in parallel
  </Card>
</CardGroup>


# Pipelining
Source: https://docs.monad.xyz/monad-arch/concepts/pipelining



*Pipelining* is a technique for implementing parallelism by dividing tasks into a series of smaller tasks which can be processed in parallel.

Pipelining is used in computer processors to increase the throughput of executing a series of instructions sequentially at the same clock rate. (There are other techniques used in processors to increase throughput as well.)  More about instruction-level parallelism (ILP) can be read [here](https://en.wikipedia.org/wiki/Instruction_pipelining).

A simple example of pipelining:

<img alt="Pipelining, Laundry Day" />

<p>Pipelining laundry day. Top: Naive; Bottom: Pipelined. Credit: <a href="https://www.cs.fsu.edu/~hawkes/cda3101lects/chap6/index.html?$$$F6.1.html$$$">Prof. Lois Hawkes, FSU</a></p>

When doing four loads of laundry, the naive strategy is to wash, dry, fold, and store the first load of laundry before starting on the second one.  The pipelined strategy is to start washing load 2 when load 1 goes into the dryer.  Pipelining gets work done more efficiently by utilizing multiple resources simultaneously.


# Asynchronous Execution
Source: https://docs.monad.xyz/monad-arch/consensus/asynchronous-execution

Pipelined consensus-execution staging

## Summary

Asynchronous Execution is a technique that allows Monad to substantially increase execution throughput by decoupling consensus from execution.

Decoupling consensus from execution allows Monad to substantially increase the execution budget, since execution goes from occupying a small fraction of the block time to occupying the full block time.

## Background: interleaved execution is inefficient

Consensus is the process where nodes come to agreement about the official ordering of transactions. Execution is the process of actually executing those transactions and updating the state.

In Ethereum and most other blockchains, execution is a prerequisite to consensus. When nodes come to consensus on a block, they are agreeing on both (1) the list of transactions in the block, and (2) the merkle root summarizing all of the state after executing that list of transactions. As a result, the leader must execute all of the transactions in the proposed block *before* sharing the proposal, and the validating nodes must execute those transactions *before* responding with a vote.

We refer to this style of blockchain as one that has execution **interleaved** with consensus. In this paradigm, the time budget for execution is extremely limited, since it has to happen twice *and* leave enough time for multiple rounds of cross-globe communication for consensus.

Additionally, since execution will block consensus, the per-block gas limit must be chosen extremely conservatively to ensure that the computation completes on all nodes within the budget even in the worst-case scenario.

The result is that the per-block gas limit is a tiny fraction of the block time. In particular, in Ethereum, the gas limit (30M worst-case gas) corresponds to a roughly 100ms time budget, even though the the block time is 12 seconds:

<img />

<p>Comparing Ethereum execution budget to block time</p>

That's 1% of the block time! In short, interleaving consensus and execution has a massive time-shrinking effect.

What if it didn't have to be this way?

## Asynchronous Execution

Monad decouples consensus from execution, moving execution out of the hot path of consensus into a separate, slightly-lagged swim lane.

**In Monad, nodes come to consensus (i.e. agreement about the official ordering of transactions), without ever executing those transactions.**

That is, the leader proposes an ordering without knowing the resultant state root, and the validating nodes vote on block validity without knowing (for example) whether all of the transactions in the block execute without reverting.

When a block is finalized, every node in the network (validators and full nodes) can execute the block's transactions to produce the latest, agreed-upon state.

As a result of this change, execution can be budgeted the full block time. To see why, consider the somewhat stylized diagrams, in which blue rectangles correspond to execution, and orange rectangles correspond to consensus:

**Interleaved execution**

In interleaved execution, the sum of the execution and consensus budgets equals the block time, and consensus occupies most of the block time.

<img />

<p>Interleaved execution</p>

**Asynchronous execution**

In asynchronous execution, consensus occupies the full block time - and so does execution, because they are occurring in separate swim lanes, *at the same time*:

<img />

<p>Asynchronous execution</p>

**Comparison**

Comparing the two styles side by side, you can see the benefit of the asynchronous style: the execution budget can be significantly expanded to occupy the full block time:

<img />

<p>Top: interleaved; bottom: asynchronous.</p>

## Determined ordering implies state determinism

Although execution lags consensus, the true state of the world is determined as soon as the ordering is determined. Execution is required to unveil the truth, but the truth is already determined.

It's worth noting that in Monad, like in Ethereum, it is fine for transactions in a block to "fail" in the sense that the intuitive outcome did not succeed.(For example, there could be a transaction included in a block in which Bob tries to send 10 tokens to Alice but only has 1 token in his account. The transfer 'fails' but the transaction is still valid.

The outcome of any transaction, including failure, is deterministic.

<img />

<p>Example of transaction determinism even when some transactions fail</p>

## Finer details

### Delayed Merkle Root

As mentioned above, Monad block proposals don't include the merkle root of the state trie, since that would require execution to have already completed.

All nodes should stay in sync because they're all doing the same work. But it'd be nice to be sure! As a precaution, proposals also includes a merkle root from `D` blocks ago, allowing nodes to detect if they're diverging. `D` is a systemwide parameter (currently set in testnet and mainnet to `3`).

Delayed merkle root validity is part of block validity, so if the leader proposes a block but the delayed merkle root is wrong, the block will be rejected.

As a result of this delayed merkle root:

1. After the network comes to consensus (2/3 majority vote) on block `N` (typically upon receiving block `N+2`, which contains a QC-on-QC for block `N`), it means that the network has agreed that the official consequence of block `N-D` is a state rooted in merkle root `M`. Light clients can then query full nodes for merkle proofs of state variable values at block `N-D`.
2. Any node with an error in execution at block `N-D` will fall out of consensus starting at block `N`. This will trigger a rollback on that node to the end state of block `N-D-1`, followed by re-execution of the transactions in block `N-D` (hopefully resulting in the merkle root matching), followed by re-execution of the transactions in block `N-D+1`, `N-D+2`, etc.

Ethereum's approach uses consensus to enforce *state machine replication* in a very strict way: after nodes come to consensus, we know that the supermajority agrees about the official ordering and the state resulting from that ordering. However, this strictness comes at great cost because interleaved execution limits execution throughput. Asynchronous execution achieves state machine replication without this limitation, and the delayed merkle root serves an additional precaution.

<img />

<p>Delayed merkle root</p>

### Reserve balance

Because consensus can only be assumed to have up to the `D`-block delayed view of the global
state, it is necessary to adjust the consensus and execution rules slightly to allow consensus to
safely build blocks that include only transactions whose gas costs can be paid for.

Monad introduces the [Reserve Balance](/developer-essentials/reserve-balance) rules to
ensure this. The rules place light restrictions on when transactions can be
included at consensus time, and imposes some conditions under which transactions will
revert at execution time.

### Speculative execution

In MonadBFT, nodes receive a proposed block `N` at slot `N`, but it is not finalized until slot `N+2`. During the intervening time, a node can still locally execute the proposed block (without the guarantee that it will become voted or finalized). This allows a few nice properties:

1. In the likely event that the proposed block is finalized, the validator node has already done the work and can immediately update its merkle root pointer to the result.
2. Transactions can be simulated (in `eth_call` or `eth_estimateGas`) against the speculative state which is likely more up-to-date.

### Transactions from newly-funded accounts

Because consensus runs slightly ahead of execution, newly-funded accounts which previously had zero balance cannot send transactions until the transfer that credits them with tokens is `D` blocks old.

In practice, this means that if you send tokens from account `A` into an account `B` (which has 0 balance), then you should wait until seeing the transaction receipt (indicative that that block has reached [`Proposed`](/monad-arch/consensus/block-states#Proposed) state), and then wait another 1.2 seconds.

Alternatively, depending on the nature of intended transaction from `B`, it may be possible to write a smart contract callable by `A` which combines the funding operation and whatever `B` was intending to do, requiring no delay between funding and spending.

## Block states

See [block states](/monad-arch/consensus/block-states) for a summary of the states through which each block progresses.


# Message Authentication
Source: https://docs.monad.xyz/monad-arch/consensus/authentication



## BLS Multi-Signatures

Certificates (QCs and TCs) can be naively implemented as a vector of ECDSA signatures on the secp256k1 curve. These certificates are explicit and easy to construct and verify. However, the size of the certificate is linear with the number of signers. It poses a limit to scaling because the certificate is included in almost every consensus message, except vote message.

Pairing-based BLS signature on the BLS12-381 curve helps with solving the scaling issue. The signatures can be incrementally aggregated into one signature. Verifying the single valid aggregated signature provides proof that the stakes associated with the public keys have all signed on the message.

BLS signature is much slower than ECDSA signature. So for performance reasons, Monad's implementation of MonadBFT adopts a blended signature scheme where BLS signatures are only used on aggregatable message types (votes and timeouts). Message integrity and authenticity is still provided by ECDSA signatures.


# Block States
Source: https://docs.monad.xyz/monad-arch/consensus/block-states

Block lifecycle

In [MonadBFT](/monad-arch/consensus/monad-bft), a block progresses through [three states](/monad-arch/consensus/monad-bft#block-states-due-to-monadbft).
Additionally, due to [asynchronous execution](/monad-arch/consensus/asynchronous-execution), block finalization is a
separate (earlier) matter from state root verification. As a result of this architecture, each
Monad block can be considered to be in one of four states.

Note that a block's state is from the perspective of a particular observer (any other validator or
full node). As new messages arrive, they allow that observer to progress the block's state locally.
Although the states are defined locally, they correspond to assurance that the rest of the network
will ultimately converge on an outcome consistent with that state.

For example, if a node marks a block as `Finalized`, it is because that node has received a message
carrying sufficient proof that the rest of the network will ultimately converge on enshrining that
block at that block height.

## States

A Monad block is in one of the four states:

1. `Proposed`
2. `Voted`
3. `Finalized`
4. `Verified`

<img />

<p>Classification of historical blocks based on the latest <strong>proposed</strong> block N.</p>

### Proposed

The block has been proposed by a leader but has not been voted upon.

Note: if execution is not lagging behind consensus, a node may
[speculatively execute](/monad-arch/consensus/asynchronous-execution#speculative-execution) the proposed block.

### Voted

We have a [Quorum Certificate (QC)](/monad-arch/consensus/monad-bft#quorum-certificate-qc) in hand for the block,
indicating that it has been voted affirmatively for by a supermajority of validators. (Typically,
this is due to receiving a child block for this block.)

In MonadBFT, `Voted` means the block can be
[speculatively finalized](/monad-arch/consensus/monad-bft#speculative-finality).

### Finalized

We have a QC-squared in hand for the block (that is, we have a
[QC](/monad-arch/consensus/monad-bft#quorum-certificate-qc) for a block that contains a QC on the original block).
This serves as proof that a supermajority of validators have ratified the existence and validity
of a QC on the original block.

Due to the consensus rules of MonadBFT, this means that the block is finalized.

### Verified

A block containing the [delayed merkle root](/monad-arch/consensus/asynchronous-execution#delayed-merkle-root)
has been finalized, meaning that the execution outputs of the block has been agreed upon by a
supermajority of validator nodes.

Concretely, the latest verified block will be the
`latest_finalized_block - execution_delay`.

## Mapping to JSON-RPC commitment levels

Monad uses a different consensus algorithm than Ethereum, but is API compatible with the
[JSON-RPC](/reference) programming interface defined by the
[Geth client](https://geth.ethereum.org/docs/interacting-with-geth/rpc).

Geth communicates consensus information about blocks publicly over JSON-RPC using the tags
`"latest"`, `"safe"`, and `"finalized"`. Here is how they map to Monad's block states:

| Geth RPC state | ...corresponds to Monad block state | Why?                                                                                                                                                                      |
| -------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"latest"`     | `Proposed`                          | Both states refer to the most recently observed block, before consensus finalizes the result                                                                              |
| `"safe"`       | `Voted`                             | In Ethereum's LMD-GHOST algorithm, "safe" means something like "extremely unlikely to be reverted, but still theoretically possible"; Monad's voted has a similar meaning |
| `"finalized"`  | `Finalized`                         | This has the same meaning on both chains: not revertible without a hard fork                                                                                              |

<Note>
  Geth recognizes two other block tags, `"earliest"` and `"pending"`. These are not consensus
  states. The former is a synonym for the genesis block, and the latter does not make sense given
  how Monad's [transaction propagation mechanism](/monad-arch/consensus/local-mempool) is
  different.
</Note>

## Real-time data and block states

Monad offers several [sources of real-time blockchain data](/monad-arch/realtime-data/data-sources).
To provide the fastest service possible, some data feeds report blockchain data for the latest
block your node knows about, as soon as it learns about it.

As you can see above, the *latest* block your node is aware of -- the most recent block in the
`Proposed` state -- may be *speculatively executed*. Thus, you may see data about blocks that do
not ultimately become part of the Monad blockchain, although this is very rare.
[This page](/monad-arch/realtime-data/spec-realtime) gives an in-depth overview of how the
block state progression works, in case you want to consume real-time data and wish to understand
how speculative execution and real-time data reporting fit together.

To see an explicit example of how this relates to a real data feed, see the
[WebSocket Guide](/reference/websockets) section about
[`monadNewHeads`](/reference/websockets#monadnewheads-and-monadlogs), an extension to the
[Geth `newHeads` data feed](https://geth.ethereum.org/docs/interacting-with-geth/rpc/pubsub) that
includes additional data for tracking each block's progression through consensus.


# Blocksync
Source: https://docs.monad.xyz/monad-arch/consensus/blocksync

Mechanism for synchronizing missing blocks

## Summary

Blocksync is a mechanism that nodes can use to acquire missing blocks. A block is considered missing when a Quorum Certificate is observed that references an unknown block.

Blocks can be missing from a node in one of two scenarios:

1. After the node completes statesync and its local block height is close enough to the network tip.
2. During ordinary consensus operations, the node does not receive enough RaptorCast chunks to decode the block. This can be due to packet loss or a network partition.

## Blocksync procedure

1. A single header request is made for a range of `num_blocks` blocks, starting with `last_block_id`.
2. A chain of `num_blocks` headers are received, forming a cryptographically verifiable chain back to `last_block_`.
3. For each of the `num_blocks` headers received, concurrent (up to a max concurrency factor) body requests are made containing the `body_id` included in the header.
4. Each body response is cryptographically verifiable by comparing against the corresponding header `body_id`.

<img alt="Blocksync procedure" />


# Consensus
Source: https://docs.monad.xyz/monad-arch/consensus/index



<CardGroup>
  <Card title="MonadBFT" href="/monad-arch/consensus/monad-bft">
    Tail-fork-resistant pipelined consensus
  </Card>

  <Card title="RaptorCast" href="/monad-arch/consensus/raptorcast">
    Efficient block propagation of large blocks, utilized by leaders in MonadBFT
  </Card>

  <Card title="Asynchronous Execution" href="/monad-arch/consensus/asynchronous-execution">
    Moving execution out of the hot path of consensus so it can use the full block time
  </Card>

  <Card title="Block States" href="/monad-arch/consensus/block-states">
    Summarizing the progression of Monad blocks from proposal to verification
  </Card>

  <Card title="Local Mempool" href="/monad-arch/consensus/local-mempool">
    Policies for sharing pending transactions to leaders while minimizing bandwidth
  </Card>

  <Card title="Statesync" href="/monad-arch/consensus/statesync">
    Algorithms for bootstrapping a node from peers
  </Card>

  <Card title="Blocksync" href="/monad-arch/consensus/blocksync">
    Algorithms for catching up on missed traffic
  </Card>

  <Card title="Peer Discovery" href="/monad-arch/consensus/peer-discovery">
    How nodes know where to find each other
  </Card>

  <Card title="Message Authentication" href="/monad-arch/consensus/authentication">
    Signature schemes used in Monad
  </Card>

  <Card title="Transport Protocol Usage" href="/monad-arch/consensus/transport-protocols">
    TCP and UDP usage for node communication
  </Card>
</CardGroup>


# Local Mempool
Source: https://docs.monad.xyz/monad-arch/consensus/local-mempool

Mempool local to each node

## Summary

Most blockchains use a global mempool with peer-to-peer gossipping for transaction propagation. This approach is not suitable for high-performance distributed consensus for a few reasons:

1. It is slow because it may involve many hops for a transaction to reach a leader, increasing time to inclusion.
2. It is wasteful on bandwidth because the gossip protocol involves many retransmissions.
3. It ignores the leader schedule which is typically known well in advance.

In Monad, there is no global mempool; instead, each validator maintains a local mempool, and RPC nodes forward transactions to the next few leaders for inclusion in their local mempool. This is much more efficient on bandwidth usage and allows transactions to be included more quickly.

## Background

A mempool is a collection of pending transactions. Many blockchain networks use a global mempool design, using peer-to-peer gossip protocols to keep roughly the same mempool state across all nodes in the network. A primary motivation of a global mempool design is that no matter who is leader, they will have access to the same set of pending transactions to include in the next block.

A global mempool is effective for low-throughput networks, where network bandwidth is typically not a bottleneck. However, at thousands of transactions per second, the gossip protocols (and especially the required retransmission at each node) can easily consume the entire network bandwidth budget. Moreover, a global mempool is wasteful since the leader schedule is typically known well in advance.

## Transaction Lifecycle in Monad

There is no global mempool in Monad. Validators maintain local mempools; RPC nodes forward transactions to upcoming leaders to ensure that those transactions are available for inclusion.

More precisely, transaction flow is as follows:

1. A transaction is submitted to the RPC process of a node (typically a full non-validator node). We'll call this node the **"owner node"** of the transaction, since it assumes responsibility for communicating the status with the user.
2. The RPC process performs some static checks on the transaction.
3. The RPC process passes the transaction to the consensus process.
4. The consensus process performs static checks and dynamic checks against local state in MonadDb, such as checking the sender's account balance and nonce.
5. If the transaction is valid, the consensus process forwards the transaction to `N` upcoming leader validator nodes. Currently, `N` is set to 3 in Monad testnet and mainnet.
6. Each of those `N` validators performs the same checks before inserting valid transactions into their local mempools.
7. When it is a leader's turn to create a proposal, it selects transactions from its local mempool.
8. The owner node of the transaction monitors for that transaction in subsequent blocks. If it doesn't see the transaction in the next `N` blocks, it will re-send to the next `N` leaders. It repeats this behavior for a total of `K` times. Currently, `K` is set to 3 in Monad testnet and mainnet.

The behavior of this transaction flow is chosen to reduce time-to-inclusion while minimizing the number of messages.

<img alt="Transaction path to leader" />

<p>Transaction path from RPC to leader (through the local mempool).</p>

## Local mempool eviction

Transactions are evicted from a validator's local mempool for the following reasons:

1. Whenever a validator finalizes a block, any replicas of transactions in that block are pruned from the local mempool.
2. Validators periodically check the validity of each transaction in the mempool and evict invalid transactions (e.g. nonces are too low, account balances are insufficient).
3. If the local mempool's size reaches a soft limit, older transactions will be evicted.


# MonadBFT
Source: https://docs.monad.xyz/monad-arch/consensus/monad-bft

MonadBFT - Fast, Responsive, Fork-Resistant, Streamlined Consensus

## Summary

MonadBFT represents a major leap in Byzantine Fault Tolerant (BFT) consensus. It is responsible
for ensuring that the Monad network aligns on valid proposed blocks efficiently and securely,
while supporting 10,000+ tx/s and sub-second time-to-finality, while also supporting a large
consensus node set.

MonadBFT combines all of these properties while also being resilient to **tail-forking**, a
critical weakness of pipelined leader-based BFT protocols where a leader can fork away its
predecessor's block.

For a full description and deep technical dive into MonadBFT, please refer to the
[full research paper](https://arxiv.org/abs/2502.20692), the
[latest blog post from Category Labs](https://www.category.xyz/blogs/monadbft-update-fast-recovery-leader-fault-isolation) and the
[original blog post](https://www.category.xyz/blogs/monadbft-fast-responsive-fork-resistant-streamlined-consensus)
introducing MonadBFT.

MonadBFT achieves:

* **Speculative finality in a single consensus round**, and **full finality in two rounds**.
* **Linear message and authenticator complexity** on the happy path (meaning under normal operations, when no failures occur). This allows the consensus
  validator set to scale to a large number of nodes.
* **Optimistic responsiveness**: round progression without
  waiting for the worst-case network delay, both in the common case and while recovering
  from failed rounds.
* **Leader fault isolation** A single failed leader only incurs one timeout delay. All other
  rounds are able to proceed as quickly as the network allows. This is in contrast to existing
  pipelined BFT protocols, which have a two timeouts for a failed leader.
* **Tail-forking resistance**: built-in protection against [tail-forking](#no-tail-forking), a
  class of Maximal Extractable Value (MEV) attacks where a malicious leader could otherwise
  fork away its predecessor's block. This resolves a critical issue in prior pipelined
  leader-based BFT consensus mechanisms.

No other pipelined leader-based BFT protocol combines all these features.

<Note>
  Category Labs has made several recent improvements to MonadBFT. This page and the research paper
  have now been updated with full details. Find out what's new in the
  [Fast Recovery](#fast-recovery) section or by reading [this blog post](https://www.category.xyz/blogs/monadbft-update-fast-recovery-leader-fault-isolation).
</Note>

## Configuration in Monad

<div>
  <table>
    <thead>
      <tr>
        <th />

        <th />
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Sybil resistance mechanism</td>
        <td>Proof-of-Stake (PoS)</td>
      </tr>

      <tr>
        <td>Min block time</td>
        <td>400 ms</td>
      </tr>

      <tr>
        <td>Finality</td>
        <td>2 slots (800 ms)</td>
      </tr>

      <tr>
        <td>Speculative finality *(can only revert in [rare circumstances](#speculative-finality) requiring equivocation by the original leader*)</td>
        <td>1 slot (400 ms)</td>
      </tr>

      <tr>
        <td>Delegation allowed</td>
        <td>Yes</td>
      </tr>
    </tbody>
  </table>
</div>

## Demo

See [this](https://www.category.xyz/blogs/monad-viz-a-visual-representation-of-monadbft)
blog post from Category Labs for a live demo of MonadBFT!

The demo runs the exact implementation of [`monad-bft`](https://github.com/category-labs/monad-bft)
that powers the live Monad blockchain, compiled to Wasm and run in your browser against a
simulation framework
([`mock-swarm`](https://github.com/category-labs/monad-bft/tree/master/monad-mock-swarm)).

## Common Concepts

To explain MonadBFT, it helps to define a few concepts first. We will start with some
concepts common to many BFT mechanisms:

### Byzantine threshold

As is customary, let there be `n = 3f+1` nodes, where `f` is the max number of Byzantine
(faulty) nodes. That is, `2f+1` (2/3) of the nodes are non-Byzantine. In the discussion
below, we treat all nodes as having equal stake weight; in practice all thresholds can be
expressed in terms of stake weight rather than in node count.

### Supermajority

\>2/3 of the stake weight.

### Round

The protocol proceeds in rounds, also referred to as views. The round number increases by 1
with each step of the protocol regardless of whether a block proposal is successfully made.

### Leader

Each round has one leader who has the authority to make a block proposal. The leader rotates each
round according to a schedule determined previously using the stake weights.

### Block

A block consist of a round number, a payload (an ordered list of transactions), and a
[QC](#quorum-certificate-qc). A block builds on a *parent* block, and includes a QC certifying
that parent block. Blocks are chained together via the parent relationship, which is why we called
it a blockchain.

### Quorum Certificate (QC)

Validators evaluate the validity of each block proposal and send their votes to the next leader. If
the next leader receives a supermajority of YES votes, they aggregate those votes into a
Quorum Certificate (QC) on that block proposal. A QC is proof that 2/3 of the network received and
voted YES on a block proposal.

Although this is more of an implementation detail, it is worth noting that in Monad's
implementation of MonadBFT, validators sign with [BLS signatures](https://en.wikipedia.org/wiki/BLS_digital_signature)
because those signatures can be efficiently aggregated, making signature verification on the
QC relatively inexpensive.

### Linear communication

Each round follows a fan-out fan-in pattern. The leader sends their block proposal to each validator
(using [RaptorCast](/monad-arch/consensus/raptorcast) for efficient broadcast). Validators evaluate the block proposal
and send a signed vote directly to the next leader. This linear communication mechanism
contrasts with other protocols which rely on all-to-all (quadratic) communication; it allows
the consensus set to scale.

## Concepts relatively unique to MonadBFT

The following are concepts that are relatively unique to MonadBFT. We are splitting them out
to aid in comprehension.
For simplicity, we focus on the standard recovery in MonadBFT. The fast recovery optimizations
are explained in the [Fast Recovery](#fast-recovery) section.

### Proposal

A block proposal (often just called *proposal*) consists of the current round number, a block, an optional [TC](#timeout-certificate-tc)
or [NEC](#no-endorsement-message-and-no-endorsement-certificate), and a signature
(from the leader making the proposal) over the previous elements. In the simple case, optional
fields are blank and the round number is the same as the block's round number, such that the proposal
is basically a signed block. Sometimes, a block that failed to get traction gets reproposed; in
that case, the block will still have the round number from when it was first proposed, but the
proposal will have the round number of when it is reproposed.

#### Fresh Proposal

A fresh proposal is a [proposal](#proposal) containing a new block, i.e. one that is not
influenced by prior failed proposals.

A fresh proposal will either:

1. have a round number that is equal to its [QC](#quorum-certificate-qc)'s round number plus 1.
   This is the common case, when leaders are honest and online, and the network does not have
   any abnormal delays.
2. have a [TC](#timeout-certificate-tc) identifying a high QC. This happens when a leader
   recovers from a failed round ([fast recovery](#fast-recovery)).
3. have a [NEC](#no-endorsement-message-and-no-endorsement-certificate). This happens very rarely,
   when a leader recovers from a more complex failure (standard recovery).

#### Reproposal

A reproposal is a [proposal](#proposal) containing a block from a previous fresh proposal that
the current leader is trying to revive or finalize. A reproposal will have a round number
greater than its [QC](#quorum-certificate-qc)'s round number plus 1.

Whether a leader recovering from a failure has to repropose a previous block or not is determined
by the [TC](#timeout-certificate-tc). If the TC contains a high tip (instead of a high QC), then
the block corresponding to the high tip must be reproposed. Reproposals are part of the standard
recovery. In practice, reproposals can often be skipped with fast recovery.

### Tip

A tip is a proposal minus the block's payload. You can think of it as the block header of the
proposal plus a bit of extra metadata, including the round number that that proposal was
received.

In MonadBFT, every validator keeps track of its latest tip, which is updated whenever the validator
votes for a proposal. If the validator votes for a reproposal, the tip is set to the original
proposal, not its reproposal.

### High Tip

Given a set of tips, high tip is just the tip with the highest round number. If there are multiple
such tips, then the tip that builds on the highest QC embedded in it is chosen.

### Timeout Message

A timeout message is a signed attestation that a validator produces when it hasn't received a
valid block from the scheduled leader in the expected time. The timeout message attests to the
lack of a valid block.

Each validator sends the timeout message to all other validators, utilizing all-to-all
communication.

Timeout messages are utilized in other BFT protocols. In MonadBFT, timeout messages include
the sender's [tip](#tip) - additional information about their view of the world which will be
utilized in MonadBFT to recover gracefully from the timeout.
For fast recovery, the timeout message contains the validator's highest QC, if it is of equal
or higher view than the view of the local tip.

### Timeout Certificate (TC)

When a timeout occurs, validators start sending and receiving [timeout messages](#timeout-message).
Each validator accumulates the timeout messages that it receives; if it gets to a supermajority
of such messages, it builds a Timeout Certificate (TC).

The TC includes information on all of the tips from all of the validators contributing timeout
messages. The [high tip](#high-tip) (for standard recovery) is also computed. In most cases, fast
recovery is possible, and the TC contains a high QC instead of a high tip.

### No-Endorsement Message and No-Endorsement Certificate

Under certain conditions, a leader will ask the other validators for the full proposal (block)
corresponding to a tip. If the validator doesn't have it, they will respond with a signed
No-Endorsement Message attesting to this.

If the leader gets a supermajority of No-Endorsement Messages when trying to recover the
proposal of a tip, they can produce a No-Endorsement Certificate - proof that a supermajority
of the network didn't have that proposal.

## Block states due to MonadBFT

Blocks can be in one of three states due to MonadBFT:

1. `Proposed`
2. `Voted`
3. `Finalized`

These are three of the four states that blocks can be in overall within Monad, as mentioned in
[Block States](/monad-arch/consensus/block-states). (The fourth state, `Verified`, is achieved outside of MonadBFT
as a part of [Asynchronous Execution](/monad-arch/consensus/asynchronous-execution).)

Below, we describe how blocks progress through these states.

## Happy Path

The happy path describes the ordinary case of how a block goes from being proposed to being
finalized without any timeouts or failed rounds.

### Scenario

To describe the flow of the happy path, we'll follow the scenario shown in the diagram below.

It is currently [round](#round) `K` and the scheduled [leader](#leader) is Alice. Bob and Charlie
are the next two leaders in the schedule. Alice has last seen [block](#block) `N-1`, so she is
going to propose block `N`.

<img />

<br />

MonadBFT proceeds as follows.

### Round `K`: Alice's proposal

1. **Proposal:** Alice, the designated leader for round `K`, chooses a payload, i.e. a
   list of transactions chosen from her mempool. She builds block `N`, consisting of the
   payload and a QC from the previous proposal (don't worry about this part). Alice sends the
   proposal consisting of that block directly to all other validators.

2. **Voting:** Each validator checks Alice's proposal for validity. If the proposal is valid,
   the validator sends signed votes directly to Bob, the designated leader for round `K+1`, and
   marks block `N` as [`Proposed`](/monad-arch/consensus/block-states#proposed).

3. **QC Formation**: Upon getting a supermajority of votes about Alice's proposal, Bob aggregates
   the votes into a [QC](#quorum-certificate-qc) about Alice's proposal.

### Round `K+1`: Bob's proposal

4. **Proposal:** Bob chooses a payload. Bob combines the payload with the
   [QC](#quorum-certificate-qc) from Alice's proposal to produce a new block, which he sends
   to all other validators.

5. **Voting:** Each validator checks Bob's proposal for validity. If the proposal is valid,
   the validator sends votes directly to Charlie, the designated leader for round `K+2`, and
   marks block `N` as [`Voted`](/monad-arch/consensus/block-states#voted) (and block `N+1` as
   [`Proposed`](/monad-arch/consensus/block-states#proposed).)

   This also means that the block can be **speculatively finalized**. This speculative finality
   will only revert under very specific rare conditions, which also come with accountability.
   [More on this later.](#speculative-finality)

6. **QC Formation**: Upon getting a supermajority of votes about Bob's proposal, Charlie
   aggregates the votes into a [QC](#quorum-certificate-qc) about Bob's proposal. This QC can
   also be thought of a QC-squared on Alice's proposal, since it is a QC attesting to the fact
   that a supermajority received the QC about Alice's proposal.

### Round `K+2`: Charlie's proposal

7. **Charlie's proposal:** As before, Charlie builds a block, consisting of a new payload and
   the [QC](#quorum-certificate-qc) on Bob's proposal. Charlie sends the proposal to everyone.

8. **Voting:** Each validator checks Charlie's proposal for validity. If the proposal is valid,
   the validator sends votes directly to David, the designated leader for round `K+3`, and marks
   block `N` as [`Finalized`](/monad-arch/consensus/block-states#finalized) (and block `N+1` as
   [`Voted`](/monad-arch/consensus/block-states#voted) and block `N+2` as
   [`Proposed`](/monad-arch/consensus/block-states#proposed).)

Although we will stop describing the sequence at this point, the consensus mechanism continues
repetitively. As soon as each validator receives David's proposal (which contains a QC about
Charlie's proposal aka a QC-squared about Bob's proposal), they can mark Bob's proposal as
`Finalized` (and Charlie's as `Voted`). And so on.

This underscores the pipelining aspect of MonadBFT. Every round, a new payload and a new QC
about the previous proposal gets shared, allowing the parent proposal to be speculatively
finalized and the grandparent proposal to be fully finalized. You can see this here:

<img />

<p>Illustrating the pipelined (staggered) nature of MonadBFT. Same diagram as the previous, but zoomed out to include one more round.</p>

## Unhappy Path (Fault Handling)

The unhappy path describes the abnormal case where either the leader fails to send out a valid proposal or
the QC builder (next leader) fails to build a QC.

Understanding the unhappy path is crucial to understanding how the happy path works as well!
The thing that ultimately allows a validator to speculatively finalize a proposal after
receiving the child proposal, or finalize a proposal after receiving the grandchild proposal,
is knowing that the fallback mechanism will still preserve the original proposal.

Here, we will focus on the standard recovery, which is actually the fallback of the fallback
mechanism. In most cases in practice, we can use [fast recovery](#fast-recovery), which substantially
speeds up the time for the protocol to go back to the happy path after a failure occurs.
However, for the protocol as a whole to achieve the tail forking resistance, even in the worst
case of Byzantine failures, we rely on the standard recovery, which we now present.

### Scenario

As before, to describe the flow of the unhappy path, we'll follow a scenario shown in a diagram.

Again, suppose that it is currently round `K` and Alice is the scheduled leader. Bob and
Charlie are the next two leaders in the schedule. Alice has last seen block `N-1`, so she is
going to propose block `N`.

In our example, Alice sends block `N` at round `K`, but Bob fails to send a block at round `K+1`.
This could be because he was offline, or it could be that Alice either sent an invalid block,
or not enough people voted for it.

<img />

### Round `K`: Alice's proposal

1. **Proposal:** Alice, the designated leader for round `K`, chooses a payload and
   builds block `N`, consisting of the payload and a [QC](#quorum-certificate-qc) from the
   previous proposal (again, don't worry about this part).

   Alice sends the proposal directly to all other validators.

2. **Voting:** Each validator checks the proposal for validity and, if valid, sends signed
   votes directly to Bob, the designated leader for round `K+1`. Each validator marks Alice's
   proposal locally as [`Proposed`](/monad-arch/consensus/block-states#proposed).

### When round `K+1` was expected: Bob's missed slot

3. **Bob fails to propose block `N+1`**, so all votes are blackholed and no QC for Alice's
   block is produced.

4. **Everyone sends timeout messages:** After a timeout window, each validator "realizes" that
   round `K` has failed since no QC is formed for Alice's block. Therefore, everyone sends a
   [timeout message](#timeout-message) about block `K` to every other validator. (Note that this
   communication is all-to-all.)

5. **TC assembly**: Upon getting a supermajority of timeout messages, every validator including
   Bob assembles a [TC](#timeout-certificate-tc), proving that round `K` (Alice proposer, Bob
   QC builder) failed. Upon building a TC for `K`, validators advance their round to `K+1`.

### Round `K+1`, as progressed by TC

The TC contains a computed value called [`high_tip`](#high-tip), which (roughly speaking)
is the block header of the latest valid block that any of the validators contributing to
the timeout message have seen. You can think of `high_tip` as the max block observed over
the 2/3 of the stake weight required to sign the TC.

In this specific example, `high_tip` will be the block header of Alice's block.

Under the rules of MonadBFT, the next leader is obligated to either re-propose the block
referenced in `high_tip` of the TC (i.e. Alice's block), or to prove that that block is
unsupported. (We'll discuss this in more detail below.)

Since we are now in Round `K+1`, the next leader is **Bob**. (You might find this ironic, but it
is a necessary consequence of the fact that the protocol cannot distinguish between the
possibility that Bob was offline, and the possibility that either Alice sent an invalid block
or not enough people voted on Alice's block. In either of the latter cases, it would be
unfair to skip Bob.)

6. **(Optional) Requesting Alice's block from other validators**: Bob needs to re-propose Alice's
   block. However, the `high_tip` is only a block header - not the full block body - so if Bob
   doesn't have Alice's block, he can request the full version from the other validators (via
   [blocksync](/monad-arch/consensus/blocksync)).

#### Reproposal case (Bob re-proposes Alice's block)

7. **Reproposal**: If Bob has Alice's block (either due to already receiving it when he
   originally proposed it, or via blocksync) then he proposes it along with the TC justifying
   the re-proposal.

8. **Voting:** Each validator votes on the validity of Bob's reproposal. If the reproposal
   is valid, validators send their votes to the next leader, Charlie.

9. **QC Formation:** Charlie assembles a QC from the votes.

10. **Charlie's proposal:** Charlie builds a block at round `K+2`, consisting of a new payload and
    the QC on reproposal from round `K+1`, and sends the block to everyone. At this point Alice's
    block becomes [`Voted`](/monad-arch/consensus/block-states#voted) to anyone who receives Charlie's block.
    Everyone advances their rounds to `K+2` and the protocol returns to the happy path.

#### Fresh proposal case (Bob proves Alice's block is unsupported)

7. **No-Endorsement of Bob's block**: Recall that in step 6, Bob was allowed to poll
   the other validators for Alice's block. When a validator is polled, if they also don't
   have it, they can send Bob a signed
   [No-Endorsement Message](#no-endorsement-message-and-no-endorsement-certificate) attesting
   to *not* having seen Alice's block. If a supermajority of the validators sign
   No-Endorsement Messages, then Bob may assemble a
   [No-Endorsement Certificate (NEC)](#no-endorsement-message-and-no-endorsement-certificate).

8. **Bob's fresh proposal**: Under the rules of MonadBFT, Bob may skip re-proposing
   Alice's block, and instead make a [fresh proposal](#fresh-proposal) of a new block (at the
   same block height `N`) if he can also supply a NEC.

   It's important to emphasize that Bob is only allowed to skip reproposing Alice's
   block if a supermajority of validators sign the NEC. Otherwise, he is obligated to re-propose.
   This rule helps ensure that Alice's block finalizes even though Bob failed to build a QC for
   Alice's block.

   From this point, consensus proceeds normally, returning to the happy path.

#### No proposal case

There is a third possibility, which is that Bob fails to propose anything at all in round `K+1`.
(This is fairly likely, because he failed to send a block the first time that round `K+1` was
expected.) In this case, a timeout occurs again, this time of round `K+1`, allowing consensus
to move to round `K+2`, Charlie's turn. Charlie then inherits the situation Bob was in in round
`K+1`, i.e. he must either re-propose Alice's block, or prove that Alice's block is unsupported.

More generally, if Charlie (and maybe a few subsequent leaders) also fail to propose anything,
the situation will persist until someone either re-proposes Alice's proposal or proves that it is
unsupported. That's the MonadBFT rule about the `high_tip`, and it ensures that Alice's block
will eventually finalize unless it never should have been supported.

## Discussion

### No-Tail-Forking

In prior implementations of pipelined HotStuff-family consensus protocols, the case where Bob misses his slot results
in Alice's proposal also being rolled back (tail forked). The intuition behind this is: Bob is
the only person responsible for receiving everyone's votes on Alice's proposal, so when he goes
offline, all of those votes are blackholed, making it hard to distinguish between the case
where most validators voted YES for Alice's proposal and the case where most validators
rejected her proposal.

For instance, in [Fast-HotStuff](https://arxiv.org/abs/2010.11454), TCs carry enough information to prove that Bob missed his slot, allowing
Bob  to justifiably propose a block that skips Alice's block, making Alice's
block a casualty. Bob simply re-proposes the same block height as Alice did,
replacing Alice's block in the final blockchain. This is the reason why pipelined HotStuff
consensus mechanisms prior to MonadBFT frequently see pairs of missed slots.

**Tail forking is a serious weakness.** When Alice’s block is proposed, if Bob sees valuable MEV opportunities in it, Bob—as QC builder (next leader)—may refuse to build the QC for Alice’s block and to propose his own block carrying Alice’s QC. In this case, validators cannot detect whether Alice failed to propagate her proposal or Bob refused to build a QC; therefore Bob is given an opportunity in round K+1 to propose a block. Bob can then extract high-value MEV by selecting only preferred transactions, and by reordering or replacing them at will. In other blockchains, unintentionally allowing blocks to be re-mined has resulted in [massive impact](https://ethresear.ch/t/equivocation-attacks-in-mev-boost-and-epbs/15338).

The key to MonadBFT's No-Tail-Forking property lies in the handling of the missed slot
situation. Intuitively speaking, in MonadBFT, [TCs](#timeout-certificate-tc) carry enough
information to propagate the knowledge of the existence of Alice's block forward even when Bob
blackholes all of the votes about it.

When it becomes Bob's turn to propose, he is obliged to re-propose Alice's block (based on the TC,
which includes high\_tip, aka a valid block header for Alice's block) unless he can get a
supermajority (`2f+1`) to attest to *not* seeing Alice's block. The fact that a supermajority
sign the [NEC](#no-endorsement-message-and-no-endorsement-certificate)
is key: even if `f` nodes are Byzantine, that still leaves `f+1` non-Byzantine nodes attesting
to *not* seeing Alice's block, which guarantees that Alice's block should *not* have achieved
quorum since quorum requires `2f+1` votes and there were at least `f+1` non-Byzantine NO votes.

The [MonadBFT paper](https://arxiv.org/abs/2502.20692) provides a far more robust definition
of the protocol, and a formal proof that tail-forking cannot occur.

### Speculative Finality

The other extremely nice property of MonadBFT is one-slot speculative finality.

To explain this, it is first helpful to issue a reminder that a block's state is always from
the perspective of a particular observer. For example, if you receive a QC for a block, then
you can move that block to the [`Voted`](/monad-arch/consensus/block-states#voted) state, but if your friend didn't
receive that QC yet, then she would still consider that block to be in the
[`Proposed`](/monad-arch/consensus/block-states#proposed) state.

The challenge of building a distributed consensus mechanism lies in defining rules that allow
nodes to individually update their state machines in response to messages even while assuming
the worst, i.e. even while assuming that they might be the only one that received that message.

#### After receiving Alice's Proposal

Say that you are Valerie, one of the validators in the network. You receive Alice's proposal;
you run the validity checks on it and they pass, so you mark Alice's proposal as
[`Proposed`](/monad-arch/consensus/block-states#proposed).

Note that you don't know if anyone else has received this proposal, Alice could be being tricky
and have only sent the proposal to you (or to a very small number of nodes) in an attempt to
get you to diverge from everyone else.

#### After receiving Bob's Proposal

Now say you receive Bob's proposal, which carries a QC for Alice's proposal. You run validity
checks on Bob's proposal and they pass, so you mark Alice's proposal as
[`Voted`](/monad-arch/consensus/block-states#voted).

Again, although you now possess proof that a supermajority voted for Alice's proposal, you
should be worried that Bob might be trying to trick you by only sending this to you. You
should be worried that Bob's proposal doesn't reach quorum.

The superpower of MonadBFT is that, due to the complicated set of rules for handling a timeout
described earlier, when you are in Valerie's position of having received Bob's proposal, you
can mostly overpower that fear, at least as it pertains to the status of Alice's proposal. You
may **speculatively finalize** Alice's proposal upon moving it to the `Voted` stage. That is,
you can be confident that Alice's proposal will almost certainly end up being finalized, unless
a very specific set of rare circumstances arises.

Intuitively, this makes sense given what we said above. You, Valerie, possess a QC for Alice's
block, assembled by Bob. That actually means that, from your point of view, Bob was not offline.

And **even if** Bob were *effectively offline* to most people (e.g. he only sent the next
proposal and QC-on-Alice's-block to you), you know that the procedure will be to assemble a
TC; that the `high_tip` in that TC will probably point to Alice's block. Why? Because:

1. the QC in your hands proves that a supermajority (`2f+1`) has seen Alice's block,
2. the TC will also require a supermajority (`2f+1`)
3. So at least `f+1` voters will be common to both the QC and TC, and at most `f` are
   Byzantine, so at least 1 will reference Alice's block.

And if Alice's block makes it into `high_tip`, then Charlie will be forced to re-propose it
(unless he could get a NEC on it, which he can't because that would require
No-Endorsement Messages from a supermajority, when a supermajority already signed a QC on
Alice's block).

So at first glance it seems like we, Valerie, might be able to finalize Alice's block as soon
as we receive a QC on it.

#### The only loophole

It turns out that there is one loophole which prevents us from being so confident. The loophole
arises if *Alice* **equivocated** -- signed a second block `b'` at the same height as the first
block `b` (which we have a QC for), and sent `b'` to a few nodes.

Under those circumstances, in the event where Bob sent his proposal only to us before going
offline, then it is possible that `high_tip` in the resultant TC will resolve to `b'` instead
of `b`. If that were to happen, then Charlie could end up either re-proposing `b'`, or
collecting an NEC on `b'` and using that to justify proposing a new block at Alice's block
height.

In practice, this loophole is extremely rare for several reasons:

1. Equivocation is an easily provable fault - all you need as evidence is both blocks at the
   same height both signed by Alice. Equivocation is a huge deal in blockchains, and can be
   severely punished.

2. When Alice equivocates, she is only potentially disrupting herself (while also exposing
   herself to punishment for equivocation).

The [MonadBFT paper](https://arxiv.org/abs/2502.20692) provides a much more rigorous version
of this argument. But in summary, locally observing a QC (moving a proposal to `Voted`) is a
very strong indicator that the proposal will finalize, since the only way it won't is if Alice
equivocated, Bob missed his slot, almost 1/3 of the network was Byzantine, and we still got
quite unlucky with respect to which nodes ended up populating the TC.

## Fast Recovery

Since releasing the original [MonadBFT paper](https://arxiv.org/abs/2502.20692) in early 2025,
Category Labs has analyzed the protocol’s behavior and designed, evaluated, and implemented
several improvements.
The protocol changes allow for fast recovery in the most common failure scenarios.
This [blog post](https://www.category.xyz/blogs/monadbft-update-fast-recovery-leader-fault-isolation) gives a great introduction to how fast recovery
works. In summary:

* Validators now send their votes not only to the leader of the next view, but also to the leader of
  the current view. This gives each leader a chance to collect votes for its own proposal to
  form a QC, rather than relying solely on the next leader (who may be Byzantine). The leader
  broadcasts this QC.
* Validators can include the highest QC that they have observed in their timeout message, instead
  of the tip. They do so if the QC is fresher (more recent) than the locally highest tip or produced in the same
  round as the tip.
* If a validator sends a tip (instead of a high QC) in a timeout message, the validator also
  includes a tip vote, i.e., a vote for that tip with the current view number. `2f+1` votes
  for the same proposal in the same view, obtained via regular votes or timeout messages can be
  combined to form a new QC that can directly be extended by the next leader.
* The timeout certificate includes the highest QC of the received timeout messages if it is at least
  as high as the highest tip. It also contains proof that the correct high tip or high QC was chosen.
  If the TC contains the high QC, then the leader can directly propose a fresh block extending that high QC.

These mechanisms enable faster recovery in the most common failure scenarios. For example, consider a
situation where the leader in view `v` is offline. In the original MonadBFT protocol, this would cause
views `v-1` and `v` to time out (since the votes cast in `v-1` are lost, and no block is proposed in
view `v`). Additionally, the block proposed in view `v-1` would have to be reproposed in view `v+1`,
resulting in two consecutive views without a fresh block proposal.

With the updated protocol, several mechanisms enable faster recovery. For instance, in the timeout
message of view `v`, each validator includes a tip vote for the block proposed in view `v-1`. This
allows the leader of view `v+1` to construct a QC in view `v`. Since no two conflicting QCs can be
formed in the same view, the leader of `v+1` can directly propose a fresh block extending this QC.
As a result, a single crashed leader only causes the leader's view to time out; all other views
succeed, and in each of them, a fresh block is proposed.

The other mechanisms similarly provide fast recovery options. We still retain the reproposal and
[NEC](#no-endorsement-message-and-no-endorsement-certificate)
mechanisms from the original MonadBFT paper to address more complex Byzantine failures. However,
with these improvements, we believe most failures can now be handled smoothly via the new fast
recovery paths.

***

## References

* Mohammad Mussadiq Jalalzai, Kushal Babel.
  [MonadBFT: Fast, Responsive, Fork-Resistant Streamlined Consensus](https://arxiv.org/pdf/2502.20692), 2025.
* Maofan Yin, Dahlia Malkhi, Michael K. Reiter, Guy Golan Gueta, and Ittai Abraham.
  [HotStuff: BFT Consensus in the Lens of Blockchain](https://arxiv.org/abs/1803.05069), 2018.
* Mohammad M. Jalalzai, Jianyu Niu, Chen Feng, Fangyu Gai.
  [Fast-HotStuff: A Fast and Resilient HotStuff Protocol](https://arxiv.org/abs/2010.11454), 2020.
* Rati Gelashvili, Lefteris Kokoris-Kogias, Alberto Sonnino, Alexander Spiegelman, and Zhuolun Xiang.
  [Jolteon and ditto: Network-adaptive efficient consensus with asynchronous fallback](https://arxiv.org/pdf/2106.10362.pdf).
  arXiv preprint arXiv:2106.10362, 2021.
* The Diem Team.
  [DiemBFT v4: State Machine Replication in the Diem Blockchain](https://developers.diem.com/papers/diem-consensus-state-machine-replication-in-the-diem-blockchain/2021-08-17.pdf), 2021.


# Peer Discovery
Source: https://docs.monad.xyz/monad-arch/consensus/peer-discovery



## Summary

Peer discovery enables a new validator or full node to join the network by connecting with
other existing nodes, in order to receive consensus messages necessary to validate and
keep up to the chain tip.

To participate in peer discovery, a node needs to generate a `MonadNameRecord`, which
contains a name record and a signature over that record using its secp key.

```rust theme={null}
struct MonadNameRecord {
  name_record: NameRecord,
  signature: SecpSignature,
}
```

A `NameRecord` contains the node's IPv4 address, port information, and a sequence number.
Currently only IPv4 addresses are supported. There are two wire formats: a legacy format
with a single port shared across protocols, and a newer format that supports multiple ports
tagged by protocol (TCP, UDP, AuthenticatedUDP) along with a capabilities field. The newer
format is used by nodes that have opted into
[authenticated UDP](/node-ops/upgrade-instructions/auth-udp).

The IP address and ports describe the network endpoints at which other nodes in the network may
contact it. A sequence number is necessary to ensure newer name records take priority over older
name records. For example, when a node sees a peer's name records with a higher sequence number,
it will update its routing table with the new name record.

A node specifies a few bootstrap nodes and their name records when starting up. Bootstrap
nodes are not specialized nodes; any node in the network can be a bootstrap node. The
node will then advertise its own name record by sending pings to other peers, where the
ping message contains its own name record. The node also sends lookup request to its peers
when it is missing name records of current active validators. Periodically, the node looks
for new nodes or prunes excessive nodes depending on the min and max number of peers
configured.


# RaptorCast
Source: https://docs.monad.xyz/monad-arch/consensus/raptorcast

Multicast message delivery protocol used for block propagation

## Summary

RaptorCast is a specialized multicast message delivery protocol used in [MonadBFT](/monad-arch/consensus/monad-bft) to send block proposals from leaders to validators. Block proposals are converted into erasure-coded chunks using the Raptor code in [RFC 5053](https://datatracker.ietf.org/doc/html/rfc5053). Each chunk is sent to all validators through a two-level broadcast tree, where the first level is a single non-leader node. Each non-leader node is responsible for serving as the first-level node for a different set of chunks; the proportion of chunk assignments is equal to the validator's stake weight.

RaptorCast thus utilizes the full upload bandwidth of the entire network to propagate block proposals to all validators, while preserving Byzantine fault tolerance.

<Tip>
  Check out this [**blog post**](https://www.category.xyz/blogs/raptorcast-designing-a-messaging-layer) by Category Labs for a full briefing on RaptorCast's data transmission, erasure coding, and broadcast strategy.
</Tip>

## Introduction

<Info>
  The technical description of RaptorCast below relates to block propagation amongst **validator** nodes participating in consensus. In particular, [block propagation to full nodes](#secondary-raptorcast---full-node-block-propagation) is handled differently.
</Info>

In MonadBFT, leaders need to send block proposals to every validator. Getting block proposals from a leader to the rest of the network is one of the challenging problems in high-performance distributed consensus because block proposals are large and the network is not reliable.

Consider the following two naive approaches to addressing this problem:

1. Sending messages directly from the leader to each validator. This is the simplest approach, but it would impose very high upload bandwidth requirements for a leader because block proposals are large - for example, 10,000 transactions at 200 bytes per transaction is 2MB.

2. Sending messages from the leader to a few peers, who each re-broadcast to a few peers. This approach would reduce the upload bandwidth requirements for the leader, but it would increase maximum latency to all of the nodes, and it risks message loss if some of the peers are Byzantine and fail to forward the message.

RaptorCast is the multicast message delivery protocol that solves this problem, offering the best tradeoff between bandwidth requirements, latency, and fault-tolerance. RaptorCast was developed specifically for MonadBFT, and satisfies the following requirements.

In the below discussion, the "message" is the block proposal, and the "message originator" is the leader.

## Design requirements

* Reliable message delivery to all participating consensus nodes is guaranteed if a `2/3` supermajority of the stake weight is non-faulty (honest and online).

* Upload bandwidth requirements for a validator are linearly proportional to message size and are independent of the total number of participating validators.[^1]

[^1]: This holds when participating validators are (approximately) equally staked. In situations with (very) unevenly distributed stake weights, we need to deviate from the equal-upload property in order to maintain reliable message delivery for every possible scenario where two-thirds of the stake weight corresponds to non-faulty nodes.

* The worst-case message propagation time is twice the worst-case one-way latency between any two nodes. In other words, the propagation of a message to all intended recipients happens within the round-trip time (RTT) between the two most distant nodes in the network.

* Messages are transmitted with a configurable amount of redundancy (chosen by the node operator). Increased redundancy mitigates packet loss and reduces message latency (recipient can decode sooner and more quickly).

## How RaptorCast works

### Erasure coding

Messages are erasure-coded by the message originator. Erasure coding means that the message is encoded into a set of chunks, and the message can be decoded from any sufficiently-large subset of the chunks.

The specific code used by RaptorCast is a variant of the Raptor code documented in [RFC 5053](https://datatracker.ietf.org/doc/html/rfc5053), with some Monad-specific modifications to

* improve the encoding efficiency of small messages
* reduce the computational complexity of message encoding (at the cost of a slight increase in decoding complexity)

### Message and chunk distribution model

RaptorCast uses a two-level broadcast tree for each chunk. The message originator is the root of the tree, a single non-originator node lives at level 1, and every other node lives at level 2.

Each chunk of the encoded message potentially corresponds to a different broadcast tree, but the current implementation uses the same broadcast tree for contiguous ranges of the encoded message chunk space.

The following diagram illustrates this chunk distribution model:

<img alt="RaptorCast Broadcast Tree" />

<p>Generic view of the two-hop Raptorcast broadcast tree.</p>

Using a two-level broadcast tree minimizes latency for message delivery. Each level of the tree has worst-case latency of the one-way latency between any two nodes in the network (the network’s “latency diameter”), so the worst case delivery time under RaptorCast is the round-trip-time of the network.

### Fault tolerance

<Info>
  RaptorCast runs directly over UDP, with a single message chunk per UDP packet.
</Info>

Note that the broadcast tree is unidirectional. Unlike TCP, RaptorCast does not include a recovery mechanism for downstream nodes in the tree to detect packet loss and request retransmission, since this would violate latency expectations. To compensate, RaptorCast transmits the message in a redundant fashion, with a redundancy factor chosen by the message originator based on the network’s expected packet loss.

For example, under the following assumptions:

* 20% network packet loss
* maximum 33% of the network is faulty or malicious

then the message originator should expect in the worst case that (1 - 0.2) \* (1 - 0.33) or \~53.6% of chunks reach the intended destination. To offset that worst case loss, the originator should send 1 / 0.536 - 1 or roughly 87% *additional* chunks.

The default [MTU](https://en.wikipedia.org/wiki/Maximum_transmission_unit) used is 1480 bytes. After subtracting RaptorCast header overhead for the default Merkle tree depth of 6, this leaves 1220 bytes per packet for an encoded Raptor payload.  A 2 MB block maps to 2e6 / 1220 = 1640 source chunks. Using the current redundancy factor of 2.5, 4100 encoded chunks will then be distributed to other validators by proportionate stake weight.

If there are 100 validators, those 4100 encoded chunks will be divided into 99 (the originator is excluded) distinct chunk ranges and the leader will initiate a broadcast tree for each validator corresponding to its unique chunk range (and payload). If the validators had equal stake, each would receive 4100 / 99 = 41 chunks in contiguous ranges.

<img alt="RaptorCast encoding and redundancy" />

<p>A 2 MB block is split into chunks, expanded and disseminated.</p>

Note that the two-stage distribution model allows participating consensus nodes to receive a copy of a message even if direct network connectivity with the message originator is intermittently or entirely faulty.

<img alt="Block proposal" />

<p>RaptorCast used to send erasure-encoded chunks from a leader to each validator.</p>

The message originator (leader) typically[^2] distributes generated chunks to the first-hop recipients according to stake weight. For example:

* Validator 1 has stake 1
* Validator 2 has stake 2
* Validator 3 has stake 3
* Validator 4 has stake 4

When Validator 1 is the leader, they will send:

* 2 / (2 + 3 + 4) of generated chunks to validator 2
* 3 / (2 + 3 + 4) of generated chunks to validator 3
* 4 / (2 + 3 + 4) of generated chunks to validator 4

The leader *currently* sends chunks in contiguous ranges but development work is currently being done to enable dissemination at a more granular level. With the new algorithm, individual or much smaller sets of chunks would be sent randomly to first-hop validators without replacement, weighted by stake. This approach produces better utilization of the network as all validators can start processing chunks as they arrive and send for redistribution (start the second-hop).

[^2]: The pure stake-weighted distribution scheme can break down when the number of required chunks is sufficiently small, e.g. 12 chunks distributed to 100 validators. This corner case is actively being addressed.

### Chunk transport integrity

The originator signs every encoded chunk, so intermediate nodes (level one) in the broadcast tree can verify the integrity of an encoded chunk before forwarding it.

Furthermore, the number of source chunks `K` is encoded in the message. For given `K`, the recipient currently accepts encoded chunks in the range of 0 to `7 * K - 1`. This gives the originator sufficient freedom to specify a high degree of redundancy (up to 7), while also limiting the potential for network spam by a rogue validator.

To amortize the cost of generating and verifying these signatures over many chunks, RaptorCast aggregates contiguous ranges of encoded message chunks in variable-depth Merkle trees, and produces a single signature for every Merkle tree root.

## Other uses of RaptorCast

RaptorCast is not only used for broadcasting a block in chunks from the leader.

### Transaction forwarding

Transaction forwarding, e.g. from a full node to the next three validator hosts, is
performed via RaptorCast, benefiting from its properties of speed and robustness. In this
context, only one hop is required - the receiver should not rebroadcast.

### Secondary RaptorCast - full node block propagation

RaptorCast is also used to disseminate block proposals to full nodes. As described in
[full node configurations](/node-ops/full-node-block-delivery), each participating
validator creates a secondary RaptorCast network rooted in itself, utilizing full nodes
as the recipients. Full nodes are added to a validator's secondary RaptorCast group
if they are **prioritized** by the validator, or if they are running in **public** mode and
are selected by the selection algorithm.

<img alt="Dissemination to full nodes" />

<p>Each validator, after reconstructing the proposal, can disseminate all received (or produced) chunks to full nodes via dedicated relationship or secondary RaptorCast.</p>

Secondary RaptorCast mirrors the primary RaptorCast diagram above. Under secondary
RaptorCast, the originator is now *any* validator, and the group receiving chunks is a collection
of public and prioritized full nodes, rather than the stake-weighted validator set. All
full nodes in secondary RaptorCast receive an equal number of chunks (no stake-weight applicable).

In terms of bandwidth, secondary RaptorCast is much more efficient than dedicated full nodes,
because the upload bandwidth requirement for the validator is constant, rather than scaling
linearly for the number of dedicated full nodes. Similar to primary RaptorCast, by adding a
second hop, the burden of dissemination is borne more evenly by the participants in the group.


# Staking
Source: https://docs.monad.xyz/monad-arch/consensus/staking

How Monad's staking system works

Monad uses staking to determine validator voting weights and each epoch's leader schedule in [MonadBFT](/monad-arch/consensus/monad-bft). Validators must stake at least a minimum amount, and others can delegate to them.

For a developer-oriented guide to interacting with the staking precompile, see the documentation [overview](/reference/staking/overview) and [API](/reference/staking/api).

## Validator set

To be part of the active validator set, a validator must meet all of the following criteria:

* **Self-delegation:** the validator's `authAddress` must have self-delegated at least `MIN_AUTH_ADDRESS_STAKE` (100,000 MON)
* **Total stake:** the validator must have total delegation of at least `ACTIVE_VALIDATOR_STAKE` (10,000,000 MON)
* **Rank:** the validator must be in the top `ACTIVE_VALSET_SIZE` (200) validators by stake weight

Validators that fall below these thresholds are removed from the active set at the next epoch boundary.

## Rewards and commission

When a block is produced, the leader who produced it earns a block reward from two sources:

1. **Inflationary reward** — a fixed `REWARD` of 25 MON per block, minted by the protocol
2. **Priority fees** — the priority fees from all transactions in the block

### Commission

Each validator sets a commission rate (0%–100%) that determines what fraction of the inflationary block reward they keep before distributing the remainder to delegators.

The remainder is distributed **pro rata** by stake weight. As a delegator, your share of a block's reward is proportional to your stake relative to the validator's total stake.

**Example:** Suppose you have delegated to a validator and comprise 20% of that validator's total stake. The inflationary block reward is 10 MON and the commission is 10%. You receive:

> 10 MON × 90% × 20% = **1.8 MON**

### Priority fees

Currently, priority fees go only to the validator. Validators may choose to share priority fees with delegators (including themselves) by calling the [`externalReward`](/reference/staking/api#externalreward) method on the staking precompile. Commission is **not** deducted from external rewards.

### Claiming and compounding

Each delegation accumulates rewards over time. Delegators can either:

* **Claim** rewards — withdrawn to the delegator's account immediately
* **Compound** rewards — added to the delegation, increasing stake weight (follows the standard epoch timing rules described below)

## Epochs and boundaries

An **epoch** uses one set of delegations and leader validators for its entire duration.

Every 50,000 blocks (the `BOUNDARY_BLOCK_PERIOD`) is a **boundary block** that commits the upcoming staking changes and the validator set to be used in the next epoch. Boundary blocks happen approximately every 5.5 hours. The next epoch does not start immediately at the boundary block, but after a 5,000-round delay (`EPOCH_DELAY_ROUNDS`) to allow all nodes to update their epoch information.

<img alt="timeline showing the placement of boundary blocks within an epoch" />

### Timing of staking actions

Most staking actions take effect after they are committed in a boundary block and the next epoch starts. The exceptions are `claimRewards()` and `externalReward()`, which take effect immediately.

As an example, consider `delegate()` during epoch #4:

* If the `delegate()` takes place before the boundary block for epoch #5, the stake will be included in epoch #5.
* If the `delegate()` transaction is in the boundary block itself, it will not be included in epoch #5 (the snapshot is taken at the start of the block, before user transactions). The delegation will be picked up in the boundary block for epoch #6.
* If the `delegate()` transaction is after the boundary block but before the end of epoch #4, the delegation will take effect in epoch #6.

<Note>
  The `BOUNDARY_BLOCK_PERIOD` is denominated in **blocks**, while `EPOCH_DELAY_ROUNDS` is denominated in **rounds**. If perfect consensus is achieved, these increment at the same rate. However, upon a failed block proposal (e.g. timeout), the round increments while the block does not.
</Note>

## Execution, snapshot, and consensus views

The staking system maintains three views that staking state passes through:

1. **Execution view** — the real-time state. When validators are added, delegations change, or any staking transaction happens, the execution view is updated immediately.

2. **Snapshot view** — at the start of each boundary block, the current execution view is copied into the snapshot view. Any transaction changes after this point will not affect the following epoch. The snapshot now matches what the next epoch will look like.

3. **Consensus view** — after `EPOCH_DELAY_ROUNDS` (5,000 rounds) from the boundary block, the new epoch starts and the snapshot view is copied into the consensus view. The consensus view holds the validators and voting stake weights being used by the consensus system for the remainder of the epoch.

## Slashing

Robust logging provides accountability for malicious, slashable offenses. However, automated in-protocol slashing is not currently implemented.

## Constants

| Constant                 | Meaning                                                                 | Value          |
| ------------------------ | ----------------------------------------------------------------------- | -------------- |
| `BOUNDARY_BLOCK_PERIOD`  | Blocks from boundary block to boundary block                            | 50,000 blocks  |
| `EPOCH_DELAY_ROUNDS`     | Rounds between the boundary block and the start of each epoch           | 5,000 rounds   |
| `WITHDRAWAL_DELAY`       | Number of epochs before unstaked tokens can be withdrawn                | 1 epoch        |
| `MIN_AUTH_ADDRESS_STAKE` | Min MON self-delegated by a validator to be eligible for the active set | 100,000 MON    |
| `ACTIVE_VALIDATOR_STAKE` | Min total MON staked with a validator for active set eligibility        | 10,000,000 MON |
| `ACTIVE_VALSET_SIZE`     | Number of validators in the active set                                  | 200            |
| `REWARD`                 | MON reward per block                                                    | 25 MON         |


# Statesync
Source: https://docs.monad.xyz/monad-arch/consensus/statesync

Mechanism for synchronizing MonadDb state

## Summary

Statesync is the process for synchronizing state to a target block close to the current tip. A synchronizing node ("client") requests data from other up-to-date validators ("servers") to help it progress from its current view to its target view; the servers rely on metadata in MonadDb to efficiently respond to the request.

Since the current tip is a moving target, following completion of statesync, the client makes another statesync request to get closer to the current tip, or replays queued blocks if within striking distance.

## Approach

Statesync is the process of synchronizing state stored in [MonadDb](/monad-arch/execution/monaddb) to a target block close to the current tip.

The current tip is a moving target, so as statesync is running, the syncing node stores new blocks beyond the target block and, upon completion of statesync, replays these additional blocks through normal execution to catch up to the current tip. The target block may be updated several times during this process.

Statesync follows a client-server model, where the statesync requester is the client and the validator node servicing a statesync request is the server.

## Data included in statesync

MonadDb stores a variety of data relating to the execution of blocks. However, only a subset is required for full participation in the active set and thus included in statesync:

* accounts, including balances, code, and storage
* the last 256 block headers (to verify correctness)

In an effort to evenly distribute load, each of the aforementioned is spliced into chunks. The client assigns each chunk to a server who remains the peer for that chunk until synchronization is complete.

Servers are randomly selected from the list of available peers. The client maintains a certain number of sessions up to a configured maximum. In the event that servers are unresponsive, the client’s statesync request will timeout and request from a different server.

## Versioning and verification

For efficiency, the client requests state from least- to most-recently updated, converging on the tip near the end of the process. Servers serve diffs relative to the client's latest block.

<img alt="statesync_requests" />

In the example above, the statesync client makes three consecutive requests to the statesync server assigned to prefix p. For each request, there are five parameters specified:

* `prefix` - the prefix of the Merkle Patricia Trie
* `i` - the start block number
* `j` - the end block number
* `target` - the target block number
* `last_target` - last target block number, this is used to deduce deletions to send

Because there may be multiple rounds of statesync (as statesync occurs, the chain is progressing and the target block may need to adjust), `j` is buffered by some offset B from the target block to avoid retransmitting most recently used nodes in the MPT.  When `i` and `target` block are sufficiently close, as in the last round above, the statesync client will request `j = target`.

At this point, if `target` is less than `statesync_threshold` (600 blocks by default) from the tip of the chain, statesync is concluded and the state root will be validated. Any remaining blocks between `target` and tip are then synced via [blocksync](/monad-arch/consensus/blocksync). If `target` is greater than `statesync_threshold` blocks from the tip of the chain, a new round of statesync will begin.

During block execution, the server stores the version alongside node contents. As such, upon receipt of a statesync request, the server is able to quickly narrow down the relevant subtrie and submit read requests, which are embarrassingly parallel.

## Trust assumptions

Statesync clients trust that the requested data (including state root and parent hash) from statesync servers is correct. This is currently sampled randomly from the validator set according to stakeweight, but clients can optionally whitelist specific known providers as statesync servers.

The current implementation validates the data transmitted when the whole transfer is complete by comparing the state root. Because the work is split between multiple servers, a single server sending invalid data can cause a state root mismatch, without attribution to the faulty server. The only recourse in this situation is to retry the whole transfer, giving the faulty server an opportunity to fail the operation again.

Changes are currently being implemented to verify the data transmitted on a per-server basis. In the event of a faulty server sending invalid data, the statesync client can discard and retry *only* the affected prefix. Further, it can identify the faulty server, log the error and potentially blacklist it from subsequent requests.


# Transport Protocol Usage
Source: https://docs.monad.xyz/monad-arch/consensus/transport-protocols

Overview of transport protocol usage for node communication

Monad nodes use both TCP and UDP protocols for different types of communication.

| Traffic Type                                                                                                | Protocol |
| ----------------------------------------------------------------------------------------------------------- | -------- |
| [Primary RaptorCast](/monad-arch/consensus/raptorcast)                                                      | UDP      |
| [Secondary RaptorCast](/monad-arch/consensus/raptorcast#secondary-raptorcast---full-node-block-propagation) | UDP      |
| [Peer Discovery](/monad-arch/consensus/peer-discovery)                                                      | UDP      |
| [Transaction Forwarding](/monad-arch/consensus/local-mempool)                                               | UDP      |
| [Block Forwarding to Dedicated Full Nodes](/node-ops/full-node-block-delivery#dedicated-upstream)           | UDP      |
| [Blocksync](/monad-arch/consensus/blocksync)                                                                | TCP      |
| [Statesync](/monad-arch/consensus/statesync)                                                                | TCP      |


# Execution
Source: https://docs.monad.xyz/monad-arch/execution/index



<CardGroup>
  <Card title="Parallel Execution" href="/monad-arch/execution/parallel-execution">
    Optimistic parallel execution
  </Card>

  <Card title="MonadDb" href="/monad-arch/execution/monaddb">
    Custom database for storing the Ethereum Merkle Patricia Trie natively on SSD
  </Card>

  <Card title="JIT Compilation" href="/monad-arch/execution/native-compilation">
    High-performance execution of EVM bytecode by compiling to machine code
  </Card>
</CardGroup>


# MonadDb
Source: https://docs.monad.xyz/monad-arch/execution/monaddb

High-performance database for storing blockchain data.

## Summary

MonadDb is a critical component in Monad for maintaining full Ethereum compatibility while delivering high performance. It is a custom-built key-value database designed for storing authenticated blockchain data. MonadDb, specifically, is optimized for efficiently storing Merkle Patricia Trie nodes on disk.

## Merkle Patricia Trie Structured Database

Most Ethereum clients use generic key-value databases that are implemented as either B-Tree (e.g. [LMDB](https://www.symas.com/lmdb)) or LSM-Tree (e.g. [LevelDB,](https://github.com/google/leveldb) [RocksDB](https://rocksdb.org/)) data structures. However Ethereum uses the [Merkle Patricia Trie](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie/) (MPT) data structure for storing state and other authenticated fields like receipts and transactions. This results in a suboptimal solution where one data structure is embedded into another data structure. MonadDb implements a [Patricia Trie](https://en.wikipedia.org/wiki/Radix_tree) (a specific variant of radix tree) data structure natively, both on-disk and in-memory. Despite the opinionated design, MonadDb is a flexible key-value store capable of storing any type of data. For instance, MonadDb is also used to store block headers and payloads for Monad.

## Asynchronous IO

Monad executes multiple transactions in [parallel](/monad-arch/execution/parallel-execution). In order to enable this, reads should not block continued operation, and this goal motivates [asynchronous I/O](/monad-arch/concepts/asynchronous-io) (async I/O) for the database. The above-mentioned key-value databases lack proper async I/O support (although there are some efforts to improve in this area). MonadDb fully utilizes the latest kernel support for async I/O (on Linux this is [io\_uring](https://unixism.net/loti/index.html)). This avoids spawning a large number of kernel threads to handle pending I/O requests in an attempt to perform work asynchronously.

## Filesystem bypass

Modern filesystems provide a convenient abstraction for applications, but introduce overhead when building high-throughput I/O software. These often hidden costs include block allocation, fragmentation, read/write amplification, and metadata management. The abstraction of files and a set of system calls allows applications to interact with the file data as if it were stored contiguously. The complexity of managing exact physical disk locations is abstracted away from the applications (and their developers). However, the actual content on disk might be fragmented into multiple non-contiguous pieces.  Accessing or writing to such a file usually involves more than one simple I/O operation.

To minimize overhead, MonadDb provides operators the option to bypass the filesystem. MonadDb implements its own indexing system based on the Patricia trie data structure, eliminating filesystem dependencies. Users have the flexibility to operate MonadDb on either regular files or block devices. For optimal performance, it is recommended to run MonadDb directly on block devices. This approach avoids all filesystem-related overhead, allowing MonadDb to fully unlock SSD performance.

## Concurrency Control

The Monad blockchain consists of multiple clients, each interacting with the database as either reader or writer. To support this functionality, MonadDb must efficiently synchronize between a single writer (execution) and multiple readers (consensus and RPC).

MonadDb implements a persistent (or immutable) Patricia trie. When a branch in the trie is updated, new versions of the nodes on that branch are created, and the previous version of the trie is preserved. This approach facilitates versioning within the database and significantly simplifies synchronization between readers and the writer. It ensures that all reads are accurate and consistent while guaranteeing that writes are both complete and atomic from the perspective of the readers.

## Write Performance on Modern SSD

The usage of a persistent data structure also allows us to perform sequential writes, which offers better performance than random writes on modern SSDs. Modern SSD garbage collection occurs at the block level. On sequential writes, an entire block gets filled before the next one, which dramatically simplifies garbage collection. Garbage collection is much more expensive for random writes. Sequential writes also distribute data more efficiently, thereby reducing write amplification and increasing SSD longevity.

## Compaction

As historical versions accumulate, the amount of data written to disk will grow. Given the limited disk capacity it operates on, it is impossible to retain complete historical records. MonadDb stores recent versions of blockchain data and state and dynamically adjusts the history length based on available disk space. As newer versions are stored and older versions are pruned, the underlying storage space becomes fragmented. To address this, MonadDb performs compaction inline with updates, consolidating active data and releasing unused storage for recycling. This reduces fragmentation while maintaining performance and data integrity.


# JIT Compilation
Source: https://docs.monad.xyz/monad-arch/execution/native-compilation

High-performance execution of EVM bytecode by compiling to machine code.

## Summary

Executing each EVM contract call to completion as quickly as possible is a key part of Monad’s overall performance. To do this, Monad uses both a highly optimized interpreter and a bespoke native-code compiler. The compiler analyzes frequently used contracts once and caches native code so subsequent calls execute more efficiently while preserving exact EVM semantics (including gas and error behavior).

## Interpreting vs. Compiling

Most Ethereum clients execute smart contract code one instruction at a time, checking stack bounds and available gas before applying the instruction’s semantics. This is an *interpreter*. Interpreters are straightforward to build and maintain, have low startup latency, and can perform very well when implemented with modern techniques.

An alternative is to *compile* programs. Before execution begins, code is analyzed and transformed into a representation that executes more efficiently. Compilation adds upfront latency and complexity, but it happens once per contract version. If repeated executions are faster, overall system performance improves.

For simplicity and portability, many compilers target a higher-level *intermediate representation* (e.g., [LLVM IR](https://llvm.org/) or [Cranelift](https://cranelift.dev/)). Because the Monad client targets a specific hardware configuration, the compiler emits native [x86-64](https://en.wikipedia.org/wiki/X86_assembly_language) directly to maximize control and performance while still matching EVM behavior exactly.

## Eliminating Redundant Work

Compilation lets us precompute behavior ahead of time. Consider this straight-line fragment:

```
JUMPDEST
PUSH1 0x1
ADD
PUSH0
JUMP
```

Once execution reaches the `JUMPDEST`, it must proceed through `PUSH1`, `ADD`, `PUSH0` and `JUMP`. A pure interpreter would charge gas and perform checks for each instruction as it executes. A compiler can recognize the straight-line block and perform a single upfront gas check for the combined cost of the block (subject to EVM rules), then emit code that runs the block without per-instruction bookkeeping. The result is fewer CPU instructions while preserving identical gas accounting and out-of-gas semantics.

[Constant folding](https://en.wikipedia.org/wiki/Constant_folding) is another example. Given:

```
PUSH1 0x2
PUSH1 0x3
ADD
```

the compiler can determine the stack state at ADD and fold it to:

```
PUSH1 0x5
```

internally, while still charging the same total gas as the original sequence and maintaining 256-bit modular arithmetic semantics.

## Optimizing Code

Beyond removing redundant work, the compiler chooses efficient implementations based on where operands reside. It maintains a *simulated EVM stack* that maps each 256-bit stack word to a location on the machine: main memory, a set of general-purpose integer registers, or a single AVX vector register. This approach is a combination of [register allocation](https://en.wikipedia.org/wiki/Register_allocation) in a traditional optimizing compiler and [stack caching](https://dl.acm.org/doi/abs/10.1145/223428.207165) techniques for compiling stack-based languages.

Each EVM instruction is then specialized to the operand locations it sees. For example, `AND` can be implemented with a single [x86 `vpand`](https://www.felixcloutier.com/x86/pand) when both arguments are already in AVX registers. Much of the compiler’s effectiveness comes from emitting specialized sequences for common operand-location combinations.

## Compilation Performance

Compiling every contract ahead of time is impractical. Instead, the compiler tracks contracts by cumulative gas consumed over all executions and caches native code for the “hottest” ones. As blocks execute, newly hot contracts enter a compile queue. Compilation runs asynchronously, and contracts that are not yet compiled (or never become hot) continue to run on the highly optimized interpreter. The cache ensures repeated calls to popular contracts benefit from compilation without blocking execution on compile latency.


# Parallel Execution
Source: https://docs.monad.xyz/monad-arch/execution/parallel-execution



## Summary

Monad executes transactions in parallel.  While at first it might seem like this implies different execution semantics than exist in Ethereum, it actually does not.  Monad blocks are the same as Ethereum blocks - a linearly ordered set of transactions.  The result of executing the transactions in a block is identical between Monad and Ethereum.

## Optimistic Execution

At a base level, Monad uses optimistic execution. This means that Monad will start executing transactions before earlier transactions in the block have completed.  Sometimes (but not always) this results in incorrect execution.

Consider two transactions (in this order in the block):

1. Transaction 1 reads and updates the balance of account A (for example, it receives a transfer from account B).
2. Transaction 2 also reads and updates the balance of account A (for example, it makes a transfer to account C).

If these transactions are run in parallel and transaction 2 starts running before transaction 1 has completed, then the balance it reads for account A may be different than if they were run sequentially.  This could result in incorrect execution.

The way optimistic execution solves this is by tracking the inputs used while executing transaction 2 and comparing them to the outputs of transaction 1.  If they differ, we have detected that transaction 2 used incorrect data while executing and it needs to be executed again with the correct data.

While Monad executes transactions in parallel, the updated state for each transaction is "merged" sequentially in order to check the condition mentioned above.

Related computer science topics are [optimistic concurrency control](https://en.wikipedia.org/wiki/Optimistic_concurrency_control) (OCC) and [software transactional memory](https://en.wikipedia.org/wiki/Software_transactional_memory) (STM).

## Optimistic Execution Implications

In a naïve implementation of optimistic execution, one doesn't detect that a transaction needs to be executed again until earlier transactions in the block have completed.  At that time, the state updates for all the earlier transactions have been merged so it's not possible for the transaction to fail due to optimistic execution a second time.

There are steps in executing a transaction that do not depend on state. An example is signature recovery, which is an expensive computation.  This work does not need to be repeated when executing the transaction again.

Furthermore, when executing a transaction again due to failure to merge, often the account(s) and storage accessed will not change.  This state is still be cached in memory, so again this is expensive work that does not need to be repeated.

## Further Work

There are other opportunities to avoid re-executing transactions which are still being explored.


# Monad Architecture
Source: https://docs.monad.xyz/monad-arch/index



This section surveys Monad's major architectural innovations.

<CardGroup>
  <Card title="Concepts" href="/monad-arch/concepts">
    Explaining high level themes (async io and pipelining) that recur in Monad
  </Card>

  <Card title="Consensus" href="/monad-arch/consensus">
    Algorithms for maintaining a globally distributed, decentralized validator set
  </Card>

  <Card title="Execution" href="/monad-arch/execution">
    Algorithms for executing EVM transactions efficiently
  </Card>

  <Card title="Real-time Data" href="/monad-arch/realtime-data">
    Consuming recent blockchain data as quickly as possible
  </Card>

  <Card title="Transaction Lifecycle" href="/monad-arch/transaction-lifecycle">
    Mapping the path of a transaction in Monad
  </Card>
</CardGroup>

The first Monad client is built by [Category Labs](https://www.category.xyz/) and is
written from scratch in C++ and Rust. Check out the codebase:

* [`monad-bft`](https://github.com/category-labs/monad-bft) (consensus client)
* [`monad`](https://github.com/category-labs/monad) (execution client)


# Real-Time Data Sources
Source: https://docs.monad.xyz/monad-arch/realtime-data/data-sources



For many use cases, developers and users can access current and historical
data for the Monad blockchain via the JSON-RPC interface.

This is not the most efficient way to receive data about the latest blocks,
however. The traditional JSON-RPC access methods use a request/response
model (which requires polling) instead of a notification model, where new
updates are pushed to you as soon as they happen.

<Warning>
  Because the Monad blockchain is much faster than other EVM-compatible
  L1 blockchains, the traditional JSON-RPC methods may not provide enough
  performance if you consume a *lot* of data, even if they've worked for you on
  other EVM ecosystems. The next section explains why in detail.
</Warning>

## Why might I need real-time data, even if I didn't before?

Monad is a fast blockchain capable of thousands of transactions per second:
when the Monad ecosystem runs at peak rates there is much more data per second
than in other L1 EVM-compatible blockchains such as mainnet Ethereum.

The data ecosystem of original Ethereum evolved around a network that ran at
less than 100 TPS, so certain data query patterns that work there might not
perform well enough when the amount of data is almost 100 times larger.

A classic example is an indexer workflow of fetching data about every
transaction and every log in a block, using JSON-RPC methods like
[`eth_getLogs`](/reference/json-rpc/eth_getLogs). A typical Ethereum block will have hundreds of transactions in
it, and there will be one new block every 12 seconds or so. For Monad, there
are 2.5 blocks every second, and each block can contain thousands of
transactions.

The number of `eth_getLogs` requests would be almost 100 times greater, putting
a strain on the JSON-RPC service provider. Using real-time data services can
help. Such services exist on other EVM blockchains too, but they're essential
in more situations for Monad.

## How do I receive real-time data?

Monad currently offers three sources of real-time data, which offer different
trade-offs in latency vs. complexity.

### Source #1: Geth-compatible real-time events

This is a [WebSocket-based protocol](https://geth.ethereum.org/docs/interacting-with-geth/rpc/pubsub)
that originated in the Geth Ethereum client but is widely supported by other
EVM-compatible blockchains. Monad implements the `eth_subscribe` method and
the `newHeads` and `logs` subscription types. The `syncing` and
`newPendingTransactions` subscription types are not supported.

This real-time data feed is published by the Monad RPC server component.

### Source #2: Monad extensions to Geth real-time events

The Monad RPC server also offers an extension to the Geth protocol; it
provides `eth_subscribe` subscriptions called `monadNewHeads` and `monadLogs`.
These publish almost the same data as the Geth real-time events protocol, but include extra
data for tracking each block's progression through consensus.

This requires the user to understand speculative execution
and [how it affects real-time data](/monad-arch/realtime-data/spec-realtime). You can
read more about these subscriptions in the [WebSocket Guide](/reference/websockets#monadnewheads-and-monadlogs).

### Source #3: Execution events SDK

This is the fastest way to consume real-time data. It requires you to write
your own real-time data processing software using the Monad client SDK in C,
C++, or Rust -- and then run it alongside your own Monad node.

This is the source of data that powers the other two access methods: it is
what the RPC server itself is listening to, to create the WebSocket feeds.
It has its own [documentation](/execution-events).

## Comparison of data offerings

| Data offering                                 | How to consume                     | Published by     | Granularity  | Transaction-level info                | When data is published                |
| --------------------------------------------- | ---------------------------------- | ---------------- | ------------ | ------------------------------------- | ------------------------------------- |
| Geth real-time events                         | [WebSocket](/reference/websockets) | RPC server       | Block commit | Logs only                             | When a block reaches `Voted` state    |
| Geth real-time events (with Monad extensions) | [WebSocket](/reference/websockets) | RPC server       | Block commit | Logs only                             | When a block reaches `Proposed` state |
| Execution event SDK                           | C/C++ or Rust SDK                  | Execution daemon | Tx commit    | Logs, call frames, state reads/writes | As soon as proposal is received       |

The first two offerings are consumed using `eth_subscribe` method over a
WebSocket. They are available from third-party data providers if you don't
wish to run your own Monad node.

The SDK offering requires you to write your own third-party program using
the C/C++ or Rust SDK. These programs are not plugins that run inside the
node software -- they are free-standing programs written entirely by you. As
events occur inside the EVM (in the execution daemon), they are recorded to
shared memory. Your program also is reading this same shared memory.
Therefore, your program must run on the same host as a Monad node.


# Real-time Data
Source: https://docs.monad.xyz/monad-arch/realtime-data/index



<CardGroup>
  <Card title="Real-Time Data Sources" href="/monad-arch/realtime-data/data-sources">
    How Monad reports real-time blockchain data
  </Card>

  <Card title="Speculative Real-Time Data" href="/monad-arch/realtime-data/spec-realtime">
    An optimization for reporting real-time data with very low latency
  </Card>
</CardGroup>


# Speculative Real-Time Data
Source: https://docs.monad.xyz/monad-arch/realtime-data/spec-realtime



The Monad architectural overview explains the [asynchronous execution](/monad-arch/consensus/asynchronous-execution)
feature. It is essential to have a basic understanding of how this feature
works before you consume Monad's fastest real-time data feeds, especially
the [speculative execution](/monad-arch/consensus/asynchronous-execution#speculative-execution)
and [block states](/monad-arch/consensus/block-states) sections.

## Why do I need to understand speculative execution?

Monad's design has considerably more parallelism than a typical EVM-compatible
blockchain. This includes nodes speculatively executing the transactions in a
newly-received block before being certain that that block will finalize. The
real-time data feeds are created during speculative execution, so if you
consume them, you might see data about transactions and their effects (e.g.,
logs and balance changes), but *those transactions may never really happen!*

To avoid reacting to blockchain data that is not "real", you need to know how
Monad real-time data feeds express speculative execution, and how they inform
you later whether blocks (and their transactions and state effects) were
ultimately added to the blockchain (or not).

Given this additional complexity, why would you consume these real-time feeds?
The answer is so that *your* software can get the same performance benefits
from speculative execution that Monad itself gets
[(explained below)](#what-benefits-do-i-get-from-speculative-execution).

The cost you pay for this benefit is that you need to understand more about
how Monad works, so that you can write your data processing code correctly.

## Can I consume real-time data without dealing with speculative execution?

Yes.

Monad's JSON-RPC interface supports the `"safe"` and `"finalized"` block tags, which return
data only from blocks that have reached stronger commitment levels (`Voted` and `Finalized`
respectively). See [block states](/monad-arch/consensus/block-states) for details
on what each commitment level guarantees.

<Info>
  Geth-style reorganizations don't occur in the `monadNewHeads` or `monadLogs`
  subscriptions. Instead, you are explicitly told what the consensus
  algorithm is doing with the blocks you have already seen, so you know what
  blockchain data gets committed or not. The purpose of this document is to
  explain exactly what this information means, so you know how to react to it.
</Info>

## What benefits do I get from speculative execution?

Realtime data generated by speculative execution is valuable to a consumer
for two reasons:

1. It allows you to use the same pipelining tricks that Monad itself uses
2. Sometimes it's valuable to react as soon as possible, even when the
   data you're seeing is not a sure thing

### Advantage #1: pipelining

Monad's pipelining tricks are explained [here](/monad-arch/concepts/pipelining)
and [here](/introduction/monad-for-users#whats-different-about-monad). You may
recall the below illustration of the laundry analogy, which helps explain the
concept in both places:

<img alt="Pipelining, Laundry Day" />

<p>Pipelining laundry day. Top: Naive; Bottom: Pipelined. Credit: <a href="https://www.cs.fsu.edu/~hawkes/cda3101lects/chap6/index.html?$$$F6.1.html$$$">Prof. Lois Hawkes, FSU</a></p>

Here's a concrete example of how you can use pipelining yourself:

Suppose you are writing a automated trading application. Further suppose that
when a certain contract (e.g., a CLOB contract) emits a particular log event,
your trading algorithm uses data from that log event as a signal to buy or
sell.

Before actually trading, you may need to perform additional actions first.
Some of the things you might do are:

* Check your risk limits, to see if increasing the position will
  give you too much exposure, or bring you too close to a potential
  liquidation

* Run a more complex mathematical model, if your strategy needs to perform
  complex computations based on the input in the trading signal

* Create and cryptographically sign the transaction for your buy/sell order

All these things take time, and you can do them *in preparation* for your
eventual trade, while you wait to find out if the block containing the market
signal was actually finalized. If the block *is* finalized, you've already
completed the essential work and can just "pull the trigger" (i.e., send the
presigned trade transaction message). If the block is *not* finalized, you
just throw the preparatory work away and never do the trade.

### Advantage #2: reacting before we know it's "real"

Consider a UI component which wants to keep users informed about the progress
of their transaction. When the transaction is speculatively executed, it can
be marked as `Pending` in the UI, so that the user knows it has been seen and
there's a very good chance it will go through. Even if it fails to progress
to a later commit state, seeing a bit of instant feedback tends to be a
superior user experience.

Also, consider again the example of our automated trading application. Timing
is very important in financial markets. When prices are changing rapidly, a
trade *right now* could be much more valuable than a trade a few seconds
later. It might make sense to initiate a trade *immediately* off of
speculative data, even knowing that some tiny percentage of the time, the
trade is based on a false premise.

You may lose money sometimes, i.e., when your strategy reacts to "not real"
market data in a block that fails to finalize. But *usually* this does not
happen, and the gains from being early most of the time could outweigh the
occasional losses when you react to "false" data.

There are also other kinds of applications, e.g., on-chain games, where
being more interactive is better than being perfectly accurate all the time.

# Block commit states

Elsewhere in the [documentation](/monad-arch/consensus/block-states),
we learned that a block can be in one of four states: `Proposed`, `Voted`,
`Finalized`, and `Verified`. These are sometimes called "commit states" or
"consensus states" in the documentation.

In speculative real-time data feeds, whenever you are given blockchain data, you
will also be told:

* What commit state the associated block is in
* If the initial state was not *verified*, you will be notified at some point
  later when the block transitions to a different state

Later in this article, we'll walk through exactly how the process happens in the
current version of the software.

## Block numbers and block ids

Once a block is canonically appended to the blockchain, it becomes uniquely
identified by a (sequentially increasing) block number, also called a "block
height." The inclusion of a block on the blockchain is the goal of the
consensus algorithm, and is called "finalization."

When a block is first constructed, it is constructed assuming it will become
the next block number, `N`. But prior to finalization, consensus nodes are
still trying to agree whether or not this candidate block will actually become
block `N`.

In consensus terminology, a leader constructs a block and *proposes* it to
the Monad network. Consensus nodes vote on the proposal of a particular
candidate block `B` to become the finalized block with number `N`. We call
this candidate block a "proposed block." It's not part of the blockchain
yet, but it probably will be soon.

It's possible for the proposal to fail for many reasons. In the most common
case, the proposed block does not reach enough other nodes before the timeout
period expires, due to network issues.

In that case, you would see another candidate to become the same block number
`N` later on. Because the real-time data feeds are fed by speculative
execution, you might see blockchain data for *both* of the block `N`
candidates, and will be told later which one was correct.

The critical thing to understand is that this blockchain data may claim to be
for "block number `N`", but it's not be the "real" block `N` yet: it's just
a *proposal* to become block `N`.

Consequently, when you see real-time data for a block *before* it finalizes,
the block number alone is not enough to uniquely identify it. This is only
the block number that the block *will* have, if it eventually gets
finalized. Instead, consensus uses a "block id" to uniquely identify
proposed blocks. The id can be used to track a specific block through its
commit state lifecycle.

Consider the following situation:

```
                                   ■
                                   ║  ┌─────────────┐   ┌─────────────┐
                                   ║  │             │   │             │
                         ┌─────────╬──┤  Block 102  ◀───┤  Block 103  │
                         │         ║  │  id: 79c25  │   │  id: 13a33  │
┌─────────────┐   ┌──────▼──────┐  ║  │             │   │             │
│             │   │             │  ║  └─────────────┘   └─────────────┘
│  Block 100  ◀───┤  Block 101  │  ║
│  id: 5b3a6  │   │  id: 6d585  │  ║
│             │   │             │  ║
└─────────────┘   └──────▲──────┘  ║  ┌─────────────┐
                         │         ║  │             │
                         └─────────╬──┤  Block 102  │
                                   ║  │  id: 3ed4d  │
                                   ║  │             │
                                   ║  └─────────────┘
                                   ║
                                   ║
                                 ◀ ║ ▶
                  Finalized blocks ║ Proposed blocks
                     (committed to ║ (may not become
                       blockchain) ║ committed to
                                   ║ blockchain)
                                   ║
                                   ■
```

In this diagram:

* Block 101 is the latest block to be finalized
* There are two competing proposed blocks vying to become block 102;
  they can be distinguished by their block ids
* One of the proposed blocks (`13a33`) is the parent of another
  proposed block
* You might see real-time data for *all* of these blocks; for those
  which are not finalized, you can start your pipeline processing right
  away, but you *may* want to wait until they reach a better commitment
  state before acting

<Info>
  The above situation is very rare in practice, but you should be aware that
  it is possible.
</Info>

# Consensus, execution, and commit states

Monad's real-time data stream is emitted directly by the EVM. In Category
Labs' implementation of a Monad node, execution and consensus are decoupled,
as they are in most Ethereum-compatible blockchain software. That is,
consensus and execution are not *just* different algorithms, but completely
separate programs that communicate with each other. Consensus is the
algorithm (and the daemon) which decides whether or not a potential block
will become part of the blockchain.

Execution hosts the EVM, and executes blocks on a speculative basis, before
it is told the fate of the block by the consensus algorithm. Meanwhile,
consensus is in the "driver's seat": it is the primary driver in the creation
of new blocks, and execution acts as service that consensus uses. However,
only execution produces real-time data and maintains the state database,
because it is the only thing that sees the details of every log, every call
frame, etc.

The exact way that blocks progress from one state to the next is explained below.
Note that a block's state is from the perspective of a particular observer --
for example if you receive a [QC](/monad-arch/consensus/monad-bft#quorum-certificate-qc)
for a block, then you can move that block to the `Voted` state, but if your friend didn't
receive that QC yet, then she would still consider that block to be in the `Proposed` state.

The challenge of building a distributed consensus mechanism lies in defining
rules that allow nodes to individually update their state machines in response
to messages even while assuming the worst, i.e. even while assuming that they
might be the only one that received that message.

## First commit state: `Proposed`

When a new block is proposed by a leader (a Monad validator node), it is sent
from that leader's consensus node to all other consensus nodes to be voted on.
From the perspective of each of those nodes (as well as any observers), if
the block is valid (i.e., follows all protocol rules), it is in the
[`Proposed`](/monad-arch/consensus/block-states#proposed) state.

Upon receiving a valid block, each consensus node will send a "yes" vote
to the next leader, while also scheduling it for immediate [speculative execution](/monad-arch/consensus/asynchronous-execution#speculative-execution)
by its local execution daemon.

Shortly after this happens -- even as the "yes" vote is starting to be
transmitted over the Internet -- the execution daemon begins executing the
proposed block in the EVM. A few milliseconds later, the EVM will begin
publishing real-time data for this block.

In the current implementation of the software, *all* blockchain data is first
observed in the `Proposed` state. A `Proposed` block is a tricky thing. Nearly
100% of proposals that are received do eventually become finalized. In a
statistical sense then, seeing a `Proposed` block seems quite good.

However, that is because usually the global Monad network is functioning
properly: the vast majority of the time, there are no major telecom outages
on the Internet and there is no attempted malicious activity going on.

You are seeing the block so early, that no one has voted for it except you
(if you are a validator), and the leader that proposed it. The first stage vote
is occurring in parallel, at roughly the same time that you are watching
real-time data from its execution.

This is the paradox of a `Proposed` block: the transactions within it are almost
certainly going to happen. And yet if you need very high levels of assurance
before acting, it would be foolish to assume they definitely will: the
blockchain's primary defense against errors, outages, and attacks (its consensus
algorithm) has not weighed in yet.

Make sure you understand the implications of a block being in the `Proposed`
state: it's very early, but has no defense against network problems, software
errors, or malicious behavior. Each later stage reduces the likelihood of
problems occurring, and the kinds of problems that can occur.

## Second commit state: `Voted`

As mentioned above, the consensus algorithm is conducting a first round vote
on whether or not that block will be appended to the blockchain. The goal of
this referendum is to produce a "quorum (minimum number of required votes
for referendum to pass) of "yes" votes.

The vote is coordinated by the second-round leader, who gathers a quorum of
cryptographically-signed "yes" votes into an aggregate signature called a
"quorum certificate" ([QC](/monad-arch/consensus/monad-bft#quorum-certificate-qc)). The second round leader sends out that QC to all
consensus nodes.

If you have received a QC on a block, that means that you
have proof that the block passed the first round of voting. When this
happens, you may consider the block to be in the
[`Voted`](/monad-arch/consensus/block-states#voted) state.

A few things to note about the voted state:

### `Voted` does not mean it's on the blockchain

A block *cannot* yet be definitively appended to the blockchain when it reaches
the `Voted` state. Monad's consensus algorithm uses two rounds of voting.
Possession of a QC (i.e. proof that the first round concluded in most
participants voting yes) removes the most common kinds of risks, but some risk
of being reverted remains.

Possessing a QC removes the risk that a block will be "lost" due to the most
common issues such as network outages and latency issues. Even if it turned
out that you were the only observer with this QC due to a severe network outage,
Monad's consensus algorithm has a fallback mechanism that ensures that the
original block will be reproposed and ultimately finalized under almost all
conditions.

Under what conditions is the existence of a QC not enough? [Several things must
have happened](/monad-arch/consensus/monad-bft#the-only-loophole), but the most notable is that the original leader must have
*equivocated*, i.e. proposed two different blocks at the same block height,
sending each to a different set of nodes.

Equivocation is an unlikely thing for a leader to do, since it is an easily
attributable fault (proof is just the pair of conflicting blocks signed by the
same leader), and since the leader only hurts themselves by invalidating their
own proposal. This is why a block that has reached the `Voted` stage is very
likely to be finalized.

### A block might never enter the `Voted` state

A proposed block might never receive a QC, if its first consensus vote fails.
The most common reason that a block does not get voted in is network latency
issues. Suppose, for example, that both your node and the leader are in
Australia, and there is significant congestion with the cross-continental
network traffic. In that case, most of the blockchain nodes may not learn
about the proposal before the timeout period expires, and the vote will fail.
Note that you will *not* be told that the vote fails. The failure of the vote
is *implicit*, but you can tell it happened because of the next property.

### For some block number `N`, *some* proposed block will eventually be voted in

If you do not receive a QC for a particular block with block number `N`, then
at some other time you will receive a *different* proposed block to become
block `N` and that *will* receive a QC.

A sequence like the following may occur:

* You see all of real-time data for some block `B1`, which is proposed to
  become block number `N`
* You see a *different* block, `B2` (and all of its execution events) also
  competing to become block `N`
* `B2` receives a QC, and this is the only thing that happens. Namely, `B1`
  does *not* receive an explicit "abandonment" event: it is just never
  mentioned again, and is implicitly abandoned by the network endorsing
  another block with the same number

## Third commit state: `Finalized`

[`Finalized`](/monad-arch/consensus/block-states#finalized) means the block is now part of the canonical blockchain and cannot
be reverted without a hard fork. From this point forward, we no longer need
the block id and can refer to a block solely by its block number.

When a block number `N` is finalized, it *implicitly* abandons all other
proposed blocks with the same block number `N`. Such blocks could be in either
the proposed or the voted state. We say the abandonment is implicit because no
event will be recorded to explicitly announce the abandonment of previously
seen block id.

If you are using pipelining programming techniques when you consume real-time
data, then you are probably keeping track of some state associated with
unfinalized blocks. In our trading example, this would be the pre-prepared
buy or sell order transaction message.

Every time a block is finalized, you read must check for any blocks
(1) with the same block number, but (2) with a different id, and abort your
pipelined processing for those blocks. They will never be appended to the
blockchain and the associated transactions and their effects -- whose
execution events you have already seen -- will never occur.

### Why are there two different stages of voting?

This is because the *subject* of the vote -- the thing we are trying to
get agreement on -- is different.

1. In the *first* vote, the network wants to verify that a block satisfies
   all the protocol rules. If a QC is obtained, we know that a majority
   of the honest nodes agree that the block *should* be added. This first
   vote is called the "voted" stage since *the block itself* has been
   voted for.

2. In the *second* vote, we want to get cryptographically secure agreement
   that *enough of the network has actually seen the result of the first vote*.
   This second vote is called the "finalized" stage since, now that everyone
   knows the first vote succeeded, they can also agree that it must be the
   next block on the blockchain.

The second vote is trying to answer the question posed by the old saying
"If a tree falls in a forest and no one is around to hear it, does it make a
sound?"

Consider how the "fan-in, fan-out"
[linear communication pattern](/monad-arch/consensus/monad-bft#happy-path)
of the BFT protocol works. We talk about nodes "having a QC", but the QC is
computed by the leader of the next round -- this leader is the one actually
"conducting" the vote.

Even if the leader is dishonest, it cannot forge the vote because it cannot
forge other nodes' cryptographic signatures. But it *can* fail to successfully
tell enough of its peers about the QC, since it must communicate the QC to
everyone. Network problems are common, so communication can always fail.

Thus we need a second round of voting, for validators to reach distributed
agreement about the fact that they've seen the first QC. Now it's safe to
assume that everyone (or at least the honest majority) will have the same
canonical blockchain.

The reason that `Voted` is a very reliable commit state on Monad is that if
common problems occur during the *second* stage vote, the
algorithm will continue trying to conduct the second stage vote, failing only
in some narrow corner cases involving equivocation.

## Fourth commit state: `Verified`

The consensus algorithm produces one last state transition for a block, called
[`Verified`](/monad-arch/consensus/block-states#verified).

The `Verified` state is a consequence of Monad's [asynchronous execution](/monad-arch/consensus/asynchronous-execution). Recall
that a consensus node votes on a block *before* its execution is complete.
This implies that consensus must be voting on the block's execution inputs,
but *not* on the block's execution outputs.

Consensus nodes cannot be voting, for example, on the correct value of the
state root produced by the execution of the block, because they don't know
what it is (remember, it is being computed in parallel with the vote
occurring). This means that the `Voted` state does not certify the
correctness of any output fields in the Ethereum block header such as
`state_root`, `receipts_root`, etc.

This is possible because any well-formed Ethereum block will have completely
deterministic effects on the blockchain state, when executed by a conforming
EVM implementation. Thus, it is safe to append a block onto the blockchain,
knowing that everyone will agree on its behavior, even if we don't know
exactly what the behavior will be.

Clearly though, for the blockchain to be reliable, consensus nodes *must*
eventually vote on the correctness of the execution outputs. Suppose they did
not, and further suppose that a bug existed in some execution nodes but not
in others (perhaps running a different version of the client software). If
there were no mechanism to feed the execution outputs back into consensus
decisions, the state could become forked without anyone noticing. Consensus
proposals *start* by assuming that all execution nodes will compute the
correct state, but to prevent bugs and malicious actions from compromising
the network, it must check that this happens eventually.

Here is how Monad solves this issue:

To give execution ample time to finish, execution outputs for block `B`
are not incorporated into the consensus protocol until three rounds in the
future, alongside the proposal of block `B+3`. When *this* proposal is
finalized (ideally two rounds later, during the proposal of block `B+5`),
then a supermajority of nodes will have voted for the correct values of
the execution outputs.

To roughly summarize the difference:

* `Finalized` means the block's definition (i.e., its transactions) are
  definitely part of the blockchain
* `Verified` means that a supermajority stake's worth of other nodes have
  verified that your local node's computation of the state changes of these
  transactions match the supermajority's

To understand more, read [here](/monad-arch/consensus/asynchronous-execution#delayed-merkle-root).

Does this imply that verified state is the gold standard for "100%, can never
fail" transaction reporting? Also no, if you are trusting a data feed produced
by a single node. Who is to say, for example, that the node producing the data
in not suffering from a bug, or has been hacked?

As always in the blockchain universe, critical transactions that demand
*total* peace of mind can only be verified by widespread agreement, *broadly*
defined. This includes explicitly checking with other nodes, to ensure no
hosts or network intermediaries have been compromised and the software is
working properly.

In practice, the `Voted` state is usually good enough for most things: it should
*very* rarely revert in practice, so it is also used as the `"safe"` block tag
in Monad's RPC implementation.


# Transaction Lifecycle in Monad
Source: https://docs.monad.xyz/monad-arch/transaction-lifecycle



## Transaction Submission

The lifecycle of a transaction starts with a user preparing a signed transaction and submitting it to an RPC node.

Transactions are typically prepared by an application frontend, then presented to the user's wallet for signing. Most wallets make an `eth_estimateGas` RPC call to populate the gas **limit** for this transaction, although the user can also override this in their wallet. The user is also typically asked to choose a gas **price** for the transaction, which is a number of NativeTokens per unit of gas.

After the user approves the signing in their wallet, the signed transaction is submitted to an RPC node using the `eth_sendTransaction` or `eth_sendRawTransaction` API call.

## Mempool Propagation

As described in [Local Mempool](/monad-arch/consensus/local-mempool):

The RPC node performs validity checks:

* signature verification
* nonce not too low
* gas limit below transaction gas limit

before forwarding the pending transaction to the next `N` leaders.

Each of those leaders replicate those validity checks before adding the pending transaction to their local mempool.

If the transaction isn't included in any of the blocks proposed by those leaders, the RPC node repeats this process, sending to the next `N` leaders. The process is repeated up to `K` times.

## Block Inclusion

Pending transactions are included in a block only if further dynamic checks pass:

* account balance is sufficient to pay for gas (taking into account the [reserve balance rules](/developer-essentials/reserve-balance))
* nonce is contiguous
* pays valid [base fee per gas](/developer-essentials/gas-pricing#eip-1559-compatibility)
* there is space in the block and the leader has chosen to include this transaction

## Block Propagation

Blocks are propagated through the network as discussed in [MonadBFT](/monad-arch/consensus/monad-bft), using the [RaptorCast](/monad-arch/consensus/raptorcast) messaging protocol for outbound messages from the leader.

Under MonadBFT, a block progresses from the Proposed phase to the Voted phase (after 1 block) and then to the Finalized phase (after 2 blocks).

Once the block is Finalized, the transaction has officially "occurred" in the history of the blockchain. Since its order is determined, its truth value (i.e., whether it succeeds or fails, and what the outcome is immediately after that execution) is determined.

## Local Execution

As soon as a node receives a block, it begins executing the transactions from that block. For efficiency reasons, transactions are executed [optimistically in parallel](/monad-arch/execution/parallel-execution), but it is as if the transactions were executed serially, since results are always committed in the original order.

## Querying the Outcome

The user can query the result of the transaction by calling `eth_getTransactionByHash` or `eth_getTransactionReceipt` on any RPC node. The RPC node will return as soon as execution completes locally on the node.


# Announcements
Source: https://docs.monad.xyz/node-ops/announcements



## Channels

Subscribe to the following channels to receive Monad Foundation announcements:

| Channel  | Link                                                                 |
| -------- | -------------------------------------------------------------------- |
| Email    | Delivered to the address associated with your validator registration |
| Discord  | [#mainnet-validator-announcements](https://discord.gg/monaddev)      |
| Telegram | [Node Announcements](https://t.me/MonadNodeAnnouncements)            |

## Severity System

In order to provide a standardized framework for network-related communications, the Monad Foundation uses the following color-coded categories to preface announcements. These categories are directly attributed to level of severity, recommended action, and timeframe.

<Info>
  Ecosystem participants can use this framework to set up alerts (e.g. PagerDuty) for "CODE RED" in email subjects or social channels, further assisting in the dissemination of time-critical information.
</Info>

Announcements may be reclassified as more information becomes available. In an emergency, the Foundation may use any available communication channel regardless of the classification below.

### Green 🟢

**Subject contains "CODE GREEN"** — informational, no action required.

Examples:

* Optional upgrades
* Validator info updates
* Social coordination messaging
* Non-critical additions to the operations layer

### Orange 🟠

**Subject contains "CODE ORANGE"** — action recommended within 24–48 hours.

Examples:

* Upcoming non-emergency upgrades

Communication will be shared over email, Discord, and the Telegram Node Announcements channel.

### Red 🔴

**Subject contains "CODE RED"** — action recommended immediately upon receiving communication.

Examples:

* Critical emergency upgrades
* Chain halts
* Staking protocol compromises

Communication channels depend on the nature of the incident:

* **Resetricted rollout** (emergency and sensitive, e.g. security vulnerability) — to minimize the risk of exploitation before a patch is widely deployed, communication may initially be shared **exclusively over email** to known validators.
* **Unrestricted rollout** (emergency but not sensitive, e.g. emergency upgrade affecting chain liveness) — communication will generally be shared over email, Discord, and the Telegram Node Announcements channel.


# Configuring RPC to use archive data
Source: https://docs.monad.xyz/node-ops/archive-data/configuring-rpc



<Warning title="This is not for validator nodes">
  Integration with the archive is designed for full nodes servicing RPC requests, **not for validator
  nodes**.
</Warning>

<Note title="Enabling call traces">
  Enabling `--trace_calls` is recommended for **RPC** nodes.
  This preserves the detailed error information necessary for call traces, e.g. `debug_traceTransaction`.
  To make this override, please run `sudo systemctl edit monad-execution` and add the `--trace_calls` CLI param
  to the `ExecStart` definition (may need a line continuation character `\`):

  ```sh theme={null}
  sudo systemctl edit monad-execution
  ```

  ```toml theme={null}
  [Service]
  Type=simple
  ExecStart=
  ExecStart=/usr/local/bin/monad \
      [... existing cli commands, see comment at the bottom of the systemctl editor ...]
      --trace_calls
  ```
</Note>

## Configuring `monad-rpc` with Archive Server backup

1. Configure an [Archive Server](/node-ops/archive-data/running-an-archive-server) that is geographically close to
   this full node.

2. Add the following vars to your `/home/monad/.env`:

   ```sh theme={null}
   # Replace <db username>, <db pwd> and <db hostname> with your values from Step (1)
   MONGO_URL="mongodb://<db username>:<db pwd>@<db hostname>:27017"
   MONGO_DB_NAME="archive-db"
   DB_HOST=<db hostname>
   DB_PWD=<db pwd>
   DB_USERNAME=<db username>
   ```

3. Verify connectivity:

   ```sh theme={null}
   source /home/monad/.env

   nc -vz $DB_HOST 27017
   mongosh "$MONGO_URL" --quiet --eval '
       try {
       db.adminCommand({ping: 1});
       const archiveDb = db.getSiblingDB("archive-db");
       const hasCollection = archiveDb.getCollectionNames().includes("block_level");
       print(hasCollection ? "OK: Collection exists" : "FAIL: Collection missing");
       quit(hasCollection ? 0 : 1);
       } catch(e) {
       print("FAIL: " + e.message);
       quit(1);
       }
   '
   ```

4. Add the following systemd override to `monad-rpc`:

   ```sh theme={null}
   sudo systemctl edit monad-rpc
   ```

   ```toml theme={null}
   [Service]
   ExecStart=
   ExecStart=/usr/local/bin/monad-rpc \
       [... existing cli commands, see comment at the bottom of the systemctl editor ...]
       --mongo-url ${MONGO_URL} \
       --mongo-db-name ${MONGO_DB_NAME} \
       --use-eth-get-logs-index
   ```

5. Reload and restart:

   ```sh theme={null}
   sudo systemctl daemon-reload
   sudo systemctl restart monad-rpc
   ```

6. Check for an early block outside local retention:

   ```sh theme={null}
   curl -X POST -H "Content-Type: application/json" --data '{
           "jsonrpc": "2.0",
           "method": "eth_getBlockByNumber",
           "params": ["0x1", false],
           "id": 1
       }'  http://localhost:8080
   ```

## Configuring `monad-rpc` with AWS backup

1. Ensure an AWS identity and credentials are on the box.

   * Run `aws configure` to setup your AWS credentials and config on the full node. This should
     generate `config` and `credentials` files under `/home/monad/.aws/`. See the
     [AWS CLI docs](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).
   * When running in systemd, AWS permissions need to be created under `monad` user. See the
     general validator or fullnode docs for the broader instructions to run rpc, but ensure the
     `monad` user has aws credentials with access to the bucket.

2. Create an AWS IAM policy using this [user guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html#access_policies_create-json-editor) and the following sample json:

   ```json theme={null}
   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "s3:GetObject",
                   "s3:ListBucket",
                   "s3:GetBucketRequestPayment",
                   "execute-api:Invoke"
               ],
               "Resource": [
                   "arn:aws:s3:::*/*",
                   "arn:aws:s3:::*",
                   "arn:aws:execute-api:*:*:*"
               ],
               "Condition": {
                   "StringEquals": {
                       "aws:ResourceOrgID": "o-sq9ayub2wk"
                   }
               }
           }
       ]
   }
   ```

3. To obtain a free-tier api-key, send an AWS Signature v4 signed request to `https://9df09fanz1.execute-api.us-east-2.amazonaws.com/prod/free-tier-key`

   * ex. using `awscurl` utility:

     ```bash theme={null}
     awscurl https://9df09fanz1.execute-api.us-east-2.amazonaws.com/prod/free-tier-key --region us-east-2
     ```

4. Add the following vars to your `/home/monad/.env`:

   ```sh theme={null}
   ARCHIVE_API_KEY=<key from step 3>
   # Replace with appropriate mainnet, localnet or testnet bucket
   # Below is the public testnet bucket maintained by Category Labs
   ARCHIVE_BUCKET="testnet-can-004-0-aavn9ll"
   # Below is the public mainnet bucket maintained by Category Labs
   ARCHIVE_BUCKET="mainnet-deu-010-0" # mainnet-deu-009-0 is a sibling bucket you can also use
   ```

5. Add the following systemd override to `monad-rpc`:

   ```sh theme={null}
   sudo systemctl edit monad-rpc
   ```

   ```toml theme={null}
   [Service]
   ExecStart=
   ExecStart=/usr/local/bin/monad-rpc \
       [... existing cli commands, see comment at the bottom of the systemctl editor ...]
       --s3-bucket ${ARCHIVE_BUCKET} \
       --region "us-east-2" \
       --archive-url "https://9df09fanz1.execute-api.us-east-2.amazonaws.com/prod" \
       --archive-api-key ${ARCHIVE_API_KEY}
   ```

6. Reload and restart:

   ```sh theme={null}
   sudo systemctl daemon-reload
   sudo systemctl restart monad-rpc
   ```

7. Check for an early block outside local retention:

   <Note>
     If you already have MongoDB backend enabled, this will not test anything by default. To test,
     temporarily remove the MongoDB backend, run the following and restore the MongoDB config.
   </Note>

   ```sh theme={null}
   curl -X POST -H "Content-Type: application/json" --data '{
           "jsonrpc": "2.0",
           "method": "eth_getBlockByNumber",
           "params": ["0x1", false],
           "id": 1
       }'  http://localhost:8080
   ```


# The Data Waterfall
Source: https://docs.monad.xyz/node-ops/archive-data/data-waterfall



## Background

As a high throughput blockchain with frequent blocks, Monad generates a lot of data - both
**transactional data** (blocks, transactions, receipts, logs, and traces), and **state data**
(the full state trie at the end of each block).

Full nodes and validators store as much of both kinds of data as possible in MonadDB, overwriting
the oldest data when the storage capacity hits 80%. If an RPC call requests data older than
whatever is locally available, the node must reference an
external source.

For transactional data, the waterfall is:

1. Chain State Buffer (in-memory cache)
2. MonadDb
3. Archive Server (if configured)
4. Object Storage (if configured)

## MonadDB

MonadDB, also called TrieDB, is a local state database run by each full node and validator. It
maintains the most recent state tries, as well as the corresponding transactional data.

Once the storage capacity of MonadDB reaches 80%, the node begins overwriting the oldest data.
Because of this mechanism, and because of frequent blocks and high chain throughput, most MonadDB
instances don't store the entire blockchain history.

## Archive Server (MongoDB)

An Archive Server is a standalone server that stores historical transactional data in MongoDB.
Note that Archive Servers don't store state data - see
[here](/developer-essentials/historical-data) for a discussion why.

An Archive Server is fed this data by an ordinary full node running an additional process called
the Archive Writer.

<img />

<p>Monad Archive Server architecture</p>

Many full nodes and validators can point to the same Archive Server.

For instructions on running an Archive Server, please refer to
[Running an Archive Server](/node-ops/archive-data/running-an-archive-server).

Archive Servers store the following data types:

* blocks
* transactions
* receipts
* logs
* traces

Note: We call this an "Archive Server" rather than an "Archive Node" to reduce confusion.
Archive Servers typically don't host a Monad full node (consensus and execution).

## Object Storage

Archive data can also be stored in an object storage service (e.g., AWS S3).

While MongoDB is preferred for performance and query efficiency, object storage provides a viable
fallback option for users who prefer off-site or cloud-based data retention.

Like ArchiveDB, the object storage can also be configured in the RPC client as a  source of
historical data.

Object Storage stores the following data types:

* blocks
* transactions
* receipts
* logs
* traces

<Info>
  Archive Server is given preference over Object Storage if both are configured. Configuring both is
  recommended to ensure that there is a fallback mechanism in case of any issues with the Archive
  Server instance.
</Info>

<Info>
  For more details about historical data, see the
  [Historical Data](/developer-essentials/historical-data) page.
</Info>


# Genesis Replay
Source: https://docs.monad.xyz/node-ops/archive-data/genesis-replay

Re-execute historical blocks to reconstruct state

Genesis replay re-executes historical blocks so that additional copies of state are available at
any given point in time. Historically, blocks have been stored in a static archive format. This
process downloads those blocks and replays them through the EVM to reconstruct full state.

## Prerequisites

* monad version `0.12.3` or later
* Credentials and configuration to read from your chosen archive source (AWS, R2, MongoDB, MinIO,
  etc.). These are the same credentials used by `monad-archiver`; see
  [Running an Archive Server](/node-ops/archive-data/running-an-archive-server) for details.

## Setup

### 1. Prepare the block database directory

Choose a directory to store EVM-format historical blocks. This guide refers to it as `block-db`.

### 2. Initialize triedb

Create an empty `triedb`:

```bash theme={null}
monad-mpt \
    --storage /dev/triedb \
    --root-offsets-chunk-count 16 \
    --create-empty
```

### 3. Start the block writer

Run inside `tmux` or create a systemd service to download blocks continuously:

```bash theme={null}
monad-block-writer stream \
    --block-data-source <your source string> \
    --dest-path <your block-db path>
```

The source string follows the same format used by `monad-archiver`, for example
`"aws mainnet-deu-009-0"` or `"mongodb ..."`.

The block writer will:

1. Download all blocks from the source
2. Transform them into EVM format
3. Brotli-compress the data
4. Write blocks into subdirectories of the form `block-db/XM/<block_number>`, where
   `X = block_number / 1_000_000` (one million blocks per directory)

**Resumption behavior:** The writer saves a `latest` file in the `block-db` directory. If the
process stops, on the next startup it reads `latest` and compares it against the latest block
available from the `--block-data-source`, then continues from that point.

<Tip>
  If you only need a specific range of blocks, run `monad-block-writer stream --help` for range
  options.
</Tip>

### 4. Configure the replay service

While `monad-block-writer` is running, add the following systemd override for `monad-execution`
in a separate terminal:

```bash theme={null}
sudo systemctl edit monad-execution
```

```ini theme={null}
[Service]
ExecStart=
ExecStart=/usr/local/bin/monad \
    --chain "$CHAIN" \
    --as_eth_blocks \
    --block_db <your block-db path> \
    --nblocks 0 \
    --db /dev/triedb \
    --no-compaction \
    --trace_calls \
    --block-db-timeout 60

AllowedCPUs=
CPUAffinity=
Restart=
Restart=always
```

<Note>
  Ensure `$CHAIN` is defined in your environment. Valid options:

  * `ethereum_mainnet`
  * `monad_devnet`
  * `monad_testnet`
  * `monad_mainnet`
</Note>

**`--block-db-timeout`** sets the number of seconds the replay service will wait for new blocks
to appear in the block database. If the timeout is reached without new blocks, the replay service
will crash and be restarted by systemd. If this happens, verify that the block writer from step 3
is still running and writing blocks to disk. Set to `0` to disable retries.

### 5. Reload and start

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl restart monad-execution
```

## Running RPC on a replay host

If you want to run `monad-rpc` on this host, you must remove the `--ipc-path` flag from the
`monad-rpc` systemd configuration.


# Archive Data Setup
Source: https://docs.monad.xyz/node-ops/archive-data/index



<CardGroup>
  <Card title="The Data Waterfall" href="/node-ops/archive-data/data-waterfall">
    Where RPC looks for historical data
  </Card>

  <Card title="Running an Archive Server" href="/node-ops/archive-data/running-an-archive-server" />

  <Card title="Configuring RPC to use Archive Data" href="/node-ops/archive-data/configuring-rpc">
    How to configure RPC to use archive data
  </Card>

  <Card title="Genesis Replay" href="/node-ops/archive-data/genesis-replay">
    Re-execute historical blocks to reconstruct state
  </Card>
</CardGroup>


# Running an Archive Server
Source: https://docs.monad.xyz/node-ops/archive-data/running-an-archive-server



Please see [The Data Waterfall](/node-ops/archive-data/data-waterfall) for an overview
of the different sources of archive data. This page is dedicated to operational details on
running an Archive Server.

## Recommended footprint

For anyone looking to reliably serve historical transactional data, it is recommended to run
multiple Archive Servers, fed by multiple full nodes running the Archive Writer process.

Suggested configuration:

* 2 Archive Servers running MongoDB + monad-indexer
* 2 Archive Writer nodes, aka full node + monad-archiver
* Many full nodes serving RPC requests, connected to both Archive Servers for historical
  transactional data

## Recommended Archive Server host specs

* CPU: 16 cores
* RAM: minimum 64GB; prefer >512GB for best performance
* Storage: minimum recommended 16TB; preferred 32TB+
  * NVMe SSD
  * RAID 10
  * Minimum 10K IOPS sustained
* Network: >1GbE, scale higher as needed when serving more RPC servers

## Fresh installation

These instructions assume an existing full node (for Archive Writer) and a new host (for Archive
Server).

### On your Archive Server:

1. Add the following section to `/home/monad/.env`

   ```sh theme={null}
   # Replace <db username> and <db pwd> with your actual values
   DB_USER="<your db username>"
   DB_PWD="<your db pwd>"
   DB_VOLUME="~/archive-db-data"

   # Note: source and sink should generally be the same local MongoDB.
   # Indexer reads from:
   BLOCK_DATA_SOURCE="mongodb mongodb://${DB_USER}:${DB_PWD}@0.0.0.0:27017 archive-db"
   # Indexer writes to:
   ARCHIVE_SINK="mongodb mongodb://${DB_USER}:${DB_PWD}@0.0.0.0:27017 archive-db"
   OTEL_ENDPOINT="http://0.0.0.0:4317"
   ```

2. Run mongodb. Instructions show how to run in Docker, but operators can run however they choose.

   ```yml theme={null}
   archive-db:
     image: mongo:latest
     command: mongod --bind_ip 0.0.0.0
     networks:
       - host
     environment:
       MONGO_INITDB_ROOT_USERNAME: ${DB_USER}
       MONGO_INITDB_ROOT_PASSWORD: ${DB_PWD}
     ports:
       - "27017:27017"
     volumes:
       - ${DB_VOLUME}:/data/db
     logging:
       driver: journald
       options:
         tag: "mongo"
   ```

3. Start the db

   ```sh theme={null}
   # create directory from .env db volume
   source /home/monad/.env
   sudo mkdir -p $DB_VOLUME
   sudo chown -R monad:monad $DB_VOLUME
   sudo chmod 700 $DB_VOLUME

   docker compose up archive-db -d
   ```

### On your Archive Writer host:

4. Add the following section to `/home/monad/.env`

   ```sh theme={null}
   ###############################################################
   ################### Vars that do not change ###################
   ###############################################################
   # Replace with your Archive Server credentials
   ARCHIVE_DB_USER="<your db username>"
   ARCHIVE_DB_PWD="<your db pwd>"
   ARCHIVE_DB_HOST="<your db hostname>"

   ## Where block data gets written (your Archive Server)
   ARCHIVE_SINK="mongodb mongodb://${ARCHIVE_DB_USER}:${ARCHIVE_DB_PWD}@${ARCHIVE_DB_HOST}:27017 archive-db"
   ## Change this if your ledger folder is in a different location
   BFT_BLOCK_PATH=~/monad-bft/ledger
   OTEL_ENDPOINT=http://0.0.0.0:4317
   ## This can be significantly higher during backfill
   MAX_CONCURRENT_BLOCKS=50


   ###############################################################
   ####### Backfill from Genesis (initial configuration) #########
   ###############################################################
   BLOCK_DATA_SOURCE="aws testnet-can-004-0-aavn9ll 50" # testnet
   BLOCK_DATA_SOURCE="aws mainnet-deu-010-0 50" # mainnet
   ## Alternatively you can use your other ArchiveDB if it has already been backfilled
   ## If using another Archive Server, define variables for it and use them:
   #OTHER_DB_USER="<other db username>"
   #OTHER_DB_PWD="<other db pwd>"
   #OTHER_DB_HOST="<other db hostname>"
   #BLOCK_DATA_SOURCE="mongodb mongodb://${OTHER_DB_USER}:${OTHER_DB_PWD}@${OTHER_DB_HOST}:27017 archive-db"
   FALLBACK_BLOCK_DATA_SOURCE="aws testnet-can-004-0-aavn9ll-0 50" # testnet
   FALLBACK_BLOCK_DATA_SOURCE="aws mainnet-deu-010-0 50" # mainnet

   ###############################################################
   ###################### Normal Operation #######################
   ###############################################################
   ## Archiver checks triedb first for block data
   BLOCK_DATA_SOURCE="triedb /dev/triedb 5000"

   ### FALLBACK_BLOCK_DATA_SOURCE ###
   ## This is used whenever data is missing from BLOCK_DATA_SOURCE
   ## Normally used after state-sync
   ## If you have another Archive Server for redundancy, configure it here:
   #OTHER_DB_USER="<other db username>"
   #OTHER_DB_PWD="<other db pwd>"
   #OTHER_DB_HOST="<other db hostname>"
   #FALLBACK_BLOCK_DATA_SOURCE="mongodb mongodb://${OTHER_DB_USER}:${OTHER_DB_PWD}@${OTHER_DB_HOST}:27017 archive-db"

   ## Alternatively you can use category-labs aws bucket
   ## Note: YOU pay for S3 egress costs if pulling from this bucket
   FALLBACK_BLOCK_DATA_SOURCE="aws testnet-can-004-0-aavn9ll 50" # testnet
   FALLBACK_BLOCK_DATA_SOURCE="aws mainnet-deu-010-0 50" # mainnet
   ```

5. Backfilling:

   <Note>
     As of v0.12.3, `--start-block` is no longer supported as a daemon argument. Instead, use the `set-start-block` subcommand to set the starting block marker imperatively before starting the daemon. This prevents accidental progress loss from systemd overrides.
   </Note>

   ```sh theme={null}
   # [Optional] Set a specific start block if needed
   # This is typically only needed for initial setup or recovery scenarios
   # Example: start archiving from block 1000000
   monad-archiver set-start-block --block 1000000 --archive-sink "${ARCHIVE_SINK}"

   # For async backfill marker, add the --async-backfill flag:
   # monad-archiver set-start-block --block 1000000 --archive-sink "${ARCHIVE_SINK}" --async-backfill

   # Start the archiver daemon
   sudo systemctl start monad-archiver
   # Should show it running
   # Double check the arguments look correct based on the above ^
   systemctl status monad-archiver
   # Expect many:
   # > INFO: Successfully archived block block_num=X
   journalctl -u monad-archiver -o cat
   ```

6. Once `monad-archiver` has caught up to the chain tip you will see:

   > `INFO: Nothing to process`

7. This means backfilling is done and you should

   1. Comment out `BACKFILL` section in your `.env` and uncomment `Normal Operation`
   2. Restart: `systemctl restart monad-archiver`
   3. Verify status and logs as above

### On your ArchiveDB host

8. Start `monad-indexer`

   ```sh theme={null}
   sudo systemctl start monad-indexer
   systemctl status monad-indexer
   # Expect many:
   # > INFO: Indexing block...
   # > INFO: Index spot-check successful
   journalctl -u monad-indexer -o cat
   ```

## \[Optional] Set up `monad-archive-checker`

Typically only 1 checker is run per organization, but more can be run if desired

1. Add the following systemd override to `monad-archive-checker`

   ```sh theme={null}
   sudo systemctl edit monad-archive-checker
   ```

   ```toml theme={null}
   [Service]
   ExecStart=
   ExecStart=/usr/local/bin/monad-archive-checker \
       # Example --bucket my-org-mainnet-checker
       # Note: storing checker state in local mongo or filesystem
       #       will be supported in a future release
       --bucket <S3 Bucket for storing checker state>
       checker
       # Example of comparing a local self-hosted mongo against a Category Labs aws bucket
       # --init-replicas "<aws mainnet-deu-009-0 50,mongodb mongodb://<username>:<pwd>@<db hostname>:27017 archive-db>,mongodb mongodb://<username>:<pwd>@<second db hostname>:27017 archive-db>"
       --init-replicas "<ArchiveDB 1>,<ArchiveDB 2>"
   ```

2. Reload and Restart

   ```sh theme={null}
   sudo systemctl daemon-reload
   sudo systemctl restart monad-archive-checker
   systemctl status monad-archive-checker

   # Check for errors
   journalctl -u monad-archive-checker -o cat -f
   ```


# Execution Events and WebSocket Setup
Source: https://docs.monad.xyz/node-ops/events-and-websockets



## Summary

The [Execution Events](/execution-events) and [WebSocket](/reference/websockets)
features were designed to work together to make Monad even faster for high volume applications.
Execution Events is a low-level system, and WebSocket support is one specific usage of that system.

### Execution Events

[Execution Events](/execution-events) offers developers the highest performance option
for listening to real-time data from the Monad blockchain.

* Execution Events uses a shared memory communication system that requires additional setup,
  which is described here. This setup is not part of the default instructions; it's only needed
  if you run real-time data consumers that use the Execution Events feature.

* The "shared memory" nature of the communication means that consumers
  of execution events must run directly on the same host as the Monad node, so
  they can observe real-time data in the host's RAM

* Monad's RPC server can optionally use execution events for better
  performance, and to support certain features, namely, the `eth_subscribe`
  JSON-RPC call

<Note>
  [Here](/monad-arch/realtime-data/data-sources) is an overview of all real-time data offerings
  in Monad. [Here](/execution-events) is a tutorial on writing programs that consume
  execution events.
</Note>

### WebSockets

In Monad's JSON-RPC server, WebSockets have two uses:

* Creating a persistent connection to make JSON-RPC requests
* The ability to call the `eth_subscribe` API, which will "push" new real-time
  data as it happens, so you do not need to poll for new events

WebSocket support must be explicitly enabled in the RPC server with
command-line flag `--ws-enabled`. When
`--ws-enabled` is passed, then the host must be configured to support
execution events, otherwise RPC will exit with an error.

A user guide to WebSockets on Monad is [here](/reference/websockets).

## Requirements

* A running Monad full node ([setup instructions](/node-ops/full-node-installation))
* A `hugetlbfs` filesystem mount
  * This can be set up using the `hugeadm` utility; see below for an example
* Custom (aka "override") `systemd` unit files for both `RPC` and `Execution`
  * Examples are both below

## Setup a `hugetlbfs` mount using `hugeadm`

### General prerequisites

Install the required package:

```bash theme={null}
sudo apt install libhugetlbfs-bin
```

### Execution events SDK prerequisites

If you want to consume real-time data in your own software using the execution
events SDK, you must install these additional packages:

```bash theme={null}
sudo apt install libhugetlbfs-dev libhugetlbfs0 libzstd-dev
```

These are only required for the SDK; if you only need to enable WebSocket
support in the RPC server, you *do not* need these packages.

### CLI one-time setup

<Warning>
  This is for one-time testing and will NOT persist after a reboot
</Warning>

```bash theme={null}
# NOTE: here we use `monad` but if you are running as a custom user, that should be set here
$ sudo hugeadm --create-user-mounts monad
```

### Sample `systemd` unit file

This makes the mounts persistent after a reboot.

Create the service file:

```bash theme={null}
sudo nano /etc/systemd/system/events-hugepages-mounts.service
```

Paste the following contents:

```ini theme={null}
# NOTE: as mentioned above, you can change the `monad` user to your custom user (if needed)
[Unit]
Description=Create hugepage mounts for monad
After=local-fs.target

[Service]
Type=oneshot
ExecStart=/usr/bin/hugeadm --create-user-mounts monad
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
```

Save and exit (`Ctrl+O`, `Enter`, `Ctrl+X`).

Enable and start the service:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl enable --now events-hugepages-mounts
```

### Create the event-rings directory

The event-rings directory must exist for WebSocket events to work:

```bash theme={null}
sudo mkdir -p /var/lib/hugetlbfs/user/monad/pagesize-2MB/event-rings
sudo chown monad:monad /var/lib/hugetlbfs/user/monad/pagesize-2MB/event-rings
```

## Configure the `systemd` overrides

### Important items

`systemd`:

* As a reminder, if you installed Monad via `apt`, the `systemd` unit files live in: `/usr/lib/systemd/system`
* This means we need to create a `systemd` override
* `systemd` overrides for ExecStart (and other additive settings) require two blocks. The first "clears" the original value and the second sets the new value.
* You will need to do a `systemctl daemon-reload` after the changes

`events` + `WebSockets`:

* `RPC` + `WebSockets` has a HARD dependency on `Execution` running with `events`

`WebSockets` specific:

* You will need to open a port in your firewall
* The default is `8081`
* If you want to use a custom port, the `--ws-port <PORT>` for `RPC` allows you to set the port of your choosing

### Configure the `Execution` override for `systemd`

This override enables the `events` sub-component for `Execution`

<Warning>
  If `RPC` + `WebSockets` is started without `events` being enabled for `Execution`, `RPC` will start and then crash
</Warning>

You can launch the override editor via:

```bash theme={null}
sudo systemctl edit monad-execution
```

Which will make a new file at `/etc/systemd/system/monad-execution.service.d/override.conf`

File contents (as viewed when using the override editor):

```ini theme={null}
### Anything between here and the comment below will become the contents of the drop-in file

# NOTE: BOTH ExecStarts are REQUIRED

[Service]
ExecStart=
ExecStart=/usr/local/bin/monad \
    --chain "$CHAIN" \
    --db /dev/triedb \
    --block_db /home/monad/monad-bft/ledger \
    --statesync /home/monad/monad-bft/statesync.sock \
    --exec-event-ring /var/lib/hugetlbfs/user/monad/pagesize-2MB/event-rings/monad-exec-events \
    --sq_thread_cpu 1 \
    --log_level INFO

### Edits below this comment will be discarded
```

Do reload:

```bash theme={null}
sudo systemctl daemon-reload
```

### Restart `Execution`

Adding this step here to ensure that `Execution` is restarted with the `events` enabled

```bash theme={null}
sudo systemctl restart monad-execution
```

### Configure the `RPC` override for `systemd`

This override enables the `WebSockets` sub-component for `RPC`

You can launch the override editor via:

```bash theme={null}
sudo systemctl edit monad-rpc
```

Which will make a new file at `/etc/systemd/system/monad-rpc.service.d/override.conf`

File contents:

```ini theme={null}
# NOTE: BOTH ExecStarts are REQUIRED

[Service]
ExecStart=
ExecStart=/usr/local/bin/monad-rpc \
    --ipc-path /home/monad/monad-bft/mempool.sock \
    --triedb-path /dev/triedb \
    --otel-endpoint "http://0.0.0.0:4317" \
    --allow-unprotected-txs \
    --node-config /home/monad/monad-bft/config/node.toml \
    --exec-event-path /var/lib/hugetlbfs/user/monad/pagesize-2MB/event-rings/monad-exec-events \
    --ws-enabled
```

### Restart `RPC`

```bash theme={null}
sudo systemctl restart monad-rpc
```

### Checking the connectivity

A quick way to check if WebSocket connectivity is working is to use a
general purpose command-line tool that can act as WebSocket client,
such as [`websocat`](https://github.com/vi/websocat). This is a
powerful command-line "swiss army knife" tool, like `nc` or the
original `socat`. It is not officially packaged for Debian/Ubuntu yet,
but precompiled binaries can be downloaded or installed via
`cargo install websocat` (it is a Rust program).

Here is an example of running it in verbose mode (`-v`), with the
WebSocket service hosted on default port 8081:

```shell theme={null}
$ websocat -v ws://localhost:8081
[INFO  websocat::lints] Auto-inserting the line mode
[INFO  websocat::stdio_threaded_peer] get_stdio_peer (threaded)
[INFO  websocat::ws_client_peer] get_ws_client_peer
[INFO  websocat::net_peer] Connected to TCP 127.0.0.1:8081
[INFO  websocat::ws_client_peer] Connected to ws
[INFO  websocat::ws_peer] Received WebSocket ping
```

To subscribe, type the subscription JSON RPC call for
`eth_subscribe` into your terminal's stdin and press enter:

```json theme={null}
{ "id": 1, "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newHeads"] }
```

Every half-second or so, you should see updates about new blocks.


# How Full Nodes Receive Blocks
Source: https://docs.monad.xyz/node-ops/full-node-block-delivery



<Note>
  See [here](/node-ops/full-node-installation) for instructions on how to set up a full node.
</Note>

The [RaptorCast](/monad-arch/consensus/raptorcast) protocol is a new method of one-to-many
block propagation that uses an erasure-coded two-level broadcast tree to propagate large blocks
from a message originator to many listeners.

RaptorCast is used both for communication among validators, as well as for validators to
propagate blocks outward to full nodes.

The former is **primary RaptorCast** - how validators in the active set receive block proposals
from the leader.

The latter is **secondary RaptorCast** - how each validator pushes a block proposal to downstream
full nodes.
Secondary RaptorCast follows the same mechanism as primary RaptorCast, except the message
originator is fixed, other full nodes serve as the other participants, and all weights on the nodes
are equal rather than stake-weighted.

Secondary RaptorCast allows the network to support a huge set of full nodes. In the
recommended configuration, each validator has a secondary RaptorCast group of size 150, so if the
network has 200 nodes, there is capacity for 30,000 full nodes. After accounting for a redundancy
factor of 2 (full nodes may register for multiple secondary RaptorCast groups), there is still
capacity for 15,000 full nodes.

## How full nodes register for secondary RaptorCast

1. Full nodes start by peering with some of the validators. They do this by peering with the
   bootstrap peers specified in `node.toml`, then asking them for their peers, and repeating until they
   have the name records of the full validator set.

2. On a recurring basis, each validator (provided that it has `enable_publisher = true` in
   `node.toml`) sends invites to the full nodes in its routing table up to `max_group_size`,
   inviting the full nodes to join that validator's secondary RaptorCast group.

3. A full node will accept or reject, rejecting if they are already in too many groups.

4. The validator will collect these accept/reject responses and confirm a group.

5. The group will lasts for `round_span` specified in the validator's `node.toml` (default: 240
   rounds). When one of these intervals is close to finishing, the validator starts sending
   invites for its next secondary RaptorCast group.

6. Full nodes can (and should) join multiple secondary RaptorCast groups for redundancy.
   This is controlled by the `max_num_group` parameter below.

Note that when a full node first statesyncs, it will need to wait a little bit before being added
to a secondary RaptorCast group.

## Configuration

`node.toml` contains the following settings:

```
[fullnode_raptorcast]
enable_publisher = true
enable_client = true
raptor10_fullnode_redundancy_factor = 2.0
max_group_size = 150
round_span = 240
invite_lookahead = 20
max_invite_wait = 10
deadline_round_dist = 10
init_empty_round_span = 23
max_num_group = 3
invite_future_dist_min = 1
invite_future_dist_max = 600
invite_accept_heartbeat_ms = 10000

[fullnode_raptorcast.full_nodes_prioritized]
identities = []
```

Some parameters only affect validators:

* `enable_publisher = true` means that if the full node becomes a validator, it will participate
  as a secondary RaptorCast originator.
* `max_group_size` maximum number of full nodes in a group
* `round_span` number of rounds that a group last for
* `invite_lookahead` how far ahead (in rounds) does a validator sends invites to full nodes before the start of the round
* `max_invite_wait` maximum number of rounds that a validator wait for invite response from the full node

Some parameters only affect full nodes:

* full nodes should have `enable_client = true` to participate in secondary RaptorCast
* `max_num_group` indicates the maximum number of groups that the full node will join
* `invite_future_dist_min` and `invite_future_dist_max` indicates the time range (in rounds) that
  the full node will accept the secondary raptorcast group invite
* `invite_accept_heartbeat_ms` is a heartbeat which is used to determine whether the full node is
  receiving proposals

Although some parameters only affect full nodes, node operators running validators should still
populate these parameters thoughtfully because whenever the validator is not in the active set,
it should still keep up with the chain tip. Operators will likely want to start their validators
as full nodes before activating to avoid missing block proposals.

## Additional options

### Prioritized secondary RaptorCast inclusion

A full node may coordinate with a validator to be explicitly and consistently invited to that
validator's secondary RaptorCast group.

To do this, the full node provides some information for the validator to include in its
`[fullnode_raptorcast.full_nodes_prioritized.identities]` section.  See
[Validator Installation](/node-ops/validator-installation#configure-nodetoml) for details on what needs to
be provided. Note that this means the full node doesn't have to rely on peer discovery to peer with
that validator.

### Dedicated upstream

Validators also have the option of specifying full nodes to which they wish to directly forward
all primary RaptorCast chunks.

This utilizes a lot of validator bandwidth, since each registered downstream requires another
copy of all chunks to be sent. It is potentially more reliable for the downstream node than
subscribing via secondary RaptorCast, although in practice secondary RaptorCast is quite reliable.

Note that if a full node is designated by one or more validators for dedicated chunk forwarding,
then it could be configured with `enable_client = false`. This turns off attempting to participate
in secondary RaptorCast.

### Comparison

| Configuration                        | Requires validator to whitelist full node | RaptorCast mode         | Data Source          |
| ------------------------------------ | ----------------------------------------- | ----------------------- | -------------------- |
| **Normal**                           | No                                        | `enable_client = true`  | Secondary RaptorCast |
| **Prioritized secondary RaptorCast** | Yes                                       | `enable_client = true`  | Secondary RaptorCast |
| **Chunk forwarding**                 | Yes                                       | `enable_client = false` | Primary RaptorCast   |

Note that these configurations are properties of a **relationship** between a full node and a
validator, rather than properties of the full node itself.

A full node could coordinate with multiple validators to treat it specially, while
also participating in normal secondary RaptorCast with other validators that it automatically
peers with.

## RaptorCast configurations for validators

Validators can toggle off their participation in secondary RaptorCast by setting
`enable_publisher = false`.

Although turning secondary RaptorCast off will reduce bandwidth usage,
note that the bandwidth cost of secondary RaptorCast is relatively low; for example, even at
10,000 transactions per second, the expected usage will be about 6 MB per second (3 MB of
block data with 2x redundancy). Therefore, it is recommended to keep `enable_publisher = true`.

<Tip title="RaptorCast">
  For more technical details about the RaptorCast, see the
  [RaptorCast documentation](/monad-arch/consensus/raptorcast).
</Tip>


# Full Node Installation
Source: https://docs.monad.xyz/node-ops/full-node-installation



## Components

Monad nodes are running services using `systemd`:

* `monad-bft` - Consensus client
* `monad-execution` - Execution client
* `monad-rpc` - RPC server
* `monad-mpt` - One-time execution for initializing the TrieDB disk
* `monad-cruft` - Cleanup service running hourly
* `otelcol` - OTEL collector service for metric collection

The systemd services are running using `monad` service user.

The configuration and data structure is:

* `/home/monad/.env` - contains the environment variables to configure monad services
* `/home/monad/monad-bft/config/node.toml` - contains configurable consensus parameters, most
  notably the name of the node, typically `"<PROVIDER_NAME>-1"` and a list of upstream validators
  (denoted by secp pubkey and DNS) who have been configured to republish blocks to your full node.
* `/home/monad/monad-bft/config/forkpoint/` - contains consensus quorum checkpoints (written every
  block) used for bootstrapping state
* `/home/monad/monad-bft/config/validators/` - contains validator sets generated at the
  [boundary block](/monad-arch/consensus/staking#epochs-and-boundaries). The newly generated
  file contains the consensus validator sets for the current epoch and for the upcoming epoch.
  The most recent validator set is found at `validators.toml`.
* `/home/monad/monad-bft/ledger/` - contains consensus (BFT) block headers and bodies, including the transactions
* `/dev/triedb` - TrieDB database device, contains the state of the blockchain

## Prerequisites

Please refer to the [Hardware Requirements](/node-ops/hardware-requirements) before continuing.

* Bare-metal server
* Ubuntu 24.04+ Operating system
* Linux Kernel >= 6.8.0.60 (see warning below)
* Disabled HyperThreading (HT) or Simultaneous MultiThreading (SMT) via BIOS settings
  * these features degrade the node performance

<Warning>
  There is a [known bug](https://bugs.launchpad.net/ubuntu/%2Bsource/linux/%2Bbug/2105471) affecting
  Linux kernel versions `v6.8.0.56-generic` - `v6.8.0.59-generic` (inclusive) that causes Monad
  clients to hang in an uninterruptible sleep state, severely impacting node stability.
  We recommend `v6.8.0.60-generic` or higher.
</Warning>

## Prepare the Node

<Info>
  The following instructions assume the commands are executed as `root` user.
</Info>

### Update the system

Update the system.

```bash theme={null}
apt update
apt upgrade -y
```

Reboot the machine if required, for example if the upgrade prints `Pending kernel upgrade!`.

Install additional dependencies.

```bash theme={null}
apt install -y curl nvme-cli aria2 jq
```

### Install `monad` package

Configure the APT repository.

```bash theme={null}
cat <<EOF > /etc/apt/sources.list.d/category-labs.sources
Types: deb
URIs: https://pkg.category.xyz/
Suites: noble
Components: main
Signed-By: /etc/apt/keyrings/category-labs.gpg
EOF

curl -fsSL https://pkg.category.xyz/keys/public-key.asc \
  | gpg --dearmor --yes -o /etc/apt/keyrings/category-labs.gpg
```

<Tabs>
  <Tab title="Mainnet">
    Install `monad` package.

    <CodeBlock />
  </Tab>

  <Tab title="Testnet">
    Install `monad` package.

    <CodeBlock />
  </Tab>
</Tabs>

### Create `monad` user

Create a non-privileged user named `monad` with a home directory and Bash shell.

```bash theme={null}
useradd -m -s /bin/bash monad
```

Create config directories structure in `/home/monad`.

```bash theme={null}
mkdir -p /home/monad/monad-bft/config \
         /home/monad/monad-bft/ledger \
         /home/monad/monad-bft/config/forkpoint \
         /home/monad/monad-bft/config/validators
```

### Configure TrieDB Device

#### Create the device

Set the NVMe drive (e.g. `/dev/nvme1n1`) to be used for TrieDB device, create a new partition table and a partition that spans the
entire drive. The drive should be on a disk that has no filesystem mounted and no RAID configured.

<Warning title="IMPORTANT: Identify drives carefully">
  **Formatting the wrong drive will destroy your operating system!**
  Before proceeding, verify which drive to use:

  ```bash theme={null}
  nvme list
  lsblk -o NAME,SIZE,TYPE,MOUNTPOINT,MODEL
  ```

  Look for a drive with **no mountpoints**. Your OS drive will show `/`, `/boot`, or swap partitions.
</Warning>

```bash theme={null}
TRIEDB_DRIVE=/dev/nvme1n1 # CHANGE THIS TO YOUR NVME DRIVE

parted $TRIEDB_DRIVE mklabel gpt
parted $TRIEDB_DRIVE mkpart triedb 0% 100%
```

Create a udev rule to set permissions and create a symlink for the partition.

```bash theme={null}
PARTUUID=$(lsblk -o PARTUUID $TRIEDB_DRIVE | tail -n 1)
echo "Disk PartUUID: ${PARTUUID}"

echo "ENV{ID_PART_ENTRY_UUID}==\"$PARTUUID\", MODE=\"0666\", SYMLINK+=\"triedb\"" \
  | tee /etc/udev/rules.d/99-triedb.rules
```

Trigger and reload udev rules, and verify TrieDB is pointing to the NVMe device.

```bash theme={null}
udevadm trigger
udevadm control --reload
udevadm settle
ls -l /dev/triedb
```

#### Verify the LBA configuration

Verify LBA Configuration, and enable 512 byte LBA if not enabled.

Check if 512 byte LBA is enabled on `TRIEDB_DRIVE`:

```bash theme={null}
nvme id-ns -H $TRIEDB_DRIVE | grep 'LBA Format' | grep 'in use'
```

This command should return the following expected output:

```
LBA Format  0 : Metadata Size: 0   bytes - Data Size: 512 bytes - Relative Performance: 0 Best (in use)
```

<Info>
  `Data Size` should be set to `512 bytes` and marked as `(in use)`. If that is **not** the case,
  then you will need to set the `TRIEDB_DRIVE` to use 512 byte LBA with the following command.

  ```bash theme={null}
  nvme format --lbaf=0 $TRIEDB_DRIVE
  ```

  Verify that the configuration has been corrected.

  ```bash theme={null}
  nvme id-ns -H $TRIEDB_DRIVE | grep 'LBA Format' | grep 'in use'
  ```
</Info>

#### Format the partition

Format the TrieDB partition by executing the `monad-mpt` one-time service.

```
systemctl start monad-mpt
journalctl -u monad-mpt -n 14 -o cat
```

This should return similar output.

```
MPT database on storages:
          Capacity           Used      %  Path
           1.75 Tb      256.03 Mb  0.01%  "/dev/nvme1n1p1"
MPT database internal lists:
     Fast: 1 chunks with capacity 256.00 Mb used 0.00 bytes
     Slow: 1 chunks with capacity 256.00 Mb used 0.00 bytes
     Free: 7148 chunks with capacity 1.75 Tb used 0.00 bytes
MPT database has 1 history, earliest is 18446744073709551615 latest is 18446744073709551615.
     It has been configured to retain no more than 33554432.
     Latest proposed is (18446744073709551615, 0000000000000000000000000000000000000000000000000000000000000000).
     Latest voted is (18446744073709551615, 0000000000000000000000000000000000000000000000000000000000000000).
     Latest finalized is 18446744073709551615, latest verified is 18446744073709551615, auto expire version is 0
monad-mpt.service: Deactivated successfully.
Finished monad-mpt.service - "Service file for Monad MPT".
```

### Configure Firewall rules

Configure these firewall rules:

* block all incoming traffic and enable all outgoing (default)
* allow SSH inbound connections (remote access)
* allow inbound and outbound to port 8000 for TCP/UDP (Consensus client P2P traffic)

Setup the UFW firewall:

```bash theme={null}
ufw allow ssh
ufw allow 8000
ufw allow 8001
ufw enable
ufw status
```

Configure the following iptables rule for improved robustness against spam:

```bash theme={null}
sudo iptables -I INPUT -p udp --dport 8000 -m length --length 0:1400 -j DROP
```

Please note that this rule will be reset upon reboot, so node operators should use their preferred mechanism, e.g. `iptables-persistent` for persisting iptables rules.

<Tip title="Hardware firewalls">
  If using hardware firewalls, you may need to perform additional steps to open up port 8000 to UDP
  and TCP traffic.
</Tip>

<Note title="Test outbound TCP">
  To verify outbound connectivity on TCP port 8000, test a connection to remote host:

  ```
  $ nc -vz 64.31.29.190 8000
  Connection to 64.31.29.190 8000 port [tcp/*] succeeded!
  ```

  See the `node.toml` file to test with a remote bootstrap peer.
</Note>

### Configure OTEL Collector

The monad package supports OTEL collector. Through this, you will be able to see all the
relevant Monad-specific metrics, available at `http://0.0.0.0:8889/metrics`.

```bash theme={null}
OTEL_VERSION="0.139.0"
OTEL_CHECKSUM="1a1576dde7d51fa7094f4963ceaff37c91ac7b9c9593ba735a3a328ec6f8acd9"
OTEL_PACKAGE="https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v${OTEL_VERSION}/otelcol_${OTEL_VERSION}_linux_amd64.deb"
OTEL_DEB="/tmp/otelcol_linux_amd64.deb"

curl -fsSL "$OTEL_PACKAGE" -o "$OTEL_DEB"

if echo "${OTEL_CHECKSUM}  ${OTEL_DEB}" | sha256sum --check --quiet; then
  dpkg -i "$OTEL_DEB"
  cp /opt/monad/scripts/otel-config.yaml /etc/otelcol/config.yaml
  systemctl restart otelcol
else
  echo "Checksum verification failed — aborting install." >&2
fi
```

## Configure the Node

### Get configuration files

<Tabs>
  <Tab title="Mainnet">
    Configuration files for **full nodes**:

    ```bash theme={null}
    MF_BUCKET=https://bucket.monadinfra.com
    curl -o /home/monad/.env $MF_BUCKET/config/mainnet/latest/.env.example
    curl -o /home/monad/monad-bft/config/node.toml $MF_BUCKET/config/mainnet/latest/full-node-node.toml
    ```

    Configuration files for **validators**:

    ```bash theme={null}
    MF_BUCKET=https://bucket.monadinfra.com
    curl -o /home/monad/.env $MF_BUCKET/config/mainnet/latest/.env.example
    curl -o /home/monad/monad-bft/config/node.toml $MF_BUCKET/config/mainnet/latest/node.toml
    ```
  </Tab>

  <Tab title="Testnet">
    Configuration files for **full nodes**:

    ```bash theme={null}
    MF_BUCKET=https://bucket.monadinfra.com
    curl -o /home/monad/.env $MF_BUCKET/config/testnet/latest/.env.example
    curl -o /home/monad/monad-bft/config/node.toml $MF_BUCKET/config/testnet/latest/full-node-node.toml
    ```

    Configuration files for **validators**:

    ```bash theme={null}
    MF_BUCKET=https://bucket.monadinfra.com
    curl -o /home/monad/.env $MF_BUCKET/config/testnet/latest/.env.example
    curl -o /home/monad/monad-bft/config/node.toml $MF_BUCKET/config/testnet/latest/node.toml
    ```
  </Tab>
</Tabs>

### Define Keystore password

Set your own unique and strong password for `KEYSTORE_PASSWORD`.
This password is used to encrypt and decrypt your keystores.
It must be wrapped in single quotes (e.g. `'password'`).

Assuming `KEYSTORE_PASSWORD` in `/home/monad/.env` file is not already set, generate a secure random password.

```
sed -i "s|^KEYSTORE_PASSWORD=$|KEYSTORE_PASSWORD='$(openssl rand -base64 32)'|" /home/monad/.env
source /home/monad/.env

mkdir -p /opt/monad/backup/
echo "Keystore password: ${KEYSTORE_PASSWORD}" > /opt/monad/backup/keystore-password-backup
```

### Generate Keystores

Generate encrypted BLS and SECP keys using `monad-keystore` binary.

```bash theme={null}
bash <<'EOF'
set -e

source /home/monad/.env

if [[ -z "$KEYSTORE_PASSWORD" || \
      -f /home/monad/monad-bft/config/id-secp || \
      -f /home/monad/monad-bft/config/id-bls ]]; then
  echo "Skipping: missing KEYSTORE_PASSWORD or keys already exist."
  exit 1
fi

monad-keystore create \
  --key-type secp \
  --keystore-path /home/monad/monad-bft/config/id-secp \
  --password "${KEYSTORE_PASSWORD}" > /opt/monad/backup/secp-backup

monad-keystore create \
  --key-type bls \
  --keystore-path /home/monad/monad-bft/config/id-bls \
  --password "${KEYSTORE_PASSWORD}" > /opt/monad/backup/bls-backup

grep "public key" /opt/monad/backup/secp-backup /opt/monad/backup/bls-backup \
  | tee /home/monad/pubkey-secp-bls

echo "Success: New keystores generated"

EOF
```

Public keys are exported to `/home/monad/pubkey-secp-bls` for convenience.

<Warning title="External Backup">
  These files contain your node's private keys — they define your node identity. Anyone with access to them can take over your node's identity.

  **Please ensure that these backup files are stored in an external location outside of the node (e.g. a password manager or secrets vault). They are required to restore your full node or validator identity in the event of hardware failure or system loss:**

  * `/opt/monad/backup/secp-backup`
  * `/opt/monad/backup/bls-backup`

  For validators, this is especially important: losing your keys means you cannot migrate your validator, and re-registering with a new identity requires moving all delegations manually.
</Warning>

### Update `node.toml`

<Note title="Public full node configuration">
  Full nodes can receive block proposals either directly from a validator that whitelists it,
  or via a raptorcast group. These different configurations are described
  [here](/node-ops/full-node-block-delivery).

  The bellow instructions are intended for the **public full node** configuration,
  where a full node joins the network by connecting to available upstream validators participating
  in secondary raptorcast. Joining in this configuration is **permissionless**.
</Note>

Update the configuration that was downloaded previously (for reference, you can check the [testnet config](https://bucket.monadinfra.com/config/testnet/latest/full-node-node.toml) and the [mainnet config](https://bucket.monadinfra.com/config/mainnet/latest/full-node-node.toml)):

1. Edit `/home/monad/monad-bft/config/node.toml` using a text editor (e.g., `nano /home/monad/monad-bft/config/node.toml`).

2. The `beneficiary` field to include the address that should receive block rewards.<br />
   For **full nodes**, this field can be set to the burn address.
   ```
   beneficiary = "0x0000000000000000000000000000000000000000"
   ```
   For **validator**, use the beneficiary wallet address. This address should be prefixed by `0x`.
   ```
   beneficiary = "0x<VALIDATOR_REWARDS_ADDRESS>"
   ```

3. Update the `node_name` field to include your provider name.
   Note that if you are operating multiple nodes, **the node name should be unique**.
   ```bash theme={null}
   node_name = "full_<PROVIDER>-<OPTIONAL_SUFFIX>"
   ```

4. Ensure `enable_client = true` under `[fullnode_raptorcast]`.

5. Ensure `expand_to_group = true` under `[statesync]`.

6. `[blocksync_override]` peers should remain empty for public full nodes.

### Node signature record

The node Name record is a cryptographically signed record that contains a node's network address information and is used for peer discovery and network topology management in the monad-bft system.

Using the keypairs are created, a fullnode will need to sign its name record using the SECP key in order to participate in peer discovery.

The sequence number (seq) in the record allows nodes to determine which version of a peer's address information is most recent, supporting scenarios where nodes change their network location.

```
source /home/monad/.env
monad-sign-name-record \
  --address $(curl -s4 ifconfig.me):8000 \
  --authenticated-udp-port 8001 \
  --keystore-path /home/monad/monad-bft/config/id-secp \
  --password "${KEYSTORE_PASSWORD}" \
  --self-record-seq-num 1
```

Update the `peer_discovery` section in `node.toml` with the IP addresses, sequence number and name record signature generated from the previous command, for example:

```
self_address = "12.34.56.78:8000"
self_record_seq_num = 1
self_name_record_sig = "5995f8dc5af4ca70e3b49ce793e7fe353d72b261c14037272958a9f0cc105fdd4890e56cb99765750ca48bab113cccbb378fc61dff8b23da4a03c07bba60034300"
```

### Remote Configuration Fetching (v0.12.1+)

Nodes can automatically fetch `forkpoint.toml` and `validators.toml` from remote locations on startup.
This feature is configured using the following environment variables in `/home/monad/.env`:

<Tabs>
  <Tab title="Mainnet">
    ```bash theme={null}
    REMOTE_VALIDATORS_URL='https://bucket.monadinfra.com/validators/mainnet/validators.toml'
    REMOTE_FORKPOINT_URL='https://bucket.monadinfra.com/forkpoint/mainnet/forkpoint.toml'
    ```
  </Tab>

  <Tab title="Testnet">
    ```bash theme={null}
    REMOTE_VALIDATORS_URL='https://bucket.monadinfra.com/validators/testnet/validators.toml'
    REMOTE_FORKPOINT_URL='https://bucket.monadinfra.com/forkpoint/testnet/forkpoint.toml'
    ```
  </Tab>
</Tabs>

These URLs point to the latest configuration files.
When defined, the node will automatically attempt to download fresh configuration files on startup, simplifying node operations and reducing manual intervention during network updates.
Monad Foundation is not the exclusive provider of these configuration files. Feel free to replace the above remote links with those from other providers.

### Call traces (optional)

For full nodes intended for archiving or RPC workflows, enabling `--trace_calls` is recommended.
This preserves the detailed error information necessary for call traces, e.g. `debug_traceTransaction`.
To make this override, please run `systemctl edit monad-execution` and add the `--trace_calls` CLI param
to the `ExecStart` definition (may need a line continuation character `\`):

```sh theme={null}
systemctl edit monad-execution
```

```toml theme={null}
[Service]
Type=simple
ExecStart=
ExecStart=/usr/local/bin/monad \
    ...
    --trace_calls
    ...
```

### Monad Cruft service

Installation of the `monad` Debian package enables the `monad-cruft` timer, which runs hourly to
clear old artifacts (`/opt/monad/scripts/clear-old-artifacts.sh`). This is necessary to prevent
inode exhaustion as artifacts like `forkpoint.toml` and ledger files accumulate.

Starting with v0.12.2, you can configure artifact retention times by setting environment variables in `/home/monad/.env`. The following variables control how long artifacts are retained before deletion (all values in minutes):

* `RETENTION_LEDGER` - Ledger files (headers and bodies, default: 600 = 10 hours)
* `RETENTION_WAL` - WAL files (default: 300 = 5 hours)
* `RETENTION_FORKPOINT` - Forkpoint files (default: 300 = 5 hours)
* `RETENTION_VALIDATORS` - Validators files (default: 43200 = 30 days)

```bash theme={null}
# Example: Add retention configuration to /home/monad/.env
RETENTION_LEDGER=600
RETENTION_WAL=300
RETENTION_FORKPOINT=300
RETENTION_VALIDATORS=43200
```

To customize retention, add or modify these variables in `/home/monad/.env`. For example, to retain ledger files for 20 hours:

```bash theme={null}
echo "RETENTION_LEDGER=1200" >> /home/monad/.env
```

These settings will be automatically picked up by the `monad-cruft` timer on its next hourly run.

## Start the Node

Set filesystem permissions:

```bash theme={null}
chown -R monad:monad /home/monad/
```

Enable the monad services to allow them to automatically start whenever the server is rebooted:

```bash theme={null}
systemctl enable monad-bft monad-execution monad-rpc
```

**Next, run the [Hard Reset Instructions](/node-ops/node-recovery/hard-reset)** to import a recent database snapshot into the node.

Start the monad services:

```bash theme={null}
systemctl start monad-bft monad-execution monad-rpc
```

**This completes the process of starting up a full node!**

Refer to the [General Operations](/node-ops/general-operations) to monitor the state of the node.

## Keeping Updated

To stay updated on new releases:

* join the [Monad Node Announcements](https://t.me/MonadNodeAnnouncements) telegram group, or
* join the [Monad Developer Discord](https://discord.gg/monaddev) and follow the `#mainnet-fullnode-announcements` channel


# General Operations
Source: https://docs.monad.xyz/node-ops/general-operations



## Version Information

View the version and build information for your Monad binaries:

```bash theme={null}
monad-node --version
# Example output: monad-node {"commit":"c0cdcaae8eb527e44d72c4638c1f1335025a5132","tag":"v0.12.2-rc","branch":"","modified":true}
```

## CLI Help

View available command-line arguments for any Monad binary:

```bash theme={null}
monad-rpc --help
monad --help
monad-bft --help
```

<Warning>
  CLI arguments should not be changed arbitrarily as some configurations may result in unexpected behavior or crashes.
</Warning>

## Service Management

Check the status of Monad services:

```bash theme={null}
# Check all services at once
systemctl status monad-bft monad-execution monad-rpc --no-pager -l

# Check individual service status
systemctl status monad-bft
systemctl status monad-execution
systemctl status monad-rpc

# View logs for a specific service
journalctl -u monad-bft -f
journalctl -u monad-execution -f
journalctl -u monad-rpc -f
```

## Monitoring Block Height

The RPC service will start listening on port `8080` when the statesync is completed.

Check the current block height via RPC:

```bash theme={null}
curl http://localhost:8080/ \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}'
```

## Viewing MonadDB Disk Usage

Note that MonadDB (TrieDB) will automatically compact when at 80% capacity to preserve
optimal SSD performance. To check MonadDB disk usage and retained block history:

```bash theme={null}
monad-mpt --storage /dev/triedb
```

Example output:

```
MPT database on storages:
          Capacity           Used      %  Path
           3.49 Tb       24.30 Gb  0.68%  "/dev/nvme1n1p1"
MPT database internal lists:
     Fast: 94 chunks with capacity 23.50 Gb used 23.40 Gb
     Slow: 3 chunks with capacity 768.00 Mb used 658.72 Mb
     Free: 14207 chunks with capacity 3.47 Tb used 0.00 bytes
MPT database has 599928 history, earliest is 36784905 latest is 37384832.
     It has been configured to retain no more than 33554432.
     Latest proposed is (37384832, 88a5550ba067c2f21cef6b6e8953fbf700fe300905952e5621335fe2bd58729c).
     Latest voted is (37384831, 56074c2429909c2966bfe8df55810ec3b8f4f4f599b407ff89ec92b090656ab1).
     Latest finalized is 37384830, latest verified is 37384827, auto expire version is 36784905
```

## Log Analysis with `monlog`

`monlog` is a lightweight tool maintained by [Category Labs](https://www.category.xyz)
that scrapes BFT logs and provides useful status information and suggestions. It
examines logs from the last 60 seconds.

**Setup (as root user):**

First, grant the monad user access to read systemd journal logs:

```bash theme={null}
# Add monad user to systemd-journal group
usermod -a -G systemd-journal monad
```

**Download monlog (as monad user):**

```bash theme={null}
cd /home/monad
curl -sSL https://pub-b0d0d7272c994851b4c8af22a766f571.r2.dev/scripts/monlog -O
chmod u+x ./monlog

# confirm sha
sha256sum ./monlog
f8a1066d8c093bbdb5f722f5b3d89904c17a76fa01fa1dd62e950f445e88327f  ./monlog
```

<Info>
  If you're already logged in as the monad user when the group is added, you'll need to log out and log back in for the group membership to take effect. Alternatively, you can run `su - monad` to start a new session.
</Info>

**Run monlog (as monad user):**

```bash theme={null}
./monlog

# For live updates
watch -d "./monlog"

# Show last 10 lines of grabbed logs
./monlog -r

# Show secp keys mapped to validator names
./monlog -n 
e.g. 
    0123123ae (validator name)

# Show with no color coding
./monlog --no-color
```

Example output for a healthy node:

```
# FYI this is without color coding 

Installed version:
ii monad 0.12.1~rc amd64 Monad BFT stack (symbols stripped)

No StateSync messages.
---
No BlockSync messages.
---
Most recent round: 52268965
Most recent epoch: 1001
Most recent block: 50041845
Blocks processing and being committed ✅
```

## Consensus Information with `ledger-tail`

`monad-ledger-tail` exposes consensus information by directly parsing ledger artifacts
and streams the data in JSON format.

Start the service:

```bash theme={null}
systemctl start monad-ledger-tail

# View output
journalctl -fu monad-ledger-tail
```

Example output:

```json theme={null}
// the real output is all on one line, but we've prettified this for legibility:
{
  "timestamp": "2025-11-23T03:09:09.534974Z",
  "level": "INFO",
  "fields": {
    "message": "proposed_block",
    "round": "53449032",
    "parent_round": "53449031",
    "epoch": "1024",
    "seq_num": "51203516",
    "num_tx": "3",
    "author": "036daee7750e29e46eb64d86ad1cc7b235d7f1ad9597941a3a77cdd641cead4528",
    "block_ts_ms": "1763867349470",
    "now_ts_ms": "1763867349534",
    "author_address": ""
  },
  "target": "ledger_tail"
}
```

## Node Status with `monad-status`

Install `monad-status`:

```
curl -sSL https://bucket.monadinfra.com/scripts/monad-status.sh -o /usr/local/bin/monad-status
chmod +x /usr/local/bin/monad-status
```

Run `monad-status` to get the status of the node.

This should print similar output:

```yaml theme={null}
### Monad Node Status

hostname: monad-node
date: Wed Nov 26 10:48:26 PM CET 2025
uptime: 0d 00h 41m 49s
version: 0.12.2
config:
  network: mainnet
  chain: monad_mainnet
  chainId: 143
  secpPublicKey: 03831b36b50261011d82f94d58f8aa0edfe058359e2c365c37cce678436b9eb371
  blsPublicKey: b9c1905e11e8395a789bece454ec24bed98b96cf9dc04c02c9512fb94900d3e0355383e542c44a0eb1be4d2780a1fb2f
  nodeSignature: 4f6e3e47af0e8ff3614e1eb53f9015ef4fc8593e60c13d52c2b458d05385b5f94cff8776ceb8b9401c3647148637d599622353d0631864a23b07f6d7fb55e84f00
  selfAddress: 65.109.145.172:8000
  recordSeqNum: 0
services:
  monad-bft: running
  monad-execution: running
  monad-rpc: running
  otelcol: running
  monad-cruft:
    activated: true
    previous: 48min ago
    next: 11min
peers:
  peersNumber: 1146
consensus:
  status: in-sync
  mode: live
  epoch: 764
  round: 38259075
  blockNumber: 38200041
  blockNumberFromExternal: 38200040
  blockDifference: 0
statesync:
  percentage: 100.0000%
  progress: 38193694
  target: 38193694
rpc:
  status: active
  clientVersion: Monad/0.12.2
  netVersion: 143
  blockNumber: 38200041
```

## Exporting Key Backups

If you followed the [full node installation](/node-ops/full-node-installation#generate-keystores) guide,
backup files for your keys were automatically created at:

* `/opt/monad/backup/secp-backup`
* `/opt/monad/backup/bls-backup`

If those files are missing or you need to re-export your keys, use the commands below to
recreate them. Any existing backup files will be preserved with a timestamp suffix before
being overwritten.

```bash theme={null}
source /home/monad/.env

[ -f /opt/monad/backup/secp-backup ] && mv /opt/monad/backup/secp-backup "/opt/monad/backup/secp-backup.$(date +%Y%m%d%H%M%S).bak"
[ -f /opt/monad/backup/bls-backup ] && mv /opt/monad/backup/bls-backup "/opt/monad/backup/bls-backup.$(date +%Y%m%d%H%M%S).bak"

monad-keystore recover \
  --password "$KEYSTORE_PASSWORD" \
  --keystore-path /home/monad/monad-bft/config/id-secp \
  --key-type secp > /opt/monad/backup/secp-backup

monad-keystore recover \
  --password "$KEYSTORE_PASSWORD" \
  --keystore-path /home/monad/monad-bft/config/id-bls \
  --key-type bls > /opt/monad/backup/bls-backup
```

<Warning title="External Backup">
  These files contain your node's private keys — they define your node identity. Anyone with access to them can take over your node's identity.

  **Ensure that these backup files are stored in an external location outside of the node (e.g. a password manager or secrets vault). They are required to restore your full node or validator identity in the event of hardware failure or system loss:**

  * `/opt/monad/backup/secp-backup`
  * `/opt/monad/backup/bls-backup`

  For validators, this is especially important: losing your keys means you cannot migrate your validator, and re-registering with a new identity requires moving all delegations manually.
</Warning>

## Importing Keys from Backups

To restore your node identity from a backup, extract the IKM secret from each backup file and
import it using `monad-keystore import`:

```bash theme={null}
source /home/monad/.env

[ -f /home/monad/monad-bft/config/id-secp ] && mv /home/monad/monad-bft/config/id-secp "/home/monad/monad-bft/config/id-secp.$(date +%Y%m%d%H%M%S).bak"
[ -f /home/monad/monad-bft/config/id-bls ] && mv /home/monad/monad-bft/config/id-bls "/home/monad/monad-bft/config/id-bls.$(date +%Y%m%d%H%M%S).bak"

SECP_IKM=$(grep -E "Keystore secret:|Keep your IKM secure:" /opt/monad/backup/secp-backup | awk '{print $NF}')
BLS_IKM=$(grep -E "Keystore secret:|Keep your IKM secure:" /opt/monad/backup/bls-backup | awk '{print $NF}')

monad-keystore import \
  --ikm "$SECP_IKM" \
  --password "$KEYSTORE_PASSWORD" \
  --keystore-path /home/monad/monad-bft/config/id-secp \
  --key-type secp

monad-keystore import \
  --ikm "$BLS_IKM" \
  --password "$KEYSTORE_PASSWORD" \
  --keystore-path /home/monad/monad-bft/config/id-bls \
  --key-type bls
```

## Keeping Updated

To stay updated on new releases:

* join the [Monad Node Announcements](https://t.me/MonadNodeAnnouncements) telegram group, or
* join the [Monad Developer Discord](https://discord.gg/monaddev) and follow the `#mainnet-fullnode-announcements` channel


# Hardware Requirements
Source: https://docs.monad.xyz/node-ops/hardware-requirements



<Warning>
  Cloud-based environments are not officially supported.
</Warning>

## Requirements

All requirements are the same between validators (consensus participants) and full nodes
aside from bandwidth:

* **CPU**: 16 core CPU with 4.5 GHz+ base clock speed, e.g. AMD Ryzen 9950x, AMD Ryzen 7950x,
  AMD EPYC 4584PX, etc.
* **Memory**: 32 GB+ RAM
* **Storage**:
  * 2TB dedicated disk for TrieDB (Execution)
  * 500GB Disk for MonadBFT / OS
  * PCIe Gen4x4 NVME SSD or better for both
* **Bandwidth**:
  * 300 Mbit/s (Validators)
  * 100 Mbit/s (Full Nodes)

<Warning>
  Hard drive performance can vary dramatically by manufacturer. Below are results from internal testing:

  **Ranked performance**

  1. Samsung 980 / 990 Pro - PCIe 4.0, top class performance
  2. Samsung PM9A1 - PCIe 4.0, pretty good performance and stable performance under load
  3. Micron 7450 - PCIe 4.0, pretty good performance BUT has weird random slowdowns under a lot of load

  **Known unreliable**

  1. Nextorage SSDs - can become unresponsive under load due to overheating, requiring a system reboot.
</Warning>

A community-driven set of hardware recommendations and notes can be found [here](https://monadhcl.xyz/#recommended-hardware).

## Why Bare Metal?

Monad nodes must operate on bare metal servers rather than virtualized or cloud-based environments (e.g., AWS EC2, GCP, Azure) due to the system's strict performance and timing requirements.

A bare metal server gives the node direct, stable access to hardware, ensuring smooth operation and synchronization with the network:

* Monad’s consensus protocol enforces tight time windows—blocks are proposed and voted on in sub-second intervals, and the network assumes nodes can validate and execute blocks within this budget. In such a situation, cloud-based environments may introduce latency and unpredictability, which can cause nodes to miss deadlines, fall behind in block processing, or become unstable during high-throughput periods.

* Even when resources appear sufficient on paper, virtualization adds an additional layer of software between the node and physical hardware. This layer introduces context switching overhead and restricts direct I/O access to SSDs and network interfaces. These effects are negligible for average compute tasks but become significant when sustained high-throughput and low-latency operations are required, as in Monad’s consensus and execution loops.

In summary, a bare metal server provides predictability and determinism, which are crucial for maintaining synchronization and throughput across the network. Cloud-hosted VMs may work under light loads, but they cannot guarantee consistent real-time performance required by Monad consensus at scale.


# Node Operations
Source: https://docs.monad.xyz/node-ops/index



## Setup

<CardGroup>
  <Card title="Hardware Requirements" href="/node-ops/hardware-requirements">
    High performance on commodity hardware
  </Card>

  <Card title="Full Node Installation" href="/node-ops/full-node-installation">
    How to run a full node
  </Card>

  <Card title="Validator Installation" href="/node-ops/validator-installation">
    How to run a validator
  </Card>
</CardGroup>

## Operations

<CardGroup>
  <Card title="General Operations" href="/node-ops/general-operations">
    Command-line tools for debugging or checking node status
  </Card>

  <Card title="Upgrade Instructions" href="/node-ops/upgrade-instructions">
    Instructions for specific upgrade sequences
  </Card>

  <Card title="Recovering a node" href="/node-ops/node-recovery">
    Procedures for recovering node operation
  </Card>
</CardGroup>

## Advanced

<CardGroup>
  <Card title="How Full Nodes Receive Blocks" href="/node-ops/full-node-block-delivery">
    How to configure node.toml to receive blocks from validators
  </Card>

  <Card title="Execution Events and WebSockets" href="/node-ops/events-and-websockets">
    Additional setup instructions if you need real-time data
  </Card>

  <Card title="Archive Data Setup" href="/node-ops/archive-data">
    How to configure your node to serve historical transactional data
  </Card>

  <Card title="Validator Delegation Program" href="/node-ops/validator-delegation-program">
    Foundation delegation framework for validators
  </Card>
</CardGroup>


# Full Replay
Source: https://docs.monad.xyz/node-ops/node-recovery/full-replay



Full Replay allows a node to catch up on missed blocks by simply retrieving and replaying them
serially. This is helpful for nodes that want all intermediary state and transactional artifacts
to be generated. For example, an RPC provider would probably want this to ensure that they can
respond to requests like `eth_call`, `eth_getBalance`, or `eth_estimateGas` for blocks
that were skipped.

## Context

A node that has not locally executed block `forkpoint.root - delay` will statesync on startup. Also, nodes don’t serve blocksync requests more than statesync\_threshold (600) blocks ago. Statesync is the only in-protocol way for that node to recover.

This document describes an *alternate* way to recover a node while backfilling historical state in the event that a node has been down for longer than the blocksync provision window (600 blocks).

Note that if `statesync_threshold` in `node.toml` is set to a value larger than that, blocksync will fail.

<Warning title="Access to a healthy node required">
  In order to recover the faulty node with complete historical state, the below
  procedure *requires SSH access to a node that was healthy* throughout the faulty node's downtime.

  Let `REMOTE_HOST` be the healthy node that can be used for recovery.
</Warning>

## Procedure

1. SSH into the faulty node as `monad` user.
2. Ensure `statesync_threshold = 600` in `node.toml`

```bash theme={null}
$ grep statesync_threshold /home/monad/monad-bft/config/node.toml
statesync_threshold = 600
```

1. Stop the monad services

```bash theme={null}
sudo systemctl stop monad-bft monad-execution monad-rpc
```

1. Run this script to copy missing blocks, then run execution up to that point. You will need to run it several times since the tip of the chain will continue advancing while this script is executing.

   1. NOTE: You will need to manually interrupt the process (Ctrl - C) once output stops.

   2. Copy this script and name it `manual-sync.sh`

      ```bash theme={null}
      #!/usr/bin/env bash
      set -euo pipefail

      # Load config first so SSH_PORT, REMOTE_HOST, CHAIN etc are set
      source .env

      : "${SSH_PORT:?SSH_PORT must be set}"
      : "${REMOTE_HOST:?REMOTE_HOST must be set}"
      : "${CHAIN:?CHAIN must be set}"

      echo "Reading files from $REMOTE_HOST"
      echo "Using ssh port: $SSH_PORT"

      # Copy proposed and finalized header symlinks first
      rsync -avP -e "ssh -p $SSH_PORT" \
        "monad@$REMOTE_HOST:/home/monad/monad-bft/ledger/headers/*_head" \
        /home/monad/monad-bft/ledger/headers/

      # Copy new headers and bodies, but don't overwrite existing ones
      rsync -avP --ignore-existing -e "ssh -p $SSH_PORT" \
        "monad@$REMOTE_HOST:/home/monad/monad-bft/ledger/" \
        /home/monad/monad-bft/ledger/

      # Note: the --state-sync flag is NOT present
      /usr/local/bin/monad \
        --chain "$CHAIN" \
        --db /dev/triedb \
        --block_db /home/monad/monad-bft/ledger \
        --sq_thread_cpu 1 \
        --log_level INFO
      ```

   3. Run the script
      ```bash theme={null}
      REMOTE_HOST=node1.<provider>.com SSH_PORT=22 CHAIN=monad_mainnet bash manual-sync-step-1.sh
      ```

2. Once the first script completes in under 1 min, run this script:

   1. Copy this and name it `manual-sync-step-2.sh`
      ```bash theme={null}
      #!/usr/bin/env bash
      set -euo pipefail

      # Load config first so SSH_PORT, REMOTE_HOST, CHAIN etc are set
      source .env

      : "${SSH_PORT:?SSH_PORT must be set}"
      : "${REMOTE_HOST:?REMOTE_HOST must be set}"
      : "${CHAIN:?CHAIN must be set}"

      # Copy current forkpoint
      rsync -av -e "ssh -p $SSH_PORT" \
        "monad@$REMOTE_HOST:/home/monad/monad-bft/config/forkpoint/forkpoint.rlp" \
        /home/monad/monad-bft/config/forkpoint/
      rsync -av -e "ssh -p $SSH_PORT" \
        "monad@$REMOTE_HOST:/home/monad/monad-bft/config/forkpoint/forkpoint.toml" \
        /home/monad/monad-bft/config/forkpoint/forkpoint.toml
      rsync -av -e "ssh -p $SSH_PORT" \
        "monad@$REMOTE_HOST:/home/monad/monad-bft/config/validators/validators.toml" \
        /home/monad/monad-bft/config/validators/validators.toml

      systemctl start monad-bft monad-execution monad-rpc
      ```
   2. Run the script
      ```bash theme={null}
      REMOTE_HOST=node1.<provider>.com SSH_PORT=22 CHAIN=monad_mainnet bash manual-sync-step-2.sh
      ```

## Check

To check that statesync has been avoided, send an `eth_getBlockByNumber` RPC request
for blocks finalized while the node was down.

```bash theme={null}
curl http://localhost:8080 \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["0xdedbeef", false],"id":1}'
```


# Hard Reset Instructions
Source: https://docs.monad.xyz/node-ops/node-recovery/hard-reset



Hard reset wipes the local state and downloads the most recent chain snapshot. After the snapshot
is applied, the node catches up using [statesync](/monad-arch/consensus/statesync) and
[blocksync](/monad-arch/consensus/blocksync).

Hard reset is the most powerful means of resetting a node. Steps are:

1. Download a recent snapshot of the network state.
2. Initialize the DB from the snapshot (this can take up to an hour on testnet and a few minutes on mainnet)
3. Catch up to the tip of the chain via statesync / blocksync (typically \< 5 minutes assuming
   snapshot is a few hours old)

<Warning title="Snapshot Restore">
  **Monad Foundation** and **Category Labs** are snapshot providers.
  If there is an issue, please refer to Discord validator channels for more snapshot providers.
</Warning>

## Prerequisite

* `aria2` must be installed on the node

## Instructions

1. SSH into the node as `root` user.

2. Stop the monad services and reset the workspace to delete all runtime data.
   ```bash theme={null}
   bash /opt/monad/scripts/reset-workspace.sh
   ```

3. Download and import TrieDB database snapshot.

   <Tabs>
     <Tab title="Mainnet">
       <Info>
         On mainnet, database snapshot restoration **takes from 1 to 5 minutes**.
         As the blockchain grows over time, snapshot restoration takes longer.
       </Info>

       Using Monad Foundation provider:

       ```bash theme={null}
       MF_BUCKET=https://bucket.monadinfra.com
       curl -sSL $MF_BUCKET/scripts/mainnet/restore-from-snapshot.sh | bash
       ```

       Using Category Labs provider:

       ```
       CL_BUCKET=https://pub-b0d0d7272c994851b4c8af22a766f571.r2.dev
       curl -sSL $CL_BUCKET/scripts/mainnet/restore_from_snapshot.sh | bash
       ```
     </Tab>

     <Tab title="Testnet">
       <Info>
         On testnet, database snapshot restoration **takes under 5 minutes**.
         As the blockchain grows over time, snapshot restoration takes longer.
       </Info>

       Using Monad Foundation provider:

       ```bash theme={null}
       MF_BUCKET=https://bucket.monadinfra.com
       curl -sSL $MF_BUCKET/scripts/testnet/restore-from-snapshot.sh | bash
       ```

       Using Category Labs provider:

       ```
       CL_BUCKET=https://pub-b0d0d7272c994851b4c8af22a766f571.r2.dev
       curl -sSL $CL_BUCKET/scripts/testnet/restore_from_snapshot.sh | bash
       ```
     </Tab>
   </Tabs>

4. Fetch latest `forkpoint.toml` and `validators.toml` runtime files.

   <Info title="Automatic Fetch">
     This step is optional if automatic remote config fetching is configured (v0.12.1+).
     Ensure `REMOTE_VALIDATORS_URL` and `REMOTE_FORKPOINT_URL` are defined in `/home/monad/.env` file.
     See [Full Node Installation](/node-ops/full-node-installation#remote-configuration-fetching-v0121) for configuration details.
     If not configured, you may run the below commands.
   </Info>

   <Tabs>
     <Tab title="Mainnet">
       ```bash theme={null}
       MF_BUCKET=https://bucket.monadinfra.com
       VALIDATORS_FILE=/home/monad/monad-bft/config/validators/validators.toml

       curl -sSL $MF_BUCKET/scripts/mainnet/download-forkpoint.sh | bash
       curl $MF_BUCKET/validators/mainnet/validators.toml -o $VALIDATORS_FILE
       chown monad:monad $VALIDATORS_FILE
       ```
     </Tab>

     <Tab title="Testnet">
       ```bash theme={null}
       MF_BUCKET=https://bucket.monadinfra.com
       VALIDATORS_FILE=/home/monad/monad-bft/config/validators/validators.toml

       curl -sSL $MF_BUCKET/scripts/testnet/download-forkpoint.sh | bash
       curl $MF_BUCKET/validators/testnet/validators.toml -o $VALIDATORS_FILE
       chown monad:monad $VALIDATORS_FILE
       ```
     </Tab>
   </Tabs>

5. Start all services
   ```bash theme={null}
   systemctl start monad-bft monad-execution monad-rpc
   ```


# Recovering a Node
Source: https://docs.monad.xyz/node-ops/node-recovery/index



When a node is stopped (e.g. due to an upgrade or network outage), it may miss some blocks
and fall out of sync with the network. The pages below describe a few options for recovering
and rejoining the tip of the chain.

Each option has tradeoffs:

* **[soft reset](/node-ops/node-recovery/soft-reset)** is fast but only works if the node tip is close to the network tip. It skips execution
  of the intervening blocks, so no artifacts (logs, receipts, traces) will be produced locally for
  those blocks
* **[hard reset](/node-ops/node-recovery/hard-reset)** is slow but works even if the node tip is far from the network tip. It skips everything
  before the snapshot, so no artifacts (logs, receipts, traces) will be produced locally for those
  blocks.
* **[full replay](/node-ops/node-recovery/full-replay)** is more expensive, but it ensures the local archive has no gaps that would have to
  be served by [S3](/node-ops/archive-data/data-waterfall). Full replay may be desirable
  for RPC providers.
* **[node migration](/node-ops/node-recovery/node-migration)** allows validators to achieve high availability by promoting a synced full node
  to validator status. This is useful for planned or unplanned maintenance with minimal downtime.

<CardGroup>
  <Card title="Soft Reset" href="/node-ops/node-recovery/soft-reset">
    Utilizes statesync to catch up to the tip of the chain, skipping
    execution of blocks in between.
  </Card>

  <Card title="Hard Reset" href="/node-ops/node-recovery/hard-reset">
    Restores state from a snapshot before resyncing.
  </Card>

  <Card title="Full Replay" href="/node-ops/node-recovery/full-replay">
    Fetches and replays all missing blocks serially so that all transactional
    artifacts are available.
  </Card>

  <Card title="Node Migration" href="/node-ops/node-recovery/node-migration">
    Promotes a synced full node to a validator by migrating configuration files
    and keys with minimal downtime.
  </Card>
</CardGroup>


# Node Migration (Promoting a Full Node to Validator)
Source: https://docs.monad.xyz/node-ops/node-recovery/node-migration



Backup Recommendation:
We highly recommend backing up all validator configuration files and keys. This ensures you can recover quickly in the event of a node crash or unexpected failure.

There are several ways to achieve high availability for your validator node. This document specifically provides instructions for running a full node and promoting it to a validator using the proper configuration files and keys.

In situations of planned or unplanned maintenance, validators can migrate their node keys with minimal downtime by running a full node. This node can be seamlessly converted into a validator, allowing for continuous participation in consensus.

At the moment downtime results in the loss of rewards for validators and their delegators. However there is **no slashing** live on the chain as of now.

Follow these steps to safely migrate your validator role, minimize downtime, and maintain network health.

## Prerequisites

1. Monad version >= `0.12.x`.
2. `id-secp` and `id-bls` keys of the validator.
3. `node.toml` configuration file of the validator.
4. `KEYSTORE_PASSWORD` value from the `.env` file.

## Instructions

1. Follow the [full node instructions](/node-ops/full-node-installation) to sync a full node to the tip of the network.

2. Backup existing configuration files on the full node from `/home/monad/monad-bft/config` and move them to `/opt/monad/backup`.
   * `/home/monad/monad-bft/config/node.toml`
   * `/home/monad/monad-bft/config/id-secp`
   * `/home/monad/monad-bft/config/id-bls`

3. Copy `id-secp`,`id-bls` and `node.toml` from the validator to the full node.

4. From the full node, run the `monad-sign-name-record` utility to generate a name-record signature for the new IP address.

```bash theme={null}
# Source the .env file to load the keystore password env variable
source /home/monad/.env
# Generate a name record and signature
monad-sign-name-record --address $(curl -s4 ifconfig.me):8000 \
--node-config /home/monad/monad-bft/config/node.toml \
--authenticated-udp-port 8001 \
--self-record-seq-num 1 \
--keystore-path /home/monad/monad-bft/config/id-secp \
--password "$KEYSTORE_PASSWORD"
```

**Example Output:**

```bash theme={null}
self_address = "<IP>:8000"
self_record_seq_num = 1  # Incremented by 1 from the previous value
self_name_record_sig = "<HEX SIG>"
```

1. From the full node, replace the `[peer_discovery]` block in `node.toml` with the output of the above command (3 lines).

<Info>
  * The `self_record_seq_num` is incremented each time the node undergoes a migration process.
  * This value is crucial as it is directly linked to the `self_name_record_sig`, ensuring
    consistency and integrity of the node's identity during transitions.
</Info>

1. If the original validator had (other) custom configuration related to dedicated full nodes, e.g. `[[fullnode_dedicated.identities]]`, those will need to be added to the full node's `node.toml`. To maintain connectivity with downstream nodes all downstream peers must update the name record for the validator in their `node.toml` configuration.

2. Ensure `enable_publisher = true`, `enable_client = true` and `expand_to_group = true`. In `expand_to_group = true` mode, full nodes support relies on secondary raptorcast peers specified in the full node's `node.toml`

3. Double-check and ensure if the **`beneficiary = `** values are copied from the validator's `node.toml` to full node's `node.toml`.

4. From the validator node, run `systemctl` commands to stop the services.

```bash theme={null}
systemctl stop monad-bft monad-rpc monad-execution
```

1. Verify the validator services are stopped.

```bash theme={null}
systemctl status monad-bft monad-rpc monad-execution
```

1. Stop the **full node** services and restart the services as a **validator**.

```bash theme={null}
systemctl stop monad-bft monad-rpc monad-execution
sleep 1
systemctl start monad-bft monad-rpc monad-execution
```

1. Verify the systemd services are running:

```bash theme={null}
systemctl status monad-bft monad-execution monad-rpc

# Check logs for each service
journalctl -fu monad-bft
journalctl -fu monad-execution
journalctl -fu monad-rpc
```

## Restoring the original validator

If you would like to restore the original validator (A) to its original role, you will need to perform one of two procedures:

1. Re-sync A - this will result in some downtime based on the time to statesync / blocksync
   1. Copy the `node.toml` from node B to node A
   2. From A, run `monad-sign-name-record` using node B's `node.toml` with incremented `self_record_seq_num`
   3. Update the corresponding two fields in `node.toml`
   4. From the temporary validator (B), stop the services.
   5. Soft or hard reset (A)
2. Run A as a full node, then perform steps above
   1. For A, generate [new keys](/node-ops/full-node-installation#Generate-Keystores)
   2. Sign a new name record (see instructions above) and [setup as a dedicated node](/node-ops/full-node-installation) to a validator, e.g. your temporary validator (B)
   3. Perform the steps above with roles reversed.

<Warning title="Node Name Management">
  Always ensure that each node maintains distinct `node_name` values in their respective `node.toml` files.

  * If node B was originally a full node with `node_name = "node_B"`, it should retain this name when returning to full node operation
  * Node B should only temporarily use node A's `node_name` during the migration procedure
  * After restoration, each node must return to its original `node_name` to avoid conflicts
</Warning>


# Soft Reset Instructions
Source: https://docs.monad.xyz/node-ops/node-recovery/soft-reset



A soft reset is typically required when node is (re-)joining the network and the node tip is close to the network tip. Soft reset utilizes [statesync](/monad-arch/consensus/statesync) to
determine the difference between the current state and the chain tip and to skip ahead.

<Note title="Automated Remote Configuration Fetching (v0.12.1+)">
  In v0.12.1+, the node will automatically attempt to fetch remote configuration files on startup if env variables are defined:

  * `forkpoint.toml`: Changes every round
  * `validators.toml`: Changes every epoch

  This simplifies node operations by automating configuration updates. The remote fetching includes threshold logic to determine when remote configs should be used.

  **Note**: For automatic remote config fetching (v0.12.1+), ensure `REMOTE_VALIDATORS_URL` and `REMOTE_FORKPOINT_URL` are defined in `/home/monad/.env` file. See [Full Node Installation](/node-ops/full-node-installation#remote-configuration-fetching-v0121) for configuration details.
</Note>

## Automated Soft Reset (v0.12.1+)

Starting with v0.12.1, soft resets are largely automated if the appropriate variables are defined in `.env`:

1. SSH into the node as `root` user
2. Restart monad-related services (`monad-bft` will auto-fetch configs on startup):
   ```bash theme={null}
   systemctl restart monad-bft monad-execution monad-rpc
   ```
3. Verify the systemd services are running:
   ```bash theme={null}
   systemctl list-units --type=service monad-bft.service monad-execution.service monad-rpc.service
   UNIT                    LOAD   ACTIVE SUB     DESCRIPTION
   monad-bft.service       loaded active running "Service file for Monad BFT"
   monad-execution.service loaded active running "Service file for Monad Execution"
   monad-rpc.service       loaded active running "Service file for Monad RPC"

   # Check logs for a specific process to verify config fetching
   journalctl -u monad-bft
   ```

## Manual Soft Reset

To disable the automated fetching, remove any existing definitions (and remove from `/home/monad/.env` if desired)

```bash theme={null}
unset REMOTE_VALIDATORS_URL
unset REMOTE_FORKPOINT_URL
```

1. SSH into the node as `root` user

2. Stop monad-related services
   ```bash theme={null}
   systemctl stop monad-bft monad-execution monad-rpc
   ```

3. Fetch new `forkpoint.toml` and `validators.toml`.

   <Tabs>
     <Tab title="Mainnet">
       ```bash theme={null}
       MF_BUCKET=https://bucket.monadinfra.com
       VALIDATORS_FILE=/home/monad/monad-bft/config/validators/validators.toml

       curl -sSL $MF_BUCKET/scripts/mainnet/download-forkpoint.sh | bash
       curl $MF_BUCKET/validators/mainnet/validators.toml -o $VALIDATORS_FILE
       chown monad:monad $VALIDATORS_FILE
       ```
     </Tab>

     <Tab title="Testnet">
       ```bash theme={null}
       MF_BUCKET=https://bucket.monadinfra.com
       VALIDATORS_FILE=/home/monad/monad-bft/config/validators/validators.toml

       curl -sSL $MF_BUCKET/scripts/testnet/download-forkpoint.sh | bash
       curl $MF_BUCKET/validators/testnet/validators.toml -o $VALIDATORS_FILE
       chown monad:monad $VALIDATORS_FILE
       ```
     </Tab>
   </Tabs>

   You may see the following log message:

   ```bash theme={null}
   failed to fetch remote configs, using local forkpoint and validators config
   ```

4. Start monad-related services
   ```bash theme={null}
   systemctl start monad-bft monad-execution monad-rpc
   ```

5. Verify the systemd services are running:
   ```bash theme={null}
   systemctl list-units --type=service monad-bft.service monad-execution.service monad-rpc.service
   UNIT                    LOAD   ACTIVE SUB     DESCRIPTION
   monad-bft.service       loaded active running "Service file for Monad BFT"
   monad-execution.service loaded active running "Service file for Monad Execution"
   monad-rpc.service       loaded active running "Service file for Monad RPC"

   # Check logs for a specific process, e.g. bft
   journalctl -u monad-bft
   ```

## Configuration Details

### Forkpoint Serialization

Starting with v0.12.1, forkpoints are serialized in both TOML and RLP formats:

* **RLP format**: Source of truth
* **TOML format**: Maintained for backward compatibility
* If TOML serialization fails, the node will no longer panic
* Nodes can start from either format for operational backwards compatibility


# Solonet
Source: https://docs.monad.xyz/node-ops/solonet

Run a complete Monad network locally in Docker for testing node operations and validator workflows.

[Solonet](https://github.com/monad-crypto/monad-solonet) lets you spin up a private Monad network on your laptop in seconds. It runs a self-contained chain in Docker — validator nodes, execution client, and RPC endpoint — booted from genesis with unlimited tokens. It uses the same binaries that run on testnet and mainnet, so node behavior closely matches production. Linux is supported natively, and macOS works through a small VM layer.

## When to use Solonet

Solonet gives node operators a fast feedback loop without depending on a public network:

* **Practice node operations**: rehearse upgrades, recoveries, and configuration changes against a disposable local chain.
* **Test validator workflows**: run `staking-cli` operations against your own validator without spending testnet MON or waiting for finality.
* **Develop tooling**: validate scripts, monitoring dashboards, or block-delivery integrations against a chain whose state you fully control.
* **Reproduce issues**: spin up a multi-validator topology to investigate consensus or block-sync edge cases.

For application development that only needs a fast EVM endpoint, `anvil --monad` starts faster and is usually sufficient. Reach for Solonet when you need full node behavior: consensus, staking, archive RPC, or production-like timing.

## Prerequisites

* Linux x86\_64 host, or macOS (Apple Silicon)
* 4+ CPU cores and 16 GB RAM
* Docker on Linux; Homebrew on macOS (used to install the Lima + Colima setup below)

## macOS setup (Apple Silicon)

Solonet's containers are x86\_64 Linux, so on Apple Silicon you need a small Linux VM to host Docker. [Lima](https://lima-vm.io/) and [Colima](https://github.com/abiosoft/colima) handle this:

```bash theme={null}
brew install lima colima lima-additional-guestagents
```

Start an x86\_64 Linux VM with enough resources:

```bash theme={null}
colima start \
  --arch x86_64 \
  --cpu-type max \
  --cpu 8 \
  --memory 16 \
  --disk 300 \
  --foreground
```

Verify Docker is wired to the VM (output should show `Architecture: x86_64`):

```bash theme={null}
docker info
```

The Docker CLI automatically points at the Colima VM, so every `docker compose` command below works identically on macOS and Linux.

To tear everything down later:

```bash theme={null}
colima delete --data
```

## Quick start

Clone the repository and bring up a single-validator network:

```bash theme={null}
git clone https://github.com/monad-crypto/monad-solonet
cd monad-solonet
docker compose up --build
```

Once the network is up:

* RPC: `http://localhost:8080`
* WebSocket: `ws://localhost:8081`
* CORS RPC: `http://localhost:8082/rpc/`
* Dashboard: `http://localhost:8082`

## Other network configurations

Multi-validator network:

```bash theme={null}
docker compose -f networks/multi-validators.yaml up --build
```

Full-components network (validators plus auxiliary services):

```bash theme={null}
docker compose -f networks/full-network.yaml up --build
```

## Included tooling

The Solonet containers come with the tools most commonly used for node operations:

* `forge` and `cast` ([Foundry](https://book.getfoundry.sh/))
* `staking-cli` for validator staking operations
* `monad-status` for inspecting node health

## Notes

* Solonet boots a fresh chain from genesis. State and validator sets are independent of testnet and mainnet, so it is suited for verifying your operational processes against a chain you control.
* Because the chain is local, finality is fast and gas is effectively free. Realistic latency or load tests still require a deployed network.

For installation details, environment variables, and configuration options, see the [Solonet README](https://github.com/monad-crypto/monad-solonet#readme).


# Authenticated UDP Migration
Source: https://docs.monad.xyz/node-ops/upgrade-instructions/auth-udp



<Warning>
  Please do not proceed until Monad Foundation provides notice.
</Warning>

## Overview

UDP Authentication provides secure, authenticated peer-to-peer communication for Monad nodes. This feature is currently **opt-in** and will become required in a future release.

**Benefits:**

* **Enhanced Security**: Cryptographically authenticated peer connections using your existing validator keys
* **DoS Protection**: Prevents resource exhaustion from spoofed packets
* **Traffic Prioritization**: Enables efficient QoS policies for transaction forwarding
* **Performance**: \~100x faster packet verification compared to per-packet ECDSA signatures

***

## Prerequisites

* **Monad Version**: `0.12.6` or later
* **Access**: Root/sudo privileges on your node
* **Keystore**: Existing `/home/monad/monad-bft/config/id-secp` file
* **Network**: Ability to open UDP port 8001 on your firewall

***

## Instructions for node operators

### 1. Verify the Monad version

Verify the installation:

```bash theme={null}
monad-node --version
# Expected output 0.12.6+
```

If not, please refer to the official documentation to upgrade to the latest recommended version: [https://docs.monad.xyz/node-ops/upgrade-instructions/](https://docs.monad.xyz/node-ops/upgrade-instructions/).

***

### 2. Configure Firewall

Open UDP port 8001 for authenticated traffic:

```bash theme={null}
sudo ufw allow 8001/udp comment 'monad authenticated udp'
```

Verify the rule was added:

```bash theme={null}
sudo ufw status | grep 8001
```

**Expected output:**

```
8001/udp                   ALLOW       Anywhere                   # monad authenticated udp
```

Note: if the node is behind a Network Firewall, make sure to also open the port 8001.

***

### 3. Generate Authentication Signature

Generate your node's authenticated name record signature:

```bash theme={null}
source /home/monad/.env
monad-sign-name-record \
  --address $(curl -4 -s ifconfig.me):8000 \
  --authenticated-udp-port 8001 \
  --self-record-seq-num 1 \
  --keystore-path /home/monad/monad-bft/config/id-secp \
  --password "$KEYSTORE_PASSWORD"
```

> **Important**: The `--self-record-seq-num` value must be **greater** than your current `self_record_seq_num` in `node.toml`.
>
> * If your config shows `self_record_seq_num = 0`, use `1`
> * If your config shows `self_record_seq_num = 1`, use `2`

**Example Output:**

```
self_address = "15.235.224.21:8000"
self_record_seq_num = 1
authenticated_udp_port = 8001
self_name_record_sig = "f754ed009f82a5c0e402b8f573a1b7e44e9f5fc957cf6360316b5a3baf617f0d1ffe23558845747dd21a51408ac2555a4f4bb70a0032cdf59921d5905663e41200"
```

Warning: do not copy the `authenticated_udp_port` parameter, as the parameter name in `node.toml` is `self_auth_port`.

**Save this output** - you'll need it in the next step.

***

### 4. Update Configuration

Edit your Monad configuration:

```bash theme={null}
sudo vim /home/monad/monad-bft/config/node.toml
```

#### 4.1 Update Peer Discovery Section

In the node configuration:

* replace the values in the `[peer_discovery]` section with your output from Step 3
* add the `self_auth_port` parameter

```toml theme={null}
[peer_discovery]
self_address = "YOUR_IP:8000"
self_auth_port = 8001
self_record_seq_num = 1
self_name_record_sig = "YOUR_GENERATED_SIGNATURE_FROM_STEP_3"
```

#### 4.2 Update Network Section

Add the `authenticated_bind_address_port` parameter to `[network]`:

```toml theme={null}
[network]
bind_address_host = "0.0.0.0"
bind_address_port = 8000
authenticated_bind_address_port = 8001  # Add this line
max_rtt_ms = 300
max_mbps = 1000
```

#### 4.3 Update Peer Records (Validators Only)

If you operate a **validator** with downstream full nodes, update peer configurations as they enable UDP authentication.

**For peers that have enabled UDP authentication**:

* update `record_seq_num` and `name_record_sig` using the new values of the downstream node
* set the `auth_port = 8001`

Note: Authenticated UDP activated nodes would appear in the `peers.toml` file with `auth_port = 8001`.

```toml theme={null}
[[bootstrap.peers]]
address = "188.214.131.5:8000"
record_seq_num = 1
secp256k1_pubkey = "0x0342f3e447bd6951b2cf7cd717958a84e58dbe8cfbe2780f0247c69591216d2d7c"
name_record_sig = "0x215e845dade986e48f6fcb1f065f3ff993ddf0d38b0ef41a05f6621d71bf4c6c2d25747629ac8a3d583418857bc0b4c75140202e14919faf643f431ade4b944d00"
auth_port = 8001  # Add this for upgraded peers
```

**For peers not yet enabled**, nothing needs to be updated, `auth_port` line should be omited:

```toml theme={null}
[[bootstrap.peers]]
address = "188.214.131.6:8000"
record_seq_num = 0
secp256k1_pubkey = "0x..."
name_record_sig = "0x..."
# No auth_port - this peer hasn't upgraded yet
```

Note: the downstream nodes peering configuration do not need to be updated.

Save and exit the file.

***

### 5. Restart and Verify

Restart the Monad service:

```bash theme={null}
sudo systemctl restart monad-bft
```

Monitor the logs for successful startup:

```bash theme={null}
journalctl -u monad-bft -f -n 50 --no-pager
```

***

## Verification

### Check Service Status

```bash theme={null}
systemctl status monad-bft --no-pager
```

Expected: `active (running)`

### Verify Port Binding

```bash theme={null}
sudo ss -ulpn | grep 8001
```

**Expected output:**

```
udp   UNCONN 0   0   0.0.0.0:8001   0.0.0.0:*   users:(("monad-node",pid=12345,fd=20))
```

## Troubleshooting

***

### Issue: "invalid name record signature in config file"

**Cause:** The signature in `node.toml` doesn't match the parameters.

**Solution:**

1. Verify you incremented `self_record_seq_num` correctly
2. Re-run `monad-sign-name-record` with the correct seq\_num
3. Copy the new signature to `node.toml`
4. Restart the service

***

### Issue: Port 8001 Not Listening

**Solution:**

```bash theme={null}
# Verify config
grep -A5 "\[network\]" /home/monad/monad-bft/config/node.toml | grep authenticated

# Check for startup errors
journalctl -u monad-bft -n 100 --no-pager | grep -i error

# Restart service
sudo systemctl restart monad-bft
```

***

### Issue: Firewall Blocking Connections

**Solution:**

```bash theme={null}
# Check current UFW rules
sudo ufw status numbered

# Add rule if missing
sudo ufw allow 8001/udp comment 'monad authenticated udp'

# Reload firewall
sudo ufw reload
```

***

## Rollback Instructions

To disable UDP authentication if needed:

### 1. Generate New Signature Without Auth Port

```bash theme={null}
source /home/monad/.env
monad-sign-name-record \
  --address $(curl -4 -s ifconfig.me):8000 \
  --self-record-seq-num 2 \
  --keystore-path /home/monad/monad-bft/config/id-secp \
  --password "$KEYSTORE_PASSWORD"
```

Note: Increment the seq\_num from your current value.

### 2. Update Configuration

Edit `/home/monad/monad-bft/config/node.toml`:

* Update `self_record_seq_num` and `self_name_record_sig` in `[peer_discovery]`
* Remove or comment out `authenticated_bind_address_port` in `[network]`
* Remove all `auth_port` entries from peer configurations

### 3. Restart Service

```bash theme={null}
sudo systemctl restart monad-bft
```

***

## Quick Health Check Script

Save this as `check_udp_auth.sh` for quick verification:

```bash theme={null}
#!/bin/bash
echo "=== Monad UDP Authentication Health Check ==="
echo ""
echo "Checking Monad version..."
monad-node --version 2>/dev/null || echo "monad-node not found"
echo ""
echo "Checking firewall rule..."
sudo ufw status | grep 8001 || echo "No UFW rule for 8001/udp"
echo ""
echo "Checking port binding..."
sudo ss -tulpn | grep 8001 || echo "Port 8001 not bound"
echo ""
echo "Checking service status..."
systemctl is-active monad-bft || echo "Service not active"
echo ""
echo "Checking configuration..."
grep -q "authenticated_bind_address_port = 8001" /home/monad/monad-bft/config/node.toml && \
  echo "authenticated_bind_address_port configured" || \
  echo "authenticated_bind_address_port not found"
echo ""
echo "Complete!"
```

Make it executable:

```bash theme={null}
chmod +x check_udp_auth.sh
./check_udp_auth.sh
```

**Expected output:**

```
=== Monad UDP Authentication Health Check ===

Checking Monad version...
monad-node {"commit":"e1e9489b8fc42c0a5af208bab20f6704f83c91c0","tag":"v0.12.7","branch":"","modified":true}

Checking firewall rule...
8001/udp                   ALLOW       Anywhere                   # authenticated udp port

Checking port binding...
udp   UNCONN 0      0             0.0.0.0:8001       0.0.0.0:*    users:(("monad-node",pid=3433495,fd=13))

Checking service status...
active

Checking configuration...
authenticated_bind_address_port configured

Complete!
```

***

## Additional Notes

* **Backward Compatibility**: Nodes can communicate with both authenticated and non-authenticated peers
* **Gradual Rollout**: You can enable authentication at your own pace during the opt-in period
* **Future Requirement**: UDP authentication will become mandatory in a future release (date TBD)
* **Sequence Numbers**: Always increment `self_record_seq_num` when regenerating signatures
* **Key Reuse**: Authentication uses your existing validator keys (secp256k1)

***

## Support

If you encounter issues not covered in this guide:

1. Check logs: `journalctl -u monad-bft -n 500 --no-pager`
2. Verify all configuration parameters match the examples
3. Ensure your firewall and network policies allow UDP/8001
4. Contact Monad support with your logs and configuration (sanitized of sensitive data)


# Authenticated UDP Checking
Source: https://docs.monad.xyz/node-ops/upgrade-instructions/authenticated-udp-checking



In preparation for the upcoming Clear UDP traffic decommission, this guide helps verify that a Monad node is properly configured for Authenticated UDP.
It checks that the node's configuration and peer settings fully support Auth UDP operation.

## Steps

### 1. Install yq (`tomlq` tool)

```bash theme={null}
sudo apt-get update && sudo apt-get install -y yq
```

### 2. Verify the configuration validation script

```bash theme={null}
MF_BUCKET=https://bucket.monadinfra.com
curl -fsSL $MF_BUCKET/scripts/validate-auth-udp-config.sh
```

### 3. Run the configuration validation script

```bash theme={null}
MF_BUCKET=https://bucket.monadinfra.com
curl -fsSL $MF_BUCKET/scripts/validate-auth-udp-config.sh | bash -s -
```

**Example output:**

```
======================================
Checking monad client configuration...

Node name        : my-node
Node config file : /home/monad/monad-bft/config/node.toml
Peers file       : /home/monad/monad-bft/config/peers.toml

peer_discovery.self_auth_port = 8001 ✔
bootstrap.peers[1] address=64.31.29.190:8000 auth_port=8001 ✔
bootstrap.peers[2] address=64.31.53.173:8000 auth_port=8001 ✔
bootstrap.peers[3] address=208.115.197.25:8000 auth_port=8001 ✔
bootstrap.peers[4] address=64.130.52.235:8000 auth_port=8001 ✔
bootstrap.peers[5] address=64.130.56.50:8000 auth_port=8001 ✔
bootstrap.peers[6] address=64.130.49.148:8000 auth_port=8001 ✔
bootstrap.peers[7] address=69.162.93.53:8000 auth_port=8001 ✔
bootstrap.peers[8] address=185.189.46.19:8001 auth_port=8001 ✔

Current peers (depends on the network):
Auth UDP          : 166
Clear UDP         : 25
Total             : 191

✔ Configuration is Auth UDP compliant, and ready for Clear UDP decommission.
```

## If the configuration is not Auth UDP compliant

Please consider the following steps:

1. Follow the Auth UDP guide: [Authenticated UDP Migration](./auth-udp)

2. Verify the **bootnode peers configuration** are updated, previous communication:

<Accordion title="Bootstrap Peers Update (11 Feb 2026)">
  With the recent activation Authenticated UDP traffic, the bootstrap peers needed to be updated on all nodes, in order to join the network.

  1. Get the new bootstrap peers signatures (all \[\[bootstrap.peers]] items):

  Mainnet:

  * Validators: [https://bucket.monadinfra.com/config/mainnet/latest/node.toml](https://bucket.monadinfra.com/config/mainnet/latest/node.toml)

  * Full node: [https://bucket.monadinfra.com/config/mainnet/latest/full-node-node.toml](https://bucket.monadinfra.com/config/mainnet/latest/full-node-node.toml)

  Testnet:

  * Validators: [https://bucket.monadinfra.com/config/testnet/latest/node.toml](https://bucket.monadinfra.com/config/testnet/latest/node.toml)

  * Full node: [https://bucket.monadinfra.com/config/testnet/latest/full-node-node.toml](https://bucket.monadinfra.com/config/testnet/latest/full-node-node.toml)

  2. Make sure to replace existing peering records with the new ones. The configuration should not have duplicated entries for a given secp256k1\_pubkey.

  3. Restart the node: systemctl restart monad-bft monad-execution monad-rpc. (No hard reset required)

  4. Verify the node can rejoin the network.

  Note: Be aware that a hard reset wipes the node's peering cache, since the reset-workspace.sh script deletes the peers.toml file. Any outdated peering setup may cause connection issues. After a hard reset, nodes must rebuild their peer list from scratch using the new bootstrap peering signatures.
</Accordion>

3. Ensure the **upstream/downstream connections** (validator \<> dedicated/prioritized full node) are using Auth UDP

* If the **remote peer already supports Auth UDP**, the script should locate the corresponding record in peers.toml and print the expected configuration.
* If the **remote peer is still using Clear UDP**, the script will not find a matching record.
  In this case, contact the remote peer operator to request Auth UDP activation and the new name record signature.


# Upgrade Instructions
Source: https://docs.monad.xyz/node-ops/upgrade-instructions/index



<Note>
  To stay updated on new releases:

  * join the [Monad Node Announcements](https://t.me/MonadNodeAnnouncements) telegram group, or
  * join the [Monad Developer Discord](https://discord.gg/monaddev) and follow the `#mainnet-fullnode-announcements` channel
</Note>

<CardGroup>
  <Card title="v0.14.3" href="/node-ops/upgrade-instructions/v0.14.3">
    Upgrade instructions for v0.14.3
  </Card>

  <Card title="v0.14.2" href="/node-ops/upgrade-instructions/v0.14.2">
    Upgrade instructions for v0.14.2
  </Card>

  <Card title="v0.14.1" href="/node-ops/upgrade-instructions/v0.14.1">
    Upgrade instructions for v0.14.1 - eth\_fillTransaction patch
  </Card>

  <Card title="v0.14.0" href="/node-ops/upgrade-instructions/v0.14.0">
    Upgrade instructions for v0.14.0
  </Card>

  <Card title="v0.13.1" href="/node-ops/upgrade-instructions/v0.13.1">
    Upgrade instructions for v0.13.1 - State Archive patch
  </Card>

  <Card title="v0.13.0 (MONAD_NINE)" href="/node-ops/upgrade-instructions/v0.13.0">
    Upgrade instructions for v0.13.0 - Hard Fork
  </Card>

  <Card title="v0.12.7" href="/node-ops/upgrade-instructions/v0.12.7">
    Upgrade instructions for v0.12.7
  </Card>

  <Card title="Authenticated UDP Migration" href="/node-ops/upgrade-instructions/auth-udp">
    Migration instructions for Authenticated UDP
  </Card>

  <Card title="Authenticated UDP Checking" href="/node-ops/upgrade-instructions/authenticated-udp-checking">
    Validate that your node is properly configured for Authenticated UDP
  </Card>

  <Card title="v0.12.6" href="/node-ops/upgrade-instructions/v0.12.6">
    Upgrade instructions for v0.12.6
  </Card>

  <Card title="v0.12.5 Testnet Re-genesis" href="/node-ops/upgrade-instructions/v0.12.5-testnet-regenesis">
    Re-genesis instructions for testnet v0.12.5
  </Card>

  <Card title="v0.12.3" href="/node-ops/upgrade-instructions/v0.12.3">
    Upgrade instructions for v0.12.3
  </Card>
</CardGroup>


# v0.12.3
Source: https://docs.monad.xyz/node-ops/upgrade-instructions/v0.12.3



<Warning>
  Please do not proceed until Monad Foundation provides notice.
</Warning>

## Instructions for node operators

### 1. SSH into the node as `monad` user

### 2. Upgrade monad package

<Tabs>
  <Tab title="Mainnet">
    ```bash theme={null}
    sudo apt update && sudo apt install --reinstall monad=0.12.3 -y --allow-downgrades --allow-change-held-packages
    ```
  </Tab>

  <Tab title="Testnet">
    ```bash theme={null}
    sudo apt update && sudo apt install --reinstall monad=0.12.3~rc.2 -y --allow-downgrades --allow-change-held-packages
    ```
  </Tab>
</Tabs>

### 3. Restart the services and verify

```bash theme={null}
sudo systemctl restart monad-bft monad-execution monad-rpc
sudo systemctl status monad-bft monad-execution monad-rpc --no-pager -l
```

Expected output: All services should show `Active: active (running)`

### 4. Verify the correct version is running

```bash theme={null}
monad-rpc --version
```

Expected output:

<Tabs>
  <Tab title="Mainnet">
    ```json theme={null}
    monad-rpc {"commit":"6323f3fcaf067c18884e3ffe72a22fb1a8d0216a","tag":"v0.12.3","branch":"","modified":true}
    ```
  </Tab>

  <Tab title="Testnet">
    ```json theme={null}
    monad-rpc {"commit":"6323f3fcaf067c18884e3ffe72a22fb1a8d0216a","tag":"","branch":"","modified":true}
    ```
  </Tab>
</Tabs>

## Patch notes

Please refer to the public changelog for [`v0.12.3`](/developer-essentials/changelog/releases#v0123).

### Important updates for node operators

* **\[Node ops]** Add `--root-offsets-chunk-count` flag to `monad-mpt` to configure the number of chunks allocated for root offsets
  * Each chunk holds approximately 16.5M blocks. Previously, all nodes were hardcoded to use 2 chunks (max TrieDB capacity of \~33M blocks)
  * New default: 16 **must be a power of 2**
  * Note that the default value of 16 translates to approximately 268M blocks \~ 1240 days. In most cases the limiting factor is disk capacity which will auto-compact when filled to 80%
  * Ref: [monad PR #1937](https://github.com/category-labs/monad/pull/1937)
* **\[RPC / Node ops]** Allow RPC to run without `monad-bft`
  * Enables standalone RPC operation for improved deployment flexibility
  * Ref: [monad-bft PR #2613](https://github.com/category-labs/monad-bft/pull/2613)
* **\[RPC]** [EIP-7966](https://eips.ethereum.org/EIPS/eip-7966) (`eth_sendRawTransactionSync`) support
  * Ref: [monad-bft PR #2542](https://github.com/category-labs/monad-bft/pull/2542)
* **\[Node ops / Archive]** Archive infrastructure improvements
  * Refactor `monad-block-writer` for improved reliability with `--max-blocks-per-iter` configuration
  * Async backfill with traces-only archive support
  * Add `require-traces` archiver flag and indexer fallback source
  * Support for historical execution event archiving with generic directory archiving
  * **Potentially breaking: Remove `--start-block` from `monad-archiver` systemd service; operators must use imperative CLI to set start block**
    * Example: `monad-archiver set-start-block --block 1000000 --archive-sink s3://bucket-name/path`
    * Use `--async-backfill` flag to set the async-backfill marker instead of primary marker
  * Ref: [monad-bft PR #2610](https://github.com/category-labs/monad-bft/pull/2610), [monad-bft PR #2606](https://github.com/category-labs/monad-bft/pull/2606), [monad-bft PR #2598](https://github.com/category-labs/monad-bft/pull/2598), [monad-bft PR #2514](https://github.com/category-labs/monad-bft/pull/2514), [monad-bft PR #2612](https://github.com/category-labs/monad-bft/pull/2612), [monad-bft PR #2569](https://github.com/category-labs/monad-bft/pull/2569), [monad-bft PR #2623](https://github.com/category-labs/monad-bft/pull/2623)
* **\[Node ops]** Networking configuration updates
  * Use default MTU 1500
  * Add HDR histogram for broadcast latency tracking in `monad-executor` and `monad-raptorcast`
  * Ref: [monad-bft PR #2576](https://github.com/category-labs/monad-bft/pull/2576), [monad-bft PR #2602](https://github.com/category-labs/monad-bft/pull/2602)
* **\[Consensus]** *Opt-in* Wire authentication protocol for UDP
  * Node operator instructions to be provided in the future
  * Includes replay window adjustments for improved reliability
  * Ref: [monad-bft PR #2417](https://github.com/category-labs/monad-bft/pull/2417), [monad-bft PR #2544](https://github.com/category-labs/monad-bft/pull/2544), [monad-bft PR #2626](https://github.com/category-labs/monad-bft/pull/2626), [monad-bft PR #2091](https://github.com/category-labs/monad-bft/pull/2091)


# v0.12.5 - `testnet` re-genesis
Source: https://docs.monad.xyz/node-ops/upgrade-instructions/v0.12.5-testnet-regenesis



<Warning>
  These instructions are only applicable to **`testnet`**. This can be ignored for `mainnet`.
</Warning>

## Part 1: To Halt

Node operators must stop all `monad` services before re-genesis.

### 1. SSH into the node as `root` user

### 2. Stop all monad services

```bash theme={null}
systemctl stop monad-bft monad-execution monad-rpc
```

### 3. Verify services are stopped

```bash theme={null}
systemctl status monad-bft monad-execution monad-rpc --no-pager -l
```

Expected output: All services should show `Active: inactive (dead)`

***

## Part 2: Re-genesis

<Warning>
  **Do not proceed until Monad Foundation provides notice that re-genesis is ready.**
</Warning>

### 1. Hard reset

Perform a hard reset to wipe local state and prepare for the new genesis.

```bash theme={null}
bash /opt/monad/scripts/reset-workspace.sh
```

### 2. Upgrade monad package

```bash theme={null}
sudo apt update && sudo apt install --reinstall monad=0.12.5 -y --allow-downgrades --allow-change-held-packages
```

### 3. Fetch configuration files

<Info title="Automated Remote Configuration Fetching">
  If you have automated remote config fetching configured (v0.12.1+), the new `forkpoint.toml` and `validators.toml` files will be automatically fetched on startup.

  Ensure `REMOTE_VALIDATORS_URL` and `REMOTE_FORKPOINT_URL` are defined in `/home/monad/.env`. See [Soft Reset Instructions](/node-ops/node-recovery/soft-reset) for more details on automated configuration fetching.

  If not using automated fetching, run the commands below.
</Info>

```bash theme={null}
MF_BUCKET=https://bucket.monadinfra.com
VALIDATORS_FILE=/home/monad/monad-bft/config/validators/validators.toml

curl -sSL $MF_BUCKET/scripts/testnet/download-forkpoint.sh | bash
curl $MF_BUCKET/validators/testnet/validators.toml -o $VALIDATORS_FILE
chown -R monad:monad /home/monad/monad-bft/config/
```

### 4. (Optional) Archivers: Reset archive sources

<Note title="For Archive Node Operators Only">
  If you are running an archive node, you must either:

  1. **Wipe your existing archiver sources** - Clear all existing archived data to start fresh with the new genesis, or
  2. **Point to a new bucket/source** - Configure your archiver to use a new destination for the re-genesis chain

  Failure to do so may result in conflicting data from the previous chain.
</Note>

### 5. Start services and verify

```bash theme={null}
systemctl start monad-bft monad-execution monad-rpc
systemctl status monad-bft monad-execution monad-rpc --no-pager -l
```

Expected output: All services should show `Active: active (running)`

### 6. Verify the correct version is running

```bash theme={null}
monad-rpc --version
```

Expected output:

```json theme={null}
monad-rpc {"commit":"a1fe1fbef7ff5d51e1eeb42809457cd68f7525dd","tag":"v0.12.5","branch":"","modified":true}
```

<Info title="Validator Registration">
  All nodes are expected to initially join the network as **public full nodes** before transitioning to validators. Monad Foundation will coordinate validator registration and delegation.
</Info>

## Patch notes

Please refer to the public changelog for [`v0.12.5`](/developer-essentials/changelog/releases#v0125).


# v0.12.6
Source: https://docs.monad.xyz/node-ops/upgrade-instructions/v0.12.6



<Warning>
  Please do not proceed until Monad Foundation provides notice.
</Warning>

## Instructions for node operators

### 1. SSH into the node as `root` user

### 2. Update configuration file

Add the `ping_rate_limit_per_second` parameter to the `[peer_discovery]` section in your configuration file:

```bash theme={null}
nano /home/monad/monad-bft/config/node.toml
```

Add the following line to the `[peer_discovery]` section:

```toml theme={null}
[peer_discovery]
self_address = "YOUR_IP:8000"
self_record_seq_num = 0 # This remains the same as your current self_record_seq_num
self_name_record_sig = "YOUR_SIGNATURE"
refresh_period = 20
request_timeout = 5
unresponsive_prune_threshold = 3
last_participation_prune_threshold = 1000
min_num_peers = 1
max_num_peers = 450
ping_rate_limit_per_second = 100  # This is new to 0.12.6
```

### 3. Check systemctl overrides (if applicable)

<Warning title="Important for operators with custom systemctl overrides">
  This release adds `--persisted-peers-path /home/monad/monad-bft/config/peers.toml` to the `monad-bft` service startup. If you have existing systemctl overrides for `monad-bft`, you must ensure this flag is included in your override configuration.
</Warning>

To check if you have overrides:

```bash theme={null}
systemctl cat monad-bft | grep -A 10 "override"
```

If you have an existing override, edit it to include the persisted peers path:

```bash theme={null}
sudo systemctl edit monad-bft
```

Ensure your override includes:

```
--persisted-peers-path /home/monad/monad-bft/config/peers.toml
```

### 4. Upgrade monad package

```bash theme={null}
sudo apt update && sudo apt install --reinstall monad=0.12.6 -y --allow-downgrades --allow-change-held-packages
```

### 5. Restart the services and verify

```bash theme={null}
sudo systemctl restart monad-bft monad-execution monad-rpc
sudo systemctl status monad-bft monad-execution monad-rpc --no-pager -l
```

Expected output: All services should show `Active: active (running)`

### 6. Verify the correct version is running

```bash theme={null}
monad-rpc --version
```

Expected output:

```json theme={null}
monad-rpc {"commit":"cced63c687c6ab67846c94bc9fd6d6ae60272cd4","tag":"v0.12.6","branch":"","modified":true}
```

<Info title="Sidecar CPU core configuration">
  Sidecars need their own CPU cores and **cannot share cores** with monad processes. Monad uses all 16 cores on a standard setup (cores 0-15), so running a sidecar on the same cores will cause performance issues.
</Info>

## Patch notes

Please refer to the public changelog for [`v0.12.6`](/developer-essentials/changelog/releases#v0126).

### Important updates for node operators

* **\[Node ops / Peer Discovery]** Add ping rate limiting configuration
  * New **required** parameter: `ping_rate_limit_per_second = 100` in `[peer_discovery]` section
  * Prevents excessive ping traffic and improves network stability


# v0.12.7
Source: https://docs.monad.xyz/node-ops/upgrade-instructions/v0.12.7



<Warning>
  Please do not proceed until Monad Foundation provides notice.
</Warning>

## Instructions for node operators

<Tip title="No configuration changes required">
  This release does not require any `node.toml` or systemctl override changes. It is a drop-in upgrade from v0.12.6.
</Tip>

### 1. SSH into the node as `root` user

### 2. Upgrade monad package

```bash theme={null}
sudo apt update && sudo apt install --reinstall monad=0.12.7 -y --allow-downgrades --allow-change-held-packages
```

### 3. Restart the services and verify

```bash theme={null}
sudo systemctl restart monad-bft monad-execution monad-rpc
sudo systemctl status monad-bft monad-execution monad-rpc --no-pager -l
```

Expected output: All services should show `Active: active (running)`

### 4. Verify the correct version is running

```bash theme={null}
monad-rpc --version
```

Expected output:

```json theme={null}
monad-rpc {"commit":"e1e9489b8fc42c0a5af208bab20f6704f83c91c0","tag":"v0.12.7","branch":"","modified":true}
```

## Patch notes

Please refer to the public changelog for [`v0.12.7`](/developer-essentials/changelog/releases#v0127).


# v0.13.0 (MONAD_NINE)
Source: https://docs.monad.xyz/node-ops/upgrade-instructions/v0.13.0



# v0.13.0 (MONAD\_NINE)

<Warning>
  Please do not proceed until Monad Foundation provides notice.
</Warning>

<Warning title="Hard Fork Release">
  This release activates **MONAD\_NINE** at timestamps (all nodes must upgrade before activation):

  * `1773153000` - `2026-03-10 14:30GMT` (testnet)
  * `1773930600` - `2026-03-19 14:30GMT` (mainnet)
</Warning>

## Instructions for node operators

<Tip title="No configuration changes required">
  This release does not require any `node.toml` or systemctl override changes. It is a drop-in upgrade from v0.12.7.
</Tip>

### 1. SSH into the node as `root` user

### 2. Upgrade monad package

```bash theme={null}
sudo apt update && sudo apt install --reinstall monad=0.13.0 -y --allow-downgrades --allow-change-held-packages
```

### 3. Restart the services and verify

```bash theme={null}
sudo systemctl restart monad-bft monad-execution monad-rpc
sudo systemctl status monad-bft monad-execution monad-rpc --no-pager -l
```

Expected output: All services should show `Active: active (running)`

### 4. Verify the correct version is running

```bash theme={null}
monad-rpc --version
```

Expected output:

```json theme={null}
monad-rpc {"commit":"0a9cbb8227207a7b33ddf5caf7bd796e855df99f","tag":"v0.13.0","branch":"","modified":true}
```

## Patch notes

Please refer to the public changelog for [`v0.13.0`](/developer-essentials/changelog/releases#v0130-monad_nine).

### Key changes in MONAD\_NINE

* **[MIP-3](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-3.md)**: Linear memory implementation
* **[MIP-4](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-4.md)**: Reserve balance precompile
* **[MIP-5](https://github.com/monad-crypto/MIPs/blob/main/MIPS/MIP-5.md)**: Osaka fork (CLZ opcode - EIP-7939)


# v0.13.1 Upgrade Instructions
Source: https://docs.monad.xyz/node-ops/upgrade-instructions/v0.13.1



<Warning>
  This is a **patch release** specifically for State Archive nodes experiencing RPC block query issues. Regular validator and full nodes on v0.13.0 are not affected and do not need to upgrade.
</Warning>

## 1. SSH into the node as `monad` user

## 2. Upgrade monad package

```bash theme={null}
sudo apt update && sudo apt install --reinstall monad=0.13.1 -y --allow-downgrades --allow-change-held-packages
```

## 3. Restart the services and verify

```bash theme={null}
sudo systemctl restart monad-rpc
sudo systemctl status monad-rpc --no-pager -l
```

Expected output: Service should show `Active: active (running)`

## 4. Verify the correct version is running

```bash theme={null}
monad-rpc --version
```

Expected output:

```json theme={null}
monad-rpc {"commit":"7db6cea2e51e57bc78a8cba0d389ebb8ae73298b","tag":"v0.13.1","branch":"","modified":false}
```


# v0.14.0 Upgrade Instructions
Source: https://docs.monad.xyz/node-ops/upgrade-instructions/v0.14.0



<Warning>
  This page contains upgrade instructions for **testnet** and **mainnet**. Always verify which network the instructions apply to.
</Warning>

## Upgrade notes

<Warning>
  **Authenticated UDP configuration is enforced**

  As of this release, Authenticated UDP is required. Ensure your configuration is compliant using the [Authenticated UDP Checker](./authenticated-udp-checking), and follow the documentation if needed.
</Warning>

<Warning>
  **Raptor redundancy factor limit lowered**

  The protocol-wide `MAX_REDUNDANCY` cap has been lowered from 7 to 3. If you have customized `raptor10_fullnode_redundancy_factor` in your `node.toml` to be higher than 3, you must lower it before upgrading or the node will fail to start with `BuildError::RedundancyTooHigh`.

  Most operators use the default value (2) and are unaffected.
</Warning>

<Warning>
  **`monad-ledger-tail` flags updated**

  The `--node-config-path` flag has been removed and `--peers-path` has been introduced.
  Suggested configuration is:

  ```diff theme={null}
  - --node-config-path=/home/monad/monad-bft/config/node.toml
  + --peers-path=/home/monad/monad-bft/config/peers.toml
  ```

  If you run `monad-ledger-tail` manually or in a custom systemd unit, update the configuration before upgrading.
</Warning>

## 1. SSH into the node as `monad` user

## 2. Upgrade monad package

```bash theme={null}
sudo apt update && sudo apt install --reinstall monad=0.14.0 -y --allow-downgrades --allow-change-held-packages
```

## 3. Restart the services and verify

```bash theme={null}
sudo systemctl restart monad-bft monad-execution monad-rpc
sudo systemctl status monad-bft monad-execution monad-rpc --no-pager -l
```

Expected output: All services should show `Active: active (running)`

## 4. Verify the correct version is running

```bash theme={null}
monad-rpc --version
```

Expected output:

```json theme={null}
monad-rpc {"commit":"2d487de007d7beb70c14cbbdf20ed5c63c36de28","tag":"v0.14.0","branch":"","modified":true}
```


# v0.14.1 Upgrade Instructions
Source: https://docs.monad.xyz/node-ops/upgrade-instructions/v0.14.1



<Warning>
  This page contains upgrade instructions for **testnet** and **mainnet**. Always verify which network the instructions apply to.
</Warning>

## Upgrade notes

<Warning>
  **Authenticated UDP configuration is enforced**

  As of this release, Authenticated UDP is required. Ensure your configuration is compliant using the [Authenticated UDP Checker](./authenticated-udp-checking), and follow the documentation if needed.
</Warning>

<Warning>
  **Raptor redundancy factor limit lowered**

  The protocol-wide `MAX_REDUNDANCY` cap has been lowered from 7 to 3. If you have customized `raptor10_fullnode_redundancy_factor` in your `node.toml` to be higher than 3, you must lower it before upgrading or the node will fail to start with `BuildError::RedundancyTooHigh`.

  Most operators use the default value (2) and are unaffected.
</Warning>

<Warning>
  **`monad-ledger-tail` flags updated**

  The `--node-config-path` flag has been removed and `--peers-path` has been introduced.
  Suggested configuration is:

  ```diff theme={null}
  - --node-config-path=/home/monad/monad-bft/config/node.toml
  + --peers-path=/home/monad/monad-bft/config/peers.toml
  ```

  If you run `monad-ledger-tail` manually or in a custom systemd unit, update the configuration before upgrading.
</Warning>

> Patch release on top of v0.14.0. No breaking changes to `node.toml`.
>
> **API behavior change:** `eth_fillTransaction` with insufficient balance now returns `reserve balance violation` instead of `insufficient balance`. Callers that match on the exact error string should update accordingly.

## 1. SSH into the node as `monad` user

## 2. Upgrade monad package

```bash theme={null}
sudo apt update && sudo apt install --reinstall monad=0.14.1 -y --allow-downgrades --allow-change-held-packages
```

## 3. Restart the services and verify

```bash theme={null}
sudo systemctl restart monad-bft monad-execution monad-rpc
sudo systemctl status monad-bft monad-execution monad-rpc --no-pager -l
```

Expected output: All services should show `Active: active (running)`

## 4. Verify the correct version is running

```bash theme={null}
monad-rpc --version
```

Expected output:

```json theme={null}
monad-rpc {"commit":"4ed79392...","tag":"v0.14.1","branch":"","modified":false}
```


# v0.14.2 Upgrade Instructions
Source: https://docs.monad.xyz/node-ops/upgrade-instructions/v0.14.2



<Warning>
  This page contains upgrade instructions for **testnet** and **mainnet**. Always verify which network the instructions apply to.
</Warning>

## 1. SSH into the node as `monad` user

## 2. Upgrade monad package

```bash theme={null}
sudo apt update && sudo apt install --reinstall monad=0.14.2 -y --allow-downgrades --allow-change-held-packages
```

## 3. Restart the services and verify

```bash theme={null}
sudo systemctl restart monad-bft monad-execution monad-rpc
sudo systemctl status monad-bft monad-execution monad-rpc --no-pager -l
```

Expected output: All services should show `Active: active (running)`

## 4. Verify the correct version is running

```bash theme={null}
monad-rpc --version
```

Expected output:

```json theme={null}
monad-rpc {"commit":"6307011c2acaf1349f2b6dbf488d2bb9e2844d2e","tag":"v0.14.2","branch":"","modified":true}
```


# v0.14.3 Upgrade Instructions
Source: https://docs.monad.xyz/node-ops/upgrade-instructions/v0.14.3



<Warning>
  This page contains upgrade instructions for **testnet** and **mainnet**. Always verify which network the instructions apply to.
</Warning>

## Upgrade notes

No breaking changes. Authenticated UDP is now enforced at the code level — nodes that were already running with it (required since v0.14.0) are unaffected.

## 1. SSH into the node as `root` user

## 2. Upgrade monad package

```bash theme={null}
sudo apt update && sudo apt install --reinstall monad=0.14.3 -y --allow-downgrades --allow-change-held-packages
sudo apt-mark hold monad
```

## 3. Restart the services and verify

```bash theme={null}
sudo systemctl restart monad-bft monad-execution monad-rpc
sudo systemctl status monad-bft monad-execution monad-rpc --no-pager -l
```

Expected output: All services should show `Active: active (running)`

## 4. Verify the correct version is running

```bash theme={null}
monad-rpc --version
```

Expected output:

```json theme={null}
monad-rpc {"commit":"f2a2092b9ba52c4e1fcd333b93fa382e52e44878","tag":"v0.14.3","branch":"","modified":true}
```


# Validator Delegation Program (VDP)
Source: https://docs.monad.xyz/node-ops/validator-delegation-program/index



*Last updated April 22, 2026*

The Monad Validator Delegation Program (VDP) is a framework for strengthening the validator set for the Monad network.

## Core Objectives

### Promote decentralization

* Promote decentralized block building/proposing
* Promote a wide distribution of stake
* Promote geographic diversity and infrastructure provider diversity
* Oppose forces that centralize authority over block building

### Promote network performance and resilience

* Encourage a validator set that is reliable, responsive and timely with respect to network operations
* Encourage a validator set that exhibits honest behavior relative to the protocol specification

### Promote a healthy, diverse validator community

* Support emerging node operators who demonstrate exceptional ability and contributions to the validator community

### Promote value capture to MON

* Oppose forces that would give systems governed by third parties or alternative tokens the power to control block production
* Oppose forces that would give systems governed by third parties or alternative tokens the power to direct order flow

### Promote overall ecosystem health

* Promote a validator set that prioritizes user welfare and longer-term ecosystem health over short-term value optimization
* Promote a validator set that does not engage in forms of toxic MEV such as frontrunning or sandwiching

## Evaluation and Intake

The Monad Foundation will evaluate the participation and uptime of every validator in the VDP on a six-month rolling basis. Validators who have performed well and who meet the general requirements of the program will be considered for further delegation over another six month period. Validators who have contributed significantly to the ecosystem in this period may receive additional delegation at the Foundation's discretion.

### Intake

The VDP is open to validators who join the network and wish to receive delegation support from the Foundation. Prospective validators are evaluated on:

* Testnet uptime (minimum of 4 weeks active operations for evaluation)
* Industry experience
* Monitoring / security processes
* Geographic decentralization
* Ecosystem contributions

A new application form is soon to be made available here.

### Eligibility Criteria

* Complete KYC/KYB successfully prior to receiving delegation
* Maintain uptime above 98%
  * The Monad Foundation reserves the right to remove delegation at any given time if performance does not meet desired standards - see below for demerit criteria/considerations
* Have track record of operating on Monad Testnet
* Set a commission fee of 10% or less ([temporarily raised to 15%](#temporary-commission-adjustment))
* Allow node metrics to be accessed by the Monad Foundation
* Comply with the [policy on MEV and centralization](/node-ops/validator-delegation-program/mev)
* Operate a validator on Testnet at all times while in the VDP
* Not use a validator node to service external RPCs (Axelar, Wormhole, etc.)
  * If validators wish to do this, they can spin up a separate Full Node

<Note>
  Teams building a MON LST/LRT or an MEV system are ineligible for the VDP.
</Note>

Eligibility is monitored on a continuous basis.

### \*Temporary Commission Adjustment

*Stage 1 - Update as of January 23, 2026*

In light of the early stage of the Monad ecosystem, the Foundation temporarily increased the maximum commission cap for validators participating in the VDP from 10% to 20% for an initial period of approximately six months.

This adjustment is intended to:

* Improve validator sustainability during the network’s early growth phase
* Support continued geographic and operator diversity
* Reduce reliance on Foundation-delegated stake over time

To ensure this change did not negatively impact non-Foundation delegating tokenholders, the Foundation proportionally reduced its own delegated stake in late January. As a result, delegating tokenholders should see no material change in net rewards, while validators benefit from improved economics.

*Stage 2 - Update as of April 24, 2026*

Following the temporary increase of the maximum validator commission cap from 10% to 20% in late January 2026, the cap has been adjusted to 15%.

The initial temporary increase was implemented to support validator sustainability during the early stages of the Monad ecosystem, encourage geographic and operator diversity, and reduce reliance on Foundation-delegated stake. As the network continues to mature and validator economics improve, this adjustment reflects a step toward a more steady-state commission structure.

This change coincides with the addition of a new wave of participants to the Validator Delegation Program (VDP), further expanding and diversifying the validator set.

All validators participating in the VDP are required to be in compliance with the updated 15% maximum commission cap by Friday, April 24, 2026 at 11:59 PM UTC.

In addition, the Foundation increased the delegated amount to Tier 4 VDP participants by 10,000,000 MON, for a total delegation of 25,000,000 MON.

### Criteria for Removal of Delegation

These criteria apply to nodes receiving delegation from the VDP:

* Failure to upgrade in a timely manner (within 48 hours of announcement unless otherwise specified)
* Unresponsiveness within 24 hours of outreach in the case of node performance
* Failure to adhere to 98% uptime minimum\*
* Running any alt binary in contravention of the [MEV policy](/node-ops/validator-delegation-program/mev)
* Peering with centralized flow routers in contravention of the [MEV policy](/node-ops/validator-delegation-program/mev)
* Failure to maintain regulatory compliance

<Warning>
  \*If a validator's weekly uptime is flagged as less than 98% three times within a 3 month period, this warrants removal from the VDP, barring extenuating circumstances. This will be evaluated at Monad Foundation discretion.

  For example, if a validator's total uptime in Week 1 is 97%, that constitutes 1 of 3 weeks allowed under the benchmark in a 3 month period. If that validator's uptime for Week 4 is 97%, that constitutes a second violation in the 3 month period. That validator now has to ensure its adherence is above 98% in all weeks remaining in that 3 month period to avoid being removed from the program.
</Warning>

### Maximum Stake within the VDP

If a validator reaches 1 billion MON of non-VDP delegation, the Monad Foundation will remove the VDP allocation delegation, as one of the goals of the VDP is to promote a distributed stake weight.

## VDP Delegations

* The Monad Foundation delegated 9.3B MON (\~9.3% of total supply) through the VDP in Wave 1
* The delegation was spread across 170 validators. The Monad Foundation provided the `MIN_AUTH_ADDRESS_STAKE` (100,000 MON) as a one-time grant to all successful applicants
* The VDP delegated at least `ACTIVE_VALIDATOR_STAKE` (10,000,000 MON), to all successful applicants

### Plans for Reduction of Foundation Stake Over Time

A purpose of the VDP is to support the initial security and functionality of the Monad network by facilitating early validator participation. Over time, as network participation evolves and third-party stake increases, the Foundation may determine that a reduced level of Foundation-delegated stake is appropriate. Any adjustment to the Foundation’s staking participation will be made at its discretion, based on its assessment of network conditions, and may occur at any time or not at all.

### Delegation Tiers

The VDP will **initially** be split into 4 tiers that correspond with performance and ecosystem contribution.

<div>
  <table>
    <thead>
      <tr>
        <td>**Tier**</td>
        <td>**Criteria**\*</td>
        <td>**Delegation**</td>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>1</td>
        <td>Highest performance across high throughput networks in the industry, and/or strong level of experience operating in high throughput networks. Potential to have high impact in offering ecosystem contributions.</td>
        <td>90,000,000 MON</td>
      </tr>

      <tr>
        <td>2</td>
        <td>Strong performance across high throughput networks in the industry, and/or solid level of experience operating in high throughput networks. Potential to have a strong level of impact in contribution to the ecosystem.</td>
        <td>75,000,000 MON</td>
      </tr>

      <tr>
        <td>3</td>
        <td>Good performance across high throughput networks in the industry. Potential to have a good level of impact in contribution to the ecosystem.</td>
        <td>52,500,000 MON</td>
      </tr>

      <tr>
        <td>4</td>
        <td>Entities that can attract significant stake without the assistance of the foundation, or fair performance across high throughput networks in the industry. No extra ecosystem contributions planned beyond node operations.</td>
        <td>25,000,000 MON</td>
      </tr>
    </tbody>
  </table>
</div>

\*These categories and levels are provided to outline the general framework, but are not definitive.

Validators can work toward increasing their allocation through ecosystem contributions. This will be evaluated based on the impact an validator's contributions have had on the ecosystem.

## Changelog

The VDP launched alongside Monad Public Mainnet on November 24, 2025. The initial cohort comprised validators who had proven themselves through Monad's pre-Mainnet networks (Testnet-1 and Testnet-2), and were selected and tiered based on:

* Performance in Monad's pre-Mainnet testnets
* Contribution to geographic decentralization
* Contribution to the Monad ecosystem, including tools, dashboards, snapshots, integrations, support for other validators, and community activation / support

| Date           | Change                                                                                                                                                                                                    |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nov 24, 2025   | VDP launched with Monad Public Mainnet; initial delegation spread across 170 validators:<br />Tier 1: 120,000,000 MON<br />Tier 2: 90,000,000 MON<br />Tier 3: 70,000,000 MON<br />Tier 4: 20,000,000 MON |
| Jan 23, 2026   | Raise max VDP commission from 10% to 20%                                                                                                                                                                  |
| Jan 23, 2026   | Reduce delegations:<br />Tier 1: 120,000,000 → 90,000,000 MON<br />Tier 2: 100,000,000 → 75,000,000 MON<br />Tier 3: 70,000,000 → 52,500,000 MON<br />Tier 4: 20,000,000 → 15,000,000 MON                 |
| April 24, 2026 | Lower max VDP commission from 20% to 15%                                                                                                                                                                  |
| April 24, 2026 | Tier 4 delegation increased from 15,000,000 MON to 25,000,000 MON                                                                                                                                         |

## FAQ

### Does a delegation guarantee active set inclusion in every epoch?

All participants will have been delegated sufficient stake to exceed the `ACTIVE_VALIDATOR_STAKE` requirement. There are [multiple requirements](/monad-arch/consensus/staking), namely the validator must also rank in the top `ACTIVE_VALSET_SIZE` (200) by stake weight as well. Thus, VDP delegation does not guarantee inclusion in every epoch.

Delegated entities are expected to attract their own stake, and not solely rely on the foundation stake.

### After receiving a delegation, can I stop my Testnet Validator?

No, to remain compliant with the VDP requirements, all mainnet validators must operate a testnet validator for the duration of their participation in the VDP.


# VDP Policy on MEV Systems
Source: https://docs.monad.xyz/node-ops/validator-delegation-program/mev



The Monad Foundation is aware that several ecosystem teams are building extra-protocol systems that enable participants to express transaction ordering preferences.

The Foundation recognizes that there may be some benefits to the presence of such systems, such as reducing spam and allowing participants to express ordering preferences that economically benefits stakers. At the same time, it is extremely early in the life of the public Monad network; none of these systems are battle-tested; and there is a wide variety of possible system designs with different implications on decentralization and risks to network robustness.

In light of the VDP’s [Objectives](/node-ops/validator-delegation-program#core-objectives), the Monad Foundation has adopted the following policy:

* Systems that centralize order flow, giving a third party power to route the order flow to the highest bidder, are counter to the objectives of the VDP. The VDP will not delegate to validators that peer with centralized order flow routers.
* Systems that give a third party authority over block building are counter to the objectives of the VDP. The VDP will not delegate to validators that give authority to a third-party block builder.
* Third parties might be tempted to build modified versions of the Category Labs client to facilitate integration with their systems. At this early stage in the network’s life, the VDP is not prepared to accept risks to network liveness or security that arise from validators running a modified version of the Category Labs client. Consequently, the VDP will not delegate to validators running a version of the client software modified by a third party.


# Validator Installation
Source: https://docs.monad.xyz/node-ops/validator-installation



Setting up a validator is very similar to setting up a full node with a few extra steps.

Start by configuring a node according to the full node installation
[instructions](/node-ops/full-node-installation).

When the full node is fully operational and synced to the network tip, you can register your node
as a prospective validator by calling
[`addValidator`](/reference/staking/api#addvalidator) on the staking
precompile. This function requires passing at least `MIN_VALIDATE_STAKE = 100_000 MON` (the
minimum self-stake).

After registering, your validator must also satisfy the following conditions, described in
greater depth in the staking [docs](/monad-arch/consensus/staking):

1. Must have a total stake of at least `ACTIVE_VALIDATOR_STAKE = 10_000_000 MON`
2. Must be in the top `ACTIVE_VALSET_SIZE = 200` validators by stake weight
3. Must continue to have a self-stake of `MIN_VALIDATE_STAKE = 100_000 MON`

When all three conditions are achieved, the validator will become active in the next epoch.

## Staking CLI

[`staking-sdk-cli`](https://github.com/monad-developers/staking-sdk-cli) is an open-source
staking CLI tool for interfacing with the staking precompile. Start with the
[onboarding workflow](https://github.com/monad-developers/staking-sdk-cli/blob/main/docs/validator-onboarding.md).

## Configure `node.toml`

When following the full node instructions, when you got to
[this section](/node-ops/full-node-installation#download-a-collection-of-chain-related-configuration-files-and-scripts)
you should have downloaded the Validator-themed `node.toml`.

From that template, the following should be configured:

1. (Important) Review the `beneficiary` address. This is the address that will receive block rewards.
   ```toml theme={null}
   beneficiary = "0x<INSERT_BENEFICIARY_ADDRESS>"
   ```

2. (Optional) - Double check `node_name` makes sense after transition from full node (for example,
   remove any `full_` prefix). Please choose a unique identifier to avoid confusion.

3. (Optional) - Configure [dedicated](/node-ops/full-node-block-delivery#dedicated-upstream) or [prioritized](/node-ops/full-node-block-delivery#prioritized-secondary-raptorcast-inclusion) connections:

   * **Dedicated full node**
     ```toml theme={null}
     # Use the following to broadcast blocks to downstream full nodes
     # [[bootstrap.peers]]
     # address = "<ip>:<port>"
     # record_seq_num = "<record_seq_num>"
     # name_record_sig = "<name_record_sig>"
     # secp256k1_pubkey = "<full node pubkey>"
     # [[fullnode_dedicated.identities]]
     # secp256k1_pubkey = "<full node pubkey>"
     ```

   * **Prioritized full node**
     ```toml theme={null}
     # Use the following to broadcast blocks to downstream full nodes
     # [[bootstrap.peers]]
     # address = "<ip>:<port>"
     # record_seq_num = "<record_seq_num>"
     # name_record_sig = "<name_record_sig>"
     # secp256k1_pubkey = "<full node pubkey>"
     # [[fullnode_raptorcast.full_nodes_prioritized.identities]]
     # secp256k1_pubkey = "<full node pubkey>"
     ```

   To apply these full node configuration changes without restarting `monad-bft`, run the following command:

   ```bash theme={null}
   monad-debug-node --control-panel-ipc-path /home/monad/monad-bft/controlpanel.sock reload-config
   ```


# Official Links
Source: https://docs.monad.xyz/official-links



### Mainnet Network

<div>
  <table>
    <thead>
      <tr>
        <th>What</th>
        <th>Where</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Block Explorer (MonadVision)</td>

        <td>
          <CopyToClipboard>[https://monadvision.com](https://monadvision.com)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Block Explorer (Monadscan)</td>

        <td>
          <CopyToClipboard>[https://monadscan.com](https://monadscan.com)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Block Explorer (SocialScan)</td>

        <td>
          <CopyToClipboard>[https://monad.socialscan.io](https://monad.socialscan.io)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Network Visualization</td>

        <td>
          <CopyToClipboard>[https://gmonads.com](https://gmonads.com)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>App Hub</td>

        <td>
          <CopyToClipboard>[https://app.monad.xyz](https://app.monad.xyz)</CopyToClipboard>
        </td>
      </tr>
    </tbody>
  </table>
</div>

### Announcements and Socials

<div>
  <table>
    <thead>
      <tr>
        <th>What</th>
        <th>Where</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Website</td>

        <td>
          <CopyToClipboard>[https://monad.xyz](https://monad.xyz)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Blog</td>

        <td>
          <CopyToClipboard>[https://blog.monad.xyz](https://blog.monad.xyz)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>X</td>

        <td>
          <CopyToClipboard>[https://x.com/monad](https://x.com/monad)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Monad Ecosytem on X</td>

        <td>
          <CopyToClipboard>[https://x.com/monad\_eco](https://x.com/monad_eco)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>The Pipeline on X</td>

        <td>
          <CopyToClipboard>[https://x.com/pipeline\_xyz](https://x.com/pipeline_xyz)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Announcement Telegram</td>

        <td>
          <CopyToClipboard>[https://t.me/monad\_xyz](https://t.me/monad_xyz)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Youtube</td>

        <td>
          <CopyToClipboard>[https://www.youtube.com/@MonadFoundation](https://www.youtube.com/@MonadFoundation)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Newsletter</td>

        <td>
          <CopyToClipboard>[https://news.monad.xyz](https://news.monad.xyz)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Community Discord</td>

        <td>
          <CopyToClipboard>[https://discord.gg/monad](https://discord.gg/monad)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>r/Monad Subreddit</td>

        <td>
          <CopyToClipboard>[https://reddit.com/r/Monad](https://reddit.com/r/Monad)</CopyToClipboard>
        </td>
      </tr>
    </tbody>
  </table>
</div>

### Developer Community

<div>
  <table>
    <thead>
      <tr>
        <th>What</th>
        <th>Where</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>`monad-developers` Github</td>

        <td>
          <CopyToClipboard>[https://github.com/monad-developers](https://github.com/monad-developers)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>DevNads on X</td>

        <td>
          <CopyToClipboard>[https://x.com/monad\_dev](https://x.com/monad_dev)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Developer Discord</td>

        <td>
          <CopyToClipboard>[https://discord.gg/monaddev](https://discord.gg/monaddev)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Research Forum</td>

        <td>
          <CopyToClipboard>[https://forum.monad.xyz](https://forum.monad.xyz)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Developer Portal</td>

        <td>
          <CopyToClipboard>[https://developers.monad.xyz/](https://developers.monad.xyz/)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Dev Announcements Telegram</td>

        <td>
          <CopyToClipboard>[https://t.me/monad\_devs](https://t.me/monad_devs)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>DeltaV Founder Community</td>

        <td>
          <CopyToClipboard>[https://deltav.monad.xyz/](https://deltav.monad.xyz/)</CopyToClipboard>
        </td>
      </tr>
    </tbody>
  </table>
</div>

### Validator Community

<div>
  <table>
    <thead>
      <tr>
        <th>What</th>
        <th>Where</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Monad Node Announcements</td>

        <td>
          <CopyToClipboard>[https://t.me/MonadNodeAnnouncements](https://t.me/MonadNodeAnnouncements)</CopyToClipboard>
        </td>
      </tr>
    </tbody>
  </table>
</div>

### Tech

<div>
  <table>
    <thead>
      <tr>
        <th>What</th>
        <th>Where</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Consensus Client Github</td>

        <td>
          <CopyToClipboard>[https://github.com/category-labs/monad-bft](https://github.com/category-labs/monad-bft)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Execution Client Github</td>

        <td>
          <CopyToClipboard>[https://github.com/category-labs/monad](https://github.com/category-labs/monad)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Monad Improvement Proposals (MIPs)</td>

        <td>
          <CopyToClipboard>[https://mips.monad.xyz](https://mips.monad.xyz)</CopyToClipboard>
        </td>
      </tr>
    </tbody>
  </table>
</div>

### Opportunities

<div>
  <table>
    <thead>
      <tr>
        <th>What</th>
        <th>Where</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Monad Foundation Jobs</td>

        <td>
          <CopyToClipboard>[https://jobs.ashbyhq.com/monad.foundation](https://jobs.ashbyhq.com/monad.foundation)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Monad Ecosystem Jobs</td>

        <td>
          <CopyToClipboard>[https://eco-jobs.monad.xyz/jobs](https://eco-jobs.monad.xyz/jobs)</CopyToClipboard>
        </td>
      </tr>
    </tbody>
  </table>
</div>

### Testnet

<div>
  <table>
    <thead>
      <tr>
        <th>What</th>
        <th>Where</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Block Explorer (MonadVision)</td>

        <td>
          <CopyToClipboard>[https://testnet.monadvision.com](https://testnet.monadvision.com)</CopyToClipboard>
        </td>
      </tr>

      <tr>
        <td>Testnet Faucet</td>

        <td>
          <CopyToClipboard>[https://faucet.monad.xyz](https://faucet.monad.xyz)</CopyToClipboard>
        </td>
      </tr>
    </tbody>
  </table>
</div>


# JSON-RPC API Reference
Source: https://docs.monad.xyz/reference/json-rpc/api

Reference for Monad's JSON-RPC interface

## eth\_blockNumber

Returns the number of most recent block.

<a href="/reference/json-rpc/playground?method=eth_blockNumber">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

This method takes no parameters.

**Returns**

<ResponseField name="result" type="string">
  The current block number, hex-encoded.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x4b7"
  }
  ```
</CodeGroup>

## eth\_call

Executes a new message call immediately without creating a transaction on the block chain.

<a href="/reference/json-rpc/playground?method=eth_call">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="object">
  Transaction call object.

  <Expandable title="properties">
    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />
  </Expandable>
</ParamField>

<ParamField type="string">
  Block tag (`latest`, `safe`, `finalized`, `pending`) or 32-byte block hash.
</ParamField>

**Returns**

<ResponseField name="result" type="string">
  The return data of the executed contract call, hex-encoded.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_call",
    "params": [
      {
        "to": "0x...",
        "data": "0x..."
      },
      "latest"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## eth\_chainId

Returns the chain ID of the current network.

<a href="/reference/json-rpc/playground?method=eth_chainId">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

This method takes no parameters.

**Returns**

<ResponseField name="result" type="string">
  The chain ID, hex-encoded.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_chainId",
    "params": [],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x4b7"
  }
  ```
</CodeGroup>

## eth\_createAccessList

Returns the derived access list and gas used for a simulated transaction.

Execution failures and reverts are reported in the result object's optional
`error` field so callers can still use the generated access list.

<a href="/reference/json-rpc/playground?method=eth_createAccessList">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="object">
  Transaction call object.

  <Expandable title="properties">
    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />
  </Expandable>
</ParamField>

<ParamField type="string">
  Block tag (`latest`, `safe`, `finalized`, `pending`) or 32-byte block hash.
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  The access list and estimated gas used.

  <Expandable title="properties">
    <ResponseField name="accessList" type="array" />

    <ResponseField name="gasUsed" type="string" />

    <ResponseField name="error" type="string" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_createAccessList",
    "params": [
      {
        "to": "0x...",
        "data": "0x..."
      },
      "latest"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## eth\_estimateGas

Generates and returns an estimate of how much gas is necessary to allow the transaction to complete.

<a href="/reference/json-rpc/playground?method=eth_estimateGas">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="object">
  Transaction call object.

  <Expandable title="properties">
    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />
  </Expandable>
</ParamField>

<ParamField type="string">
  Block tag (`latest`, `safe`, `finalized`, `pending`) or 32-byte block hash.
</ParamField>

**Returns**

<ResponseField name="result" type="string">
  The estimated gas needed, hex-encoded.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_estimateGas",
    "params": [
      {
        "to": "0x...",
        "data": "0x..."
      },
      "latest"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x4b7"
  }
  ```
</CodeGroup>

## eth\_feeHistory

Transaction fee history
Returns transaction base fee per gas and effective priority fee per gas for the requested/supported block range.

<a href="/reference/json-rpc/playground?method=eth_feeHistory">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  Number of blocks in the requested range (hex-encoded integer).
</ParamField>

<ParamField type="string">
  Highest block number (hex) or tag: `latest`, `safe`, `finalized`, `pending`.
</ParamField>

<ParamField type="array">
  Array of percentile values (floats between 0 and 100) to sample effective priority fees. Can be `null`.
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  Fee history for the requested block range.

  <Expandable title="properties">
    <ResponseField name="gasUsedRatio" type="array" />

    <ResponseField name="oldestBlock" type="string" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_feeHistory",
    "params": [
      "0x1",
      "latest",
      [
        25,
        75
      ]
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "gasUsedRatio": [],
      "oldestBlock": "0x0"
    }
  }
  ```
</CodeGroup>

## eth\_fillTransaction

<a href="/reference/json-rpc/playground?method=eth_fillTransaction">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="object">
  Transaction call object.

  <Expandable title="properties">
    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />
  </Expandable>
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  <Expandable title="properties">
    <ResponseField name="raw" type="string" />

    <ResponseField name="tx" type="object" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_fillTransaction",
    "params": [
      {
        "to": "0x...",
        "data": "0x..."
      }
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "raw": "0x",
      "tx": {
        "from": null,
        "to": null,
        "gas": null,
        "maxFeePerGas": null,
        "maxPriorityFeePerGas": null,
        "value": null,
        "input": null,
        "data": null,
        "nonce": null,
        "chainId": null,
        "accessList": null,
        "authorizationList": null
      }
    }
  }
  ```
</CodeGroup>

## eth\_gasPrice

Returns the current price per gas in wei.

<a href="/reference/json-rpc/playground?method=eth_gasPrice">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

This method takes no parameters.

**Returns**

<ResponseField name="result" type="string">
  The current gas price in wei, hex-encoded.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_gasPrice",
    "params": [],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x4b7"
  }
  ```
</CodeGroup>

## eth\_getBalance

Returns the balance of the account of given address.

<a href="/reference/json-rpc/playground?method=eth_getBalance">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  20-byte account address (hex-encoded).
</ParamField>

<ParamField type="string">
  Block tag (`latest`, `safe`, `finalized`, `pending`) or 32-byte block hash.
</ParamField>

**Returns**

<ResponseField name="result" type="string">
  The account balance in wei, hex-encoded.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": [
      "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
      "latest"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## eth\_getBlockByHash

Returns information about a block by hash.

<a href="/reference/json-rpc/playground?method=eth_getBlockByHash">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  32-byte block hash (hex-encoded).
</ParamField>

<ParamField type="boolean">
  If `true`, returns full transaction objects; if `false`, returns only transaction hashes.
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  The block object, or `null` if not found.

  <Expandable title="properties">
    <ResponseField name="hash" type="string" />

    <ResponseField name="parentHash" type="string" />

    <ResponseField name="sha3Uncles" type="string" />

    <ResponseField name="miner" type="string" />

    <ResponseField name="stateRoot" type="string" />

    <ResponseField name="transactionsRoot" type="string" />

    <ResponseField name="receiptsRoot" type="string" />

    <ResponseField name="logsBloom" type="string" />

    <ResponseField name="difficulty" type="string" />

    <ResponseField name="number" type="string" />

    <ResponseField name="gasLimit" type="string" />

    <ResponseField name="gasUsed" type="string" />

    <ResponseField name="timestamp" type="string" />

    <ResponseField name="extraData" type="string" />

    <ResponseField name="mixHash" type="string" />

    <ResponseField name="nonce" type="string" />

    <ResponseField name="uncles" type="array" />

    <ResponseField name="transactions" type="array" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_getBlockByHash",
    "params": [
      "0xdc0818cf78f21a8e70579cb46a43643f78291264dda342ae31049421c82d21ae",
      false
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "miner": "0x0000000000000000000000000000000000000000",
      "stateRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
      "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
      "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
      "logsBloom": "0x00000000...",
      "difficulty": "0x0",
      "number": "0x0",
      "gasLimit": "0x0",
      "gasUsed": "0x0",
      "timestamp": "0x0",
      "extraData": "0x",
      "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "nonce": "0x0000000000000000",
      "uncles": [],
      "transactions": []
    }
  }
  ```
</CodeGroup>

## eth\_getBlockByNumber

Returns information about a block by number.

<a href="/reference/json-rpc/playground?method=eth_getBlockByNumber">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  Block number (hex) or tag: `latest`, `safe`, `finalized`, `pending`.
</ParamField>

<ParamField type="boolean">
  If `true`, returns full transaction objects; if `false`, returns only transaction hashes.
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  The block object, or `null` if not found.

  <Expandable title="properties">
    <ResponseField name="hash" type="string" />

    <ResponseField name="parentHash" type="string" />

    <ResponseField name="sha3Uncles" type="string" />

    <ResponseField name="miner" type="string" />

    <ResponseField name="stateRoot" type="string" />

    <ResponseField name="transactionsRoot" type="string" />

    <ResponseField name="receiptsRoot" type="string" />

    <ResponseField name="logsBloom" type="string" />

    <ResponseField name="difficulty" type="string" />

    <ResponseField name="number" type="string" />

    <ResponseField name="gasLimit" type="string" />

    <ResponseField name="gasUsed" type="string" />

    <ResponseField name="timestamp" type="string" />

    <ResponseField name="extraData" type="string" />

    <ResponseField name="mixHash" type="string" />

    <ResponseField name="nonce" type="string" />

    <ResponseField name="uncles" type="array" />

    <ResponseField name="transactions" type="array" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_getBlockByNumber",
    "params": [
      "latest",
      false
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "miner": "0x0000000000000000000000000000000000000000",
      "stateRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
      "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
      "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
      "logsBloom": "0x00000000...",
      "difficulty": "0x0",
      "number": "0x0",
      "gasLimit": "0x0",
      "gasUsed": "0x0",
      "timestamp": "0x0",
      "extraData": "0x",
      "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "nonce": "0x0000000000000000",
      "uncles": [],
      "transactions": []
    }
  }
  ```
</CodeGroup>

## eth\_getBlockReceipts

Returns the receipts of a block by number or hash.

<a href="/reference/json-rpc/playground?method=eth_getBlockReceipts">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  Block tag (`latest`, `safe`, `finalized`, `pending`) or 32-byte block hash.
</ParamField>

**Returns**

<ResponseField name="result" type="array">
  Array of transaction receipt objects for the block.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_getBlockReceipts",
    "params": [
      "latest"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
      "0x..."
    ]
  }
  ```
</CodeGroup>

## eth\_getBlockTransactionCountByHash

Returns the number of transactions in a block from a block matching the given block hash.

<a href="/reference/json-rpc/playground?method=eth_getBlockTransactionCountByHash">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  32-byte block hash (hex-encoded).
</ParamField>

**Returns**

<ResponseField name="result" type="string">
  The number of transactions in the block, hex-encoded.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_getBlockTransactionCountByHash",
    "params": [
      "0xdc0818cf78f21a8e70579cb46a43643f78291264dda342ae31049421c82d21ae"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## eth\_getBlockTransactionCountByNumber

Returns the number of transactions in a block matching the given block number.

<a href="/reference/json-rpc/playground?method=eth_getBlockTransactionCountByNumber">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  Block number (hex) or tag: `latest`, `safe`, `finalized`, `pending`.
</ParamField>

**Returns**

<ResponseField name="result" type="string">
  The number of transactions in the block, hex-encoded.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_getBlockTransactionCountByNumber",
    "params": [
      "latest"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## eth\_getCode

Returns code at a given address.

<a href="/reference/json-rpc/playground?method=eth_getCode">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  20-byte account address (hex-encoded).
</ParamField>

<ParamField type="string">
  Block tag (`latest`, `safe`, `finalized`, `pending`) or 32-byte block hash.
</ParamField>

**Returns**

<ResponseField name="result" type="string">
  The bytecode at the given address.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_getCode",
    "params": [
      "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
      "latest"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## eth\_getLogs

Returns an array of all logs matching filter with given id.

<a href="/reference/json-rpc/playground?method=eth_getLogs">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="object">
  Log filter object.

  <Expandable title="properties">
    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="array" />
  </Expandable>
</ParamField>

**Returns**

<ResponseField name="result" type="array">
  Array of log objects matching the filter.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_getLogs",
    "params": [
      {
        "fromBlock": "0x0",
        "toBlock": "0x1",
        "address": "0xac4b3dacb91461209ae9d41ec517c2b9cb1b7daf",
        "topics": []
      }
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
      "0x..."
    ]
  }
  ```
</CodeGroup>

## eth\_getStorageAt

Returns the value from a storage position at a given address.

<a href="/reference/json-rpc/playground?method=eth_getStorageAt">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  20-byte account address (hex-encoded).
</ParamField>

<ParamField type="string">
  Storage position (hex-encoded 256-bit integer).
</ParamField>

<ParamField type="string">
  Block tag (`latest`, `safe`, `finalized`, `pending`) or 32-byte block hash.
</ParamField>

**Returns**

<ResponseField name="result" type="string">
  The value at the given storage position, hex-encoded.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_getStorageAt",
    "params": [
      "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
      "0x0",
      "latest"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## eth\_getTransactionByBlockHashAndIndex

Returns information about a transaction by block hash and transaction index position.

<a href="/reference/json-rpc/playground?method=eth_getTransactionByBlockHashAndIndex">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  32-byte block hash (hex-encoded).
</ParamField>

<ParamField type="string">
  Transaction index position (hex-encoded integer).
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  The transaction object, or `null` if not found.

  <Expandable title="properties">
    <ResponseField name="type" type="string" />

    <ResponseField name="chainId" type="string" />

    <ResponseField name="nonce" type="string" />

    <ResponseField name="gas" type="string" />

    <ResponseField name="maxFeePerGas" type="string" />

    <ResponseField name="maxPriorityFeePerGas" type="string" />

    <ResponseField name="to" type="string" />

    <ResponseField name="value" type="string" />

    <ResponseField name="accessList" type="array" />

    <ResponseField name="input" type="string" />

    <ResponseField name="r" type="string" />

    <ResponseField name="s" type="string" />

    <ResponseField name="yParity" type="string" />

    <ResponseField name="v" type="string" />

    <ResponseField name="hash" type="string" />

    <ResponseField name="blockHash" type="string" />

    <ResponseField name="blockNumber" type="string" />

    <ResponseField name="transactionIndex" type="string" />

    <ResponseField name="from" type="string" />

    <ResponseField name="gasPrice" type="string" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_getTransactionByBlockHashAndIndex",
    "params": [
      "0xdc0818cf78f21a8e70579cb46a43643f78291264dda342ae31049421c82d21ae",
      "0x1"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "type": "0x2",
      "chainId": "0x1",
      "nonce": "0x16d",
      "gas": "0x46a02",
      "maxFeePerGas": "0x7fc1a20a8",
      "maxPriorityFeePerGas": "0x59682f00",
      "to": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45",
      "value": "0x4a6ed55bbcc180",
      "accessList": [],
      "input": "0x5ae401dc...",
      "r": "0x7f2153019a74025d83a73effdd91503ceecefac7e35dd933adc1901c875539aa",
      "s": "0x334ab2f714796d13c825fddf12aad01438db3a8152b2fe3ef7827707c25ecab3",
      "yParity": "0x0",
      "v": "0x0",
      "hash": "0x0e07d8b53ed3d91314c80e53cf25bcde02084939395845cbb625b029d568135c",
      "blockHash": "0x883f974b17ca7b28cb970798d1c80f4d4bb427473dc6d39b2a7fe24edc02902d",
      "blockNumber": "0xe26e6d",
      "transactionIndex": "0xad",
      "from": "0x3cf412d970474804623bb4e3a42de13f9bca5436",
      "gasPrice": "0x50101df3a"
    }
  }
  ```
</CodeGroup>

## eth\_getTransactionByBlockNumberAndIndex

Returns information about a transaction by block number and transaction index position.

<a href="/reference/json-rpc/playground?method=eth_getTransactionByBlockNumberAndIndex">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  Block number (hex) or tag: `latest`, `safe`, `finalized`, `pending`.
</ParamField>

<ParamField type="string">
  Transaction index position (hex-encoded integer).
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  The transaction object, or `null` if not found.

  <Expandable title="properties">
    <ResponseField name="type" type="string" />

    <ResponseField name="chainId" type="string" />

    <ResponseField name="nonce" type="string" />

    <ResponseField name="gas" type="string" />

    <ResponseField name="maxFeePerGas" type="string" />

    <ResponseField name="maxPriorityFeePerGas" type="string" />

    <ResponseField name="to" type="string" />

    <ResponseField name="value" type="string" />

    <ResponseField name="accessList" type="array" />

    <ResponseField name="input" type="string" />

    <ResponseField name="r" type="string" />

    <ResponseField name="s" type="string" />

    <ResponseField name="yParity" type="string" />

    <ResponseField name="v" type="string" />

    <ResponseField name="hash" type="string" />

    <ResponseField name="blockHash" type="string" />

    <ResponseField name="blockNumber" type="string" />

    <ResponseField name="transactionIndex" type="string" />

    <ResponseField name="from" type="string" />

    <ResponseField name="gasPrice" type="string" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_getTransactionByBlockNumberAndIndex",
    "params": [
      "latest",
      "0x1"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "type": "0x2",
      "chainId": "0x1",
      "nonce": "0x16d",
      "gas": "0x46a02",
      "maxFeePerGas": "0x7fc1a20a8",
      "maxPriorityFeePerGas": "0x59682f00",
      "to": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45",
      "value": "0x4a6ed55bbcc180",
      "accessList": [],
      "input": "0x5ae401dc...",
      "r": "0x7f2153019a74025d83a73effdd91503ceecefac7e35dd933adc1901c875539aa",
      "s": "0x334ab2f714796d13c825fddf12aad01438db3a8152b2fe3ef7827707c25ecab3",
      "yParity": "0x0",
      "v": "0x0",
      "hash": "0x0e07d8b53ed3d91314c80e53cf25bcde02084939395845cbb625b029d568135c",
      "blockHash": "0x883f974b17ca7b28cb970798d1c80f4d4bb427473dc6d39b2a7fe24edc02902d",
      "blockNumber": "0xe26e6d",
      "transactionIndex": "0xad",
      "from": "0x3cf412d970474804623bb4e3a42de13f9bca5436",
      "gasPrice": "0x50101df3a"
    }
  }
  ```
</CodeGroup>

## eth\_getTransactionByHash

Returns the information about a transaction requested by transaction hash.

<a href="/reference/json-rpc/playground?method=eth_getTransactionByHash">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  32-byte transaction hash (hex-encoded).
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  The transaction object, or `null` if not found.

  <Expandable title="properties">
    <ResponseField name="type" type="string" />

    <ResponseField name="chainId" type="string" />

    <ResponseField name="nonce" type="string" />

    <ResponseField name="gas" type="string" />

    <ResponseField name="maxFeePerGas" type="string" />

    <ResponseField name="maxPriorityFeePerGas" type="string" />

    <ResponseField name="to" type="string" />

    <ResponseField name="value" type="string" />

    <ResponseField name="accessList" type="array" />

    <ResponseField name="input" type="string" />

    <ResponseField name="r" type="string" />

    <ResponseField name="s" type="string" />

    <ResponseField name="yParity" type="string" />

    <ResponseField name="v" type="string" />

    <ResponseField name="hash" type="string" />

    <ResponseField name="blockHash" type="string" />

    <ResponseField name="blockNumber" type="string" />

    <ResponseField name="transactionIndex" type="string" />

    <ResponseField name="from" type="string" />

    <ResponseField name="gasPrice" type="string" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_getTransactionByHash",
    "params": [
      "0xdc0818cf78f21a8e70579cb46a43643f78291264dda342ae31049421c82d21ae"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "type": "0x2",
      "chainId": "0x1",
      "nonce": "0x16d",
      "gas": "0x46a02",
      "maxFeePerGas": "0x7fc1a20a8",
      "maxPriorityFeePerGas": "0x59682f00",
      "to": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45",
      "value": "0x4a6ed55bbcc180",
      "accessList": [],
      "input": "0x5ae401dc...",
      "r": "0x7f2153019a74025d83a73effdd91503ceecefac7e35dd933adc1901c875539aa",
      "s": "0x334ab2f714796d13c825fddf12aad01438db3a8152b2fe3ef7827707c25ecab3",
      "yParity": "0x0",
      "v": "0x0",
      "hash": "0x0e07d8b53ed3d91314c80e53cf25bcde02084939395845cbb625b029d568135c",
      "blockHash": "0x883f974b17ca7b28cb970798d1c80f4d4bb427473dc6d39b2a7fe24edc02902d",
      "blockNumber": "0xe26e6d",
      "transactionIndex": "0xad",
      "from": "0x3cf412d970474804623bb4e3a42de13f9bca5436",
      "gasPrice": "0x50101df3a"
    }
  }
  ```
</CodeGroup>

## eth\_getTransactionCount

Returns the number of transactions sent from an address.

<a href="/reference/json-rpc/playground?method=eth_getTransactionCount">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  20-byte account address (hex-encoded).
</ParamField>

<ParamField type="string">
  Block tag (`latest`, `safe`, `finalized`, `pending`) or 32-byte block hash.
</ParamField>

**Returns**

<ResponseField name="result" type="string">
  The number of transactions sent from this address, hex-encoded.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_getTransactionCount",
    "params": [
      "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
      "latest"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## eth\_getTransactionReceipt

Returns the receipt of a transaction by transaction hash.

<a href="/reference/json-rpc/playground?method=eth_getTransactionReceipt">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  32-byte transaction hash (hex-encoded).
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  The transaction receipt object, or `null` if not found.

  <Expandable title="properties">
    <ResponseField name="type" type="string" />

    <ResponseField name="status" type="string" />

    <ResponseField name="cumulativeGasUsed" type="string" />

    <ResponseField name="logs" type="array" />

    <ResponseField name="logsBloom" type="string" />

    <ResponseField name="transactionHash" type="string" />

    <ResponseField name="transactionIndex" type="string" />

    <ResponseField name="blockHash" type="string" />

    <ResponseField name="blockNumber" type="string" />

    <ResponseField name="gasUsed" type="string" />

    <ResponseField name="effectiveGasPrice" type="string" />

    <ResponseField name="from" type="string" />

    <ResponseField name="to" type="string" />

    <ResponseField name="contractAddress" type="string" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_getTransactionReceipt",
    "params": [
      "0xdc0818cf78f21a8e70579cb46a43643f78291264dda342ae31049421c82d21ae"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "type": "0x2",
      "status": "0x1",
      "cumulativeGasUsed": "0xa42aec",
      "logs": [
        {
          "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
          "topics": [
            "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925"
          ],
          "data": "0x00000000000000000000000000000000000000000052b7d2dcc80cd2e4000000",
          "blockHash": "0x4acbdefb861ef4adedb135ca52865f6743451bfbfa35db78076f881a40401a5e",
          "blockNumber": "0x129f4b9",
          "transactionHash": "0x21f6554c28453a01e7276c1db2fc1695bb512b170818bfa98fa8136433100616",
          "transactionIndex": "0x7f",
          "logIndex": "0x118",
          "removed": false
        }
      ],
      "logsBloom": "0x00000000...",
      "transactionHash": "0x21f6554c28453a01e7276c1db2fc1695bb512b170818bfa98fa8136433100616",
      "transactionIndex": "0x7f",
      "blockHash": "0x4acbdefb861ef4adedb135ca52865f6743451bfbfa35db78076f881a40401a5e",
      "blockNumber": "0x129f4b9",
      "gasUsed": "0xbde1",
      "effectiveGasPrice": "0xfb0f6e8c9",
      "from": "0x9a53bfba35269414f3b2d20b52ca01b15932c7b2",
      "to": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "contractAddress": null
    }
  }
  ```
</CodeGroup>

## eth\_maxPriorityFeePerGas

Returns the current maxPriorityFeePerGas per gas in wei.

<a href="/reference/json-rpc/playground?method=eth_maxPriorityFeePerGas">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

This method takes no parameters.

**Returns**

<ResponseField name="result" type="string">
  The current max priority fee per gas in wei, hex-encoded.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_maxPriorityFeePerGas",
    "params": [],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x4b7"
  }
  ```
</CodeGroup>

## eth\_sendRawTransaction

Submits a raw transaction. For EIP-4844 transactions, the raw form must be the network form.
This means it includes the blobs, KZG commitments, and KZG proofs.

<a href="/reference/json-rpc/playground?method=eth_sendRawTransaction">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  Signed transaction data (hex-encoded).
</ParamField>

**Returns**

<ResponseField name="result" type="string">
  The 32-byte transaction hash.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_sendRawTransaction",
    "params": [
      "0x..."
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## eth\_sendRawTransactionSync

<a href="/reference/json-rpc/playground?method=eth_sendRawTransactionSync">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  Signed transaction data (hex-encoded).
</ParamField>

<ParamField type="integer" />

**Returns**

<ResponseField name="result" type="object">
  <Expandable title="properties">
    <ResponseField name="type" type="string" />

    <ResponseField name="status" type="string" />

    <ResponseField name="cumulativeGasUsed" type="string" />

    <ResponseField name="logs" type="array" />

    <ResponseField name="logsBloom" type="string" />

    <ResponseField name="transactionHash" type="string" />

    <ResponseField name="transactionIndex" type="string" />

    <ResponseField name="blockHash" type="string" />

    <ResponseField name="blockNumber" type="string" />

    <ResponseField name="gasUsed" type="string" />

    <ResponseField name="effectiveGasPrice" type="string" />

    <ResponseField name="from" type="string" />

    <ResponseField name="to" type="string" />

    <ResponseField name="contractAddress" type="string" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_sendRawTransactionSync",
    "params": [
      "0x...",
      "0x..."
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "type": "0x2",
      "status": "0x1",
      "cumulativeGasUsed": "0xa42aec",
      "logs": [
        {
          "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
          "topics": [
            "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925"
          ],
          "data": "0x00000000000000000000000000000000000000000052b7d2dcc80cd2e4000000",
          "blockHash": "0x4acbdefb861ef4adedb135ca52865f6743451bfbfa35db78076f881a40401a5e",
          "blockNumber": "0x129f4b9",
          "transactionHash": "0x21f6554c28453a01e7276c1db2fc1695bb512b170818bfa98fa8136433100616",
          "transactionIndex": "0x7f",
          "logIndex": "0x118",
          "removed": false
        }
      ],
      "logsBloom": "0x00000000...",
      "transactionHash": "0x21f6554c28453a01e7276c1db2fc1695bb512b170818bfa98fa8136433100616",
      "transactionIndex": "0x7f",
      "blockHash": "0x4acbdefb861ef4adedb135ca52865f6743451bfbfa35db78076f881a40401a5e",
      "blockNumber": "0x129f4b9",
      "gasUsed": "0xbde1",
      "effectiveGasPrice": "0xfb0f6e8c9",
      "from": "0x9a53bfba35269414f3b2d20b52ca01b15932c7b2",
      "to": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "contractAddress": null
    }
  }
  ```
</CodeGroup>

## eth\_syncing

Returns an object with data about the sync status or false.

<a href="/reference/json-rpc/playground?method=eth_syncing">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

This method takes no parameters.

**Returns**

<ResponseField name="result" type="boolean">
  `false` if not syncing, or an object with sync status data.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "eth_syncing",
    "params": [],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": false
  }
  ```
</CodeGroup>

## debug\_getRawBlock

Returns an RLP-encoded block.

<a href="/reference/json-rpc/playground?method=debug_getRawBlock">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  Block number (hex) or tag: `latest`, `safe`, `finalized`, `pending`.
</ParamField>

**Returns**

<ResponseField name="result" type="string">
  The RLP-encoded block data.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "debug_getRawBlock",
    "params": [
      "latest"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## debug\_getRawHeader

Returns an RLP-encoded header.

<a href="/reference/json-rpc/playground?method=debug_getRawHeader">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  Block number (hex) or tag: `latest`, `safe`, `finalized`, `pending`.
</ParamField>

**Returns**

<ResponseField name="result" type="string">
  The RLP-encoded header data.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "debug_getRawHeader",
    "params": [
      "latest"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## debug\_getRawReceipts

Returns an array of EIP-2718 binary-encoded receipts.

<a href="/reference/json-rpc/playground?method=debug_getRawReceipts">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  Block number (hex) or tag: `latest`, `safe`, `finalized`, `pending`.
</ParamField>

**Returns**

<ResponseField name="result" type="array">
  Array of EIP-2718 binary-encoded receipts.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "debug_getRawReceipts",
    "params": [
      "latest"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
      "0x..."
    ]
  }
  ```
</CodeGroup>

## debug\_getRawTransaction

Returns an array of EIP-2718 binary-encoded transactions.

<a href="/reference/json-rpc/playground?method=debug_getRawTransaction">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  32-byte transaction hash (hex-encoded).
</ParamField>

**Returns**

<ResponseField name="result" type="string">
  The EIP-2718 binary-encoded transaction.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "debug_getRawTransaction",
    "params": [
      "0xdc0818cf78f21a8e70579cb46a43643f78291264dda342ae31049421c82d21ae"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## debug\_traceBlockByHash

Returns the tracing result by executing all transactions in the block specified by the block hash with a tracer.

<a href="/reference/json-rpc/playground?method=debug_traceBlockByHash">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  32-byte block hash (hex-encoded).
</ParamField>

<ParamField type="object">
  Tracer configuration object.

  <Expandable title="properties">
    <ParamField type="string">
      Tracer type: `callTracer` or `prestateTracer`.
    </ParamField>

    <ParamField type="object">
      <Expandable title="properties">
        <ParamField type="boolean">
          onlyTopCall for callTracer, ignored for prestateTracer
        </ParamField>

        <ParamField type="boolean">
          diff mode for prestateTracer, ignored for callTracer
        </ParamField>

        <ParamField type="boolean">
          log for callTracer, ignored for prestateTracer
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  Array of trace result objects, one per transaction.

  <Expandable title="properties">
    <ResponseField name="txHash" type="string" />

    <ResponseField name="result" type="object" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "debug_traceBlockByHash",
    "params": [
      "0xdc0818cf78f21a8e70579cb46a43643f78291264dda342ae31049421c82d21ae",
      {
        "tracer": "callTracer"
      }
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## debug\_traceBlockByNumber

Returns the tracing result by executing all transactions in the block specified by the block number with a tracer.

<a href="/reference/json-rpc/playground?method=debug_traceBlockByNumber">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  Block number (hex) or tag: `latest`, `safe`, `finalized`, `pending`.
</ParamField>

<ParamField type="object">
  Tracer configuration object.

  <Expandable title="properties">
    <ParamField type="string">
      Tracer type: `callTracer` or `prestateTracer`.
    </ParamField>

    <ParamField type="object">
      <Expandable title="properties">
        <ParamField type="boolean">
          onlyTopCall for callTracer, ignored for prestateTracer
        </ParamField>

        <ParamField type="boolean">
          diff mode for prestateTracer, ignored for callTracer
        </ParamField>

        <ParamField type="boolean">
          log for callTracer, ignored for prestateTracer
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  Array of trace result objects, one per transaction.

  <Expandable title="properties">
    <ResponseField name="txHash" type="string" />

    <ResponseField name="result" type="object" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "debug_traceBlockByNumber",
    "params": [
      "latest",
      {
        "tracer": "callTracer"
      }
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## debug\_traceCall

Returns the tracing result by executing an eth call.

<a href="/reference/json-rpc/playground?method=debug_traceCall">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="object">
  Transaction call object.

  <Expandable title="properties">
    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />
  </Expandable>
</ParamField>

<ParamField type="string">
  Block tag (`latest`, `safe`, `finalized`, `pending`) or 32-byte block hash.
</ParamField>

<ParamField type="object">
  Tracer configuration object.

  <Expandable title="properties">
    <ParamField type="string">
      Tracer type: `callTracer` or `prestateTracer`.
    </ParamField>

    <ParamField type="object">
      <Expandable title="properties">
        <ParamField type="boolean">
          onlyTopCall for callTracer, ignored for prestateTracer
        </ParamField>

        <ParamField type="boolean">
          diff mode for prestateTracer, ignored for callTracer
        </ParamField>

        <ParamField type="boolean">
          log for callTracer, ignored for prestateTracer
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  The trace result. Structure depends on the tracer used.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "debug_traceCall",
    "params": [
      {
        "to": "0x...",
        "data": "0x..."
      },
      "latest",
      {
        "tracer": "callTracer",
        "tracerConfig": {
          "onlyTopCall": false
        }
      }
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## debug\_traceTransaction

Returns all traces of a given transaction.

<a href="/reference/json-rpc/playground?method=debug_traceTransaction">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  32-byte transaction hash (hex-encoded).
</ParamField>

<ParamField type="object">
  Tracer configuration object.

  <Expandable title="properties">
    <ParamField type="string">
      Tracer type: `callTracer` or `prestateTracer`.
    </ParamField>

    <ParamField type="object">
      <Expandable title="properties">
        <ParamField type="boolean">
          onlyTopCall for callTracer, ignored for prestateTracer
        </ParamField>

        <ParamField type="boolean">
          diff mode for prestateTracer, ignored for callTracer
        </ParamField>

        <ParamField type="boolean">
          log for callTracer, ignored for prestateTracer
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  The trace result object.

  <Expandable title="properties">
    <ResponseField name="type" type="string" />

    <ResponseField name="from" type="string" />

    <ResponseField name="to" type="string" />

    <ResponseField name="value" type="string" />

    <ResponseField name="gas" type="string" />

    <ResponseField name="gasUsed" type="string" />

    <ResponseField name="input" type="string" />

    <ResponseField name="output" type="string" />

    <ResponseField name="error" type="string" />

    <ResponseField name="revertReason" type="string" />

    <ResponseField name="logs" type="array" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "debug_traceTransaction",
    "params": [
      "0xdc0818cf78f21a8e70579cb46a43643f78291264dda342ae31049421c82d21ae",
      {
        "tracer": "callTracer"
      }
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## admin\_ethCallStatistics

Returns statistics about eth\_call capacity including inactive executors and queued requests

<a href="/reference/json-rpc/playground?method=admin_ethCallStatistics">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

This method takes no parameters.

**Returns**

<ResponseField name="result" type="object">
  Object with eth\_call capacity statistics.

  <Expandable title="properties">
    <ResponseField name="inactiveExecutors" type="string" />

    <ResponseField name="queuedRequests" type="string" />

    <ResponseField name="oldestRequestAgeMs" type="string" />

    <ResponseField name="averageRequestAgeMs" type="string" />

    <ResponseField name="totalRequests" type="string" />

    <ResponseField name="totalErrors" type="string" />

    <ResponseField name="queueRejections" type="string" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "admin_ethCallStatistics",
    "params": [],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## net\_version

Returns the current network ID.

<a href="/reference/json-rpc/playground?method=net_version">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

This method takes no parameters.

**Returns**

<ResponseField name="result" type="string">
  The current network/chain ID as a string.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "net_version",
    "params": [],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## txpool\_statusByAddress

Returns the status of pending transactions from the given address.

<a href="/reference/json-rpc/playground?method=txpool_statusByAddress">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  20-byte account address (hex-encoded).
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  Map of nonce to transaction status.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "txpool_statusByAddress",
    "params": [
      "0x407d73d8a49eeb85d32cf465507dd71d507100c1"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## txpool\_statusByHash

Returns the status of a pending transaction by hash.

<a href="/reference/json-rpc/playground?method=txpool_statusByHash">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

<ParamField type="string">
  32-byte transaction hash (hex-encoded).
</ParamField>

**Returns**

<ResponseField name="result" type="object">
  Transaction status object.

  <Expandable title="properties">
    <ResponseField name="status" type="string" />

    <ResponseField name="reason" type="string" />
  </Expandable>
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "txpool_statusByHash",
    "params": [
      "0xdc0818cf78f21a8e70579cb46a43643f78291264dda342ae31049421c82d21ae"
    ],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>

## web3\_clientVersion

Returns the Monad client version.

<a href="/reference/json-rpc/playground?method=web3_clientVersion">
  <span />

  <span>Open in RPC Playground</span>

  <svg>
    <path />
  </svg>
</a>

**Parameters**

This method takes no parameters.

**Returns**

<ResponseField name="result" type="string">
  The Monad client version string.
</ResponseField>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "web3_clientVersion",
    "params": [],
    "id": 1
  }
  ```

  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x..."
  }
  ```
</CodeGroup>


# JSON-RPC Overview
Source: https://docs.monad.xyz/reference/json-rpc/overview

JSON-RPC methods, differences from Ethereum, rate limits, and error codes

Monad supports a [JSON-RPC](https://www.jsonrpc.org/specification) interface for interacting with the blockchain. Monad aims to match the RPC behavior of [Geth](https://geth.ethereum.org/docs/interacting-with-geth/rpc) as closely as possible, but due to fundamental architectural differences, some behaviors deviate from Ethereum.

## Supported methods

| Method                                                                                                       | Notes                                                                                      |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| [`eth_blockNumber`](/reference/json-rpc/api#eth_blocknumber)                                                 |                                                                                            |
| [`eth_call`](/reference/json-rpc/api#eth_call)                                                               | [Gas limits](#eth_call--eth_estimategas), [state availability limits](#state-availability) |
| [`eth_chainId`](/reference/json-rpc/api#eth_chainid)                                                         |                                                                                            |
| [`eth_createAccessList`](/reference/json-rpc/api#eth_createaccesslist)                                       |                                                                                            |
| [`eth_estimateGas`](/reference/json-rpc/api#eth_estimategas)                                                 | [Gas limits](#eth_call--eth_estimategas)                                                   |
| [`eth_feeHistory`](/reference/json-rpc/api#eth_feehistory)                                                   | [Difference from Ethereum](#fee-estimation)                                                |
| [`eth_fillTransaction`](/reference/json-rpc/api#eth_filltransaction)                                         |                                                                                            |
| [`eth_gasPrice`](/reference/json-rpc/api#eth_gasprice)                                                       |                                                                                            |
| [`eth_getBalance`](/reference/json-rpc/api#eth_getbalance)                                                   |                                                                                            |
| [`eth_getBlockByHash`](/reference/json-rpc/api#eth_getblockbyhash)                                           |                                                                                            |
| [`eth_getBlockByNumber`](/reference/json-rpc/api#eth_getblockbynumber)                                       |                                                                                            |
| [`eth_getBlockReceipts`](/reference/json-rpc/api#eth_getblockreceipts)                                       |                                                                                            |
| [`eth_getBlockTransactionCountByHash`](/reference/json-rpc/api#eth_getblocktransactioncountbyhash)           |                                                                                            |
| [`eth_getBlockTransactionCountByNumber`](/reference/json-rpc/api#eth_getblocktransactioncountbynumber)       |                                                                                            |
| [`eth_getCode`](/reference/json-rpc/api#eth_getcode)                                                         |                                                                                            |
| [`eth_getLogs`](/reference/json-rpc/api#eth_getlogs)                                                         | [Block range limits](#eth_getlogs)                                                         |
| [`eth_getStorageAt`](/reference/json-rpc/api#eth_getstorageat)                                               |                                                                                            |
| [`eth_getTransactionByBlockHashAndIndex`](/reference/json-rpc/api#eth_gettransactionbyblockhashandindex)     |                                                                                            |
| [`eth_getTransactionByBlockNumberAndIndex`](/reference/json-rpc/api#eth_gettransactionbyblocknumberandindex) |                                                                                            |
| [`eth_getTransactionByHash`](/reference/json-rpc/api#eth_gettransactionbyhash)                               | [Does not return pending txs](#transaction-lifecycle)                                      |
| [`eth_getTransactionCount`](/reference/json-rpc/api#eth_gettransactioncount)                                 |                                                                                            |
| [`eth_getTransactionReceipt`](/reference/json-rpc/api#eth_gettransactionreceipt)                             |                                                                                            |
| [`eth_maxPriorityFeePerGas`](/reference/json-rpc/api#eth_maxpriorityfeepergas)                               | [Returns hardcoded value](#fee-estimation)                                                 |
| [`eth_sendRawTransaction`](/reference/json-rpc/api#eth_sendrawtransaction)                                   | [Async validation behavior](#transaction-lifecycle)                                        |
| [`eth_sendRawTransactionSync`](/reference/json-rpc/api#eth_sendrawtransactionsync)                           | [Async validation behavior](#transaction-lifecycle)                                        |
| [`eth_syncing`](/reference/json-rpc/api#eth_syncing)                                                         |                                                                                            |
| `eth_subscribe`                                                                                              | WebSocket only, see [WebSocket subscriptions](#websocket-subscriptions)                    |
| [`debug_getRawBlock`](/reference/json-rpc/api#debug_getrawblock)                                             |                                                                                            |
| [`debug_getRawHeader`](/reference/json-rpc/api#debug_getrawheader)                                           |                                                                                            |
| [`debug_getRawReceipts`](/reference/json-rpc/api#debug_getrawreceipts)                                       |                                                                                            |
| [`debug_getRawTransaction`](/reference/json-rpc/api#debug_getrawtransaction)                                 |                                                                                            |
| [`debug_traceBlockByHash`](/reference/json-rpc/api#debug_traceblockbyhash)                                   | [Trace options required](#debug--trace)                                                    |
| [`debug_traceBlockByNumber`](/reference/json-rpc/api#debug_traceblockbynumber)                               | [Trace options required](#debug--trace)                                                    |
| [`debug_traceCall`](/reference/json-rpc/api#debug_tracecall)                                                 | [Trace options required](#debug--trace)                                                    |
| [`debug_traceTransaction`](/reference/json-rpc/api#debug_tracetransaction)                                   | [Trace options required](#debug--trace)                                                    |
| [`admin_ethCallStatistics`](/reference/json-rpc/api#admin_ethcallstatistics)                                 | Monad-specific                                                                             |
| [`net_version`](/reference/json-rpc/api#net_version)                                                         |                                                                                            |
| [`txpool_statusByAddress`](/reference/json-rpc/api#txpool_statusbyaddress)                                   | Monad-specific                                                                             |
| [`txpool_statusByHash`](/reference/json-rpc/api#txpool_statusbyhash)                                         | Monad-specific                                                                             |
| [`web3_clientVersion`](/reference/json-rpc/api#web3_clientversion)                                           |                                                                                            |

## Differences from Ethereum

Monad is Geth-compatible, but its architecture — including [asynchronous execution](/monad-arch/consensus/asynchronous-execution) and sub-second block times — introduces behavioral differences in several areas.

### Transaction lifecycle

**Deferred nonce/balance validation.** `eth_sendRawTransaction` may not immediately reject transactions with a nonce gap or insufficient gas balance. Because Monad's RPC server is designed for asynchronous execution, it may not have the latest account state at the time of submission. These transactions are initially accepted because they may become valid during block creation.

**No pending transaction queries.** `eth_getTransactionByHash` only returns transactions that have been included in a block. Querying a transaction that is still in the mempool returns `null`.

### State availability

`eth_call` invocations that reference old state (i.e. with an old block number) may fail, because full nodes do not provide access to arbitrary historic state. See [Historical Data](/developer-essentials/historical-data) for details on what state is available and how to access it.

### Fee estimation

**`eth_maxPriorityFeePerGas`** currently returns a hardcoded suggested fee of 2 gwei. This is temporary.

**`eth_feeHistory`** with `newest_block = latest`: by convention, this method returns the fee history for the requested range *plus* one extra projected fee for the next block. Monad does not have all the inputs required to compute the next block's base fee, so when the newest requested block is `latest`, the latest `baseFeePerGas` is returned twice.

### Debug / tracing

**Trace options parameter is required.** `debug_traceCall`, `debug_traceTransaction`, and related `debug_trace*` methods require the trace options object to be explicitly provided. Unlike standard EVM clients where this parameter is optional, Monad RPC returns error `-32602 Invalid params` if it is omitted. Always include the parameter, even if empty:

```json theme={null}
{
  "method": "debug_traceCall",
  "params": [
    {
      "to": "0x6b175474e89094c44da98b954eedeac495271d0f"
    },
    "latest",
    {}
  ]
}
```

**Default tracer is `callTracer`.** When an empty trace options object `{}` is provided, Monad defaults to the `callTracer` instead of the struct logs tracer typical in other EVM clients. Monad does not currently support opcode-level struct logs at the VM level.

### Unsupported features

| Feature                                 | Affected methods                                        | Details                           |
| --------------------------------------- | ------------------------------------------------------- | --------------------------------- |
| EIP-4844 (blob transactions)            | `eth_sendRawTransaction`, `eth_call`, `eth_estimateGas` | Blob transaction type is rejected |
| `"syncing"` subscription                | `eth_subscribe`                                         | Not supported                     |
| `"newPendingTransactions"` subscription | `eth_subscribe`                                         | Not supported                     |

## Block tags

Monad blocks progress through four [commitment states](/monad-arch/consensus/block-states): `Proposed`, `Voted`, `Finalized`, and `Verified`. The JSON-RPC API exposes these through standard Ethereum-compatible block tags.

| Block tag     | Monad state | Guidance                                                                                                                                                                                                                    |
| ------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"latest"`    | `Proposed`  | Lowest-latency view, but backed by [speculative execution](/monad-arch/consensus/asynchronous-execution#speculative-execution) — no consensus vote yet. Use for read-heavy UIs where freshness matters more than certainty. |
| `"safe"`      | `Voted`     | Backed by a supermajority vote. Reverts require extremely [unlikely conditions](/monad-arch/consensus/monad-bft#the-only-loophole).                                                                                         |
| `"finalized"` | `Finalized` | Irreversible without a hard fork. Use for value settlement: bridges, deposits, payment crediting.                                                                                                                           |

<Note>The `"pending"` tag is supported but behaves the same as `"latest"`. [Learn more](/monad-arch/consensus/local-mempool).</Note>

### Unfinalized data

Any RPC response that includes data from a non-finalized block can change on a subsequent identical request.

* **Methods with a block number/tag parameter** (`eth_call`, `eth_getBalance`, `eth_getLogs`, etc.) — can return non-finalized data when called with `"latest"` or a non-finalized block number.
* **Transaction-hash lookups** (`eth_getTransactionByHash`, `eth_getTransactionReceipt`) — can match a transaction in a non-finalized block. The returned `blockNumber`, log indices, or even the result itself (`null`) can change.
* **Implicit-latest methods** (`eth_gasPrice`, `eth_maxPriorityFeePerGas`) — always return non-finalized data using the `"latest"` tag.

<Tip>
  Treat data from non-finalized blocks as provisional. For transaction-hash lookups, compare the returned `blockNumber` against the `"finalized"` block height (tracked client-side) before acting on the result.
</Tip>

## Limits

### `eth_call` / `eth_estimateGas`

#### Gas limit per call

| Provider         | Public RPC                   | Gas limit |
| ---------------- | ---------------------------- | --------- |
| QuickNode        | `rpc.monad.xyz`              | 200M gas  |
| Alchemy          | `rpc1.monad.xyz`             | 200M gas  |
| Ankr             | `rpc3.monad.xyz`             | 1B gas    |
| Monad Foundation | `rpc-mainnet.monadinfra.com` | 200M gas  |

<Note>
  **Node operators**. Use `--eth-call-provider-gas-limit` (default 30M) and `--eth-estimate-gas-provider-gas-limit` (default 30M) to configure these limits.
</Note>

#### Gas limit resolution

When the caller specifies a gas **price** (`gasPrice` or `maxFeePerGas`), the effective gas limit is `min(gas limit allowance, provider gas limit)`, where the gas limit allowance is the maximum gas given the caller's balance and specified price. When no gas price is specified, the provider gas limit applies directly. This is consistent with Geth's behavior.

#### Dual-pool execution model

`eth_call` and `eth_estimateGas` requests are routed to one of two execution pools based on the caller-specified gas limit:

| Pool     | Gas limit   | Purpose                                |
| -------- | ----------- | -------------------------------------- |
| Low-gas  | ≤ 8,100,000 | Most calls; higher throughput          |
| High-gas | > 8,100,000 | Large simulations; limited concurrency |

When the caller does not specify a gas limit, the request is first attempted in the low-gas pool. If it runs out of gas, it is automatically retried in the high-gas pool.

<Note>
  **Node operators**. Use `--eth-call-max-concurrent-requests` (default 1000) and `--eth-call-high-max-concurrent-requests` (default 20) to configure pool concurrency.
</Note>

### `eth_getLogs`

#### Block range limit per call

| Provider         | Public RPC                   | Block range limit                                             |
| ---------------- | ---------------------------- | ------------------------------------------------------------- |
| QuickNode        | `rpc.monad.xyz`              | 100 blocks                                                    |
| Alchemy          | `rpc1.monad.xyz`             | 1,000 blocks and 10,000 logs (whichever is more constraining) |
| Ankr             | `rpc3.monad.xyz`             | 1,000 blocks                                                  |
| Monad Foundation | `rpc-mainnet.monadinfra.com` | 100 blocks                                                    |

<Note>
  **Node operators**. Use `--eth-get-logs-max-block-range` to configure the block range limit.
</Note>

#### Why are block range limits low?

Monad produces a block every 400ms and can accommodate up to 5,000 transactions per block with computation up to 200M gas. Blocks are both extremely frequent and significantly larger than Ethereum blocks, which is the main motivation for keeping per-call block range limits low.

## Errors

Monad's JSON-RPC error codes aim to be equivalent to Ethereum's, but some codes deviate due to lack of standardization across Ethereum clients.

### Request-level errors (-32601)

| Message              | Explanation                                                     | Common cause                    |
| -------------------- | --------------------------------------------------------------- | ------------------------------- |
| Parse error          | Unable to parse the JSON-RPC request                            | Malformed JSON                  |
| Invalid request      | The request is structurally invalid                             | Request exceeds size limit      |
| Method not found     | The method is not part of the JSON-RPC spec                     | Typo in method name             |
| Method not supported | The method exists in the spec but is not yet supported by Monad | Calling an unimplemented method |

### Parameter errors (-32602)

| Message             | Explanation                                                        | Common cause                                                |
| ------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------- |
| Invalid block range | The requested `eth_getLogs` block range exceeds the provider limit | See [block range limits](#block-range-limit-per-call)       |
| Invalid params      | Incorrect parameters for the method                                | Wrong types, missing required fields, omitted trace options |

### Execution errors (-32603)

| Message                    | Explanation                              | Common cause                            |
| -------------------------- | ---------------------------------------- | --------------------------------------- |
| Internal error             | The request could not be fulfilled       | Server-side failure                     |
| Execution reverted         | The simulated transaction reverted       | Failed `eth_call` or `eth_estimateGas`  |
| Transaction decoding error | The raw transaction could not be decoded | Invalid RLP in `eth_sendRawTransaction` |

## WebSocket subscriptions

Monad's RPC server supports JSON-RPC over WebSocket connections, enabling persistent connections and real-time data via `eth_subscribe`. See the [Geth documentation](https://geth.ethereum.org/docs/interacting-with-geth/rpc/pubsub) for general `eth_subscribe` behavior.

Monad extends the standard subscription types with two speculative variants (`monadNewHeads` and `monadLogs`) that publish data sooner — approximately one second earlier on average — on a speculative basis. See [Speculative Real-Time Data](/monad-arch/realtime-data/spec-realtime) for background on speculative execution and [Block States](/monad-arch/consensus/block-states) for the full block lifecycle.

### Subscription types

| Type            | Fires when                                                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `newHeads`      | A new header is appended, once the block is `Voted`                                                                             |
| `logs`          | Matching logs appear in a new block, once the block is `Voted`                                                                  |
| `monadNewHeads` | A new header is available, once the block is `Proposed` and [speculatively executed](/monad-arch/realtime-data/spec-realtime)   |
| `monadLogs`     | Matching logs are available, once the block is `Proposed` and [speculatively executed](/monad-arch/realtime-data/spec-realtime) |

The subscription types `syncing` and `newPendingTransactions` are not supported.

### Speculative subscription behavior

`monadNewHeads` and `monadLogs` updates include two additional fields not present in the standard variants:

* **`blockId`** — a unique identifier for this specific block proposal (distinct from block number, since multiple proposals can exist for the same height).
* **`commitState`** — the block's current [commit state](/monad-arch/consensus/block-states): `Proposed`, `Voted`, `Finalized`, or `Verified`.

The same block will typically produce multiple updates as its `commitState` advances through the lifecycle. A block may skip `Voted` and go directly from `Proposed` to `Finalized` when consensus is ahead of execution. When a block fails to finalize, it is abandoned implicitly — the finalization of a different block at the same height supersedes it, but no explicit abandonment event is published.


# JSON-RPC Playground
Source: https://docs.monad.xyz/reference/json-rpc/playground

Interactive JSON-RPC request builder for all Monad RPC methods

<RpcForm />


# MPP API Reference
Source: https://docs.monad.xyz/reference/mpp/api

Reference for the @monad-crypto/mpp package

This page is a technical reference for `@monad-crypto/mpp`. For a developer-oriented guide with examples, visit the [overview](/reference/mpp/overview).

## Server

### Example

```ts title="server.ts" highlight={9-13} theme={null}
import { monad } from "@monad-crypto/mpp/server";
import { Mppx } from "mppx";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.SERVER_PRIVATE_KEY as `0x${string}`);

const mppx = Mppx.create({
  methods: [
    monad({
      account,
      recipient: account.address,
      // ... parameters below
    }),
  ],
});
```

### Parameters

The `monad` server payment method accepts the following parameters.

| Parameter             | Type                                       | Default | Description                                                                                                                                                        |
| --------------------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `amount`              | `string`                                   | —       | Default payment amount, human-readable (e.g. `"1.50"`)                                                                                                             |
| `currency`            | `string`                                   | USDC    | ERC-20 token contract address                                                                                                                                      |
| `decimals`            | `number`                                   | `6`     | Token decimals                                                                                                                                                     |
| `description`         | `string`                                   | —       | Human-readable description                                                                                                                                         |
| `externalId`          | `string`                                   | —       | External identifier to echo back in receipt                                                                                                                        |
| `recipient`           | `string`                                   | —       | Recipient address for payments                                                                                                                                     |
| `testnet`             | `boolean`                                  | `false` | Testnet mode                                                                                                                                                       |
| `waitForConfirmation` | `boolean`                                  | `true`  | Whether to wait for the charge transaction to confirm on-chain                                                                                                     |
| `getClient`           | `(params: { chainId?: number }) => Client` | —       | Function that returns a viem Client for the given chain ID                                                                                                         |
| `account`             | `Account \| Address`                       | —       | Server account used to broadcast `receiveWithAuthorization` transactions. Required when accepting `authorization` payloads. The server pays gas from this account. |
| `store`               | `Store`                                    | —       | Store for transaction hash replay protection. Use a shared store in multi-instance deployments so consumed hashes are visible across all server instances.         |

## Client

### Example

```ts title="client.ts" highlight={8-11} theme={null}
import { monad } from "@monad-crypto/mpp/client";
import { Mppx } from "mppx/client";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.CLIENT_PRIVATE_KEY as `0x${string}`);

const mppx = Mppx.create({
  methods: [monad({ 
    account,
    // ... parameters below
  })],
});

// Make a paid request
const response = await fetch("http://localhost:3000/premium");
const data = await response.json();
console.log(data);
```

### Parameters

The `monad` client payment method accepts the following parameters.

| Parameter   | Type                                       | Default | Description                                                                            |
| ----------- | ------------------------------------------ | ------- | -------------------------------------------------------------------------------------- |
| `account`   | `Account \| Address`                       | —       | Wallet account. If omitted, resolved from the viem Client.                             |
| `mode`      | `"push" \| "pull"`                         | Auto    | Payment mode. Defaults to `"push"` for JSON-RPC accounts, `"pull"` for local accounts. |
| `getClient` | `(params: { chainId?: number }) => Client` | —       | Custom viem Client resolver. Uses built-in RPC URLs if not provided.                   |


# MPP Overview
Source: https://docs.monad.xyz/reference/mpp/overview

Send and accept payments on Monad using the Machine Payments Protocol

The [`@monad-crypto/mpp`](https://www.npmjs.com/package/@monad-crypto/mpp) package implements Monad payments for the [Machine Payments Protocol](https://mpp.dev) (MPP). It enables one-time payment processing through ERC-20 token transfers on Monad.

This guide covers the Monad-specific `@monad-crypto/mpp` package. For general MPP concepts, see the [MPPX documentation](https://mpp.sh/docs).

## Installation

Install the package and its peer dependencies:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @monad-crypto/mpp mppx viem
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @monad-crypto/mpp mppx viem
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @monad-crypto/mpp mppx viem
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={null}
    bun add @monad-crypto/mpp mppx viem
    ```
  </Tab>
</Tabs>

## Server

The server defines what payment is required and verifies credentials submitted by clients. Import `monad` from the server entrypoint and pass it to `Mppx.create`.

```ts title="server.ts" theme={null}
import { monad } from "@monad-crypto/mpp/server";
import { Mppx } from "mppx";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.SERVER_PRIVATE_KEY as `0x${string}`);

const mppx = Mppx.create({
  methods: [
    monad({
      account,
      recipient: account.address,
    }),
  ],
});
```

### Gate an endpoint

Use `mppx.charge()` as middleware to require payment before serving a response.

```ts title="server.ts" theme={null}
import { Hono } from "hono";

const app = new Hono();

app.get("/premium", mppx.charge(), async (ctx) => {
  return ctx.json({ message: "Premium content" });
});

export default app;
```

When a client requests `/premium` without a valid payment credential, the server responds with a `402 Payment Required` status and a challenge describing the payment requirements. The client then submits a credential (transaction hash or signed authorization) to complete the payment.

### Testnet

By default, the package connects to Monad mainnet (chain ID `143`). To use testnet, set `testnet: true`.

```ts theme={null}
monad({
  account,
  recipient: account.address,
  testnet: true,
})
```

## Client

The client handles wallet interactions and credential creation. Import `monad` from the client entrypoint.

With a local private key, the client defaults to **pull mode** — it signs an ERC-3009 authorization without broadcasting a transaction.

```ts title="client.ts" theme={null}
import { monad } from "@monad-crypto/mpp/client";
import { Mppx } from "mppx/client";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.CLIENT_PRIVATE_KEY as `0x${string}`);

const mppx = Mppx.create({
  methods: [monad({ account })],
});

// Make a paid request
const response = await fetch("http://localhost:3000/premium");
const data = await response.json();
console.log(data);
```

### Push vs pull mode

|                  | Push                                | Pull                                     |
| ---------------- | ----------------------------------- | ---------------------------------------- |
| **Who pays gas** | Client                              | Server                                   |
| **Transaction**  | Client broadcasts ERC-20 `transfer` | Server calls `transferWithAuthorization` |
| **Credential**   | Transaction hash                    | Signed ERC-3009 authorization            |
| **Default for**  | JSON-RPC accounts (browser wallets) | Local accounts (private keys)            |
| **Trade-off**    | Client needs gas tokens             | Server needs gas tokens                  |

### Overriding the mode

Use the `mode` option to set the payment mode explicitly, regardless of account type.

```ts theme={null}
monad({
  account,
  mode: "push", // Always broadcast a transaction
})

monad({
  account,
  mode: "pull", // Always sign an authorization
})
```

### Monkey patch

The client `Mppx.create()` function [monkey patches](https://en.wikipedia.org/wiki/Monkey_patch) the Web `fetch` API to use the configured payment method whenever it receives a `402 Payment Required` HTTP response.

You can also use `mppx.fetch` directly.

```ts title="client.ts" theme={null}
import { monad } from "@monad-crypto/mpp/client";
import { Mppx } from "mppx/client";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.CLIENT_PRIVATE_KEY as `0x${string}`);

const mppx = Mppx.create({
  methods: [monad({ account })],
  polyfill: false,
});

const response = await mppx.fetch("http://localhost:3000/premium");
const data = await response.json();
console.log(data);
```

## Links

* NPM package: [@monad-crypto/mpp](https://www.npmjs.com/package/@monad-crypto/mpp)
* GitHub repository: [monad-crypto/monad-ts](https://github.com/monad-crypto/monad-ts)


# Staking API Reference
Source: https://docs.monad.xyz/reference/staking/api

Reference for Monad's staking precompile

This page is a technical reference for the staking precompile interface. For a developer-oriented guide to common workflows, visit the [overview](/reference/staking/overview).

## Address

| Contract           | Address                                                                         |
| ------------------ | ------------------------------------------------------------------------------- |
| Staking Precompile | <CopyToClipboard>`0x0000000000000000000000000000000000001000`</CopyToClipboard> |

## Functions and selectors

| State-modifying function                                | Selector     |
| ------------------------------------------------------- | ------------ |
| [`addValidator(bytes,bytes,bytes)`](#addvalidator)      | `0xf145204c` |
| [`delegate(uint64)`](#delegate)                         | `0x84994fec` |
| [`undelegate(uint64,uint256,uint8)`](#undelegate)       | `0x5cf41514` |
| [`withdraw(uint64,uint8)`](#withdraw)                   | `0xaed2ee73` |
| [`compound(uint64)`](#compound)                         | `0xb34fea67` |
| [`claimRewards(uint64)`](#claimrewards)                 | `0xa76e2ca5` |
| [`changeCommission(uint64,uint256)`](#changecommission) | `0x9bdcc3c8` |
| [`externalReward(uint64)`](#externalreward)             | `0xe4b3303b` |

| View function                                                         | Selector     |
| --------------------------------------------------------------------- | ------------ |
| [`getValidator(uint64)`](#getvalidator)                               | `0x2b6d639a` |
| [`getDelegator(uint64,address)`](#getdelegator)                       | `0x573c1ce0` |
| [`getWithdrawalRequest(uint64,address,uint8)`](#getwithdrawalrequest) | `0x56fa2045` |
| [`getConsensusValidatorSet(uint32)`](#getvalidatorset)                | `0xfb29b729` |
| [`getSnapshotValidatorSet(uint32)`](#getvalidatorset)                 | `0xde66a368` |
| [`getExecutionValidatorSet(uint32)`](#getvalidatorset)                | `0x7cb074df` |
| [`getDelegations(address,uint64)`](#getdelegations)                   | `0x4fd66050` |
| [`getDelegators(uint64,address)`](#getdelegators)                     | `0xa0843a26` |
| [`getEpoch()`](#getepoch)                                             | `0x757991a8` |
| [`getProposerValId()`](#getproposervalid)                             | `0xfbacb0be` |

| Syscall function                                        | Selector     |
| ------------------------------------------------------- | ------------ |
| [`syscallOnEpochChange(uint64)`](#syscallonepochchange) | `0x1d4e9f02` |
| [`syscallReward(address)`](#syscallreward)              | `0x791bdcf3` |
| [`syscallSnapshot()`](#syscallsnapshot)                 | `0x157eeb21` |

## Constants

| Constant                  | Meaning                                                          | Value            |
| ------------------------- | ---------------------------------------------------------------- | ---------------- |
| `BOUNDARY_BLOCK_PERIOD`   | Blocks from boundary block to boundary block                     | 50,000 blocks    |
| `EPOCH_DELAY_ROUNDS`      | Rounds between the boundary block and the start of each epoch    | 5,000 rounds     |
| `WITHDRAWAL_DELAY`        | Number of epochs before unstaked tokens can be withdrawn         | 1 epoch          |
| `MIN_AUTH_ADDRESS_STAKE`  | Min MON self-delegated by a validator for active set eligibility | 100,000 MON      |
| `ACTIVE_VALIDATOR_STAKE`  | Min total MON staked with a validator for active set eligibility | 10,000,000 MON   |
| `ACTIVE_VALSET_SIZE`      | Number of validators in the active set                           | 200              |
| `REWARD`                  | MON reward per block                                             | 25 MON           |
| `DUST_THRESHOLD`          | Minimum amount per individual delegation                         | 1 gwei (1e9 wei) |
| `MAX_COMMISSION`          | Maximum commission rate                                          | 100% (1e18)      |
| `ACCUMULATOR_DENOMINATOR` | Accumulator unit multiplier for accuracy                         | 1e36             |
| `PAGINATED_RESULTS_SIZE`  | Max results returned per paginated call                          | 100              |

## State-modifying functions

### addValidator

Creates a validator with an associated delegator account and returns the resultant `validatorId`.

**Function selector**

```
addValidator(bytes,bytes,bytes) : 0xf145204c
```

**Function signature**

```solidity theme={null}
function addValidator(
    bytes calldata payload,
    bytes calldata signedSecpMessage,
    bytes calldata signedBlsMessage
) external payable returns (uint64 validatorId);
```

**Parameters**

1. `payload` - consists of the following fields, packed together in big endian
   (equivalent to `abi.encodePacked()` in Solidity):
   * `bytes secpPubkey` (unique SECP public key used for consensus)
   * `bytes blsPubkey` (unique BLS public key used for consensus)
   * `address authAddress` (address used for the validator's delegator account. This address has
     withdrawal authority for the validator's staked amount)
   * `uint256 amount` (amount the validator is self-staking. Must equal `msg.value`)
   * `uint256 commission` (commission charged to delegators multiplied by 1e18, e.g. `10% = 1e17`)
2. `signedSecpMessage` - SECP signature over payload
3. `signedBlsMessage` - BLS signature over payload

**Gas cost**

505,125

**Behavior**

The function starts by unpacking the payload to retrieve the `secpPubkey`, `blsPubkey`,
`authAddress`, `amount`, and `commission`, then verifying that the `signedSecpMessage`
and `signedBlsMessage` correspond to the payload signed by the corresponding SECP and BLS
private keys.

* The validator must provide both a unique BLS key and a unique SECP key. Submissions with any
  repeated public keys will revert.
* Both signatures (`signedSecpMessage` and `signedBlsMessage`) must be valid and must sign
  over the `payload`.
* Multiple validators may share the same `authAddress`.
* `msg.value` must be equal or greater than `MIN_AUTH_ADDRESS_STAKE` or the call will revert.
* If the `msg.value` is also equal or greater than `ACTIVE_VALIDATOR_STAKE` then the validator
  will become active in the future:
  * If `addValidator` was called before the boundary block, then in epoch `n+1`;
  * Otherwise it will become active in epoch `n+2`.

<Accordion title="Pseudocode">
  ```solidity theme={null}
  secp_pubkey, bls_pubkey, auth_address, amount, commission = payload

  assert amount == msg.value

  // increment validator id
  last_val_id = last_val_id + 1;

  // set uniqueness of keys
  secp_to_val_id[secp_eth_address] = last_val_id;
  bls_to_val_id[bls_eth_address] = last_val_id;

  // set validator info
  val_execution[last_val_id] = ValExecution{
      uint256 stake = msg.value;
      uint256 commission = commission;
      bytes secp_pubkey = secp_pubkey;
      bytes bls_pubkey = bls_pubkey;
      uint256 address_flags = set_flags();
  }

  // set authority delegator info
  delegator[last_val_id][input.auth_address] = DelInfo{
      uint256 delta_stake = set_stake()[0];
      uint256 next_delta_stake = set_stake()[1];
      uint64 delta_epoch = set_stake()[2];
      uint64 next_delta_epoch = set_stake()[3];
  }

  // set delegator accumulator
  epoch_acc[last_val_id][getEpoch()] = Accumulator{
      uint256 ref_count += 1;
  }

  // set flags
  set_flags();

  // push validator id
  if (val_execution[last_val_id].stake() >= ACTIVE_VALIDATOR_STAKE
          and last_val_id not in execution_valset):
      execution_valset.push(last_val_id);

  return last_val_id;

  def set_flags():
      if msg.value + val_execution[last_val_id].stake() >= ACTIVE_VALIDATOR_STAKE:
          return ValidatorFlagsOk;
      if msg.value + val_execution[last_val_id].stake() >= MIN_AUTH_ADDRESS_STAKE
          return ValidatorFlagsStakeTooLow;

  def set_stake():
      if in_epoch_delay_rounds:
          delta_stake = 0;
          next_delta_stake = msg.value;
          delta_epoch = 0;
          next_delta_epoch = current_epoch + 2;
      else:
          delta_stake = msg.value;
          next_delta_stake = 0;
          delta_epoch = current_epoch + 1;
          next_delta_epoch = 0;
      return [delta_stake, next_delta_stake, delta_epoch, next_delta_epoch];
  ```
</Accordion>

**Usage**

Here is an example of assembling the payload and signing:

```
def generate_add_validator_call_data_and_sign(
    secp_pubkey: bytes,
    bls_pubkey: bytes,
    auth_address: bytes,
    amount: int,
    commission: int
    secp_privkey: bytes
    bls_privkey: bytes
) -> bytes:
    # 1) Encode
    payload_parts = [
        secp_pubkey,
        bls_pubkey,
        auth_address,
        toBigEndian32(amount),
        toBigEndian32(commission),
    ]
    payload = b"".join(payload_parts)

    # 2) Sign with both keys
    secp_sig = SECP256K1_SIGN(blake3(payload), secp_privkey)
    bls_sig  = BLS_SIGN(hash_to_curve(payload), bls_privkey)

    # 3) Solidity encode the payload and two signatures
    return eth_abi.encode(['bytes', 'bytes', 'bytes'], [payload, secp_sig, bls_sig])
```

### delegate

Creates a delegator account if it does not exist and increases the delegator's balance.

**Function selector**

```
delegate(uint64) : 0x84994fec
```

**Function signature**

```solidity theme={null}
function delegate(
    uint64 validatorId
) external payable returns (bool success);
```

**Parameters**

1. `validatorId` - id of the validator that delegator would like to delegate to
2. `msg.value` - the amount to delegate

**Gas cost**

260,850

**Behavior**

* The delegator account is determined by `msg.sender`.
* `validatorId` must correspond to a valid validator.
* `msg.value` must be >= `DUST_THRESHOLD`.
* If this delegation causes the validator's total stake to exceed `ACTIVE_VALIDATOR_STAKE`,
  then the validator will be added to `execution_valset` if not already present.
* The delegator stake becomes active
  * in epoch `n+1` if the request is before the boundary block
  * in epoch `n+2` otherwise

<Accordion title="Pseudocode">
  ```solidity theme={null}
  validator_id = msg.input.val_id;

  // set validator information
  val_execution[validator_id] =  ValExecution{
      uint256 stake += msg.value();
  }

  // set delegator information
  DelInfo current_delegator = delegator[validator_id][msg.sender];

  // apply get_current_stake() first. This updates the delegator stake
  // to be inline with the current stake activated in consensus.
  get_current_stake();

  // apply add_stake() second.
  uint256[4] add_stake_info = add_stake(msg.value());

  current_delegator = DelInfo{
      uint256 delta_stake = add_stake_info[0];
      uint256 next_delta_stake = add_stake_info[1];
      uint64 delta_epoch = add_stake_info[2];
      uint64 next_delta_epoch = add_stake_info[3];
  }

  // set epoch accumulator
  epoch_acc[validator_id][getEpoch()].ref_count += 1;

  // set flags
  set_flags();

  // push validator id
  if val_execution[validator_id].stake() >= ACTIVE_VALIDATOR_STAKE
          and validator_id not in execution_valset:
      execution_valset.push(validator_id);

  def add_stake(uint256 amount):
      uint256 _delta_stake;
      uint256 _next_delta_stake;
      uint64 _delta_epoch;
      uint64 _next_delta_epoch;

      if not in_epoch_delay_rounds:
          _delta_stake = current_delegator.delta_stake() + amount;
          _next_delta_stake = 0;
          _delta_epoch = current_epoch + 1;
          _next_delta_epoch = 0;
      else:
          _delta_stake = 0;
          _next_delta_stake = current_delegator.next_delta_stake() + amount;
          _delta_epoch = 0;
          _next_delta_epoch = current_epoch + 2;
      return [_delta_stake, _next_delta_stake, _delta_epoch, _next_delta_epoch];


  def maybe_process_next_epoch_state():
      """
      Helper function to process and update rewards
      based on the current epoch state.
      """

      if (
          epoch_acc[validator_id][current_delegator.delta_epoch()] != 0
          and current_epoch > current_delegator.delta_epoch()
          and current_delegator.delta_epoch() > 0
      ):
          // Compute rewards from the last checked epoch.
          _rewards += current_delegator.stake() * (
              epoch_acc[validator_id][current_delegator.delta_epoch()].val()
              - current_delegator.acc()
          )

          // Promote stake to active in delegator view.
          current_delegator.stake() += current_delegator.delta_stake()
          current_delegator.acc() = (
              epoch_acc[validator_id][current_delegator.delta_epoch()].val()
          )
          current_delegator.delta_epoch() = current_delegator.next_delta_epoch()
          current_delegator.delta_stake() = current_delegator.next_delta_stake()
          current_delegator.next_delta_epoch() = 0
          current_delegator.next_delta_stake() = 0

          epoch_acc[validator_id][current_delegator.delta_epoch].ref_count -= 1


  def get_current_stake():
      uint256 _rewards = 0;

      // Process next epoch rewards and increment stake
      maybe_process_next_epoch_state()
      // Perform again to capture max two additional epochs
      maybe_process_next_epoch_state()

      current_delegator.rewards() += _rewards;
      return _rewards;
  ```
</Accordion>

### undelegate

Deducts `amount` from the delegator account and moves it to a withdrawal request object, where it remains in a pending state for `WITHDRAWAL_DELAY` epochs before the funds are claimable via the [`withdraw`](#withdraw) function.

**Function selector**

```
undelegate(uint64,uint256,uint8) : 0x5cf41514
```

**Function signature**

```solidity theme={null}
function undelegate(
    uint64 validatorId,
    uint256 amount,
    uint8 withdrawId
) external returns (bool success);
```

**Parameters**

1. `validatorId` - id of the validator to which sender previously delegated, from which we are
   removing delegation
2. `amount` - amount to undelegate, in Monad wei
3. `withdrawId` - integer between 0 and 255, inclusive, which serves as the identifier for a
   delegator's withdrawal. For each (validator, delegator) tuple, there can be a maximum of 256
   in-flight withdrawal requests

**Gas cost**

147,750

**Behavior**

* The delegator account is determined by `msg.sender`.
* `validatorId` must correspond to a valid validator to which the sender previously delegated
* The delegator must have stake >= amount.
* If the withdrawal causes `Val(validatorId).stake()` to drop below `ACTIVE_VALIDATOR_STAKE`, then the
  validator is scheduled to be removed from the valset.
* If the `authAddress` on a validator undelegates enough of their own stake to drop below
  `MIN_AUTH_ADDRESS_STAKE`, then the validator is scheduled to be removed from the valset.
* The function will revert if there is a pending withdrawal with the same `withdrawId`.
  `withdrawId`s can be reused after calling [`withdraw`](#withdraw).
* A delegator can only remove a stake after it has been activated. This is the stake field in
  the delegator struct. Pending delegations cannot be removed until they are active.
* The delegator stake becomes inactive in the valset
  * in epoch `n+1` if the request is before the boundary block
  * in epoch `n+2` otherwise
* The delegator stake becomes withdrawable, and thus no longer subject to slashing
  * in epoch `n + 1 + WITHDRAWAL_DELAY` if the request is before the boundary block
  * in epoch `n + 2 + WITHDRAWAL_DELAY` otherwise

<img alt="timeline of undelegation and withdrawal" />

<p>Timeline of withdrawability of stake relative to <code>undelegate</code> command</p>

<Accordion title="Pseudocode">
  ```solidity theme={null}
  uint64 validator_id = msg.input.val_id;
  uint256 amount = msg.input.amount;
  uint8 withdraw_id = msg.input.withdraw_id;

  ValExecution current_validator = val_execution[validator_id];

  // set validator information
  current_validator =  ValExecution{
      uint256 stake -= amount;
  }

  // apply get_current_stake() first.
  get_current_stake();

  DelInfo current_delegator = delegator[validator_id][msg.sender];
  // set delegator information
  current_delegator = DelInfo{
      uint256 stake -= amount;
  }

  // set withdraw request
  withdrawal[validator_id][msg.sender][withdraw_id] = WithdrawalRequest{
      uint256 amount = amount;
      uint256 acc = current_validator.acc();
      uint64 epoch = getEpoch();
  };

  // set epoch accumulator
  epoch_acc[validator_id][getEpoch()].ref_count += 1;

  // schedule validator to leave set
  if current_validator.stake
   < ACTIVE_VALIDATOR_STAKE and validator_id in execution_valset:
      current_validator.set_flag(INSUFFICIENT_STAKE);

  if (current_delegator.stake <= MIN_AUTH_ADDRESS_STAKE and validator_id in execution_valset) and msg.sender == current_validator.auth_address:
      current_validator.set_flag(INSUFFICIENT_VALIDATOR_STAKE);
  ```
</Accordion>

### withdraw

Completes an undelegation action (which started with a call to the `undelegate` function), sending the amount to `msg.sender`, provided that sufficient epochs have passed.

**Function selector**

```
withdraw(uint64,uint8) : 0xaed2ee73
```

**Function signature**

```solidity theme={null}
function withdraw(
    uint64 validatorId,
    uint8 withdrawId
) external returns (bool success);
```

**Parameters**

1. `validatorId` - id of the validator to which sender previously delegated, from which we previously
   issued an `undelegate` command
2. `withdrawId` - identifier for a delegator's previously created withdrawal; the same id
   previously supplied to [`undelegate`](#undelegate). For each (validator, delegator) tuple,
   there can be a maximum of 256 in-flight withdrawal requests.

**Gas cost**

68,675

**Behavior**

* The delegator is `msg.sender`. The withdrawal is identified by `msg.sender`, `validatorId`,
  and `withdrawId`
* The withdraw action can take place once the undelegation is complete, and the withdraw delay has passed:
  * in epoch `n + 1 + WITHDRAWAL_DELAY` if the undelegate request is before the boundary block
  * in epoch `n + 2 + WITHDRAWAL_DELAY` otherwise

<Accordion title="Pseudocode">
  ```solidity theme={null}
  uint64 validator_id = msg.input.val_id;
  uint8 withdraw_id = msg.input.withdraw_id;

  WithdrawalRequest current_withdraw = withdrawal[validator_id][msg.sender][withdraw_id];

  // Compute any additional rewards and transfer funds to delegator
  transfer(msg.sender, current_withdraw.amount + get_withdraw_rewards());

  // unset withdraw request
  withdrawal[validator_id][msg.sender][withdraw_id] = WithdrawalRequest{
      uint256 amount = 0,
      uint256 acc = 0,
      uint64 epoch = 0
  };

  def get_withdraw_rewards():
      epoch_acc[validator_id][current_withdraw.epoch].ref_count -= 1;
      return current_withdraw.amount() * (epoch_acc[validator_id][current_withdraw.epoch()].val() - current_withdraw.acc());
  ```
</Accordion>

### compound

Converts the delegator's accumulated rewards into additional stake.

**Function selector**

```
compound(uint64) : 0xb34fea67
```

**Function signature**

```solidity theme={null}
function compound(
    uint64 validatorId
) external returns (bool success);
```

**Parameters**

1. `validatorId` - id of the validator to which sender previously delegated, for which we are
   compounding rewards

**Gas cost**

289,325

**Behavior**

* The account compounded is determined by `msg.sender`. If a delegator account does not exist, then the call reverts
* `validatorId` must correspond to a valid validator to which the sender previously delegated
* The delegator rewards become active in the valset
  * in epoch `n+1` if the request is before the boundary block
  * in epoch `n+2` otherwise.

<Accordion title="Pseudocode">
  ```solidity theme={null}
  validator_id = msg.input.val_id;

  // set delegator information
  DelInfo current_delegator = delegator[validator_id][msg.sender];

  // apply get_current_stake() first. This updates the delegator stake
  // to be inline with the current stake activated in consensus.
  rewards_compounded = get_current_stake();

  // apply add_stake() second.
  uint256[4] add_stake_info = add_stake(rewards_compounded);

  // set delegator information
  current_delegator = DelInfo{
      uint256 delta_stake = add_stake_info[0];
      uint256 next_delta_stake = add_stake_info[1];
      uint64 delta_epoch = add_stake_info[2];
      uint64 next_delta_epoch = add_stake_info[3];
      uint256 rewards = 0;
  }

  // set validator information
  val_execution[validator_id] = ValExecution{
      uint256 stake += rewards_compounded;
  }

  // set accumulator
  epoch_acc[validator_id][getEpoch()] = Accumulator{
      uint256 ref_count += 1;
  }

  // set flags
  set_flags();

  // push validator id
  if val_execution[validator_id].stake() >= ACTIVE_VALIDATOR_STAKE and validator_id not in execution_valset:
      execution_valset.push(validator_id);

  ```
</Accordion>

### claimRewards

Allows a delegator to claim any rewards instead of [compounding](#compound) them.

**Function selector**

```
claimRewards(uint64) : 0xa76e2ca5
```

**Function signature**

```solidity theme={null}
function claimRewards(
    uint64 validatorId
) external returns (bool success);
```

**Parameters**

1. `validatorId` - id of the validator to which sender previously delegated, for which we are
   claiming rewards

**Gas cost**

155,375

**Behavior**

* `validatorId` must correspond to a valid validator to which the sender previously delegated
* If delegator account does not exist for this `(validatorId, msg.sender)` tuple, then the call reverts
* The delegator's accumulated rewards are transferred to their delegation

<Accordion title="Pseudocode">
  ```solidity theme={null}
  // set delegator information
  DelInfo current_delegator = delegator[validator_id][msg.sender];

  // apply get_current_stake() first.
  uint256 current_rewards = get_current_stake();

  // set delegator information
  current_delegator = DelInfo{
      uint256 rewards = 0;
  )

  // send rewards to delegator
  transfer(msg.sender, current_rewards);
  ```
</Accordion>

### changeCommission

Allows the `authAddress` for a validator to modify the commission for the validator.

**Function selector**

```
changeCommission(uint64,uint256) : 0x9bdcc3c8
```

**Function signature**

```solidity theme={null}
function changeCommission(
    uint64 validatorId,
    uint256 commission
) external returns (bool success);
```

**Parameters**

1. `validatorId` - id of the validator, who would like to change their commission rate
2. `commission` - commission rate taken from block rewards, expressed in 1e18 units
   (e.g., 10% = 1e17)

**Gas cost**

39,475

**Behavior**

* The `msg.sender` must be the `authAddress` for the respective validator Id.
* The commission cannot be set larger than `MAX_COMMISSION` (currently 100%).
* The change in commission occurs in the following epochs:
  * in epoch `n+1` if request is not in the epoch delay rounds.
  * in epoch `n+2` if request is in the epoch delay rounds.

<Accordion title="Pseudocode">
  ```solidity theme={null}
  validator_id = msg.input.val_id;


  val_execution[validator_id] = ValExecution{
      uint256 commission = msg.input.commission;
  }


  ```
</Accordion>

### externalReward

Allows anyone to send extra MON to the stakers of a particular validator, typically called by the validator themselves to share extra tips to their delegators.

**Function selector**

```
externalReward(uint64) : 0xe4b3303b
```

**Function signature**

```solidity theme={null}
function externalReward(
    uint64 validatorId
) external payable returns (bool success);
```

**Parameters**

1. `validatorId` - id of the validator
2. `msg.value` - the MON to add to unclaimed rewards

**Gas cost**

66,575

**Behavior**

* This can only be called for a validator currently in the consensus validator set; otherwise
  the transaction reverts.
* `msg.value` must be between 1 MON and 1,000,000 MON; otherwise the transaction reverts.
* Commission is not deducted from this and diverted to the validator's `auth_address`. If you
  wish for a portion to be deducted, it should be deducted before sending.

<Accordion title="Pseudocode">
  ```solidity theme={null}
  validator_id = msg.input.val_id;

  require(msg.value >= 1e18 && msg.value <= 1e24, "Reward out of bounds");
  require(val_consensus[validator_id] > 0 , "Validator not active");

  val_execution[validator_id].unclaimed_reward += msg.value;
  val_execution[val_id].acc += msg.value / val_consensus[val_id].stake();

  ```
</Accordion>

## View functions

<Note>
  Because only `CALL`s are allowed to the staking precompile, all view functions are given the default `nonpayable` state mutability.
</Note>

### getValidator

Returns a complete view of the validator's state across execution, consensus, and snapshot contexts.

* [`ValExecution`](#validator-structs) (execution view)
* Stake and commission (consensus view)
* Stake and commission (snapshot view)

**Function selector**

```
getValidator(uint64) : 0x2b6d639a
```

**Function signature**

```solidity theme={null}
function getValidator(
    uint64 validatorId
) external returns (
    address authAddress,
    uint64 flags,
    uint256 stake,
    uint256 accRewardPerToken,
    uint256 commission,
    uint256 unclaimedRewards,
    uint256 consensusStake,
    uint256 consensusCommission,
    uint256 snapshotStake,
    uint256 snapshotCommission,
    bytes memory secpPubkey,
    bytes memory blsPubkey
);
```

**Parameters**

1. `validatorId` - id of the validator

**Gas cost**

97,200

### getDelegator

Returns the delegator's [`DelInfo`](#delegator-structs) for the specified validator, providing a view of the delegator's stake, accumulated rewards, and pending changes in stake.

**Function selector**

```
getDelegator(uint64,address) : 0x573c1ce0
```

**Function signature**

```solidity theme={null}
function getDelegator(
    uint64 validatorId,
    address delegator
) external returns (
    uint256 stake,
    uint256 accRewardPerToken,
    uint256 unclaimedRewards,
    uint256 deltaStake,
    uint256 nextDeltaStake,
    uint64 deltaEpoch,
    uint64 nextDeltaEpoch
);
```

**Parameters**

1. `validatorId` - id of the validator
2. `delegator` - address of the delegator about whose stake we are inquiring

**Gas cost**

184,900

### getWithdrawalRequest

Returns the pending [`WithdrawalRequest`](#delegator-structs) for the `(validatorId, delegator, withdrawId)` tuple.

**Function selector**

```
getWithdrawalRequest(uint64,address,uint8) : 0x56fa2045
```

**Function signature**

```solidity theme={null}
function getWithdrawalRequest(
    uint64 validatorId,
    address delegator,
    uint8 withdrawId
) external returns (
    uint256 withdrawalAmount,
    uint256 accRewardPerToken,
    uint64 withdrawEpoch
);
```

**Gas cost**

24,300

### get\*ValidatorSet

Returns the consensus, snapshot, and execution validator IDs, respectively.

**Function selectors**

```
getConsensusValidatorSet(uint32) : 0xfb29b729
getSnapshotValidatorSet(uint32) : 0xde66a368
getExecutionValidatorSet(uint32) : 0x7cb074df
```

**Function signatures**

```solidity theme={null}
function getConsensusValidatorSet(
    uint32 startIndex
) external returns (bool isDone, uint32 nextIndex, uint64[] memory valIds);

function getSnapshotValidatorSet(
    uint32 startIndex
) external returns (bool isDone, uint32 nextIndex, uint64[] memory valIds);

function getExecutionValidatorSet(
    uint32 startIndex
) external returns (bool isDone, uint32 nextIndex, uint64[] memory valIds);
```

**Parameters**

1. `startIndex` - since the list being looked up is potentially very long, each of these functions
   is paginated, returning a fixed-length subset of the desired list. Pass `startIndex` to
   indicate where in the list to start.

**Gas cost**

814,000 gas (assuming `PAGINATED_RESULTS_SIZE = 100`).

**Behavior**

`getExecutionValidatorSet()` returns the entire active validator set of all validators that meet the staking criteria to be considered for inclusion. `getSnapshotValidatorSet()` returns the subset of validators that have been chosen to be leaders in the next epoch. `getConsensusValidatorSet()` returns the subset of validators that are leaders in the current epoch.

Each call retrieves up to `PAGINATED_RESULTS_SIZE` validator IDs starting from `startIndex` and
returns a tuple `(bool done, uint32 nextIndex, uint256[] valids)`.

The `bool isDone` indicates whether the end of the list was reached. The `uint32 nextIndex`
is the last slot in the array.

### getDelegations

Returns a paginated list of validator IDs that a given delegator address has delegated to.

**Function selector**

```
getDelegations(address,uint64) : 0x4fd66050
```

**Function signature**

```solidity theme={null}
function getDelegations(
    address delegator,
    uint64 startValId
) external returns (bool isDone, uint64 nextValId, uint64[] memory valIds);
```

**Parameters**

1. `delegator` - the address whose delegations we want to look up
2. `startValId`

**Gas cost**

814,000

**Behavior**

Each call retrieves up to `PAGINATED_RESULTS_SIZE` validator ids starting from `startValId`
and returns a tuple `(bool isDone, uint64 nextValId, uint64[] valIds)` with delegation
from the input `delegator` address.

The `bool isdone` indicates whether the end of the list was reached.
The `uint64 nextValId` is the id after the last element in `valIds`. Use it as the
`startValId` for the next call.

If `delegator` has delegated to over `PAGINATED_RESULTS_SIZE` validator ids,
multiple calls are required (while `isDone` is false).

To capture the full set, make the first function call using `startValId = 0`.

### getDelegators

Returns a paginated list of delegator addresses for a given validator.

**Function selector**

```
getDelegators(uint64,address) : 0xa0843a26
```

**Function signature**

```solidity theme={null}
function getDelegators(
    uint64 validatorId,
    address startDelegator
) external returns (bool isDone, address nextDelegator, address[] memory delegators);
```

**Parameters**

1. `validatorId` - the id of the validator for which we want to know the delegators
2. `startDelegator`

**Gas cost**

814,000

**Behavior**

Each call retrieves up to `PAGINATED_RESULTS_SIZE` delegator addresses starting from
`startDelegator` and returns a tuple `(bool isDone, address nextDelegator, address[] delegators)`
with delegation to the input `validatorId`.

The `bool isDone` indicates the end of the list was reached.
The `nextDelegator` is the address immediately after the last element in `delegators`.
Use it as `startDelegator` for the next call.

To capture the full set, the function should be called with `startDelegator = 0`.

<Note>
  The number of delegators to a given validator can be very large, so it is recommended to
  maintain an updated list via the
  [events](/monad-arch/realtime-data/data-sources#real-time-data-sources) framework, rather
  than periodically calling this expensive lookup.
</Note>

### getEpoch

Returns the current epoch and timing within the epoch (before or after the boundary block).

**Function selector**

```
getEpoch() : 0x757991a8
```

**Function signature**

```solidity theme={null}
function getEpoch() external returns (uint64 epoch, bool inEpochDelayPeriod);
```

**Gas cost**

200

**Behavior**

If `inEpochDelayPeriod` is false, the boundary block has not been reached yet
and write operations at that time should be effective for `epoch + 1`.
If `inEpochDelayPeriod` is true, the network is past the boundary block and
and write operations at that time should be effective for `epoch + 2`

### getProposerValId

Returns the validator ID of the current block proposer, corresponding to the SECP value of the block author.

**Function selector**

```
getProposerValId() : 0xfbacb0be
```

**Function signature**

```solidity theme={null}
function getProposerValId() external returns (uint64 val_id);
```

**Gas cost**

100

## Syscalls

There are currently three syscalls. Users cannot invoke these directly. They are only
triggered through special system transactions.

### syscallOnEpochChange

Triggered at the end of the epoch delay rounds to finalize accumulator values and update epoch state.

**Function selector**

```
syscallOnEpochChange(uint64) : 0x1d4e9f02
```

**Function signature**

```solidity theme={null}
function syscallOnEpochChange(uint64 epoch) external;
```

**Parameters**

1. `epoch` - the new consensus epoch being entered

**Behavior**

1. If the validator received a request to change stake in the previous epoch and participated in the previous epoch's consensus validator set then it saves the corresponding accumulator value
2. If any validator was active in the previous epoch but becomes inactive in the current epoch,
   it also saves their current accumulator value
3. Sets the current epoch in state

<Accordion title="Pseudocode">
  ```solidity theme={null}
  uint64 current_epoch = msg.input.epoch;

  for i in snapshot_valset:
      if epoch_acc[i][current_epoch] is not empty:
          epoch_acc[i][current_epoch].val() = execution_valset[i].acc()
      if epoch_acc[i][current_epoch + 1] is not empty:
          epoch_acc[i][current_epoch].val() = execution_valset[i].acc()

  in_epoch_delay_rounds = false;
  epoch = current_epoch;
  ```
</Accordion>

### syscallReward

Rewards the block-producing validator and their delegators with the configured block reward for every block.

**Function selector**

```
syscallReward(address) : 0x791bdcf3
```

**Function signature**

```solidity theme={null}
function syscallReward(address blockAuthor) external;
```

**Parameters**

1. `blockAuthor` — the address of the validator that produced the block.

**Behavior**

1. If the validator has a nonzero commission, a portion of the reward is allocated to the
   validator's `authAddress`.
2. The remaining reward is claimable to the validator's delegators.

Note that the commission is calculated as a percentage of the total block reward.

<Info title="Example">
  * Suppose that a validator's personal stake comprises 20% of the total delegation to
    their validator.
  * The commission is set at 10% of total rewards.

  Then the validator receives 10% of the total block reward as their commission. The remaining 90%
  of the reward is distributed to the stake pool. Since the validator owns 20% of the pool, they
  also receive 20% of that remaining amount.
</Info>

<Accordion title="Pseudocode">
  ```solidity theme={null}
  uint64 val_id = secp_to_val_id[block_author];
  DelInfo auth_del = delegator[val_id][val_execution[val_id].auth_address()];
  uint256 _commission = REWARD * val_execution[val_id].commission / 1e18;
  uint256 _unclaimed_rewards = REWARD - _commission;

  // state update
  auth_del.rewards() += _commission;
  val_execution[val_id].unclaimed_rewards += _unclaimed_rewards;
  val_execution[val_id].acc += _unclaimed_rewards / val_consensus[val_id].stake();

  mint(STAKING_CONTRACT_ADDRESS, REWARD);
  ```
</Accordion>

### syscallSnapshot

Sorts the current execution-layer validator set, selects the top `N` staked validators as the upcoming consensus validator set, stores the updated set in state, and clears the previous consensus set.

**Function selector**

```
syscallSnapshot() : 0x157eeb21
```

**Function signature**

```solidity theme={null}
function syscallSnapshot() external;
```

**Behavior**

<Accordion title="Pseudocode">
  ```solidity theme={null}

  uint64[] filter_top_n_validators = sort(execution_valset);

  for i in snapshot_valset:
      val_snapshot[i].stake = 0;
      val_snapshot[i].commission = 0;

  snapshot_valset = consensus_valset;
  consensus_valset = filter_top_n_validators;

  for i in filter_top_n_validators:
      val_consensus[i].stake = val_execution[i].stake;
      val_consensus[i].commission = val_execution[i].commission;
  ```
</Accordion>

## Events

The staking precompiles emit standard events that appear in transaction receipts. These events
provide indexed information about validator and delegator actions.

### ValidatorRewarded

Emitted when block reward is allocated via [`syscallReward`](#syscallreward).

```solidity theme={null}
event ValidatorRewarded(
        uint64 indexed validatorId,
        address indexed from,
        uint256 amount,
        uint64 epoch
);
```

### ValidatorCreated

Emitted when a validator is added via [`addValidator`](#addvalidator).

```solidity theme={null}
event ValidatorCreated(
    uint64  indexed validatorId,
    address indexed authAddress,
    uint256 commission
);
```

### ValidatorStatusChanged

Emitted during [`addValidator`](#addvalidator), [`delegate`](#delegate), [`undelegate`](#undelegate), or [`compound`](#compound). if the validator's flags change.

```solidity theme={null}
event ValidatorStatusChanged(
    uint64  indexed validatorId,
    uint64  flags
);
```

### Delegate

Emitted when delegation amount is increased, i.e. during [`addValidator`](#addvalidator), [`delegate`](#delegate), or [`compound`](#compound).

```solidity theme={null}
event Delegate(
    uint64  indexed validatorId,
    address indexed delegator,
    uint256 amount,
    uint64  activationEpoch
);
```

### Undelegate

Emitted when a delegator calls [`undelegate`](#undelegate).

```solidity theme={null}
event Undelegate(
    uint64  indexed validatorId,
    address indexed delegator,
    uint8   withdrawId,
    uint256 amount,
    uint64  activationEpoch
);
```

### Withdraw

Emitted when a delegator executes [`withdraw`](#withdraw) successfully.

```solidity theme={null}
event Withdraw(
    uint64 indexed validatorId,
    address indexed delegator,
    uint8   withdrawId,
    uint256 amount,
    uint64  withdrawEpoch
);
```

### ClaimRewards

Emitted when a delegator claims rewards via [`claimRewards`](#claimrewards).

```solidity theme={null}
event ClaimRewards(
    uint64 indexed validatorId,
    address indexed delegator,
    uint256 amount,
    uint64 epoch
);
```

### CommissionChanged

Emitted when a validator changes commission via [`changeCommission`](#changecommission).

```solidity theme={null}
event CommissionChanged(
    uint64 indexed validatorId,
    uint256 oldCommission,
    uint256 newCommission
);
```

### EpochChanged

Emitted when epoch changes via [`syscallOnEpochChange`](#syscallonepochchange).

```solidity theme={null}
    event EpochChanged(
        uint64 oldEpoch,
        uint64 newEpoch
    );
```

## Precompile internals

* [Constants](#constants)
* [Validator structs](#validator-structs)
* [Delegator structs](#delegator-structs)
* [State variables](#state-variables)
* [Mappings](#mappings)

### Validator structs

```solidity theme={null}
struct ValExecution             // Realtime execution state for one validator
{
    uint256 stake;              // Upcoming stake pool balance
    uint256 acc;                // Current accumulator value for validator
    uint256 commission;         // Proportion of block reward charged as commission, times 1e18; 10% = 1e17
    bytes   secp_pubkey;        // Secp256k1 public key used by consensus
    bytes   bls_pubkey;         // Bls public key used by consensus
    uint256 address_flags;      // Flags to represent validators' current state
    uint256 unclaimed_rewards;  // Unclaimed rewards
    address auth_address;       // Delegator address with authority over validator stake
}

struct ValConsensus             // A subset of validator state for the consensus system
{
    uint256 stake;              // Current active stake
    uint256 commission;         // Commission rate for current epoch
    bytes   secp_pubkey;        // Secp256k1 public key used by consensus
    bytes   bls_pubkey;         // Bls public key used by consensus
}
```

### Delegator structs

```solidity theme={null}
struct DelInfo
{
    uint256 stake;               // Current active stake
    uint256 acc;                 // Last checked accumulator
    uint256 rewards;             // Last checked rewards
    uint256 delta_stake;         // Stake to be activated next epoch
    uint256 next_delta_stake;    // Stake to be activated in 2 epochs
    uint64 delta_epoch;          // Epoch when delta_stake becomes active
    uint64 next_delta_epoch;     // Epoch when next_delta_stake becomes active
}

struct WithdrawalRequest
{
    uint256 amount;              // Amount to undelegate from validator
    uint256 acc;                 // Validator accumulator when undelegate was called
    uint64 epoch;                // Epoch when undelegate stake deactivates
};

struct Accumulator
{
    uint256 val;               // Current accumulator value
    uint256 refcount;            // Reference count for this accumulator value
};
```

### State variables

```solidity theme={null}
// Current consensus epoch
uint64 epoch;

// Flag indicating if currently in epoch delay rounds
bool in_epoch_delay_rounds;

// Counter for validator ids
uint64 last_val_id;

// Current execution view of validator set
StorageArray<uint64> execution_valset;

// Previous consensus view of validator set
StorageArray<uint64> snapshot_valset;

// Current consensus view of validator set
StorageArray<uint64> consensus_valset;
```

### Mappings

```solidity theme={null}
//These mappings only exist to ensure the SECP/BLS Keys are unique
mapping (secp_eth_address => uint64) secp_to_val_id;
mapping (bls_eth_address => uint64) bls_to_val_id;

// Keys(val_id, epoch) => Value(acc)
// making note of the validator accumulator at start of epoch.
mapping(uint64 => mapping(uint64 => Accumulator)) epoch_acc;

// Key(val_id)
// Contains the validator info for the execution view. Changes to stake
// or commission are reflected immediately.
mapping(uint64 => ValExecution) val_execution;

// Key(val_id)
// Contains a subset of the validator info relevant to consensus. Changes to
// stake or commission are reflected in the following epoch. This is referenced
// by the reward system call *before* the epoch delay rounds.
mapping(uint64 => ValConsensus) val_consensus;

// Key(val_id)
// Contains a subset of the validator info relevant to consensus. Changes to
// stake or commission are reflected in the following epoch. This is referenced
// by the reward system call *during* the epoch delay rounds.
mapping(uint64 => ValConsensus) val_snapshot;

// Keys(val_id,msg.sender) => DelInfo
mapping(uint64 => mapping(address => DelInfo)) delegator;

// Keys(val_id,msg.sender,withdrawal_id) => WithdrawalRequest
mapping(uint64 => mapping(address => mapping (uint8 => WithdrawalRequest))) withdrawal;
```

## Solidity Staking Interface

*To copy to clipboard, click the button in the top right of the code block.*

```solidity theme={null}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.15;

interface IMonadStaking {
    function addValidator(
        bytes calldata payload,
        bytes calldata signedSecpMessage,
        bytes calldata signedBlsMessage
    ) external payable returns (uint64 validatorId);

    function delegate(
        uint64 validatorId
    ) external payable returns (bool success);

    function undelegate(
        uint64 validatorId,
        uint256 amount,
        uint8 withdrawId
    ) external returns (bool success);

    function compound(
        uint64 validatorId
    ) external returns (bool success);

    function withdraw(
        uint64 validatorId,
        uint8 withdrawId
    ) external returns (bool success);

    function claimRewards(
        uint64 validatorId
    ) external returns (bool success);

    function changeCommission(
        uint64 validatorId,
        uint256 commission
    ) external returns (bool success);

    function externalReward(
        uint64 validatorId
    ) external payable returns (bool success);


    function getValidator(
        uint64 validatorId
    ) external returns (
        address authAddress,
        uint64 flags,
        uint256 stake,
        uint256 accRewardPerToken,
        uint256 commission,
        uint256 unclaimedRewards,
        uint256 consensusStake,
        uint256 consensusCommission,
        uint256 snapshotStake,
        uint256 snapshotCommission,
        bytes memory secpPubkey,
        bytes memory blsPubkey
    );

    function getDelegator(
        uint64 validatorId,
        address delegator
    ) external returns (
        uint256 stake,
        uint256 accRewardPerToken,
        uint256 unclaimedRewards,
        uint256 deltaStake,
        uint256 nextDeltaStake,
        uint64 deltaEpoch,
        uint64 nextDeltaEpoch
    );

    function getWithdrawalRequest(
        uint64 validatorId,
        address delegator,
        uint8 withdrawId
    ) external returns (
        uint256 withdrawalAmount,
        uint256 accRewardPerToken,
        uint64 withdrawEpoch
    );

    function getConsensusValidatorSet(
        uint32 startIndex
    ) external returns (bool isDone, uint32 nextIndex, uint64[] memory valIds);

    function getSnapshotValidatorSet(
        uint32 startIndex
    ) external returns (bool isDone, uint32 nextIndex, uint64[] memory valIds);

    function getExecutionValidatorSet(
        uint32 startIndex
    ) external returns (bool isDone, uint32 nextIndex, uint64[] memory valIds);

    function getDelegations(
        address delegator,
        uint64 startValId
    ) external returns (bool isDone, uint64 nextValId, uint64[] memory valIds);

    function getDelegators(
        uint64 validatorId,
        address startDelegator
    ) external returns (bool isDone, address nextDelegator, address[] memory delegators);

    function getEpoch() external returns (uint64 epoch, bool inEpochDelayPeriod);

    function getProposerValId() external returns (uint64 val_id);

    function syscallOnEpochChange(uint64 epoch) external;

    function syscallReward(address blockAuthor) external;

    function syscallSnapshot() external;

     event ValidatorRewarded(
        uint64 indexed validatorId,
        address indexed from,
        uint256 amount,
        uint64 epoch
    );
    event ValidatorCreated(
        uint64  indexed validatorId,
        address indexed authAddress,
        uint256 commission

    );
    event ValidatorStatusChanged(
        uint64  indexed validatorId,
        uint64  flags
    );
    event Delegate(
        uint64  indexed validatorId,
        address indexed delegator,
        uint256 amount,
        uint64  activationEpoch
    );
    event Undelegate(
        uint64  indexed validatorId,
        address indexed delegator,
        uint8   withdrawId,
        uint256 amount,
        uint64  activationEpoch
    );
    event Withdraw(
        uint64 indexed validatorId,
        address indexed delegator,
        uint8   withdrawId,
        uint256 amount,
        uint64  withdrawEpoch
    );
    event ClaimRewards(
        uint64 indexed validatorId,
        address indexed delegator,
        uint256 amount,
        uint64  epoch
    );
    event CommissionChanged(
        uint64 indexed validatorId,
        uint256 oldCommission,
        uint256 newCommission
    );
    event EpochChanged(
        uint64 oldEpoch,
        uint64 newEpoch
    );
}
```

## Staking ABI JSON

*To copy to clipboard, click the button in the top right of the code block.*

```json theme={null}
[
  {"type":"function","name":"addValidator","inputs":[{"name":"payload","type":"bytes","internalType":"bytes"},{"name":"signedSecpMessage","type":"bytes","internalType":"bytes"},{"name":"signedBlsMessage","type":"bytes","internalType":"bytes"}],"outputs":[{"name":"validatorId","type":"uint64","internalType":"uint64"}],"stateMutability":"payable"},
  {"type":"function","name":"changeCommission","inputs":[{"name":"validatorId","type":"uint64","internalType":"uint64"},{"name":"commission","type":"uint256","internalType":"uint256"}],"outputs":[{"name":"success","type":"bool","internalType":"bool"}],"stateMutability":"nonpayable"},
  {"type":"function","name":"claimRewards","inputs":[{"name":"validatorId","type":"uint64","internalType":"uint64"}],"outputs":[{"name":"success","type":"bool","internalType":"bool"}],"stateMutability":"nonpayable"},
  {"type":"function","name":"compound","inputs":[{"name":"validatorId","type":"uint64","internalType":"uint64"}],"outputs":[{"name":"success","type":"bool","internalType":"bool"}],"stateMutability":"nonpayable"},
  {"type":"function","name":"delegate","inputs":[{"name":"validatorId","type":"uint64","internalType":"uint64"}],"outputs":[{"name":"success","type":"bool","internalType":"bool"}],"stateMutability":"payable"},
  {"type":"function","name":"externalReward","inputs":[{"name":"validatorId","type":"uint64","internalType":"uint64"}],"outputs":[{"name":"success","type":"bool","internalType":"bool"}],"stateMutability":"payable"},
  {"type":"function","name":"getConsensusValidatorSet","inputs":[{"name":"startIndex","type":"uint32","internalType":"uint32"}],"outputs":[{"name":"isDone","type":"bool","internalType":"bool"},{"name":"nextIndex","type":"uint32","internalType":"uint32"},{"name":"valIds","type":"uint64[]","internalType":"uint64[]"}],"stateMutability":"nonpayable"},
  {"type":"function","name":"getDelegations","inputs":[{"name":"delegator","type":"address","internalType":"address"},{"name":"startValId","type":"uint64","internalType":"uint64"}],"outputs":[{"name":"isDone","type":"bool","internalType":"bool"},{"name":"nextValId","type":"uint64","internalType":"uint64"},{"name":"valIds","type":"uint64[]","internalType":"uint64[]"}],"stateMutability":"nonpayable"},
  {"type":"function","name":"getDelegator","inputs":[{"name":"validatorId","type":"uint64","internalType":"uint64"},{"name":"delegator","type":"address","internalType":"address"}],"outputs":[{"name":"stake","type":"uint256","internalType":"uint256"},{"name":"accRewardPerToken","type":"uint256","internalType":"uint256"},{"name":"unclaimedRewards","type":"uint256","internalType":"uint256"},{"name":"deltaStake","type":"uint256","internalType":"uint256"},{"name":"nextDeltaStake","type":"uint256","internalType":"uint256"},{"name":"deltaEpoch","type":"uint64","internalType":"uint64"},{"name":"nextDeltaEpoch","type":"uint64","internalType":"uint64"}],"stateMutability":"nonpayable"},
  {"type":"function","name":"getDelegators","inputs":[{"name":"validatorId","type":"uint64","internalType":"uint64"},{"name":"startDelegator","type":"address","internalType":"address"}],"outputs":[{"name":"isDone","type":"bool","internalType":"bool"},{"name":"nextDelegator","type":"address","internalType":"address"},{"name":"delegators","type":"address[]","internalType":"address[]"}],"stateMutability":"nonpayable"},
  {"type":"function","name":"getEpoch","inputs":[],"outputs":[{"name":"epoch","type":"uint64","internalType":"uint64"},{"name":"inEpochDelayPeriod","type":"bool","internalType":"bool"}],"stateMutability":"nonpayable"},
  {"type":"function","name":"getProposerValId","inputs":[],"outputs":[{"name":"val_id","type":"uint64","internalType": "uint64"}],
  "stateMutability":"nonpayable"},
  {"type":"function","name":"getExecutionValidatorSet","inputs":[{"name":"startIndex","type":"uint32","internalType":"uint32"}],"outputs":[{"name":"isDone","type":"bool","internalType":"bool"},{"name":"nextIndex","type":"uint32","internalType":"uint32"},{"name":"valIds","type":"uint64[]","internalType":"uint64[]"}],"stateMutability":"nonpayable"},
  {"type":"function","name":"getSnapshotValidatorSet","inputs":[{"name":"startIndex","type":"uint32","internalType":"uint32"}],"outputs":[{"name":"isDone","type":"bool","internalType":"bool"},{"name":"nextIndex","type":"uint32","internalType":"uint32"},{"name":"valIds","type":"uint64[]","internalType":"uint64[]"}],"stateMutability":"nonpayable"},
  {"type":"function","name":"getValidator","inputs":[{"name":"validatorId","type":"uint64","internalType":"uint64"}],"outputs":[{"name":"authAddress","type":"address","internalType":"address"},{"name":"flags","type":"uint64","internalType":"uint64"},{"name":"stake","type":"uint256","internalType":"uint256"},{"name":"accRewardPerToken","type":"uint256","internalType":"uint256"},{"name":"commission","type":"uint256","internalType":"uint256"},{"name":"unclaimedRewards","type":"uint256","internalType":"uint256"},{"name":"consensusStake","type":"uint256","internalType":"uint256"},{"name":"consensusCommission","type":"uint256","internalType":"uint256"},{"name":"snapshotStake","type":"uint256","internalType":"uint256"},{"name":"snapshotCommission","type":"uint256","internalType":"uint256"},{"name":"secpPubkey","type":"bytes","internalType":"bytes"},{"name":"blsPubkey","type":"bytes","internalType":"bytes"}],"stateMutability":"nonpayable"},
  {"type":"function","name":"getWithdrawalRequest","inputs":[{"name":"validatorId","type":"uint64","internalType":"uint64"},{"name":"delegator","type":"address","internalType":"address"},{"name":"withdrawId","type":"uint8","internalType":"uint8"}],"outputs":[{"name":"withdrawalAmount","type":"uint256","internalType":"uint256"},{"name":"accRewardPerToken","type":"uint256","internalType":"uint256"},{"name":"withdrawEpoch","type":"uint64","internalType":"uint64"}],"stateMutability":"nonpayable"},
  {"type":"function","name":"syscallOnEpochChange","inputs":[{"name":"epoch","type":"uint64","internalType":"uint64"}],"outputs":[],"stateMutability":"nonpayable"},
  {"type":"function","name":"syscallReward","inputs":[{"name":"blockAuthor","type":"address","internalType":"address"}],"outputs":[],"stateMutability":"nonpayable"},
  {"type":"function","name":"syscallSnapshot","inputs":[],"outputs":[],"stateMutability":"nonpayable"},
  {"type":"function","name":"undelegate","inputs":[{"name":"validatorId","type":"uint64","internalType":"uint64"},{"name":"amount","type":"uint256","internalType":"uint256"},{"name":"withdrawId","type":"uint8","internalType":"uint8"}],"outputs":[{"name":"success","type":"bool","internalType":"bool"}],"stateMutability":"nonpayable"},
  {"type":"function","name":"withdraw","inputs":[{"name":"validatorId","type":"uint64","internalType":"uint64"},{"name":"withdrawId","type":"uint8","internalType":"uint8"}],"outputs":[{"name":"success","type":"bool","internalType":"bool"}],"stateMutability":"nonpayable"},
  {"type":"event","name":"ClaimRewards","inputs":[{"name":"validatorId","type":"uint64","indexed":true,"internalType":"uint64"},{"name":"delegator","type":"address","indexed":true,"internalType":"address"},{"name":"amount","type":"uint256","indexed":false,"internalType":"uint256"},{"name":"epoch","type":"uint64","indexed":false,"internalType":"uint64"}],"anonymous":false},
  {"type":"event","name":"CommissionChanged","inputs":[{"name":"validatorId","type":"uint64","indexed":true,"internalType":"uint64"},{"name":"oldCommission","type":"uint256","indexed":false,"internalType":"uint256"},{"name":"newCommission","type":"uint256","indexed":false,"internalType":"uint256"}],"anonymous":false},
  {"type":"event","name":"Delegate","inputs":[{"name":"validatorId","type":"uint64","indexed":true,"internalType":"uint64"},{"name":"delegator","type":"address","indexed":true,"internalType":"address"},{"name":"amount","type":"uint256","indexed":false,"internalType":"uint256"},{"name":"activationEpoch","type":"uint64","indexed":false,"internalType":"uint64"}],"anonymous":false},
  {"type":"event","name":"EpochChanged","inputs":[{"name":"oldEpoch","type":"uint64","indexed":false,"internalType":"uint64"},{"name":"newEpoch","type":"uint64","indexed":false,"internalType":"uint64"}],"anonymous":false},
  {"type":"event","name":"Undelegate","inputs":[{"name":"validatorId","type":"uint64","indexed":true,"internalType":"uint64"},{"name":"delegator","type":"address","indexed":true,"internalType":"address"},{"name":"withdrawId","type":"uint8","indexed":false,"internalType":"uint8"},{"name":"amount","type":"uint256","indexed":false,"internalType":"uint256"},{"name":"activationEpoch","type":"uint64","indexed":false,"internalType":"uint64"}],"anonymous":false},
  {"type":"event","name":"ValidatorCreated","inputs":[{"name":"validatorId","type":"uint64","indexed":true,"internalType":"uint64"},{"name":"authAddress","type":"address","indexed":true,"internalType":"address"},{"name":"commission","type":"uint256","indexed":false,"internalType":"uint256"}],"anonymous":false},
  {"type":"event","name":"ValidatorRewarded","inputs":[{"name":"validatorId","type":"uint64","indexed":true,"internalType":"uint64"},{"name":"from","type":"address","indexed":true,"internalType":"address"},{"name":"amount","type":"uint256","indexed":false,"internalType":"uint256"},{"name":"epoch","type":"uint64","indexed":false,"internalType":"uint64"}],"anonymous":false},
  {"type":"event","name":"ValidatorStatusChanged","inputs":[{"name":"validatorId","type":"uint64","indexed":true,"internalType":"uint64"},{"name":"flags","type":"uint64","indexed":false,"internalType":"uint64"}],"anonymous":false},
  {"type":"event","name":"Withdraw","inputs":[{"name":"validatorId","type":"uint64","indexed":true,"internalType":"uint64"},{"name":"delegator","type":"address","indexed":true,"internalType":"address"},{"name":"withdrawId","type":"uint8","indexed":false,"internalType":"uint8"},{"name":"amount","type":"uint256","indexed":false,"internalType":"uint256"},{"name":"withdrawEpoch","type":"uint64","indexed":false,"internalType":"uint64"}],"anonymous":false}
]
```

## FAQ

<Accordion title="Is there a `removeValidator` function?">
  There is no direct `removeValidator` function. Instead, if a validator's `auth_account` removes
  enough stake through [`undelegate`](#undelegate), the validator is removed from the consensus set
  in a future epoch.

  This occurs in either epoch `n+1` or epoch `n+2`, depending on whether the `undelegate`
  occurred within the epoch delay rounds.

  Even when not active, a validator's information is always retained. Validator ids are permanent since
  other delegators may still be delegating and need to reference that `val_id` to undelegate/withdraw.
</Accordion>

<Accordion title="How does a validator change their `commission`?">
  A validator can change their `commission` by calling [`changeCommission`](#changecommission).
</Accordion>

<Accordion title="Which functions give visibility into the list of validator ids?">
  See the [valset getters](#getvalidatorset).
</Accordion>

<Accordion title="Which functions give visibility into a validator's state?">
  See [`getValidator`](#getvalidator).
</Accordion>

<Accordion title="Which functions give visibility into a delegator's delegation to one particular validator?">
  See [`getDelegator`](#getdelegator).

  For pending withdrawals by that delegator from that validator, see [`getWithdrawalRequest`](#getwithdrawalrequest).
</Accordion>

<Accordion title="Is it more like a contract or a precompile?">
  Despite using Solidity selectors and ABI, it is a precompile. Accessing code at <CopyToClipboard>`0x0000000000000000000000000000000000001000`</CopyToClipboard>
  returns empty code. Its account is always accessed warm, and calls with invalid arguments consume all gas.

  Exception: if an account attempts to delegate to the staking precompile using
  [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702), all calls to it will revert.
</Accordion>


# Staking Overview
Source: https://docs.monad.xyz/reference/staking/overview

How to interact with Monad's staking system

Monad uses a [precompile](/developer-essentials/precompiles) to manage validator delegation and rewards.

This page covers the key concepts and workflows for interacting with the staking precompile. For the full interface reference, visit the [API](/reference/staking/api) page. To learn how Monad's staking system works, visit the [learn](/monad-arch/consensus/staking) tab.

The staking precompile is at address <CopyToClipboard>`0x1000`</CopyToClipboard>.

## Key concepts

### Epochs and timing

Staking state changes don't take effect immediately. Monad divides time into **epochs**, and most actions only activate at the start of a new epoch.

Every 50,000 blocks (\~5.5 hours) is a **boundary block** that commits upcoming staking changes. After a 5,000-round delay (`EPOCH_DELAY_ROUNDS`), the new epoch starts.

<img alt="timeline showing the placement of boundary blocks within an epoch" />

This means your action activates in either:

* **Epoch n+1** — if submitted before the boundary block
* **Epoch n+2** — if submitted after the boundary block (in the epoch delay period)

Use [`getEpoch()`](/reference/staking/api#getepoch) to check the current epoch and whether the boundary has passed:

```solidity theme={null}
(uint64 epoch, bool inEpochDelayPeriod) = IMonadStaking(STAKING_ADDRESS).getEpoch();
// If inEpochDelayPeriod is false: changes take effect in epoch + 1
// If inEpochDelayPeriod is true:  changes take effect in epoch + 2
```

<Note>
  A round is not a block — rounds increment even on missed proposals. You cannot calculate epoch boundaries with modular arithmetic on block numbers. Always use `getEpoch()`.
</Note>

### Withdrawal delay

Undelegated stake is not immediately available. After calling `undelegate`, you must wait `WITHDRAWAL_DELAY` (1 epoch) before calling `withdraw` to reclaim the funds.

## Common actions

### Delegate

To delegate MON to a validator, call `delegate(validatorId)` with the amount as `msg.value`:

```solidity theme={null}
IMonadStaking(STAKING_ADDRESS).delegate{value: amount}(validatorId);
```

* `msg.value` must be at least `DUST_THRESHOLD` (1 gwei).
* Your delegation becomes active in the next epoch (or the one after, if past the boundary block).
* If this causes the validator's total stake to meet `ACTIVE_VALIDATOR_STAKE`, the validator is added to the active set.

### Undelegate and withdraw

Removing stake is a two-step process:

**Step 1: Undelegate** — Initiate the withdrawal by specifying the amount and a `withdrawId` (0–255):

```solidity theme={null}
IMonadStaking(STAKING_ADDRESS).undelegate(validatorId, amount, withdrawId);
```

**Step 2: Withdraw** — After `WITHDRAWAL_DELAY` epochs have passed, call `withdraw` to reclaim the funds:

```solidity theme={null}
IMonadStaking(STAKING_ADDRESS).withdraw(validatorId, withdrawId);
```

<img alt="timeline of undelegation and withdrawal" />

<p>Timeline of withdrawability of stake relative to <code>undelegate</code></p>

* You can only undelegate **active** stake (not pending delegations).
* Each `(validator, delegator)` pair supports up to 256 concurrent withdrawal requests.
* `withdrawId`s can be reused after the withdrawal completes.

### Claim and compound rewards

Rewards accumulate automatically as your validator produces blocks. You have two options:

* **Claim rewards** — withdraw accumulated rewards to your account:
  ```solidity theme={null}
  IMonadStaking(STAKING_ADDRESS).claimRewards(validatorId);
  ```
  Claims take effect **immediately** — no epoch delay.

* **Compound rewards** — re-delegate accumulated rewards, increasing your stake:
  ```solidity theme={null}
  IMonadStaking(STAKING_ADDRESS).compound(validatorId);
  ```
  Compounded rewards activate in the next epoch (following the standard timing rules).

### Query staking state

Key view methods for reading staking state:

| Method                                                                                                  | Purpose                                                                  |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [`getValidator(validatorId)`](/reference/staking/api#getvalidator)                                      | Full validator state across execution, consensus, and snapshot views     |
| [`getDelegator(validatorId, address)`](/reference/staking/api#getdelegator)                             | Delegator's stake, rewards, and pending changes for a specific validator |
| [`getWithdrawalRequest(validatorId, address, withdrawId)`](/reference/staking/api#getwithdrawalrequest) | Status of a pending withdrawal                                           |
| [`getEpoch()`](/reference/staking/api#getepoch)                                                         | Current epoch and whether boundary has passed                            |
| [`getConsensusValidatorSet(startIndex)`](/reference/staking/api#getvalidatorset)                        | Current epoch's leader validators (paginated)                            |
| [`getSnapshotValidatorSet(startIndex)`](/reference/staking/api#getvalidatorset)                         | Next epoch's leader validators (paginated)                               |
| [`getExecutionValidatorSet(startIndex)`](/reference/staking/api#getvalidatorset)                        | All validators meeting active staking criteria (paginated)               |
| [`getProposerValId()`](/reference/staking/api#getproposervalid)                                         | Validator ID of the current block's proposer                             |
| [`getDelegations(address, startValId)`](/reference/staking/api#getdelegations)                          | All validators a delegator has delegated to (paginated)                  |
| [`getDelegators(validatorId, startDelegator)`](/reference/staking/api#getdelegators)                    | All delegators for a validator (paginated)                               |

Paginated methods return up to 100 results per call. Pass `startIndex = 0` for the first call, then use `nextIndex` for subsequent calls until `isDone` is true.

## Constraints

Because the staking system is a precompile rather than a smart contract, it has some behavioral differences.

* **Only `CALL` is allowed.** `STATICCALL`, `DELEGATECALL`, and `CALLCODE` will revert. This means all view methods use `nonpayable` state mutability rather than `view`.
* **No forked environment testing.** The staking system is a precompile, not a smart contract — there is no code at the address, so forked testing environments won't work.
* **Boundary block timing.** Actions submitted during the epoch delay period (after the boundary block) won't take effect until two epochs later. Check `getEpoch()` if timing matters.
* **Dust threshold.** Delegations below `DUST_THRESHOLD` (1 gwei) will revert.
* **EIP-7702 caveat.** If an account delegates to the staking precompile address using EIP-7702, all calls to it will revert.

## Further reading

* [API reference](/reference/staking/api) — Full reference for the staking precompile with method signatures, parameters, gas costs, events, structs, and ABI
* [How staking works](/monad-arch/consensus/staking) — How Monad's staking system determines validator voting weights, epoch scheduling, and reward distribution


# How to generate user specific images in the Farcaster Mini App
Source: https://docs.monad.xyz/templates/farcaster-miniapp/generating-custom-og-images



Creating shareable moments in the Farcaster Mini App is a great way to engage with your users.

You can generate custom shareable user specific images in the Farcaster Mini App and make it easy for the user to share them!

<img alt="Example" />

In this guide we setup a dedicated endpoint `/api/og` for generating images and we use `@vercel/og` package to generate the images.

## Generating images

If you are using the [Monad Mini App template](https://github.com/monad-developers/monad-miniapp-template), you can simply
edit [`app/api/og/route.tsx`](https://github.com/monad-developers/monad-miniapp-template/blob/main/app/api/og/route.tsx)
to generate images of your choice.

```ts lines title="app/api/og/route.tsx" theme={null}
...

export async function GET(request: NextRequest) {
  try {
    const { searchParams } = new URL(request.url);

    // The below is dependent on whether the username and image are passed as query params or not.
    const username = searchParams.get('username') || 'User'; // Username of the user
    const imageUrl = searchParams.get('image') || ''; // Image url of the user
    
    const backgroundGradient = '#2D1B69'; // Background color of the image
    
    // Load Inter font from the public folder
    const interFontData = await fetch(
      `${request.nextUrl.origin}/Inter.ttf`
    ).then((res) => res.arrayBuffer());
    
    return new ImageResponse(
    (
        // Generate the image here
    );
  } catch (e) {
    console.error('Error generating OG image:', e);
    return new Response('Failed to generate image', { status: 500 });
  }
}

...
```

If you are not using the template, you need to install `@vercel/og` package.

```bash theme={null}
npm install @vercel/og
```

Create a new file `app/api/og/route.tsx`, if you are using Next.js 14 or higher.

```ts lines title="app/api/og/route.tsx" theme={null}
import { ImageResponse } from '@vercel/og';
import { NextRequest } from 'next/server';

// Generate the image for every request
export const dynamic = "force-dynamic";

export async function GET(request: NextRequest) {
  try {
    const { searchParams } = new URL(request.url);
    
    // The below is dependent on whether the username and image are passed as query params or not.
    const username = searchParams.get('username') || 'User'; // Username of the user
    const imageUrl = searchParams.get('image') || ''; // Image url of the user
    
    return new ImageResponse(
    (
        // Generate the image here
    );
  } catch (e) {
    console.error('Error generating OG image:', e);
    return new Response('Failed to generate image', { status: 500 });
  }
}
```

If you are not using Next.js, you can setup an endpoint or dedicated microservice to generate the images.

## Sharing images via the Mini App

<img alt="Example from EGGS Mini App, prompting the user to cast a custom generated image" />

Add shareable elements to your Mini App, so the user can share the generated images via the Mini App.

Below is an example of a button that can be used to generate and share a custom image:

```tsx lines theme={null}
export default function GenerateAndShareCustomImage() {

...

    const handleGenerateCustomOGImage = () => {
        // Generate the image using the endpoint
        const ogImageUrl = `${APP_URL}/api/og?username=${username}&image=${pfpUrl}`;

        // Programmatically compose a cast with the generated image
        actions?.composeCast({
            // Text to be displayed in the cast
            text: "I generated a custom OG image using Monad Mini App template", 
            // Image to be displayed in the cast
            embeds: [ogImageUrl],
        });
    };

...

    return (
        <button
            type="button"
            className="bg-white text-black rounded-md p-2 text-sm"
            /**
             * When the button is clicked, the shareable image is generated 
             * and the cast is composed.
            */
            onClick={() => handleGenerateCustomOGImage()}
            disabled={!fid}
        >
            Generate Custom Image
        </button>
    );

}
```


# How to build a Farcaster Mini App
Source: https://docs.monad.xyz/templates/farcaster-miniapp/getting-started



In this guide, you will learn how to use the [Monad Farcaster Mini App Template](https://github.com/monad-developers/monad-miniapp-template) to build apps.

The template demonstrates all Mini App capabilities and lets you easily modify it, so you can build Mini Apps.

## Cloning the Template

You can the following command to clone the Mini App template to your local machine:

```bash theme={null}
git clone https://github.com/monad-developers/monad-miniapp-template.git
```

### Install the dependencies

```bash theme={null}
yarn
```

### Copy `.env.example` over to `.env.local`

```bash theme={null}
cp .env.example .env.local
```

### Run the template

```bash theme={null}
yarn run dev
```

### View the App in Farcaster Embed tool

Farcaster has a neat [Embed tool](https://farcaster.xyz/~/developers/mini-apps/embed) that you can use to inspect the Mini App before you publish it.

Unfortunately, the embed tool can only work with remote URL. Inputting a localhost URL does not work.

As a workaround, you may make the local app accessible remotely using a tool like `cloudflared` or `ngrok`. In this guide we will use `cloudflared`.

#### Install Cloudflared

```bash theme={null}
brew install cloudflared
```

For more installation options see the [official docs](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/).

#### Expose localhost

Run the following command in your terminal:

```bash theme={null}
cloudflared tunnel --url http://localhost:3000
```

Be sure to specify the correct port for your local server.

#### Set `NEXT_PUBLIC_URL` environment variable in `.env.local` file

```bash theme={null}
NEXT_PUBLIC_URL=<url-from-cloudflared-or-ngrok>
```

#### Use the provided url

`cloudflared` will generate a random subdomain and print it in the terminal for you to use. Any traffic to this URL will get sent to your local server.

Enter the provided URL in the [Farcaster Embed tool](https://farcaster.xyz/~/developers/mini-apps/embed).

<img alt="embed-tool" />

Let's investigate the various components of the template.

## Customizing the Mini App Embed

Mini App Embed is how the Mini App shows up in the feed or in a chat conversation when the URL of the app is shared.

The Mini App Embed looks like this:

<img alt="embed-preview" />

You can customize this by editing the file `app/page.tsx`:

```js lines title="app/page.tsx" theme={null}
...

const appUrl = env.NEXT_PUBLIC_URL;

const frame = {
  version: "next",
  imageUrl: `${appUrl}/images/feed.png`, // Embed image URL (3:2 image ratio)
  button: {
    title: "Template", // Text on the embed button
    action: {
      type: "launch_frame",
      name: "Monad Farcaster Mini App Template",
      url: appUrl, // URL that is opened when the embed button is tapped or clicked.
      splashImageUrl: `${appUrl}/images/splash.png`,
      splashBackgroundColor: "#f7f7f7",
    },
  },
};

...
```

You can either edit the URLs for the images or replace the images in `public/images` folder in the template.

Once you are happy with the changes, click `Refetch` in the Embed tool to get the latest configuration.

<Note>
  If you are developing locally, ensure that your Next.js app is running locally and the cloudflare tunnel is open.
</Note>

## Customizing the Splash Screen

Upon opening the Mini App, the first thing the user will see is the Splash screen:

<img alt="splash-screen" />

You can edit the `app/page.tsx` file to customize the Splash screen.

```js lines title="app/page.tsx" theme={null}
...

const appUrl = env.NEXT_PUBLIC_URL;

const frame = {
  version: "next",
  imageUrl: `${appUrl}/images/feed.png`,
  button: {
    title: "Launch Template",
    action: {
      type: "launch_frame",
      name: "Monad Farcaster Mini App Template",
      url: appUrl,
      splashImageUrl: `${appUrl}/images/splash.png`, // App icon in the splash screen (200px * 200px)
      splashBackgroundColor: "#f7f7f7", // Splash screen background color
    },
  },
};

...
```

For `splashImageUrl`, you can either change the URL or replace the image in `public/images` folder in the template.

## Modifying the Mini App

Upon opening the template Mini App, you should see a screen like this:

<img alt="miniapp" />

The code for this screen is in the `components/pages/app.tsx` file:

```tsx lines title="components/pages/app.tsx" theme={null}
export default function Home() {
  const { context } = useMiniAppContext();
  return (
    // SafeAreaContainer component makes sure that the app margins are rendered properly depending on which client is being used.
    <SafeAreaContainer insets={context?.client.safeAreaInsets}>
      {/* You replace the Demo component with your home component */}
      <Demo />
    </SafeAreaContainer>
  )
}
```

You can remove or edit the code in this file to build your Mini App.

### Accessing User Context

<img alt="user-context" />

Your Mini App receives various information about the user, including `username`, `fid`, `displayName`, `pfpUrl` and other fields.

The template provides a helpful hook `useMiniAppContext` that you can use to access these fields:

```js lines title="components/Home/User.tsx" theme={null}
export function User() {
    const { context } = useMiniAppContext();
    return <p>{context.user.username}</p>
}
```

The template also provide an example of the same in `components/Home/User.tsx` file.

You can learn more about Context [here](https://miniapps.farcaster.xyz/docs/sdk/context).

### Performing App Actions

<img />

Mini Apps have the capability to perform native actions that enhance the user experience!

Actions like:

* `addFrame`: Allows the user to save (bookmark) the app in a dedicated section
* `composeCast`: Allows the Mini App to prompt the user to cast with prefilled text and media
* `viewProfile`: Presents a profile of a Farcaster user in a client native UI

Learn more about Mini App actions [here](https://miniapps.farcaster.xyz/docs/sdk/actions/add-frame)

The template provides an easy way to access the actions via the `useMiniAppContext` hook!

```js title="components/Home/FarcasterActions.tsx" theme={null}
const { actions } = useMiniAppContext();
```

An example for the same can be found in `components/Home/FarcasterActions.tsx` file.

### Prompting Wallet Actions

<img alt="wallet-actions" />

Every user of Farcaster has a Farcaster wallet with Monad Testnet support.

**Mini Apps can prompt the user to perform onchain actions**!

The template provides an example for the same in `components/Home/WalletActions.tsx` file.

```js lines title="components/Home/WalletActions.tsx" theme={null}
export function WalletActions() {
    ...

    async function sendTransactionHandler() {
        sendTransaction({
            to: "0x7f748f154B6D180D35fA12460C7E4C631e28A9d7",
            value: parseEther("1"),
        });
    }

    ...
}
```

<Warning>
  The Farcaster wallet supports multiple networks. It is recommended that you ensure that the right network is connected before prompting wallet actions.

  You can use viem's `switchChain` or equivalent to prompt a chain switch.

  ```js title="components/Home/WalletActions.tsx" theme={null}
  // Switching to Monad Testnet
  switchChain({ chainId: 10143 });
  ```

  The template has an example for the same in the `components/Home/WalletActions.tsx` file.
</Warning>

## Conclusion

In this guide, you explored Farcaster Mini Apps — the simplest way to create engaging, high-retention, and easily monetizable applications!

You also discovered the key capabilities of Mini Apps and how you can use the [Monad Farcaster Mini App Template](https://github.com/monad-developers/monad-miniapp-template) to build your own.

For more details, check out the official Mini App documentation [here](https://miniapps.farcaster.xyz/).

### Explore more Farcaster Mini App guides

<CardGroup>
  <Card title="Sending Notifications" href="/templates/farcaster-miniapp/sending-notifications" />

  <Card title="Generating custom shareable images" href="/templates/farcaster-miniapp/generating-custom-og-images" />

  <Card title="Publishing Mini App" href="/templates/farcaster-miniapp/publishing-miniapp" />
</CardGroup>


# How to add haptics to a Farcaster Mini App
Source: https://docs.monad.xyz/templates/farcaster-miniapp/haptics



Haptics are a way to add tactile feedback to your app to enhance user interaction and responsiveness.

This guide walks you through implementing haptics in a Farcaster Mini App for a more intuitive and engaging user experience.

## Implementing haptics in a Farcaster Mini App

If you are using the [Monad Mini App template](https://github.com/monad-developers/monad-miniapp-template/tree/main), you can use `haptics` from the [useFrame](https://github.com/monad-developers/monad-miniapp-template/blob/main/components/farcaster-provider.tsx) hook.

If you are not using the Monad Mini App template, you can inspect the [useFrame](https://github.com/monad-developers/monad-miniapp-template/blob/main/components/farcaster-provider.tsx) hook to check out the implementation details.

Below is an example of how to implement haptics in a Farcaster Mini App:

```tsx theme={null}
...

export default function MyComponent() {
  const { haptics } = useFrame();

  return (
    <div>
      <button onClick={() => haptics.impactOccurred('light')}>Light Impact</button>
    </div>
  );
}
```

## Supported haptics

The following haptics are supported:

| Haptic Type          | Code                                      |
| -------------------- | ----------------------------------------- |
| Light Impact         | `haptics.impactOccurred('light')`         |
| Medium Impact        | `haptics.impactOccurred('medium')`        |
| Heavy Impact         | `haptics.impactOccurred('heavy')`         |
| Soft Impact          | `haptics.impactOccurred('soft')`          |
| Rigid Impact         | `haptics.impactOccurred('rigid')`         |
| Success Notification | `haptics.notificationOccurred('success')` |
| Warning Notification | `haptics.notificationOccurred('warning')` |
| Error Notification   | `haptics.notificationOccurred('error')`   |
| Selection Change     | `haptics.selectionChanged()`              |


# Farcaster Mini Apps
Source: https://docs.monad.xyz/templates/farcaster-miniapp/index



Mini Apps enable developers to distribute native-like apps to [Farcaster](https://www.farcaster.xyz/) users. Mini Apps are the easiest way to deliver engaging, high-retention, and easy-to-monetize applications!

Mini Apps are web apps built with HTML, CSS, and Javascript that can be discovered and used within [Farcaster](https://farcaster.xyz/).

## Guides

<CardGroup>
  <Card title="Getting Started" href="/templates/farcaster-miniapp/getting-started" />

  <Card title="Sending Notifications" href="/templates/farcaster-miniapp/sending-notifications" />

  <Card title="Publishing Mini App" href="/templates/farcaster-miniapp/publishing-miniapp" />

  <Card title="Generating custom shareable images" href="/templates/farcaster-miniapp/generating-custom-og-images" />

  <Card title="Haptics" href="/templates/farcaster-miniapp/haptics" />
</CardGroup>


# How to publish a Farcaster Mini App
Source: https://docs.monad.xyz/templates/farcaster-miniapp/publishing-miniapp



Publishing the Mini App makes it discoverable in the Farcaster app. However, the Mini App has to be hosted on a domain before it can be published.

Since Farcaster is a decentralized network with multiple clients, a standard has been adopted wherein the Farcaster clients look for the `farcaster.json` file on the Mini App hosted domain for information about the Mini App.

## Hosting the `farcaster.json` file

The `farcaster.json` has to be placed in `/.well-known/farcaster.json` endpoint.

If you are using the [Monad Mini App template](https://github.com/monad-developers/monad-miniapp-template/tree/main) you can edit the [farcaster.json](https://github.com/monad-developers/monad-miniapp-template/blob/main/app/.well-known/farcaster.json/route.ts) file with your app details before publishing the app!

If you are not using the template then you have to make sure you have a `farcaster.json` file hosted on your domain at `[domain]/.well-known/farcaster.json` endpoint.

```ts lines title="app/.well-known/farcaster.json/route.ts" theme={null}
...

const appUrl = process.env.NEXT_PUBLIC_URL;
const farcasterConfig = {
    // accountAssociation details are required to associate the published app with it's author
    // instructions on how to get these values are provided later in this guide.
    accountAssociation: {
        "header": "",
        "payload": "",
        "signature": ""
    },
    frame: {
        version: "1",
        name: "Monad Farcaster Mini App Template", // Name of your Mini App
        iconUrl: `${appUrl}/images/icon.png`, // Icon of the app in the app store
        homeUrl: `${appUrl}`, // Default launch URL
        imageUrl: `${appUrl}/images/feed.png`, // Default image to show if shared in a feed.
        screenshotUrls: [], // Visual previews of the app
        tags: ["monad", "farcaster", "miniapp", "template"], // Descriptive tags for search
        primaryCategory: "developer-tools",
        buttonTitle: "Launch Template",
        splashImageUrl: `${appUrl}/images/splash.png`, // URL of image to show on loading screen.	
        splashBackgroundColor: "#ffffff", // Hex color code to use on loading screen.
        webhookUrl: `${appUrl}/api/webhook` // Webhook url for notifications
    }
};

...
```

The above example is a partial representation of the `farcaster.json` file. The full reference for the [farcaster.json](https://github.com/monad-developers/monad-miniapp-template/blob/main/app/.well-known/farcaster.json/route.ts) file can be found [here](https://miniapps.farcaster.xyz/docs/guides/publishing#define-your-application-configuration).

## Generating `accountAssociation` using the Farcaster Mobile App.

The `accountAssociation` object in the [farcaster.json](https://github.com/monad-developers/monad-miniapp-template/blob/main/app/.well-known/farcaster.json/route.ts) file is used to associate the Mini App with the publisher's Farcaster account.

To generate the `accountAssociation` object you can use the Farcaster Mobile App.

Go to `Settings (under Developer) > Domains`, enter the domain where the Mini App is hosted and click `Generate Domain Manifest`.

<Accordion title="Can't see Developer options?">
  For the `Developer` options to be visible you will need to have `Developer mode` enabled in Farcaster.

  You can enable it by going to `Settings (under Profile and Account) > Advanced > scroll down and enable Developer mode`.

  <iframe title="YouTube video player" />
</Accordion>

The `accountAssociation` object will be generated it will be available in your clipboard you can then paste the values in the [farcaster.json](https://github.com/monad-developers/monad-miniapp-template/blob/main/app/.well-known/farcaster.json/route.ts) file.

```ts lines title="app/.well-known/farcaster.json/route.ts" theme={null}
...

const appUrl = process.env.NEXT_PUBLIC_URL;
const farcasterConfig = {
    accountAssociation: {
        header: "eyJmaWQiOjE3OTc5LCJ0eXBlIjoiY3VzdG9keSIsImtleSI6IjB4MGMxNWE5QkVmRTg3RjY0N0IwMDNhMjI0MTY4NDYwMzYyODQ0M2Y4YiJ9",
        payload: "eyJkb21haW4iOiJtb25hZC1taW5pYXBwLXRlbXBsYXRlLXNldmVuLnZlcmNlbC5hcHAifQ",
        signature: "MHgwYzY2NDdjZDhjOWJiY2JmYzg2NGIzZjVjYWVjY2ExMTdlOTY4ZGQwMWIzMmM0NGViMjU5ZDhlOGQyMzdhZTZiMDU1MmNmNWRiMDU1MDMwNTZmNTNhZmEwZDZlZTBlZmIyMmJmNDNmMDQ4NTdhMzk2NmY0YmMzODk2N2NlZDI5ZjFi"
    },
    ...
};

...
```

<iframe title="YouTube video player" />

You can find the `farcaster.json` file for Monad Mini App Template app [here](https://github.com/monad-developers/monad-miniapp-template/blob/main/app/.well-known/farcaster.json/route.ts).

Once the `farcaster.json` file is hosted, your Mini App is now discoverable in the Farcaster app, you can test it by searching for the Mini App in the Farcaster app!


# How to send notifications to users of the Farcaster Mini App
Source: https://docs.monad.xyz/templates/farcaster-miniapp/sending-notifications



This guide walks you through how you can send notifications to your Mini App users.

This guide uses [Monad Mini App template](https://github.com/monad-developers/monad-miniapp-template), which already has the code for sending notifications; all you have to do is modify a few lines of code.

If you aren't using the template, you can still follow the guide; feel free to copy code as needed from the template.

## Demo

If you want to try the Mini App notification experience, you can try the [Monad Mini App Template](https://farcaster.xyz/miniapps/ODHcbibktF7T/monad-farcaster-miniapp-template) app.

## Modifying the Mini App manifest

<Note>
  Mini App account association process has to be completed before the Mini App can send notifications.
</Note>

Mini Apps can send notifications to the user when:

* The user has added the Mini App and not disabled notifications manually
* The user has explicitly subscribed to notifications from the Mini App

Farcaster app or clients send events like `miniapp_added`, `miniapp_removed`, `notifications_disabled` and `notifications_enabled` to the Mini App's webhook endpoint, this allows the Mini App to keep track of which users the Mini App can send notifications to.

The `webhookUrl` has to be specified in the Mini App manifest file:

```ts title="app/.well-known/farcaster.json/route.ts" theme={null}
...

export async function GET() {
  const farcasterConfig = {
    // TODO: Add your own account association
    frame: {
        version: "1",
        name: "Monad Farcaster Mini App Template",
        ...
        splashBackgroundColor: "#ffffff",
        webhookUrl: `${APP_URL}/api/webhook`, // <--- Edit this
    },
};

...
```

If you are using the [Monad Mini App Template](https://github.com/monad-developers/monad-miniapp-template), you don't need to edit the `webhookUrl`.

## Processing Farcaster client events

The code for processing webhook events can be found in the file `/app/api/webhook/route.ts`.

### Verifying webhook events

Events are signed by the app key of a user with a [JSON Farcaster Signature](https://github.com/farcasterxyz/protocol/discussions/208). This allows Mini Apps to verify the Farcaster client that generated the notification and the Farcaster user they generated it for.

It is important to verify events in order to make sure the Mini App is correctly tracking which users it can send notifications to.

If you are using the [Monad Mini App template](https://github.com/monad-developers/monad-miniapp-template), the code for verifying events is already available in [`/app/api/webhook/route.ts`](https://github.com/monad-developers/monad-miniapp-template/blob/main/app/api/webhook/route.ts). If not, you can copy code from the same file.

<Info>
  A Neynar API key is required to verify webhook events. You can sign up to the [Neynar](https://neynar.com/) service and get an API key for free.

  Once done, add a environment variable named `NEYNAR_API_KEY` to your `.env` file.
</Info>

### Processing webhook payload

Once the `webhookUrl` is specified, Farcaster app and clients will send client events to the webhook endpoint.

The `miniapp_added` and `notifications_enabled` events are received by the Mini App along with `fid` and `notificationDetails`.

`notificationDetails` has a `url` and a `token` that can be used to send notifications to a specific Farcaster user.

Example of webhook payload:

```json theme={null}
{
    "fid": 17979,
    "event": {
        "event": "notifications_enabled",
        "notificationDetails": {
            "url": "https://api.farcaster.xyz/v1/frame-notifications",
            "token": "a05059ef2415c67b08ecceb539201cbc6"
        }
    }
}
```

You can find the code, handling the Farcaster client events in [`/app/api/webhook/route.ts`](https://github.com/monad-developers/monad-miniapp-template/blob/main/app/api/webhook/route.ts).

The Mini App can use any database service of choice to store the `url` and `token` and use it when sending notifications.

The [Monad Mini App template](https://github.com/monad-developers/monad-miniapp-template) uses [Upstash's Redis](https://console.upstash.com/redis) service for storing the `notificationDetails`, if you wish to use a different database you can modify it in [`/lib/kv.ts`](https://github.com/monad-developers/monad-miniapp-template/blob/main/lib/kv.ts).

<Note>
  Since the [Monad Mini App template](https://github.com/monad-developers/monad-miniapp-template) uses Redis for storing notification url and token, environment variables `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` are required in `.env`.

  Once you sign up for the [Upstash](https://console.upstash.com/redis) service and create a Redis database you will be able to get these environment variables.

  If you plan to use some other database, adjust environment variables accordingly.
</Note>

Example of storing notification details in Redis:

```ts title="/lib/kv.ts" theme={null}
...

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL,
  token: process.env.UPSTASH_REDIS_REST_TOKEN,
});

...

export async function setUserNotificationDetails(
    fid: number,
    notificationDetails: MiniAppNotificationDetails
): Promise<void> {
    // Modify lines that use redis to use your own database implementation
    await redis.set(getUserNotificationDetailsKey(fid), notificationDetails);  
}

...
```

## Sending notifications

<img alt="Example of a notification sent from a Farcaster Mini App" />

Once you have a notification token for a user, you can send them a notification by sending a `POST` request to the url associated with that token.

If you are using the [Monad Mini App template](https://github.com/monad-developers/monad-miniapp-template) the code for sending notification is already available in the file [`/app/api/send-notification/route.ts`](https://github.com/monad-developers/monad-miniapp-template/blob/main/app/api/send-notification/route.ts). If not, you can copy code from [`/lib/notifs.ts`](https://github.com/monad-developers/monad-miniapp-template/blob/main/lib/notifs.ts) and [`/app/api/send-notification/route.ts`](https://github.com/monad-developers/monad-miniapp-template/blob/main/app/api/send-notification/route.ts).

### Personalizing notification content

You can change a few lines of code in [`/app/api/send-notification/route.ts`](https://github.com/monad-developers/monad-miniapp-template/blob/main/app/api/send-notification/route.ts) file to personalize the notification:

```ts title="/app/api/send-notification/route.ts" theme={null}
...

// This function sends the notification
const sendResult = await sendFrameNotification({
    fid: requestBody.data.fid,
    // You can modify/personalize the below line to make the title of the notification dynamic based on the fid (user)
    title: "Test notification",
    // You can modify/personalize the below line to make the body of the notification dynamic based on the fid (user)
    body: "Sent at " + new Date().toISOString(),
});

...
```

<Warning>
  #### Notification Rate Limits

  The standard rate limits, which are enforced by Farcaster, are:

  * 1 notification per 30 seconds per token
  * 100 notifications per day per token
</Warning>

If you are using the [Monad Mini App template](https://github.com/monad-developers/monad-miniapp-template), you can send notifications from the server or the Mini App by making a `POST` to `/api/send-notification` endpoint!

That's all you need to send notifications to your Mini App users!


# How to use the Next.js Serwist 0x Privy embedded wallet template
Source: https://docs.monad.xyz/templates/next-serwist-0x-privy-embedded-wallet



This guide walks you through using the [template](https://github.com/monad-developers/next-serwist-privy-0x) which uses [Next.js](https://nextjs.org/docs), [Serwist](https://serwist.pages.dev/) (offline capabilities), [0x](https://0x.org/docs/) (token trading), and [Privy embedded wallet](https://docs.privy.io/wallets/wallets/create/create-a-wallet) (authentication) to build a Progressive Web Application (PWA) on Monad.

## Prerequisites

* [Node.js](https://nodejs.org/) (v18 or higher)
* a [Privy account](https://www.privy.io/)
* a [0x account](https://www.0x.org/)

<Accordion title="Setting up Privy">
  1. Create your Privy app:

     <img alt="Create your app" />

     Select "Web" as the platform. Then, click "Create app".

     <img alt="Name your app" />

     On the next screen, make sure to save your App ID.

  2. Set up login methods:

     <img alt="Set up login methods" />

  3. Disable External Wallets:

     <img alt="Disable external wallets" />

  4. Scroll down and enable "Automatically create embedded wallets on login" and select "EVM Wallets":

     <img alt="Create wallets automatically" />

  <Tip>
    You can enable "Test Accounts" for testing purposes.

    <img alt="Test accounts" />
  </Tip>
</Accordion>

<Accordion title="Setting up 0x">
  1. Create your 0x account:

     Go to [0x dashboard](https://dashboard.0x.org/create-account) and create your account.

     On the next screen, make sure to save your API Key.

  2. Get your API Key:

     To get your API key, create an app and then go to API Keys.

     Copy the API key and save it for later.
</Accordion>

## Setup

1. Clone the repository:

   ```bash theme={null}
   git clone https://github.com/monad-developers/next-serwist-privy-0x.git
   ```

2. `cd` into the project directory:

   ```bash theme={null}
   cd next-serwist-privy-0x
   ```

3. Install dependencies:

   ```bash theme={null}
   npm install
   ```

4. Create a `.env.local` file in the root directory:

   ```bash theme={null}
   cp .env.example .env.local
   ```

5. Start adding your environment variables to the `.env.local` file:

   ```bash theme={null}
   # Privy
   NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id_here
   NEXT_PUBLIC_PRIVY_CLIENT_ID= # optional, you can leave this empty

   # VAPID Keys for push notifications
   NEXT_PUBLIC_VAPID_PUBLIC_KEY=your_vapid_public_key_here
   VAPID_PRIVATE_KEY=your_vapid_private_key_here

   # 0x Configuration
   ZEROX_API_KEY=your_0x_api_key_here
   ```

   If you lost your Privy App ID, you can find it in the Privy dashboard.

6. Generate VAPID keys for web push notifications:

   ```bash theme={null}
   npx web-push generate-vapid-keys --json
   ```

   Copy the generated keys to your .env.local file (replace the placeholder values from step 5).

7. Running the Application:

   **Development Mode**:

   ```bash theme={null}
   npm run dev
   ```

   The application will be available at [http://localhost:3000](http://localhost:3000).

   **Production Mode**:

   For full PWA functionality (including install prompts):

   ```bash theme={null}
   npm run build && npm run start
   ```

## Folder structure of the template

```
next-serwist-privy-0x/
├── app/
│   ├── components/          # React components
│   │   ├── 0x/             # 0x Protocol integration
│   │   ├── InstallPWA.tsx  # PWA install prompt
│   │   ├── SwapComponent.tsx # Token swap interface
│   │   └── ...
│   ├── api/                # API routes
│   │   ├── price/          # Token price endpoints
│   │   └── quote/          # Swap quote endpoints
│   ├── ~offline/           # Offline page
│   └── ...
├── public/                 # Static assets
├── utils/                  # Utility functions
└── ...
```

## Changing the app name

* Edit [`public/manifest.json`](https://github.com/monad-developers/next-serwist-privy-0x/blob/main/public/manifest.json):
  * Change the `name` and `short_name` fields
* Run `npm run build` to update the app

## Notification Setup

<Warning title="Enable notifications for the best experience!">
  To receive push notifications from this app, you need to enable notifications in your browser and/or system settings:
</Warning>

### Browser Settings

<Accordion title="Chrome/Edge">
  1. Click the lock icon 🔒 in the address bar
  2. Set "Notifications" to "Allow"
  3. Or go to Settings → Privacy and security → Site Settings → Notifications
</Accordion>

<Accordion title="Firefox">
  1. Click the shield icon 🛡️ in the address bar
  2. Turn off "Enhanced Tracking Protection" for this site (if needed)
  3. Allow notifications when prompted
  4. Or go to Settings → Privacy & Security → Permissions → Notifications
</Accordion>

<Accordion title="Safari">
  1. Go to Safari → Settings → Websites → Notifications
  2. Find your site and set it to "Allow"
</Accordion>

### System Settings

<Accordion title="macOS">
  1. System Preferences → Notifications & Focus
  2. Find your browser and ensure notifications are enabled
  3. Check "Allow notifications from websites" in browser settings
</Accordion>

<Accordion title="Windows">
  1. Settings → System → Notifications & actions
  2. Ensure your browser can send notifications
  3. Check browser notification settings
</Accordion>

<Accordion title="iOS">
  1. Settings → Notifications → \[Your Browser]
  2. Enable "Allow Notifications"
  3. Also enable in browser settings
</Accordion>

<Accordion title="Android">
  1. Settings → Apps → \[Your Browser] → Notifications
  2. Enable notifications
  3. Check browser notification permissions
</Accordion>

### Backend Integration Required

<Info title="The [`SendNotification.tsx`](https://github.com/monad-developers/next-serwist-privy-0x/blob/main/app/components/SendNotification.tsx) component is sample code">
  This requires backend implementation:

  * **Save subscription data** when users subscribe (see TODO comments in code)
  * **Delete subscription data** when users unsubscribe
  * **Implement [`/notification` endpoint](https://github.com/monad-developers/next-serwist-privy-0x/blob/main/app/notification/route.ts)** to send actual push notifications
  * **Use `web-push` library** or similar for server-side notification delivery
</Info>

### Customizing Notification Content

To customize your push notification content, edit [`app/notification/route.ts`](https://github.com/monad-developers/next-serwist-privy-0x/blob/main/app/notification/route.ts) and modify the `title`, `message`, `icon`, and other properties in the `sendNotification` call.

## Modifying the App Icon & Splash Screen

### App Icons

Replace the icon files in the [`public/icons/`](https://github.com/monad-developers/next-serwist-privy-0x/tree/main/public/icons) directory with your custom icons:

* **`icon-512x512.png`** - Main app icon (512×512px)
* **`android-chrome-192x192.png`** - Android icon (192×192px)
* **`apple-touch-icon.png`** - iOS home screen icon (180×180px)

Also update the favicon:

* **[`public/favicon.ico`](https://github.com/monad-developers/next-serwist-privy-0x/blob/main/public/favicon.ico)** - Browser favicon
* **[`app/favicon.ico`](https://github.com/monad-developers/next-serwist-privy-0x/blob/main/app/favicon.ico)** - Next.js app favicon

### Splash Screen

Splash screens are automatically generated from your app icon and theme colors defined in [`manifest.json`](https://github.com/monad-developers/next-serwist-privy-0x/blob/main/public/manifest.json). To customize:

1. Update the `theme_color` and `background_color` in [`manifest.json`](https://github.com/monad-developers/next-serwist-privy-0x/blob/main/public/manifest.json)
2. Ensure your main icon (`icon-512x512.png`) represents your brand
3. Run `npm run build` to apply changes

<Tip>
  Use tools like [PWA Asset Generator](https://www.pwabuilder.com/imageGenerator) to create all required icon sizes from a single source image.
</Tip>

## Adding More Tokens

The template currently supports WMON and USDT tokens. To add more tokens for trading, follow these steps:

### 1. Find Token Information

Before adding a token, you'll need the following information:

* **Contract Address**: The token's smart contract address
* **Symbol**: The token's symbol (e.g., "ETH", "USDC")
* **Name**: The full name of the token
* **Decimals**: Number of decimal places (usually 18 for most ERC-20 tokens)
* **Logo URI**: URL to the token's logo image

You can find this information on the DEXes that 0x Swap API supports.

To get the DEXes that 0x Swap API supports, you can query the [sources](https://api.0x.org/sources) endpoint. For reference, see [getSources](https://0x.org/docs/api#tag/Sources/operation/sources::getSources) page.

### 2. Update Token Constants

Edit [`utils/constants.ts`](https://github.com/monad-developers/next-serwist-privy-0x/blob/main/utils/constants.ts) and add your new token to three places:

#### A. Add to MONAD\_TESTNET\_TOKENS array

```typescript title="utils/constants.ts" theme={null}
export const MONAD_TESTNET_TOKENS: Token[] = [
  // ... existing tokens ...
  {
    chainId: 1,
    name: "Your Token Name",
    symbol: "YOUR_SYMBOL",
    decimals: 18,
    address: "0xYourTokenContractAddress",
    logoURI: "https://your-token-logo-url.png",
  },
];
```

#### B. Add to MONAD\_TESTNET\_TOKENS\_BY\_SYMBOL record

```typescript title="utils/constants.ts" theme={null}
export const MONAD_TESTNET_TOKENS_BY_SYMBOL: Record<string, Token> = {
  // ... existing tokens ...
  your_symbol: {
    // lowercase key
    chainId: 1,
    name: "Your Token Name",
    symbol: "YOUR_SYMBOL",
    decimals: 18,
    address: "0xYourTokenContractAddress",
    logoURI: "https://your-token-logo-url.png",
  },
};
```

#### C. Add to MONAD\_TESTNET\_TOKENS\_BY\_ADDRESS record

```typescript title="utils/constants.ts" theme={null}
export const MONAD_TESTNET_TOKENS_BY_ADDRESS: Record<string, Token> = {
  // ... existing tokens ...
  "0xyourtokencontractaddress": {
    // lowercase address
    chainId: 1,
    name: "Your Token Name",
    symbol: "YOUR_SYMBOL",
    decimals: 18,
    address: "0xYourTokenContractAddress", // original case
    logoURI: "https://your-token-logo-url.png",
  },
};
```

### 3. Example: Adding shMON

Here's a complete example of adding USDC:

```typescript title="utils/constants.ts" theme={null}
// In MONAD_TESTNET_TOKENS array
{
  chainId: 1,
  name: "shMonad",
  symbol: "shMON",
  decimals: 18,
  address: "0x3a98250F98Dd388C211206983453837C8365BDc1",
  logoURI: "put_your_logo_url_here_or_use_the_default_logo",
},

// In MONAD_TESTNET_TOKENS_BY_SYMBOL record
shmon: {
  chainId: 1,
  name: "shMonad",
  symbol: "shMON",
  decimals: 18,
  address: "0x3a98250F98Dd388C211206983453837C8365BDc1",
  logoURI: "put_your_logo_url_here_or_use_the_default_logo",
},

// In MONAD_TESTNET_TOKENS_BY_ADDRESS record
"0x3a98250F98Dd388C211206983453837C8365BDc1": {
  chainId: 1,
  name: "shMonad",
  symbol: "shMON",
  decimals: 18,
  address: "0x3a98250F98Dd388C211206983453837C8365BDc1",
  logoURI: "put_your_logo_url_here_or_use_the_default_logo",
},
```

### 4. Important Notes

* **Decimals**: Most tokens use 18 decimals, but some (like USDT, USDC) use 6
* **Logo URLs**: Use permanent, reliable image URLs. Consider hosting logos yourself for better reliability
* **Testing**: Test thoroughly with small amounts before using in production
* **0x Protocol Support**: Ensure the token is supported by 0x Protocol for your target network

### 5. Rebuild and Test

After adding tokens:

```bash theme={null}
npm run build
npm run start
```

The new tokens will automatically appear in the token selector dropdowns in the swap interface.

## Configuring Slippage Tolerance

Slippage tolerance determines how much price movement you're willing to accept during a trade. The app currently uses the 0x API's default slippage tolerance of 1% (100 basis points).

### Adding Slippage Configuration

#### 1. Update Constants

Add slippage options to [`utils/constants.ts`](https://github.com/monad-developers/next-serwist-privy-0x/blob/main/utils/constants.ts):

```typescript title="utils/constants.ts" theme={null}
export const DEFAULT_SLIPPAGE_BPS = 100; // 1% in basis points

export const SLIPPAGE_OPTIONS = [
  { label: "0.1%", value: 10 },
  { label: "0.5%", value: 50 },
  { label: "1%", value: 100 },
  { label: "2%", value: 200 },
  { label: "3%", value: 300 },
];
```

#### 2. Update API Routes

Add `slippageBps` parameter to both API routes:

**[`app/api/price/route.ts`](https://github.com/monad-developers/next-serwist-privy-0x/blob/main/app/api/price/route.ts) and [`app/api/quote/route.ts`](https://github.com/monad-developers/next-serwist-privy-0x/blob/main/app/api/quote/route.ts):**

```typescript title="app/api/price/route.ts" theme={null}
export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;

  // Add default slippage if not provided
  if (!searchParams.has("slippageBps")) {
    searchParams.set("slippageBps", "100"); // 1% default
  }

  const res = await fetch(
    `https://api.0x.org/swap/permit2/price?${searchParams}`, // or /quote
    {
      headers: {
        "0x-api-key": process.env.ZEROX_API_KEY as string,
        "0x-version": "v2",
      },
    }
  );
  const data = await res.json();
  return Response.json(data);
}
```

#### 3. Add Slippage to Components

Update the price/quote requests to include `slippageBps` parameter:

**In [`app/components/0x/price.tsx`](https://github.com/monad-developers/next-serwist-privy-0x/blob/main/app/components/0x/price.tsx):**

```typescript title="app/components/0x/price.tsx" theme={null}
const [slippageBps, setSlippageBps] = useState(DEFAULT_SLIPPAGE_BPS);

// Add slippageBps to your API request parameters
const priceRequest = useMemo(
  () => ({
    chainId,
    sellToken: sellTokenObject.address,
    buyToken: buyTokenObject.address,
    sellAmount: parsedSellAmount,
    taker,
    slippageBps, // Add this
    // ... other params
  }),
  [...dependencies, slippageBps]
);
```

### Slippage Parameter Details

* **Range**: 0-10000 basis points (0%-100%)
* **Default**: 100 (1%)
* **Format**: Basis points (100 bps = 1%)

Reference: [0x API Documentation](https://0x.org/docs/api#tag/Swap/operation/swap::permit2::getPrice)

## Deploying to Vercel

### Using Vercel Dashboard

1. **Connect your repository**:

   * Push your code to GitHub
   * Visit [vercel.com](https://vercel.com) and import your repository

2. **Configure environment variables**:

   * In your Vercel project dashboard, go to Settings → Environment Variables
   * Add the same variables from your `.env.local`:
     ```
     NEXT_PUBLIC_PRIVY_APP_ID
     NEXT_PUBLIC_PRIVY_CLIENT_ID
     NEXT_PUBLIC_VAPID_PUBLIC_KEY
     VAPID_PRIVATE_KEY
     ZEROX_API_KEY
     ```

3. **Deploy**: Vercel will automatically build and deploy your app

4. **Update Privy settings**: In your Privy dashboard, add your Vercel domain (e.g., `your-app.vercel.app`) to the allowed origins

<Tip>
  PWA features (install prompts, offline support, push notifications) work automatically on HTTPS domains like Vercel deployments.
</Tip>

### Using Vercel CLI

Alternatively, deploy using the Vercel CLI:

1. **Install Vercel CLI**:

   ```bash theme={null}
   npm i -g vercel
   ```

2. **Login to Vercel**:

   ```bash theme={null}
   vercel login
   ```

3. **Deploy**:

   ```bash theme={null}
   vercel
   ```

   Follow the prompts to configure your project.

4. **Add environment variables**:

   ```bash theme={null}
   vercel env add NEXT_PUBLIC_PRIVY_APP_ID
   vercel env add NEXT_PUBLIC_PRIVY_CLIENT_ID
   vercel env add NEXT_PUBLIC_VAPID_PUBLIC_KEY
   vercel env add VAPID_PRIVATE_KEY
   vercel env add ZEROX_API_KEY
   ```

   Or you can go to the Vercel dashboard and add the environment variables there.

5. **Redeploy with environment variables**:
   ```bash theme={null}
   vercel --prod
   ```

## Learn more

* Serwist: [docs](https://serwist.pages.dev/) | [guides](https://serwist.pages.dev/docs/next/getting-started)
* Privy: [create a wallet](https://docs.privy.io/wallets/wallets/create/create-a-wallet) | [send a transaction](https://docs.privy.io/wallets/using-wallets/ethereum/send-a-transaction) | [sign a transaction](https://docs.privy.io/wallets/using-wallets/ethereum/sign-a-transaction)
* 0x: [docs](https://docs.0x.org/) | [guides](https://0x.org/docs/0x-swap-api/guides/swap-tokens-with-0x-swap-api)
* Monad: [supported tooling and infra](/tooling-and-infra)


# How to use the Next.js PWA Privy embedded wallet template
Source: https://docs.monad.xyz/templates/next-serwist-privy-embedded-wallet



This guide walks you through using the [template](https://github.com/monad-developers/next-serwist-privy-embedded-wallet) which uses [Next.js](https://nextjs.org/docs), [Serwist](https://serwist.pages.dev/) (offline capabilities), and [Privy embedded wallet](https://docs.privy.io/wallets/wallets/create/create-a-wallet) to build a Progressive Web App (PWA) on Monad.

<Info>
  This template also has a `no-privy` branch that you can switch to in order to start without Privy.

  You can switch using the following command:

  ```
  git checkout no-privy
  ```
</Info>

## Prerequisites

* [Node.js](https://nodejs.org/) (v18 or higher)
* a [Privy account](https://www.privy.io/)

<Accordion title="Setting up Privy">
  1. Create your Privy app:

  <img alt="Create your app" />

  Select "Web" as the platform. Then, click "Create app".

  <img alt="Name your app" />

  On the next screen, make sure to save your App ID.

  <br />

  2. Set up login methods:

  <img alt="Set up login methods" />

  <br />

  3. Disable External Wallets:

  <img alt="Disable external wallets" />

  <br />

  4. Scroll down and enable "Automatically create embedded wallets on login" and select "EVM Wallets":

  <img alt="Create wallets automatically" />

  <br />

  <Tip>
    You can enable "Test Accounts" for testing purposes:

    <img alt="Test accounts" />
  </Tip>
</Accordion>

## Setup

1. Clone the repository:

   ```bash theme={null}
   git clone https://github.com/monad-developers/next-serwist-privy-embedded-wallet.git
   ```

2. `cd` into the project directory:

   ```bash theme={null}
   cd next-serwist-privy-embedded-wallet
   ```

3. Install dependencies:

   ```bash theme={null}
   npm install
   ```

4. Create a `.env.local` file in the root directory:

   ```bash theme={null}
   cp .env.example .env.local
   ```

5. Start adding your environment variables to the `.env.local` file:

   ```bash theme={null}
   # Privy
   NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id_here
   NEXT_PUBLIC_PRIVY_CLIENT_ID= # optional, you can leave this empty

   # VAPID Keys for push notifications
   NEXT_PUBLIC_VAPID_PUBLIC_KEY=your_vapid_public_key_here
   VAPID_PRIVATE_KEY=your_vapid_private_key_here
   ```

   If you lost your Privy App ID, you can find it in the Privy dashboard.

6. Generate VAPID keys for web push notifications:

   ```bash theme={null}
   npx web-push generate-vapid-keys --json
   ```

   Copy the generated keys to your .env.local file (replace the placeholder values from step 5).

7. Running the Application:

   **Development Mode**:

   ```bash theme={null}
   npm run dev
   ```

   The application will be available at [http://localhost:3000](http://localhost:3000).

   **Production Mode:**

   For full PWA functionality (including install prompts):

   ```bash theme={null}
   npm run build && npm run start
   ```

## Folder structure of the template

```
next-serwist-privy-embedded-wallet/
├── app/
│   ├── components/         # React components
│   │   ├── InstallPWA.tsx  # PWA install prompt
│   │   └── ...
│   ├── ~offline/           # Offline page
│   └── ...
├── public/                 # Static assets
└── ...
```

## Changing the app name

* Edit [`public/manifest.json`](https://github.com/monad-developers/next-serwist-privy-embedded-wallet/blob/main/public/manifest.json):
  * Change the `name` and `short_name` fields
* Run `npm run build` to update the app

## Notification Setup

<Warning title="Enable notifications for the best experience!">
  To receive push notifications from this app, you need to enable notifications in your browser and/or system settings:
</Warning>

### Browser Settings

<Accordion title="Chrome/Edge">
  1. Click the lock icon 🔒 in the address bar
  2. Set "Notifications" to "Allow"
  3. Or go to Settings → Privacy and security → Site Settings → Notifications
</Accordion>

<Accordion title="Firefox">
  1. Click the shield icon 🛡️ in the address bar
  2. Turn off "Enhanced Tracking Protection" for this site (if needed)
  3. Allow notifications when prompted
  4. Or go to Settings → Privacy & Security → Permissions → Notifications
</Accordion>

<Accordion title="Safari">
  1. Go to Safari → Settings → Websites → Notifications
  2. Find your site and set it to "Allow"
</Accordion>

### System Settings

<Accordion title="macOS">
  1. System Preferences → Notifications & Focus
  2. Find your browser and ensure notifications are enabled
  3. Check "Allow notifications from websites" in browser settings
</Accordion>

<Accordion title="Windows">
  1. Settings → System → Notifications & actions
  2. Ensure your browser can send notifications
  3. Check browser notification settings
</Accordion>

<Accordion title="iOS">
  1. Settings → Notifications → \[Your Browser]
  2. Enable "Allow Notifications"
  3. Also enable in browser settings
</Accordion>

<Accordion title="Android">
  1. Settings → Apps → \[Your Browser] → Notifications
  2. Enable notifications
  3. Check browser notification permissions
</Accordion>

### Backend Integration Required

<Info title="The `SendNotification.tsx` component is sample code">
  [`SendNotification.tsx`](https://github.com/monad-developers/next-serwist-privy-embedded-wallet/blob/main/app/components/SendNotification.tsx) requires backend implementation:

  * **Save subscription data** when users subscribe (see TODO comments in code)
  * **Delete subscription data** when users unsubscribe
  * **Implement `/notification` endpoint** to send actual push notifications
  * **Use `web-push` library** or similar for server-side notification delivery
</Info>

### Customizing Notification Content

To customize your push notification content, edit [`app/notification/route.ts`](https://github.com/monad-developers/next-serwist-privy-embedded-wallet/blob/main/app/notification/route.ts) and modify the `title`, `message`, `icon`, and other properties in the `sendNotification` call.

## Modifying the App Icon & Splash Screen

### App Icons

Replace the icon files in the [`public/icons/`](https://github.com/monad-developers/next-serwist-privy-embedded-wallet/tree/main/public/icons) directory with your custom icons:

* **`icon-512x512.png`** - Main app icon (512×512px)
* **`android-chrome-192x192.png`** - Android icon (192×192px)
* **`apple-touch-icon.png`** - iOS home screen icon (180×180px)

Also update the favicon:

* **`public/favicon.ico`** - Browser favicon
* **`app/favicon.ico`** - Next.js app favicon

### Splash Screen

Splash screens are automatically generated from your app icon and theme colors defined in [`public/manifest.json`](https://github.com/monad-developers/next-serwist-privy-embedded-wallet/blob/main/public/manifest.json). To customize:

1. Update the `theme_color` and `background_color` in [`public/manifest.json`](https://github.com/monad-developers/next-serwist-privy-embedded-wallet/blob/main/public/manifest.json)
2. Ensure your main icon (`icon-512x512.png`) represents your brand
3. Run `npm run build` to apply changes

<Tip>
  Use tools like [PWA Asset Generator](https://www.pwabuilder.com/imageGenerator) to create all required icon sizes from a single source image.
</Tip>

## Deploying to Vercel

### Using Vercel Dashboard

1. **Connect your repository**:
   * Push your code to GitHub
   * Visit [vercel.com](https://vercel.com) and import your repository

2. **Configure environment variables**:
   * In your Vercel project dashboard, go to Settings → Environment Variables
   * Add the same variables from your `.env.local`:
     ```
     NEXT_PUBLIC_PRIVY_APP_ID
     NEXT_PUBLIC_PRIVY_CLIENT_ID
     NEXT_PUBLIC_VAPID_PUBLIC_KEY
     VAPID_PRIVATE_KEY
     ```

3. **Deploy**: Vercel will automatically build and deploy your app

4. **Update Privy settings**: In your Privy dashboard, add your Vercel domain (e.g., `your-app.vercel.app`) to the allowed origins

<Tip>
  PWA features (install prompts, offline support, push notifications) work automatically on HTTPS domains like Vercel deployments.
</Tip>

### Using Vercel CLI

Alternatively, deploy using the Vercel CLI:

1. **Install Vercel CLI**:
   ```bash theme={null}
   npm i -g vercel
   ```

2. **Login to Vercel**:
   ```bash theme={null}
   vercel login
   ```

3. **Deploy**:
   ```bash theme={null}
   vercel
   ```
   Follow the prompts to configure your project.

4. **Add environment variables**:

   ```bash theme={null}
   vercel env add NEXT_PUBLIC_PRIVY_APP_ID
   vercel env add NEXT_PUBLIC_PRIVY_CLIENT_ID  
   vercel env add NEXT_PUBLIC_VAPID_PUBLIC_KEY
   vercel env add VAPID_PRIVATE_KEY
   ```

   Or you can go to the Vercel dashboard and add the environment variables there.

5. **Redeploy with environment variables**:
   ```bash theme={null}
   vercel --prod
   ```

## Learn more

* Serwist: [docs](https://serwist.pages.dev/) | [guides](https://serwist.pages.dev/docs/next/getting-started)
* Privy: [create a wallet](https://docs.privy.io/wallets/wallets/create/create-a-wallet) | [send a transaction](https://docs.privy.io/wallets/using-wallets/ethereum/send-a-transaction) | [sign a transaction](https://docs.privy.io/wallets/using-wallets/ethereum/sign-a-transaction)
* Monad: [supported tooling and infra](/tooling-and-infra)


# How to use the Next.js PWA sponsored transactions template
Source: https://docs.monad.xyz/templates/next-serwist-privy-smart-wallet



This guide walks you through using the [template](https://github.com/monad-developers/next-serwist-privy-smart-wallet) which uses [Next.js](https://nextjs.org/docs), [Serwist](https://serwist.pages.dev/) (offline capabilities), and [Privy smart wallet](https://docs.privy.io/wallets/using-wallets/evm-smart-wallets/overview) (authentication and transaction sponsorship) to build a Progressive Web Application (PWA) on Monad.

## Prerequisites

* [Node.js](https://nodejs.org/) (v18 or higher)
* a [Privy account](https://www.privy.io/)
* a [Pimlico account](https://pimlico.io/)

<Accordion title="Setting up Privy">
  1. Create your Privy app:

     <img alt="Create your app" />

     Select "Web" as the platform. Then, click "Create app".

     <img alt="Name your app" />

     On the next screen, make sure to save your App ID.

  2. Set up login methods:

     <img alt="Set up login methods" />

  3. Disable External Wallets:

     <img alt="Disable external wallets" />

  4. Scroll down and enable "Automatically create embedded wallets on login" and select "EVM Wallets":

     <img alt="Create wallets automatically" />

  <Tip>
    You can enable "Test Accounts" for testing purposes:

    <img alt="Test accounts" />
  </Tip>
</Accordion>

<Accordion title="Setting up Pimlico">
  1. Sign up for a Pimlico account and go to "API Keys"

     <img alt="Pimlico API Keys" />

  2. Create a new API key:

     <img alt="Pimlico Create API Key" />

  3. Click on RPC URLs, then Select "Monad Testnet", and copy the RPC URL:

     <img alt="Pimlico RPC URLs" />

  4. Copy the RPC URL and save it to your `.env.local` file as `NEXT_PUBLIC_PIMLICO_BUNDLER_URL`.
</Accordion>

## Setup

1. Clone the repository:

   ```bash theme={null}
   git clone https://github.com/monad-developers/next-serwist-privy-smart-wallet.git
   ```

2. `cd` into the project directory:

   ```bash theme={null}
   cd next-serwist-privy-smart-wallet
   ```

3. Install dependencies:

   ```bash theme={null}
   npm install
   ```

4. Create a `.env.local` file in the root directory:

   ```bash theme={null}
   cp .env.example .env.local
   ```

5. Start adding your environment variables to the `.env.local` file:

   ```bash theme={null}
   # Privy 
   NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id_here
   NEXT_PUBLIC_PRIVY_CLIENT_ID= # optional, you can leave this empty

   # Web Push
   WEB_PUSH_EMAIL=user@example.com
   WEB_PUSH_PRIVATE_KEY=your_vapid_private_key
   NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY=your_vapid_public_key

   # Pimlico
   NEXT_PUBLIC_PIMLICO_BUNDLER_URL=your_pimlico_bundler_url
   ```

   If you lost your Privy App ID, you can find it in the Privy dashboard.

6. Generate VAPID keys for web push notifications:

   ```bash theme={null}
   npx web-push generate-vapid-keys --json
   ```

   Copy the generated keys to your .env.local file (replace the placeholder values from step 5).

7. Running the Application:

   **Development Mode**:

   ```bash theme={null}
   npm run dev
   ```

   The application will be available at [http://localhost:3000](http://localhost:3000).

   **Production Mode:**

   For full PWA functionality (including install prompts):

   ```bash theme={null}
   npm run build && npm run start
   ```

## Send sponsored transactions

Below is an example of how to use the [`useSmartWallet`](https://github.com/monad-developers/next-serwist-privy-smart-wallet/blob/main/app/hooks/useSmartWallet.tsx) hook to send sponsored transactions. You can either modify the code to send your own transactions or integrate it into your existing project.

```tsx theme={null}
// Use `useSmartWallet` hook
const { smartAccountAddress, smartAccountClient, smartAccountReady } = useSmartWallet();

// Send sponsored transaction
const txHash = await smartAccountClient?.sendTransaction({
  account: smartAccountClient?.account,
  chain: monadTestnet, // Import this from `viem/chains`
  to: NFT_CONTRACT_ADDRESS,
  data,
});
```

### Send batch sponsored transactions

You can also send batches of sponsored transactions:

```tsx theme={null}
const txHash = await smartAccountClient?.sendTransaction({
  calls: [
    {
      to: NFT_CONTRACT_ADDRESS,
      data,
    },
    {
      to: NFT_CONTRACT_ADDRESS,
      data,
    },
  ],
});
```

This example uses the Kernel smart account with Entrypoint v7. See [`useSmartWallet.tsx`](https://github.com/monad-developers/next-serwist-privy-smart-wallet/blob/main/app/hooks/useSmartWallet.tsx) to inspect the implementation details.

## Folder structure of the template

```
next-serwist-privy-smart-wallet/
├── app/
│   ├── components/         # React components
│   │   ├── InstallPWA.tsx  # PWA install prompt
│   │   └── ...
│   ├── hooks/                  # Custom React hooks
│   │   └── useSmartWallet.tsx  # Smart wallet management hook
│   ├── ~offline/           # Offline page
│   └── ...
├── public/                 # Static assets
└── ...
```

## Changing the app name

* Edit [`public/manifest.json`](https://github.com/monad-developers/next-serwist-privy-smart-wallet/blob/main/public/manifest.json):
  * Change the `name` and `short_name` fields
* Run `npm run build` to update the app

## Notification Setup

<Warning title="Enable notifications for the best experience!">
  To receive push notifications from this app, you need to enable notifications in your browser and/or system settings:
</Warning>

### Browser Settings

<Accordion title="Chrome/Edge">
  1. Click the lock icon 🔒 in the address bar
  2. Set "Notifications" to "Allow"
  3. Or go to Settings → Privacy and security → Site Settings → Notifications
</Accordion>

<Accordion title="Firefox">
  1. Click the shield icon 🛡️ in the address bar
  2. Turn off "Enhanced Tracking Protection" for this site (if needed)
  3. Allow notifications when prompted
  4. Or go to Settings → Privacy & Security → Permissions → Notifications
</Accordion>

<Accordion title="Safari">
  1. Go to Safari → Settings → Websites → Notifications
  2. Find your site and set it to "Allow"
</Accordion>

### System Settings

<Accordion title="macOS">
  1. System Preferences → Notifications & Focus
  2. Find your browser and ensure notifications are enabled
  3. Check "Allow notifications from websites" in browser settings
</Accordion>

<Accordion title="Windows">
  1. Settings → System → Notifications & actions
  2. Ensure your browser can send notifications
  3. Check browser notification settings
</Accordion>

<Accordion title="iOS">
  1. Settings → Notifications → \[Your Browser]
  2. Enable "Allow Notifications"
  3. Also enable in browser settings
</Accordion>

<Accordion title="Android">
  1. Settings → Apps → \[Your Browser] → Notifications
  2. Enable notifications
  3. Check browser notification permissions
</Accordion>

### Backend Integration Required

<Info title="The `SendNotification.tsx` component is sample code">
  [`SendNotification.tsx`](https://github.com/monad-developers/next-serwist-privy-smart-wallet/blob/main/app/components/SendNotification.tsx) requires backend implementation:

  * **Save subscription data** when users subscribe (see TODO comments in code)
  * **Delete subscription data** when users unsubscribe
  * **Implement `/notification` endpoint** to send actual push notifications
  * **Use `web-push` library** or similar for server-side notification delivery
</Info>

### Customizing Notification Content

To customize your push notification content, edit [`app/notification/route.ts`](https://github.com/monad-developers/next-serwist-privy-smart-wallet/blob/main/app/notification/route.ts) and modify the `title`, `message`, `icon`, and other properties in the `sendNotification` call.

## Modifying the App Icon & Splash Screen

### App Icons

Replace the icon files in the [`public/icons/`](https://github.com/monad-developers/next-serwist-privy-smart-wallet/tree/main/public/icons) directory with your custom icons:

* **`icon-512x512.png`** - Main app icon (512×512px)
* **`android-chrome-192x192.png`** - Android icon (192×192px)
* **`apple-touch-icon.png`** - iOS home screen icon (180×180px)

Also update the favicon:

* **`public/favicon.ico`** - Browser favicon
* **`app/favicon.ico`** - Next.js app favicon

### Splash Screen

Splash screens are automatically generated from your app icon and theme colors defined in [`public/manifest.json`](https://github.com/monad-developers/next-serwist-privy-smart-wallet/blob/main/public/manifest.json). To customize:

1. Update the `theme_color` and `background_color` in [`public/manifest.json`](https://github.com/monad-developers/next-serwist-privy-smart-wallet/blob/main/public/manifest.json)
2. Ensure your main icon (`icon-512x512.png`) represents your brand
3. Run `npm run build` to apply changes

<Tip>
  Use tools like [PWA Asset Generator](https://www.pwabuilder.com/imageGenerator) to create all required icon sizes from a single source image.
</Tip>

## Deploying to Vercel

### Using Vercel Dashboard

1. **Connect your repository**:

   * Push your code to GitHub
   * Visit [vercel.com](https://vercel.com) and import your repository

2. **Configure environment variables**:

   * In your Vercel project dashboard, go to Settings → Environment Variables
   * Add the same variables from your `.env.local`:
     ```
     NEXT_PUBLIC_PRIVY_APP_ID
     NEXT_PUBLIC_PRIVY_CLIENT_ID
     WEB_PUSH_EMAIL
     WEB_PUSH_PRIVATE_KEY
     NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY
     NEXT_PUBLIC_PIMLICO_BUNDLER_URL
     ```

3. **Deploy**: Vercel will automatically build and deploy your app

4. **Update Privy settings**: In your Privy dashboard, add your Vercel domain (e.g., `your-app.vercel.app`) to the allowed origins

<Tip>
  PWA features (install prompts, offline support, push notifications) work automatically on HTTPS domains like Vercel deployments.
</Tip>

### Using Vercel CLI

Alternatively, deploy using the Vercel CLI:

1. **Install Vercel CLI**:

   ```bash theme={null}
   npm i -g vercel
   ```

2. **Login to Vercel**:

   ```bash theme={null}
   vercel login
   ```

3. **Deploy**:

   ```bash theme={null}
   vercel
   ```

   Follow the prompts to configure your project.

4. **Add environment variables**:

   ```bash theme={null}
   vercel env add NEXT_PUBLIC_PRIVY_APP_ID
   vercel env add NEXT_PUBLIC_PRIVY_CLIENT_ID
   vercel env add WEB_PUSH_EMAIL
   vercel env add WEB_PUSH_PRIVATE_KEY
   vercel env add NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY
   vercel env add NEXT_PUBLIC_PIMLICO_BUNDLER_URL
   ```

   Or you can go to the Vercel dashboard and add the environment variables there.

5. **Redeploy with environment variables**:
   ```bash theme={null}
   vercel --prod
   ```

## Learn more

* Serwist: [docs](https://serwist.pages.dev/) | [guides](https://serwist.pages.dev/docs/next/getting-started)
* Privy: [create a wallet](https://docs.privy.io/wallets/wallets/create/create-a-wallet) | [send a transaction](https://docs.privy.io/wallets/using-wallets/ethereum/send-a-transaction) | [sign a transaction](https://docs.privy.io/wallets/using-wallets/ethereum/sign-a-transaction)
* Pimlico: [docs](https://docs.pimlico.io/) | [guides](https://docs.pimlico.io/guides/getting-started)
* Monad: [supported tooling and infra](/tooling-and-infra)


# How to use the Next.js Serwist Thirdweb embedded wallet template
Source: https://docs.monad.xyz/templates/next-serwist-thirdweb



This guide walks you through using the [template](https://github.com/monad-developers/next-serwist-thirdweb) which uses [Next.js](https://nextjs.org/docs), [Serwist](https://serwist.pages.dev/) (offline capabilities), and [Thirdweb](https://portal.thirdweb.com/) embedded wallet to build a Progressive Web Application (PWA) on Monad.

## Prerequisites

* [Node.js](https://nodejs.org/) (v18 or higher)
* a [Thirdweb account](https://thirdweb.com/)

## Setup

1. Clone the repository:

   ```bash theme={null}
   git clone https://github.com/monad-developers/next-serwist-thirdweb.git
   ```

2. `cd` into the project directory:

   ```bash theme={null}
   cd next-serwist-thirdweb
   ```

3. Install dependencies:

   ```bash theme={null}
   npm install
   ```

4. Create a `.env.local` file in the root directory:

   ```bash theme={null}
   cp .env.example .env.local
   ```

5. Start adding your environment variables to the `.env.local` file:

   ```bash theme={null}
   # Thirdweb Configuration (Required)
   NEXT_PUBLIC_THIRDWEB_CLIENT_ID=your_thirdweb_client_id_here

   # Web Push (Required)
   WEB_PUSH_EMAIL=user@example.com
   WEB_PUSH_PRIVATE_KEY=your_vapid_private_key
   NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY=your_vapid_public_key
   ```

   If you lost your Thirdweb Client ID, you can find it in the Thirdweb dashboard.

6. Generate VAPID keys for web push notifications:

   ```bash theme={null}
   npx web-push generate-vapid-keys --json
   ```

   Copy the generated keys to your .env.local file (replace the placeholder values from step 5).

7. Running the Application:

   **Development Mode**:

   ```bash theme={null}
   npm run dev
   ```

   The application will be available at [http://localhost:3000](http://localhost:3000).

   **Production Mode:**

   For full PWA functionality (including install prompts):

   ```bash theme={null}
   npm run build && npm run start
   ```

## Folder structure of the template

```
next-serwist-thirdweb/
├── app/
│   ├── components/         # React components
│   │   ├── InstallPWA.tsx  # PWA install prompt
│   │   └── ...
│   ├── ~offline/           # Offline page
│   └── ...
├── public/                 # Static assets
└── ...
```

## Changing the app name

* Edit [`public/manifest.json`](https://github.com/monad-developers/next-serwist-thirdweb/blob/main/public/manifest.json):
  * Change the `name` and `short_name` fields
* Run `npm run build` to update the app

## Notification Setup

<Warning title="Enable notifications for the best experience!">
  To receive push notifications from this app, you need to enable notifications in your browser and/or system settings.
</Warning>

### Browser Settings

<Accordion title="Chrome/Edge">
  1. Click the lock icon 🔒 in the address bar
  2. Set "Notifications" to "Allow"
  3. Or go to Settings → Privacy and security → Site Settings → Notifications
</Accordion>

<Accordion title="Firefox">
  1. Click the shield icon 🛡️ in the address bar
  2. Turn off "Enhanced Tracking Protection" for this site (if needed)
  3. Allow notifications when prompted
  4. Or go to Settings → Privacy & Security → Permissions → Notifications
</Accordion>

<Accordion title="Safari">
  1. Go to Safari → Settings → Websites → Notifications
  2. Find your site and set it to "Allow"
</Accordion>

### System Settings

<Accordion title="macOS">
  1. System Preferences → Notifications & Focus
  2. Find your browser and ensure notifications are enabled
  3. Check "Allow notifications from websites" in browser settings
</Accordion>

<Accordion title="Windows">
  1. Settings → System → Notifications & actions
  2. Ensure your browser can send notifications
  3. Check browser notification settings
</Accordion>

<Accordion title="iOS">
  1. Settings → Notifications → \[Your Browser]
  2. Enable "Allow Notifications"
  3. Also enable in browser settings
</Accordion>

<Accordion title="Android">
  1. Settings → Apps → \[Your Browser] → Notifications
  2. Enable notifications
  3. Check browser notification permissions
</Accordion>

### Backend Integration Required

<Info title="The `SendNotification.tsx` component is sample code">
  [`SendNotification.tsx`](https://github.com/monad-developers/next-serwist-thirdweb/blob/main/app/components/SendNotification.tsx) requires backend implementation:

  * **Save subscription data** when users subscribe (see TODO comments in code)
  * **Delete subscription data** when users unsubscribe
  * **Implement `/notification` endpoint** to send actual push notifications
  * **Use `web-push` library** or similar for server-side notification delivery
</Info>

### Customizing Notification Content

To customize your push notification content, edit [`app/notification/route.ts`](https://github.com/monad-developers/next-serwist-thirdweb/blob/main/app/notification/route.ts) and modify the `title`, `message`, `icon`, and other properties in the `sendNotification` call.

## Modifying the App Icon & Splash Screen

### App Icons

Replace the icon files in the [`public/icons/`](https://github.com/monad-developers/next-serwist-thirdweb/tree/main/public/icons) directory with your custom icons:

* **`icon-512x512.png`** - Main app icon (512×512px)
* **`android-chrome-192x192.png`** - Android icon (192×192px)
* **`apple-touch-icon.png`** - iOS home screen icon (180×180px)

Also update the favicon:

* **`public/favicon.ico`** - Browser favicon
* **`app/favicon.ico`** - Next.js app favicon

### Splash Screen

Splash screens are automatically generated from your app icon and theme colors defined in [`public/manifest.json`](https://github.com/monad-developers/next-serwist-thirdweb/blob/main/public/manifest.json). To customize:

1. Update the `theme_color` and `background_color` in [`public/manifest.json`](https://github.com/monad-developers/next-serwist-thirdweb/blob/main/public/manifest.json)
2. Ensure your main icon (`icon-512x512.png`) represents your brand
3. Run `npm run build` to apply changes

<Tip>
  Use tools like [PWA Asset Generator](https://www.pwabuilder.com/imageGenerator) to create all required icon sizes from a single source image.
</Tip>

## Deploying to Vercel

### Using Vercel Dashboard

1. **Connect your repository**:

   * Push your code to GitHub
   * Visit [vercel.com](https://vercel.com) and import your repository

2. **Configure environment variables**:

   * In your Vercel project dashboard, go to Settings → Environment Variables
   * Add the same variables from your `.env.local`:
     ```
     NEXT_PUBLIC_THIRDWEB_CLIENT_ID
     WEB_PUSH_EMAIL
     WEB_PUSH_PRIVATE_KEY
     NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY
     ```

3. **Deploy**: Vercel will automatically build and deploy your app

4. **Update Thirdweb settings**: In your Thirdweb dashboard, add your Vercel domain (e.g., `your-app.vercel.app`) to the allowed origins

<Tip>
  PWA features (install prompts, offline support, push notifications) work automatically on HTTPS domains like Vercel deployments.
</Tip>

### Using Vercel CLI

Alternatively, deploy using the Vercel CLI:

1. **Install Vercel CLI**:

   ```bash theme={null}
   npm i -g vercel
   ```

2. **Login to Vercel**:

   ```bash theme={null}
   vercel login
   ```

3. **Deploy**:

   ```bash theme={null}
   vercel
   ```

   Follow the prompts to configure your project.

4. **Add environment variables**:

   ```bash theme={null}
   vercel env add NEXT_PUBLIC_THIRDWEB_CLIENT_ID
   vercel env add WEB_PUSH_EMAIL
   vercel env add WEB_PUSH_PRIVATE_KEY
   vercel env add NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY
   ```

   Or you can go to the Vercel dashboard and add the environment variables there.

5. **Redeploy with environment variables**:
   ```bash theme={null}
   vercel --prod
   ```

## Learn more

* Serwist: [docs](https://serwist.pages.dev/) | [guides](https://serwist.pages.dev/docs/next/getting-started)
* Thirdweb: [docs](https://portal.thirdweb.com) | [guides](https://portal.thirdweb.com/docs/quick-start)
* Monad: [supported tooling and infra](/tooling-and-infra)


# How to use the React Native Privy embedded wallet template
Source: https://docs.monad.xyz/templates/react-native-privy-embedded-wallet



This guide walks you through using the [wallet template](https://github.com/monad-developers/react-native-privy-embedded-wallet-template) which uses Expo, React Native, and Privy embedded wallet to build a mobile app on Monad.

Start developing by editing the files inside the `app` directory. This project uses [file-based routing](https://docs.expo.dev/router/introduction).

<Info>
  This template also has a `demo` branch that you can switch to in order to view the demo project.

  You can switch using the following command:

  ```
  git checkout demo
  ```
</Info>

## Prerequisites

* Node.js
* NPM
* Expo CLI (Install using the following command: `npm i -g expo-cli`)
* a [Privy account](https://dashboard.privy.io/)

<Accordion title="For Android">
  - [Android Studio](https://developer.android.com/studio) (API version 35 and above)
    * Guide to setup Android Studio for Expo is available [here](https://docs.expo.dev/workflow/android-studio-emulator/)
</Accordion>

<Accordion title="For iOS">
  * [XCode](https://apps.apple.com/in/app/xcode/id497799835?mt=12)
    * Guide to setup iOS Simulator for Expo is available [here](https://docs.expo.dev/workflow/ios-simulator/)
</Accordion>

<Accordion title="Setting up the Privy account">
  1. Create app:

  <img alt="create app" />

  <img alt="nameing app" />

  <br />

  2. Set up login methods:

  <img alt="set up login methods" />

  <br />

  3. Enable email:

  <img alt="enable email" />

  <br />

  4. Enable "Automatically create embedded wallets on login" and select "EVM Wallets":

  <img alt="create wallets automatically" />

  <br />

  5. Disable everything in Socials.

  6. Go to "Advanced" and Make sure only "Web2: Email, SMS, and socials" under "Prioritize options displayed" is enabled:

  <img alt="prioritize web2 methods" />

  <br />

  7. Tip: You can enable "Test Accounts" for testing purposes:

  <img alt="test wallets" />

  8. A few more steps are required but we will continue once the dependencies for the project are installed.
</Accordion>

## Get started

<Info>
  This template also has a `demo` branch that you can switch to in order to view the demo project.

  You can switch using the following command:

  ```
  git checkout demo
  ```
</Info>

### Install dependencies

```bash theme={null}
npm install
```

### Set up the environment variables

* Create a copy of `.env.example`

```bash theme={null}
cp .env.example .env
```

* Add the following environment variables to it

```
EXPO_PUBLIC_PRIVY_APP_ID=
EXPO_PUBLIC_PRIVY_CLIENT_ID=
```

<Accordion title="How to get `EXPO_PUBLIC_PRIVY_APP_ID`">
  1. Go to your Privy Dashboard and click on `Home` for your Privy app and click on `Retrieve API keys`.

  <img alt="retrieve api keys" />

  2. You will find `App ID` under `API keys`.

  <img alt="api key" />
</Accordion>

<Accordion title="How to get `EXPO_PUBLIC_PRIVY_CLIENT_ID`">
  1. Go to your Privy Dashboard and click on "Home" for your Privy app and click on `Retrieve API keys`.

  <img alt="retrieve api keys" />

  2. Click on the `Clients` tab at the top and click on `Edit`.

  <img alt="clients" />

  3. Under `Allowed app identifiers` paste the name of the app bundle and click `Add`

  You can find the app bundle name in `app.json` for Android it is `package` property and iOS it is the `bundleIdentifier` property

  <img alt="allowed identifiers" />

  4. You can copy the `Client ID` and use as the value for `EXPO_PUBLIC_PRIVY_CLIENT_ID`.

  <img alt="client_id" />
</Accordion>

### Start the app

The below commands will start the app in Expo Go app on respective devices.

For iOS:

```bash theme={null}
npm run ios
```

For Android:

```bash theme={null}
npm run android
```

For native app builds use the following commands

For iOS:

```bash theme={null}
npx expo run:ios
```

For Android:

```bash theme={null}
npx expo run:android
```

## Folder structure of the template

```
react-native-privy-embedded-wallet-template/
  ├── app/                                   # Expo router entrypoint
  │   ├── _layout.tsx                        # Root Layout
  │   └── index.tsx                          # First screen
  ├── assets/
  │   ├── fonts/                             # Custom fonts go here
  │   └── images/ 
  │       ├── adaptive-icon.png
  │       ├── favicon.png
  │       ├── icon.png
  │       ├── monad-logo-inverted.png
  │       └── monad-logo.png
  │   └── readme/                            # images for the readme, you can delete this
  ├── constants/
  │   └── Colors.ts
  ├── app.json                               # App properties
  ├── babel.config.js
  ├── eas.json
  ├── entrypoint.js
  ├── eslint.config.js
  ├── metro.config.js                        # Configuration for Hermes and Polyfills
  ├── package-lock.json
  ├── package.json
  ├── README.md
  ├── tsconfig.json
  ├── types/
  │   └── react-native-qrcode-styled.d.ts
```

## Modifying the app name

<div>
  <table>
    <thead>
      <tr>
        <th>iOS</th>
        <th>Android</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          <img />
        </td>

        <td>
          <img />
        </td>
      </tr>
    </tbody>
  </table>
</div>

Edit the `name` property in the `app.json` file.

```json theme={null}
{
   "expo": {
      "name": "wallet-app", <--- Edit this
      ...
   }
}  
```

## Modifying the App Icon & Splash Screen

### App Icon

<div>
  <table>
    <thead>
      <tr>
        <th>iOS</th>
        <th>Android</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          <img />
        </td>

        <td>
          <img />
        </td>
      </tr>
    </tbody>
  </table>
</div>

You can edit the app icon by replacing the `assets/images/icon.png` file.

Recommended App Icon size is `1024x1024`.

If you name the icon file something else then edit the `icon` property in `app.json` accordingly.

```json theme={null}
{
   "expo": {
      "name": "rn-wallet-app",
      ...
      "icon": "./assets/images/icon.png", <--- Change this
      ...
   }
}
```

### Splash Screen

<div>
  <table>
    <thead>
      <tr>
        <th>iOS</th>
        <th>Android</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          <img />
        </td>

        <td>
          <img />
        </td>
      </tr>
    </tbody>
  </table>
</div>

Edit the `splash` object in `app.json` to modify the splash screen.

```json theme={null}
{
   "expo": {
      "name": "rn-wallet-app",
      ...
      "splash": { <--- Edit this object
         "image": "./assets/images/icon.png",
         "backgroundColor": "#ffffff"
      }
   }  
}
```

## Modifying fonts for the app

You can create a `fonts` folder inside `assets` folder and keep your custom font files in the `fonts` folder.

To use the custom font, load the font in the `app/_layout.tsx` file.

Example:

```ts theme={null}
const [loaded] = useFonts({
  "SF-Pro-Rounded-Black": require("../assets/fonts/SF_Pro_Rounded/SF-Pro-Rounded-Black.otf"),
  "SF-Pro-Rounded-Bold": require("../assets/fonts/SF_Pro_Rounded/SF-Pro-Rounded-Bold.otf"),
  "SF-Pro-Rounded-Heavy": require("../assets/fonts/SF_Pro_Rounded/SF-Pro-Rounded-Heavy.otf"),
  "SF-Pro-Rounded-Medium": require("../assets/fonts/SF_Pro_Rounded/SF-Pro-Rounded-Medium.otf"),
  "SF-Pro-Rounded-Regular": require("../assets/fonts/SF_Pro_Rounded/SF-Pro-Rounded-Regular.otf"),
  "SF-Pro-Rounded-Semibold": require("../assets/fonts/SF_Pro_Rounded/SF-Pro-Rounded-Semibold.otf"),
  Inter_400Regular,
  Inter_500Medium,
  Inter_600SemiBold,
});
```

## Modifying the deeplinking scheme

Edit the `scheme` property in `app.json` file, for your custom deeplinking scheme.

```json theme={null}
{
  "expo": {
    ...
    "scheme": "rnwalletapp",
    ...
  }
}
```

For example, if you set this to `rnwalletapp`, then `rnwalletapp://` URLs would open your app when tapped.

This is a build-time configuration, it has no effect in Expo Go.

## Editing the landing screen

<div>
  <table>
    <thead>
      <tr>
        <th>iOS</th>
        <th>Android</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          <img />
        </td>

        <td>
          <img />
        </td>
      </tr>
    </tbody>
  </table>
</div>

You can edit the landing page by editing the code in the file `app/index.tsx`.

## Wallet Actions

The template has example code for the following Wallet Actions:

* [Send USDC](https://github.com/monad-developers/react-native-privy-embedded-wallet-template/blob/demo/components/sheets/SendSheet.tsx)
* [Sign Message](https://github.com/monad-developers/react-native-privy-embedded-wallet-template/blob/demo/components/sheets/SignSheet.tsx)

## Modifying the package/bundle identifier

When publishing app to the app store you need to have a unique package/bundle identifier you can change it in in `app.json`.

<Warning>
  Don't forget to the change the identifier in Privy dashboard
</Warning>

```json theme={null}
{
  "expo": {
    "name": "rn-wallet-app",
    ...
    "ios": {
      "bundleIdentifier": "com.anonymous.rn-wallet-app", <--- Edit this
      ...
    },
    "android": {
      ...
      "package": "com.anonymous.rnwalletapp" <--- Edit this
    },
  }
}
```

## Check out the demo app

If you want try the demo app before you start developing you can switch to the `demo` branch available with the repo:

```bash theme={null}
git checkout demo
```

### Folder structure of the demo project (Change to `demo` branch to view this)

```
react-native-privy-embedded-wallet-template/
  ├── app/
  │   ├── _layout.tsx                        # Root layout of the project
  │   ├── +not-found.tsx
  │   ├── demo/                              # This is entrypoint for the Wallet related code.
  │   │   ├── _layout.tsx
  │   │   ├── app/                           # If Authenticated the user can access route /app
  │   │   │   ├── _layout.tsx
  │   │   │   └── index.tsx
  │   │   └── sign-in/                       # Unauthenticated user gets redirected to /sign-in
  │   └── index.tsx                          # This is the landing page
  ├── assets/
  │   ├── fonts/                             # Custom fonts go here
  │   │   └── SF_Pro_Rounded/                # Custom Font example
  │   └── images/
  │       ├── adaptive-icon.png
  │       ├── favicon.png
  │       ├── icon.png
  │       ├── monad-icon.png
  │       ├── monad-logo-inverted.png
  │       ├── monad-logo.png
  │       ├── partial-react-logo.png
  │       └── splash-icon.png
  ├── components/
  │   ├── sheets/                            # All the bottom sheets are here
  │   └── ui/
  ├── config/
  │   ├── privyConfig.ts                     # Privy related config
  │   ├── providers.tsx 
  │   └── wagmiConfig.ts                     # Monad Testnet related config
  ├── constants/
  ├── context/
  │   ├── AuthContext.tsx
  │   └── WalletContext.tsx                  # Wallet actions implementations are here
  ├── hooks/
  ├── screens/
  │   ├── Email/                             # Screen that asks for Email
  │   ├── Home/                              # Wallet Home screen (Authenticated users only)
  │   ├── Landing/                           # Screen with info on how to use the template
  │   └── OTP/                               # Screen that asks for the OTP code sent to email
  ├── types/
  ├── utils.ts
  ├── entrypoint.ts
  ├── app.json
  ├── babel.config.js
  ├── eas.json
  ├── eslint.config.js
  ├── metro.config.js
  ├── package.json
  ├── package-lock.json
  ├── README.md
  ├── tsconfig.json
```

## Learn more

To learn more about developing your project with Expo, Privy, and Monad, check out the following resources:

* Expo [docs](https://docs.expo.dev/) | [guides](https://docs.expo.dev/guides) | [tutorial](https://docs.expo.dev/tutorial/introduction/)
* Privy: [create a wallet](https://docs.privy.io/wallets/wallets/create/create-a-wallet) | [send a transaction](https://docs.privy.io/wallets/using-wallets/ethereum/send-a-transaction) | [sign a transaction](https://docs.privy.io/wallets/using-wallets/ethereum/sign-a-transaction)
* Monad: [supported tooling and infra](/tooling-and-infra)

Please report any issues [here](https://github.com/monad-developers/react-native-privy-embedded-wallet-template/issues).


# How to use the React Native sponsored transactions template
Source: https://docs.monad.xyz/templates/react-native-privy-pimlico-sponsored-transactions



Sponsored transactions enable users to interact with blockchain applications without needing to pay gas fees themselves, improving accessibility, user experience, and onboarding - especially for newcomers unfamiliar with crypto.

This guide walks you through using the [sponsored transactions template](https://github.com/monad-developers/react-native-privy-pimlico-gas-sponsorship-template) which uses [Expo](https://docs.expo.dev/), [React Native](https://reactnative.dev/), [Privy embedded wallet](https://docs.privy.io/wallets/wallets/create/create-a-wallet) and [Pimlico paymaster](https://docs.pimlico.io/references/permissionless/reference/clients/smartAccountClient) to build a mobile app with sponsored transactions on Monad.

You can start developing by editing the files inside the `app` directory. This project uses [file-based routing](https://docs.expo.dev/router/introduction).

<Info>
  This repo also has a `demo` branch that you can switch to if you'd like to inspect a completed version of the app first.
</Info>

## Prerequisites

* Node.js
* NPM
* a [Privy account](https://dashboard.privy.io/)
* a [Pimlico account](https://dashboard.pimlico.io/)

<Accordion title="For Android">
  - [Android Studio](https://developer.android.com/studio) (API version 35 and above)
    * Guide to setup Android Studio for Expo is available [here](https://docs.expo.dev/workflow/android-studio-emulator/)
</Accordion>

<Accordion title="For iOS">
  * [XCode](https://apps.apple.com/in/app/xcode/id497799835?mt=12)
    * Guide to setup iOS Simulator for Expo is available [here](https://docs.expo.dev/workflow/ios-simulator/)
</Accordion>

<Accordion title="Setting up the Privy account">
  1. Create app:

  <img alt="create app" />

  <img alt="naming the app" />

  <br />

  1. Set up login methods:

  <img alt="set up login methods" />

  <br />

  3. Enable email:

  <img alt="enable email" />

  <br />

  4. Enable "Automatically create embedded wallets on login" and select "EVM Wallets":

  <img alt="create wallets automatically" />

  <br />

  5. Disable everything in Socials.

  6. Go to "Advanced" and Make sure only "Web2: Email, SMS, and socials" under "Prioritize options displayed" is enabled:

  <img alt="prioritize web2 methods" />

  <br />

  <Tip>
    You can enable "Test Accounts" for testing purposes

    <img alt="test wallets" />
  </Tip>

  A few more steps are required but we will continue once the dependencies for the project are installed.
</Accordion>

## Get started

<Info>
  This template also has a `demo` branch that you can switch to in order to view the demo project.

  You can switch using the following command:

  ```
  git checkout demo
  ```
</Info>

### Install dependencies

```bash theme={null}
npm install
```

### Set up the environment variables

* Create a copy of `.env.example`:

  ```bash theme={null}
  cp .env.example .env
  ```

* Add the following environment variables to it

  ```
  EXPO_PUBLIC_PRIVY_APP_ID=
  EXPO_PUBLIC_PRIVY_CLIENT_ID=
  EXPO_PUBLIC_PIMLICO_BUNDLER_URL=
  ```

<Accordion title="How to get `EXPO_PUBLIC_PRIVY_APP_ID`">
  1. Go to your Privy Dashboard and click on `Home` for your Privy app and click on `Retrieve API keys`.

  <img alt="retrieve api keys" />

  2. You will find `App ID` under `API keys`.

  <img alt="api key" />
</Accordion>

<Accordion title="How to get `EXPO_PUBLIC_PRIVY_CLIENT_ID`">
  1. Go to your Privy Dashboard, click `Home` for your Privy app, and click `Retrieve API keys`.

  <img alt="retrieve api keys" />

  2. Click on the `Clients` tab at the top, then click `Edit`.

  <img alt="clients" />

  3. Under `Allowed app identifiers`, paste the name of the app bundle and click `Add`.

  You will find the app bundle name in [`app.json`](https://github.com/monad-developers/react-native-privy-pimlico-gas-sponsorship-template/blob/main/app.json). For Android, it is the `package` property. For iOS, it is the `bundleIdentifier` property.

  <img alt="allowed identifiers" />

  4. Copy the `Client ID` and use it as the value for `EXPO_PUBLIC_PRIVY_CLIENT_ID`.

  <img alt="client_id" />
</Accordion>

<Accordion title="How to get `EXPO_PUBLIC_PIMLICO_BUNDLER_URL`">
  1. Sign up on Pimlico and go to "API Keys":

  <img alt="pimlico_dashboard" />

  2. Create a new API key:

  <img alt="create_api_key" />

  3. Click on "RPC URLs":

  <img alt="rpc_urls" />

  4. Search for Monad Testnet and copy the URL. Use this as `EXPO_PUBLIC_PIMLICO_BUNDLER_URL`:

  <img alt="monad_testnet_rpc_url" />
</Accordion>

### Start the app

Start the app either in the Expo Go app, or natively.

In the Expo Go app:

* For iOS:

  ```bash theme={null}
  npm run ios
  ```

* For Android:

  ```bash theme={null}
  npm run android
  ```

As a native app build:

* For iOS:

  ```bash theme={null}
  npx expo run:ios
  ```

* For Android:

  ```bash theme={null}
  npx expo run:android
  ```

## Template folder structure

```
react-native-privy-pimlico-gas-sponsorship-template/
  ├── app/                                   # Expo router entrypoint
  │   ├── _layout.tsx                        # Root layout
  │   └── index.tsx                          # First screen
  ├── assets/
  │   ├── images/ 
  │   │   ├── adaptive-icon.png
  │   │   ├── favicon.png
  │   │   ├── icon.png
  │   │   ├── monad-logo-inverted.png
  │   │   └── monad-logo.png
  │   └── readme/                            
  ├── constants/
  │   └── Colors.ts
  ├── hooks/
  │   └── useSmartWallet.tsx                 # Smart wallet utilities
  ├── screens/
  │   └── Home.tsx                           # Start here
  ├── types/
  │   └── react-native-qrcode-styled.d.ts
  ├── app.json                               # App properties
  ├── babel.config.js
  ├── eas.json
  ├── entrypoint.js
  ├── eslint.config.js
  ├── metro.config.js                        # Configuration for Hermes and Polyfills
  ├── package-lock.json
  ├── package.json
  ├── README.md
  └── tsconfig.json
```

## Send sponsored transactions

Below is an example of how to use the [useSmartWallet](https://github.com/monad-developers/react-native-privy-pimlico-gas-sponsorship-template/blob/main/hooks/useSmartWallet.tsx) hook to send sponsored transactions. You can either modify the code to send your own transactions or integrate it into your existing project.

```ts theme={null}
...

// Use `useSmartWallets` hook
const { smartAccountAddress, smartAccountClient, smartAccountReady } = useSmartWallet();

...

// Send sponsored transaction
const txHash = await smartAccountClient?.sendTransaction({
  account: smartAccountClient?.account,
  chain: monadTestnet,
  to: NFT_CONTRACT_ADDRESS,
  data,
});

...
```

### Send batch sponsored transactions

You can also send batches of sponsored transactions:

```ts theme={null}
const txHash = await smartAccountClient?.sendTransaction({
  calls: [
    {
      to: NFT_CONTRACT_ADDRESS,
      data,
    },
    {
      to: NFT_CONTRACT_ADDRESS,
      data,
    },
  ],
});
```

This example uses the Kernel smart account with Entrypoint v7. See [`useSmartWallet.tsx`](https://github.com/monad-developers/react-native-privy-pimlico-gas-sponsorship-template/blob/main/hooks/useSmartWallet.tsx) to inspect the implementation details.

## Modify the app name

<div>
  <table>
    <thead>
      <tr>
        <th>iOS</th>
        <th>Android</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          <img />
        </td>

        <td>
          <img />
        </td>
      </tr>
    </tbody>
  </table>
</div>

Edit the `name` property in [`app.json`](https://github.com/monad-developers/react-native-privy-pimlico-gas-sponsorship-template/blob/main/app.json):

```js title="app.json" theme={null}
{
   "expo": {
      "name": "wallet-app", <--- Edit this
      ...
   }
}  
```

## Modify the app icon and splash screen

### App icon

<div>
  <table>
    <thead>
      <tr>
        <th>iOS</th>
        <th>Android</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          <img />
        </td>

        <td>
          <img />
        </td>
      </tr>
    </tbody>
  </table>
</div>

You can edit the app icon by replacing `assets/images/icon.png`.

Recommended app icon size is `1024x1024`.

If you name the icon file something else, then edit the `icon` property in [`app.json`](https://github.com/monad-developers/react-native-privy-pimlico-gas-sponsorship-template/blob/main/app.json) accordingly.

```json title="app.json" theme={null}
{
   "expo": {
      "name": "rn-wallet-app",
      ...
      "icon": "./assets/images/icon.png", <--- Change this
      ...
   }
}
```

### Splash screen

<div>
  <table>
    <thead>
      <tr>
        <th>iOS</th>
        <th>Android</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          <img />
        </td>

        <td>
          <img />
        </td>
      </tr>
    </tbody>
  </table>
</div>

Edit the `splash` object in [`app.json`](https://github.com/monad-developers/react-native-privy-pimlico-gas-sponsorship-template/blob/main/app.json) to modify the splash screen.

```json title="app.json" theme={null}
{
   "expo": {
      "name": "rn-gas-sponsorship-app",
      ...
      "splash": { <--- Edit this object
         "image": "./assets/images/icon.png",
         "backgroundColor": "#ffffff"
      }
   }  
}
```

## Change fonts

You can create a `fonts` folder inside [`assets`](https://github.com/monad-developers/react-native-privy-pimlico-gas-sponsorship-template/tree/main/assets) to store your custom font files.

To use the custom font, load the font in [`app/_layout.tsx`](https://github.com/monad-developers/react-native-privy-pimlico-gas-sponsorship-template/blob/main/app/_layout.tsx).

Example:

```ts title="app/_layout.tsx" theme={null}
const [loaded] = useFonts({
  "SF-Pro-Rounded-Black": require("../assets/fonts/SF_Pro_Rounded/SF-Pro-Rounded-Black.otf"),
  "SF-Pro-Rounded-Bold": require("../assets/fonts/SF_Pro_Rounded/SF-Pro-Rounded-Bold.otf"),
  "SF-Pro-Rounded-Heavy": require("../assets/fonts/SF_Pro_Rounded/SF-Pro-Rounded-Heavy.otf"),
  "SF-Pro-Rounded-Medium": require("../assets/fonts/SF_Pro_Rounded/SF-Pro-Rounded-Medium.otf"),
  "SF-Pro-Rounded-Regular": require("../assets/fonts/SF_Pro_Rounded/SF-Pro-Rounded-Regular.otf"),
  "SF-Pro-Rounded-Semibold": require("../assets/fonts/SF_Pro_Rounded/SF-Pro-Rounded-Semibold.otf"),
  Inter_400Regular,
  Inter_500Medium,
  Inter_600SemiBold,
});
```

## Modify the deeplinking scheme

Edit the `scheme` property in [`app.json`](https://github.com/monad-developers/react-native-privy-pimlico-gas-sponsorship-template/blob/main/app.json) to select your custom deeplinking scheme:

```json title="app.json" theme={null}
{
  "expo": {
    ...
    "scheme": "rnwalletapp",
    ...
  }
}
```

For example, if you set this to `rnwalletapp`, then `rnwalletapp://` URLs would open your app when tapped.

This is a build-time configuration; it has no effect in Expo Go.

## Edit the landing screen

You can edit the landing page by editing [`screens/Home.tsx`](https://github.com/monad-developers/react-native-privy-pimlico-gas-sponsorship-template/blob/main/screens/Home.tsx).

In the `demo` branch, we ended up adding more complex functionality, which is why `Home.tsx` became a [folder](https://github.com/monad-developers/react-native-privy-pimlico-gas-sponsorship-template/tree/demo/screens/Home).

## Modify the package/bundle identifier

When publishing app to the app store, you need to have a unique package/bundle identifier, which you may set in [`app.json`](https://github.com/monad-developers/react-native-privy-pimlico-gas-sponsorship-template/blob/main/app.json).

<Warning>
  Don't forget to change the identifier in Privy dashboard
</Warning>

```json title="app.json" theme={null}
{
  "expo": {
    "name": "rn-gas-sponsorship-app",
    ...
    "ios": {
      "bundleIdentifier": "com.anonymous.rn-wallet-app", <--- Edit this
      ...
    },
    "android": {
      ...
      "package": "com.anonymous.rnwalletapp" <--- Edit this
    },
  }
}
```

## Check out the demo app

If you'd like to try a completed version of the app before you start developing, switch to the `demo` branch:

```bash theme={null}
git checkout demo
```

### Demo app folder structure

```
react-native-privy-pimlico-gas-sponsorship-template/
  ├── app/
  │   ├── _layout.tsx                        # Root layout of the project
  │   └── index.tsx                          # This is the landing page
  │   └── sign-in/                           # Unauthenticated user gets redirected to /sign-in
  ├── assets/
  │   ├── fonts/                             # Custom fonts go here
  │   │   └── SF_Pro_Rounded/                # Custom font example
  │   └── images/
  │       ├── adaptive-icon.png
  │       ├── favicon.png
  │       ├── icon.png
  │       ├── monad-icon.png
  │       ├── monad-logo-inverted.png
  │       ├── monad-logo.png
  │       ├── partial-react-logo.png
  │       └── splash-icon.png
  ├── components/
  │   └── ui/
  ├── constants/
  │   ├── abi.json                           # NFT smart contract ABI
  ├── context/
  │   ├── AuthContext.tsx
  ├── hooks/
  │   ├── useSmartWallet.tsx                 # Hook with smart wallet related functions
  ├── screens/
  │   ├── Email/                             # Screen that asks for email
  │   ├── Home/                              # NFT minting screen (Authenticated users only)
  │   └── OTP/                               # Screen that asks for the OTP code sent to email
  ├── types/
  ├── utils.ts
  ├── entrypoint.js
  ├── app.json
  ├── babel.config.js
  ├── eas.json
  ├── eslint.config.js
  ├── metro.config.js
  ├── package.json
  ├── package-lock.json
  ├── README.md
  ├── tsconfig.json
```

## Learn more

To learn more about developing your project with Expo, Privy, and Monad, check out the following resources:

* Expo [docs](https://docs.expo.dev/) | [guides](https://docs.expo.dev/guides) | [tutorial](https://docs.expo.dev/tutorial/introduction/)
* Privy: [create a wallet](https://docs.privy.io/wallets/wallets/create/create-a-wallet) | [send a transaction](https://docs.privy.io/wallets/using-wallets/ethereum/send-a-transaction) | [sign a transaction](https://docs.privy.io/wallets/using-wallets/ethereum/sign-a-transaction)
* Permissionless: [smart wallet client](https://docs.pimlico.io/references/permissionless/reference/clients/smartAccountClient) | [sending transactions](https://docs.pimlico.io/references/permissionless/reference/smart-account-actions/sendTransaction)
* Monad: [supported tooling and infra](/tooling-and-infra)

Please report any issues [here](https://github.com/monad-developers/react-native-privy-pimlico-gas-sponsorship-template/issues).


# How to use the React Native Thirdweb embedded wallet template
Source: https://docs.monad.xyz/templates/react-native-thirdweb-embedded-wallet



This guide walks you through using the [embedded wallet template](https://github.com/monad-developers/expo-thirdweb-example) which uses [Expo](https://expo.dev/), [React Native](https://reactnative.dev/), and [Thirdweb embedded wallet](https://thirdweb.com/in-app-wallets) to build a mobile app on Monad.

Start developing by editing the files inside the [`app`](https://github.com/monad-developers/expo-thirdweb-example/tree/main/app) directory. This project uses [file-based routing](https://docs.expo.dev/router/introduction).

## Prerequisites

* Node.js
* Yarn or NPM
* a [thirdweb account](https://thirdweb.com/login)

<Accordion title="For Android">
  - JDK 17 (Java Development Kit version 17)
    * Set the `JAVA_HOME` environment variable to point to your JDK 17 installation
    * Example: `export JAVA_HOME=/Library/Java/JavaVirtualMachines/microsoft-17.jdk/Contents/Home`
  - [Android Studio](https://developer.android.com/studio) (API version 35 and above)
    * See [this](https://docs.expo.dev/workflow/android-studio-emulator/) guide to set up Android Studio for Expo
    * Configure Gradle JDK in Android Studio:
      * Open Android Studio Settings/Preferences
      * Navigate to Build, Execution, Deployment → Build Tools → Gradle
      * Set Gradle JDK to JDK 17 (e.g., `JAVA_HOME 17.0.13` - `aarch64 /Library/Java/JavaVirtualMachines/microsoft-17.jdk/Contents/Home`)
</Accordion>

<Accordion title="For iOS">
  * [Xcode](https://apps.apple.com/in/app/xcode/id497799835?mt=12) (Xcode 16 requires OpenSSL version 3.3.2000)
    * See [this](https://docs.expo.dev/workflow/ios-simulator/) guide to set up iOS Simulator for Expo
</Accordion>

## Get started

### Install dependencies

```bash theme={null}
yarn install
```

### Set up the environment variables

Create a copy of `.env.example`:

```bash theme={null}
cp .env.example .env
```

Add your thirdweb client ID to the `.env` file:

```
EXPO_PUBLIC_THIRDWEB_CLIENT_ID=your_client_id_here
```

<Accordion title="How to get `EXPO_PUBLIC_THIRDWEB_CLIENT_ID`">
  1. Navigate to [thirdweb dashboard](https://thirdweb.com/dashboard)
  2. Sign in or create a new account
  3. Create a new project

  <img alt="create new project" />

  <br />

  <img alt="create new project" />

  4. Copy your Client ID from the project settings; Client ID is the value for `EXPO_PUBLIC_THIRDWEB_CLIENT_ID`.

  <img alt="client id" />
</Accordion>

## Start the app

<Note>
  This template comes with a simple transfer example screen, which you can edit by editing the [`index.tsx`](https://github.com/monad-developers/expo-thirdweb-example/blob/main/app/index.tsx) file in the [`app`](https://github.com/monad-developers/expo-thirdweb-example/tree/main/app) folder.
</Note>

### Prebuild for native modules

<Note>
  The thirdweb SDK uses native modules, which means it cannot run on Expo Go. You must build the iOS and Android apps to link the native modules.

  ```bash theme={null}
  npx expo prebuild
  ```
</Note>

For iOS:

```bash theme={null}
yarn ios
```

For Android:

```bash theme={null}
yarn android
```

## Folder structure of the template

```
expo-thirdweb-example/
  ├── app/                                   # Expo router entrypoint 
  │   ├── +html.tsx                          # Web HTML configuration
  │   ├── +native-intent.tsx                 # Deep link handling
  │   ├── +not-found.tsx                     # 404 page
  │   ├── _layout.tsx                        # Root layout with ThirdwebProvider
  │   └── index.tsx                          # Main screen
  ├── assets/
  │   ├── fonts/                             # Custom fonts
  │   └── images/                            # App images and icons
  │       ├── adaptive-icon.png
  │       ├── icon.png
  │       ├── monad-logo.png
  │       └── splash.png
  ├── components/                            # Reusable UI components
  │   ├── ThemedButton.tsx                   # Themed button component
  │   ├── ThemedText.tsx                     # Themed text component
  │   ├── ThemedView.tsx                     # Themed view component
  │   ├── SocialProfileCard.tsx              # Social profile display
  │   └── navigation/
  │       └── TabBarIcon.tsx                 # Tab bar icons
  ├── constants/
  │   ├── Colors.ts                          # App color scheme
  │   └── thirdweb.ts                        # Blockchain configuration
  ├── hooks/                                 # Custom React hooks
  │   ├── useColorScheme.ts                  # Theme detection
  │   └── useThemeColor.ts                   # Theme color utilities
  ├── app.json                               # Expo app configuration
  ├── babel.config.js
  ├── metro.config.js                        # Metro bundler config
  ├── package.json
  ├── tsconfig.json
  └── yarn.lock
```

## Customizing your app

### Modifying the app name

Edit the `name` property in the [`app.json`](https://github.com/monad-developers/expo-thirdweb-example/blob/main/app.json) file:

```json theme={null}
{
   "expo": {
      "name": "your-app-name", // ← Edit this
      ...
   }
}  
```

### Modifying the app icon

You can edit the app icon by replacing the [`assets/images/icon.png`](https://github.com/monad-developers/expo-thirdweb-example/blob/main/assets/images/icon.png) file.

Recommended App Icon size is `1024x1024`.

If you name the icon file something else, edit the `icon` property in [`app.json`](https://github.com/monad-developers/expo-thirdweb-example/blob/main/app.json) accordingly:

```json theme={null}
{
   "expo": {
      "name": "your-app-name",
      ...
      "icon": "./assets/images/icon.png", // ← Change this
      ...
   }
}
```

### Modifying the splash screen

Edit the `splash` object in [`app.json`](https://github.com/monad-developers/expo-thirdweb-example/blob/main/app.json) to modify the splash screen:

```json theme={null}
{
   "expo": {
      "name": "your-app-name",
      ...
      "splash": { // ← Edit this object
         "image": "./assets/images/splash.png",
         "backgroundColor": "#ffffff"
      }
   }  
}
```

### Modifying the deep linking scheme

Edit the `scheme` property in [`app.json`](https://github.com/monad-developers/expo-thirdweb-example/blob/main/app.json) file for your custom deep linking scheme:

```json theme={null}
{
  "expo": {
    ...
    "scheme": "your-app-scheme",
    ...
  }
}
```

For example, if you set this to `mywalletapp`, then `mywalletapp://` URLs would open your app when tapped.

This is a build-time configuration and has no effect in Expo Go.

### Modifying the `package`/`bundleIdentifier`

When publishing to the app store, you need a unique `package`/`bundleIdentifier`. Change it in [`app.json`](https://github.com/monad-developers/expo-thirdweb-example/blob/main/app.json):

```json theme={null}
{
  "expo": {
    "name": "your-app-name",
    ...
    "ios": {
      "bundleIdentifier": "com.yourcompany.yourapp", // ← Edit this
      ...
    },
    "android": {
      ...
      "package": "com.yourcompany.yourapp" // ← Edit this
    },
  }
}
```

<Note>
  **thirdweb Bundle ID Configuration**: Your `bundleIdentifier` and `package` must match the Bundle ID Restrictions configured in your thirdweb project settings.

  1. Go to the [thirdweb dashboard](https://thirdweb.com/dashboard)
  2. Select your project
  3. Navigate to Settings → Bundle ID Restrictions
  4. Add your iOS `bundleIdentifier` and Android `package` to the allowed bundle IDs

  This ensures your app can properly authenticate with thirdweb services.
</Note>

## Learn More

To learn more about developing your project with [Expo](https://expo.dev/), [thirdweb](https://thirdweb.com/in-app-wallets), and [Monad](https://monad.xyz), look at the following resources:

* Expo: [documentation](https://docs.expo.dev/) | [guides](https://docs.expo.dev/guides) | [tutorial](https://docs.expo.dev/tutorial/introduction/)
* thirdweb: [documentation](https://portal.thirdweb.com/typescript/v5) | [templates](https://thirdweb.com/templates) | [YouTube](https://www.youtube.com/c/thirdweb)
* Monad: [supported tooling and infra](https://docs.monad.xyz/tooling-and-infra/)

### Join the Community

Chat with fellow Monad developers and ask questions in [Monad Developer Discord](https://discord.com/invite/monaddev)


# Analytics
Source: https://docs.monad.xyz/tooling-and-infra/analytics



## Provider Summary

<Tabs>
  <Tab title="Mainnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Service</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Description</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Blockaid](https://www.blockaid.io//)</td>
            <td>✅</td>

            <td />

            <td>Real-time detection platform for on-chain monitoring and fraud prevention</td>
          </tr>

          <tr>
            <td>[Birdeye](https://birdeye.so)</td>
            <td>✅</td>
            <td>[Docs](https://docs.birdeye.so/)</td>
            <td>Birdeye platform provides comprehensive multi-market data for cryptocurrency tokens, pulling information from both decentralized exchanges (DEX) and centralized exchanges (CEX). </td>
          </tr>

          <tr>
            <td>[Bubblemaps](https://bubblemaps.io/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.bubblemaps.io/)</td>
            <td>Visual analytics platform to investigate wallets, trace funds, and map token activity in real time</td>
          </tr>

          <tr>
            <td>[CoinGecko](https://www.coingecko.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.coingecko.com/)</td>
            <td>Comprehensive crypto price & market data provider with on-chain DEX data, token discovery, and trading analytics</td>
          </tr>

          <tr>
            <td>[Collab.Land](https://collab.land)</td>
            <td>✅</td>
            <td>[Docs](https://docs.collab.land/)</td>
            <td>Community management tool that supports a wide range of projects, including DAOs, NFT communities, brands, and creators of all sizes</td>
          </tr>

          <tr>
            <td>[DeBank](https://debank.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.cloud.debank.com/)</td>
            <td>DeFi portfolio tracker and analytics platform</td>
          </tr>

          <tr>
            <td>[DeFiLlama](https://defillama.com/)</td>
            <td>✅</td>
            <td>[Docs](https://defillama.com/docs/api)</td>
            <td>Open-source DeFi TVL and analytics platform aggregating data from thousands of protocols across multiple chains. See [How to list a DeFi project](https://docs.llama.fi/list-your-project/submit-a-project)</td>
          </tr>

          <tr>
            <td>[Dune](https://www.dune.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.dune.com/home)</td>
            <td>Datasets and dashboards about on-chain activity</td>
          </tr>

          <tr>
            <td>[Flipside](https://www.flipsidecrypto.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.flipsidecrypto.xyz/)</td>
            <td>AI-powered analytics for on-chain activity</td>
          </tr>

          <tr>
            <td>[InsightX](https://app.insightx.network)</td>
            <td>✅</td>
            <td>[Docs](https://docs.insightx.network/docs)</td>
            <td>Web3 transparency and security platform combining smart contract scanning with real-time holder maps for on-chain trading</td>
          </tr>

          <tr>
            <td>[Matrica](https://matrica.io/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.matrica.io/)</td>
            <td>Cross-chain Web3 social platform and community management solution.</td>
          </tr>

          <tr>
            <td>[Nansen](https://www.nansen.ai/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.nansen.ai/)</td>
            <td>Blockchain analytics platform providing wallet profiling, smart money tracking, and on-chain insights</td>
          </tr>

          <tr>
            <td>[Phalcon Explorer by Blocksec](https://blocksec.com/explorer)</td>
            <td>✅</td>
            <td>[Docs](https://docs.blocksec.com/phalcon/phalcon)</td>
            <td>Explorer for understanding transaction details with fund flow, balance changes, invocation flow, gas usage, and more</td>
          </tr>

          <tr>
            <td>[Tenderly](https://tenderly.co/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.tenderly.co/)</td>
            <td>Comprehensive toolkit including virtual testnets, explorer, debugger, transaction simulator, and monitoring</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>

  <Tab title="Testnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Service</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Description</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Dune](https://www.alchemy.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.dune.com/home)</td>
            <td>Datasets and dashboards about on-chain activity</td>
          </tr>

          <tr>
            <td>[Flipside](https://www.flipsidecrypto.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.flipsidecrypto.xyz/)</td>
            <td>AI-powered analytics for on-chain activity</td>
          </tr>

          <tr>
            <td>[Phalcon](https://blocksec.com/explorer)</td>
            <td>✅</td>
            <td>[Docs](https://docs.blocksec.com/phalcon/phalcon)</td>
            <td>Explorer for understanding transaction details with fund flow, balance changes, invocation flow, gas usage, and more</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>
</Tabs>

## Provider Details

### Birdeye

[Birdeye](https://birdeye.so/) platform provides comprehensive multi-market data for cryptocurrency tokens, pulling information from both decentralized exchanges (DEX) and centralized exchanges (CEX). This allows users to monitor and analyze token performance across different exchange types in real-time, providing a holistic view of the market landscape.

To learn more about the platform, check out the [documentation](https://docs.birdeye.so/).

### Blockaid

[Blockaid](https://blockaid.io) is the real-time detection platform purpose-built for web3 builders
and operators to measure performance, mitigate risk, and prevent theft.

### Bubblemaps

[Bubblemaps](https://bubblemaps.io) is a visual analytics platform to investigate wallets,
trace funds, and map token activity in real time across all chains.

To get started, check out the [docs](https://docs.bubblemaps.io/) or launch the
[app](https://v2.bubblemaps.io/).

### CoinGecko

[CoinGecko API](https://www.coingecko.com/en/api) is one of the most comprehensive and reliable crypto price & market data providers, serving on-chain DEX data across 250+ blockchain networks. CoinGecko provides real-time token prices, market statistics, trading data, OHLCV charts, and token discovery tools including trending pools, new pools, and advanced filtering capabilities.

To get started, visit the [documentation](https://docs.coingecko.com/) for full details, or [sign up](https://www.coingecko.com/en/api/pricing) for a free API key.

### Collab.Land

[Collab.Land](https://docs.collab.land/) is a community management tool that supports a wide range of projects, including DAOs, NFT communities, brands, and creators of all sizes. Our mission is to provide tools that encourage pro-social activity within communities, particularly those that use tokens as a means of membership verification.

To learn more about Collab.Land, check out the [documentation](https://docs.collab.land/).

### DeBank

[DeBank](https://debank.com/) is a DeFi portfolio tracker and analytics platform that helps users manage their crypto assets across multiple chains. It provides comprehensive portfolio tracking, transaction history, and protocol analytics.

To get started, check out the [DeBank documentation](https://docs.cloud.debank.com/)

### DeFiLlama

[DeFiLlama](https://defillama.com/) is the largest open-source Total Value Locked (TVL) and DeFi analytics platform. It aggregates data from thousands of DeFi protocols across multiple chains, providing comprehensive insights into protocol TVL, token prices, yields, and DeFi trends. DeFiLlama offers both a user-friendly dashboard and a robust API for developers.

To get started, visit the [DeFiLlama platform](https://defillama.com/) or check out the [API documentation](https://defillama.com/docs/api).

### Dune

Dune is a blockchain analytics platform that empowers users to query, visualize, and share on-chain data across dozens of blockchains. It uses SQL as its primary query language, enabling analysts, developers, and researchers to build custom dashboards and explore everything from DeFi protocols to NFT markets. With a large library of community-created dashboards and visualizations, Dune fosters collaboration and open access to blockchain intelligence, while also offering premium features such as faster queries and private dashboards for professional teams.

To get started, check out the [Dune documentation](https://docs.dune.com/home)

### Flipside

[Flipside](https://flipsidecrypto.xyz/home/) generates the most reliable and comprehensive blockchain data. All for free.

To get started, check out the [Flipside documentation](https://docs.flipsidecrypto.xyz/).

### InsightX

[InsightX](https://app.insightx.network) delivers actionable transparency and security insights across multiple chains, enabling traders to rapidly assess the risk and potential of on-chain assets in real time.

To get started, check out the [docs](https://docs.insightx.network/docs) or launch the [app](https://app.insightx.network).

### Matrica

[Matrica](https://matrica.io/) is a popular cross-chain web3 social platform and community management solution. It provides essential infrastructure for digital identity and community engagement, primarily focusing on Non-Fungible Tokens (NFTs).

To get started, check out the [documentation](https://docs.matrica.io/)

### Nansen

[Nansen](https://www.nansen.ai/) is a blockchain analytics platform that combines on-chain data with millions of wallet labels to provide actionable insights. It offers features like smart money tracking, wallet profiling, token analytics, and real-time alerts to help users discover opportunities and understand blockchain activity.

To get started, visit the [Nansen platform](https://www.nansen.ai/) or check out the [Nansen documentation](https://docs.nansen.ai/).

### Phalcon

Blocksec [Phalcon Explorer](https://blocksec.com/explorer) is a powerful transaction explorer designed for the DeFi community. It provides comprehensive data on invocation flow, source code, balance changes, transaction fund flows, gas profiler, and state changes. It also supports transaction debugging and transaction simulation. This tool aims to help developers, security researchers, and traders intuitively understand transactions.

To get started, check out the [explorer](https://blocksec.com/explorer) or the [Phalcon documentation](https://docs.blocksec.com/phalcon/explorer).

### Tenderly

[Tenderly](https://tenderly.co) is a comprehensive toolkit for smart contract developers. The
platform offers features like real-time transaction monitoring, advanced debugging with detailed
stack traces, gas profiling, smart contract verification, and simulation environments that allow
developers to fork mainnets and test contract interactions without deploying to live networks.

To get started, check out the [explorer](https://dashboard.tenderly.co/explorer) or the
[documentation](https://docs.tenderly.co).


# Block Explorers
Source: https://docs.monad.xyz/tooling-and-infra/block-explorers



## Block Explorer Summary

<Tabs>
  <Tab title="Mainnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Block explorer</th>
            <th>Powered by</th>
            <th>Status</th>
            <th>URL</th>
            <th>Verifier Type & URL</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>**MonadVision**</td>
            <td>BlockVision</td>
            <td>✅</td>

            <td>
              <CopyToClipboard>[https://monadvision.com/](https://monadvision.com/)</CopyToClipboard>
            </td>

            <td>
              Sourcify: <CopyToClipboard>`https://sourcify-api-monad.blockvision.org`</CopyToClipboard>
            </td>
          </tr>

          <tr>
            <td>**Monadscan**</td>
            <td>Etherscan</td>
            <td>✅</td>

            <td>
              <CopyToClipboard>[https://monadscan.com/](https://monadscan.com/)</CopyToClipboard>
            </td>

            <td>
              Etherscan: <CopyToClipboard>`https://api.monadscan.com/api`</CopyToClipboard>
            </td>
          </tr>

          <tr>
            <td>**SocialScan - Monad**</td>
            <td>Hemera</td>
            <td>✅</td>

            <td>
              <CopyToClipboard>[https://monad.socialscan.io/](https://monad.socialscan.io/)</CopyToClipboard>
            </td>

            <td>
              Etherscan: <CopyToClipboard>`https://api.socialscan.io/monad-mainnet/v1/explorer/command_api/contract`</CopyToClipboard>
            </td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>

  <Tab title="Testnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Block explorer</th>
            <th>Powered by</th>
            <th>Status</th>
            <th>URL</th>
            <th>Verifier Type & URL</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>**MonadVision**</td>
            <td>BlockVision</td>
            <td>✅</td>

            <td>
              <CopyToClipboard>[https://testnet.monadvision.com/](https://testnet.monadvision.com/)</CopyToClipboard>
            </td>

            <td>
              Sourcify: <CopyToClipboard>`https://sourcify-api-monad.blockvision.org`</CopyToClipboard>
            </td>
          </tr>

          <tr>
            <td>**Monadscan**</td>
            <td>Etherscan</td>
            <td>✅</td>

            <td>
              <CopyToClipboard>[https://testnet.monadscan.com/](https://testnet.monadscan.com/)</CopyToClipboard>
            </td>

            <td>
              Etherscan: <CopyToClipboard>`https://api-testnet.monadscan.com/api`</CopyToClipboard>
            </td>
          </tr>

          <tr>
            <td>**SocialScan - Monad**</td>
            <td>Hemera</td>
            <td>✅</td>

            <td>
              <CopyToClipboard>[https://monad-testnet.socialscan.io/](https://monad-testnet.socialscan.io/)</CopyToClipboard>
            </td>

            <td>
              Etherscan: <CopyToClipboard>`https://api.socialscan.io/monad-testnet/v1/explorer/command_api/contract`</CopyToClipboard>
            </td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>
</Tabs>

## UserOp Explorers

<div>
  <table>
    <thead>
      <tr>
        <th>UserOp Explorer</th>
        <th>Status</th>
        <th>URL</th>
        <th>Notes</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>JiffyScan</td>
        <td>✅</td>

        <td>
          <CopyToClipboard>[https://jiffyscan.xyz/?network=monad](https://jiffyscan.xyz/?network=monad)</CopyToClipboard>
        </td>

        <td>UserOp explorer for EIP-4337</td>
      </tr>
    </tbody>
  </table>
</div>

## Detailed Transaction Explorers

<div>
  <table>
    <thead>
      <tr>
        <th>Transaction Explorer</th>
        <th>Status</th>
        <th>URL</th>
        <th>Notes</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Tenderly Explorer</td>
        <td>✅</td>

        <td>
          <CopyToClipboard>[https://dashboard.tenderly.co/explorer](https://dashboard.tenderly.co/explorer)</CopyToClipboard>
        </td>

        <td>Detailed transaction analyzer featuring call stack, balance changes, gas usage, and more</td>
      </tr>

      <tr>
        <td>Blocksec Phalcon Explorer</td>
        <td>✅</td>

        <td>
          <CopyToClipboard>[https://blocksec.com/explorer](https://blocksec.com/explorer)</CopyToClipboard>
        </td>

        <td>Detailed transaction analyzer featuring call stack, balance changes, fund flows, and more</td>
      </tr>
    </tbody>
  </table>
</div>

## Provider Details

### BlockVision

[MonadVision](https://monadvision.com) is built by [BlockVision](https://blockvision.org/), a
leading provider of next-gen data infrastructure and enterprise solutions for the blockchain.
BlockVision is supports the EVM and Sui and specializes in explorer service, RPC nodes, indexing
APIs and validator service.

To get started, visit the [documentation](https://docs.blockvision.org/reference/monad-indexing-api).

### Monadscan

[Monadscan](https://monadscan.com) is built by [Etherscan](https://etherscan.io/) to deliver trusted
and high-performance access to on-chain data. Leveraging Etherscan's industry-leading expertise,
MonadScan provides robust explorer tools, developer-friendly APIs, and reliable infrastructure
tailored for the Monad ecosystem.

To get started, visit the [documentation](https://docs.monadscan.com/).

### SocialScan

[Monad SocialScan](https://monad.socialscan.io/) is a high-performance block explorer built by the
[SocialScan](https://socialscan.io/) team.

To get started, visit the [documentation](https://thehemera.gitbook.io/explorer-api).


# Cross-Chain
Source: https://docs.monad.xyz/tooling-and-infra/cross-chain



## Definitions

At a high level, bridges offer the following features:

<div>
  <table>
    <thead>
      <tr>
        <th>Feature</th>
        <th>Description</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>**Arbitrary Messaging Bridge (AMB)**</td>
        <td>Allows arbitrary messages to be securely relayed from a smart contract on chain 1 to a smart contract on chain 2.<br /><br />
        AMB provides guarantees that messages delivered to chain 2 represent events finalized on chain 1.</td>
      </tr>

      <tr>
        <td>**Token Bridge**</td>
        <td>Allows user to lock native tokens or ERC20 tokens on chain 1 and mint claim tokens on chain 2.<br /><br />
        Bridge maintains the invariant that, for each token minted on chain 2, there exists a corresponding token locked on chain 1.</td>
      </tr>

      <tr>
        <td>**Intents Bridge / Liquidity Layer**</td>
        <td>Allows user to turn in tokens on one chain and quickly redeem tokens on another chain,
        typically relying on drawing on a pool of assets maintained on each side. Provides
        greater immediacy relative to waiting for full finality of an AMB.</td>
      </tr>

      <tr>
        <td>**Bridge Aggregator**</td>
        <td>Aggregates multiple liquidity layers or token bridges, potentially integrating
        swapping as well so that users may receive a different token than the one they input.</td>
      </tr>

      <tr>
        <td>**Chain Abstraction**</td>
        <td>Enables a user experience exempt from the manual processes required to interact with multiple chains.</td>
      </tr>
    </tbody>
  </table>
</div>

## Provider Summary

<Tabs>
  <Tab title="Mainnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Bridge Type</th>
            <th>Contract Addresses</th>
            <th>Explorer</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Across](https://app.across.to/bridge-and-swap)</td>
            <td>✅</td>
            <td>[Docs](https://docs.across.to/)</td>
            <td>Intents Bridge</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/across.jsonc)</td>

            <td />
          </tr>

          <tr>
            <td>[Axelar](https://www.axelar.network/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.axelar.dev/)</td>
            <td>AMB; Token Bridge</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/axelar.jsonc)</td>
            <td>[Axelarscan](https://axelarscan.io/)</td>
          </tr>

          <tr>
            <td>[Bungee](https://www.bungee.exchange/?fromChainId=1\&fromTokenAddress=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\&toChainId=143\&toTokenAddress=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee)</td>
            <td>✅</td>
            <td>[Docs](https://docs.bungee.exchange/)</td>
            <td>Bridge Aggregator</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/bungee.jsonc)</td>

            <td />
          </tr>

          <tr>
            <td>[ChangeHero](https://changehero.io/)</td>
            <td>✅</td>
            <td>[Docs](https://api-docs.changehero.io/)</td>
            <td>Bridge Aggregator</td>

            <td />

            <td />
          </tr>

          <tr>
            <td>[Chainlink CCIP](https://chain.link/cross-chain)</td>
            <td>✅</td>
            <td>[Docs](https://docs.chain.link/ccip)</td>
            <td>AMB; Token Bridge</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/chainlink.jsonc)</td>
            <td>[CCIP Explorer](https://ccip.chain.link/)</td>
          </tr>

          <tr>
            <td>[Circle CCTP](https://www.circle.com/cross-chain-transfer-protocol)</td>
            <td>✅</td>
            <td>[Docs](https://developers.circle.com/cctp)</td>
            <td>Token Bridge</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/circle_cctp.jsonc)</td>

            <td />
          </tr>

          <tr>
            <td>[deBridge](https://app.debridge.com/?inputChain=1\&outputChain=143)</td>
            <td>✅</td>
            <td>[Docs](https://docs.debridge.com/)</td>
            <td>AMB; Token Bridge</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/debridge.jsonc)</td>
            <td>[deExplorer](https://app.debridge.finance/orders)</td>
          </tr>

          <tr>
            <td>[Flashnet](https://flashnet.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.flashnet.xyz/products/orchestration/overview)</td>
            <td>Liquidity Layer</td>

            <td />

            <td />
          </tr>

          <tr>
            <td>[Garden](https://garden.finance/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.garden.finance/)</td>
            <td>Token Bridge for BTC</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/garden.jsonc)</td>

            <td />
          </tr>

          <tr>
            <td>[Gas.zip](https://www.gas.zip)</td>
            <td>✅</td>
            <td>[Docs](https://dev.gas.zip)</td>
            <td>Token Bridge</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/gas_zip.jsonc)</td>
            <td>[Explorer](https://www.gas.zip/scan)</td>
          </tr>

          <tr>
            <td>[Hyperlane](https://nexus.hyperlane.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.hyperlane.xyz)</td>
            <td>AMB; Token Bridge</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/hyperlane_nexus.jsonc)</td>
            <td>[Hyperlane Explorer](https://explorer.hyperlane.xyz)</td>
          </tr>

          <tr>
            <td>[Jumper](https://jumper.exchange)</td>
            <td>✅</td>

            <td />

            <td>Bridge aggregator</td>

            <td />

            <td />
          </tr>

          <tr>
            <td>[LayerZero](https://layerzero.network/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.layerzero.network)</td>
            <td>AMB; Token Bridge</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/layerzero.jsonc)</td>
            <td>[LayerZeroScan](https://testnet.layerzeroscan.com/)</td>
          </tr>

          <tr>
            <td>[Li.fi](https://li.fi/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.li.fi/)</td>
            <td>Bridge aggregator SDK</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/li_fi.jsonc)</td>
            <td>[Li.Fi Scan](https://scan.li.fi/)</td>
          </tr>

          <tr>
            <td>[Mayan](https://swap.mayan.finance/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.mayan.finance/)</td>
            <td>Bridge Aggregator</td>

            <td />

            <td>[Mayan Explorer](https://explorer.mayan.finance/)</td>
          </tr>

          <tr>
            <td>[Particle Network](https://particle.network/)</td>
            <td>✅</td>
            <td>[Docs](https://developers.particle.network/intro/introduction)</td>
            <td>Chain Abstraction</td>

            <td />

            <td>Explorer: `https://universalx.app/activity/details?id=${transactionId}`<br />
            (Replace `transactionId`)</td>
          </tr>

          <tr>
            <td>[Polymer](https://polymerlabs.org/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.polymerlabs.org/docs/build/start/)</td>
            <td>AMB</td>

            <td />

            <td>[PolyScan](https://dashboard.polymerlabs.org/)</td>
          </tr>

          <tr>
            <td>[Relay](https://relay.link/bridge)</td>
            <td>✅</td>
            <td>[Docs](https://docs.relay.link)</td>
            <td>Liquidity Layer</td>

            <td />

            <td>[Transactions](https://relay.link/transactions)</td>
          </tr>

          <tr>
            <td>[SimpleSwap](https://simpleswap.io/)</td>
            <td>✅</td>
            <td>[Docs](https://api.simpleswap.io/docs/getting-started/)</td>
            <td>Bridge Aggregator</td>

            <td />

            <td />
          </tr>

          <tr>
            <td>[Socket](https://www.socket.tech/)</td>
            <td>✅</td>
            <td>[Docs](https://www.socket.tech/)</td>
            <td>AMB</td>

            <td />

            <td>[Socketscan](https://www.socketscan.io/)</td>
          </tr>

          <tr>
            <td>[Squid](https://www.squidrouter.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.squidrouter.com)</td>
            <td>Liquidity Layer</td>

            <td />

            <td>[Explorer (Axelarscan)](https://axelarscan.io)</td>
          </tr>

          <tr>
            <td>[Stargate](https://stargate.finance/?srcChain=ethereum\&srcToken=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48\&dstChain=monad\&dstToken=0x754704Bc059F8C67012fEd69BC8A327a5aafb603)</td>
            <td>✅</td>
            <td>[Docs](https://docs.stargate.finance/)</td>
            <td>Liquidity Layer</td>

            <td />

            <td />
          </tr>

          <tr>
            <td>[Trails](https://trails.build/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.trails.build/)</td>
            <td>Intents Bridge / Liquidity Layer</td>

            <td />

            <td />
          </tr>

          <tr>
            <td>[Wormhole](https://wormhole.com/) / [Portal](https://portalbridge.com/)</td>
            <td>✅</td>
            <td>[Docs](https://wormhole.com/docs)</td>
            <td>AMB; Token Bridge</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/wormhole_portal.jsonc)</td>
            <td>[WormholeScan](https://wormholescan.io/#/?network=Testnet)</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>

  <Tab title="Testnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Bridge Type</th>
            <th>Contract Addresses</th>
            <th>Explorer</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>Axelar</td>
            <td>✅</td>
            <td>[Docs](https://docs.axelar.dev/)</td>
            <td>AMB; Token Bridge</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/testnet/axelar.jsonc)</td>
            <td>[Axelarscan](https://axelarscan.io/)</td>
          </tr>

          <tr>
            <td>Chainlink CCIP</td>
            <td>✅</td>
            <td>[Docs](https://docs.chain.link/ccip)</td>
            <td>AMB; Token Bridge</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/testnet/chainlink_ccip.jsonc)</td>
            <td>[CCIP Explorer](https://ccip.chain.link/)</td>
          </tr>

          <tr>
            <td>[Garden](https://testnet.garden.finance)</td>
            <td>✅</td>
            <td>[Docs](https://docs.garden.finance/)</td>
            <td>Token Bridge</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/testnet/garden.jsonc)</td>

            <td />
          </tr>

          <tr>
            <td>LayerZero</td>
            <td>✅</td>
            <td>[Docs](https://docs.layerzero.network)</td>
            <td>AMB; Token Bridge</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/testnet/layerzero.jsonc)</td>
            <td>[LayerZeroScan](https://testnet.layerzeroscan.com/)</td>
          </tr>

          <tr>
            <td>Polymer</td>
            <td>✅</td>
            <td>[Docs](https://docs.polymerlabs.org/docs/build/start)</td>
            <td>AMB</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/testnet/polymer.jsonc)</td>
            <td>[PolyScan](https://dashboard.sepolia.polymer.zone/)</td>
          </tr>

          <tr>
            <td>Wormhole</td>
            <td>✅</td>
            <td>[Docs](https://wormhole.com/docs)</td>
            <td>AMB; Token Bridge</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/testnet/wormhole_portal.jsonc)</td>
            <td>[WormholeScan](https://wormholescan.io/#/?network=Testnet)</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>
</Tabs>

## Provider Details

### Axelar

[Axelar](https://www.axelar.network/) is an interchain platform that connects blockchains to enable universal web3 transactions. By integrating with Axelar, applications built on Monad can now easily send messages and assets between the 49+ blockchains connected via Axelar.

To learn more about Axelar visit our [docs](https://docs.axelar.dev/) and [GitHub](https://github.com/axelarnetwork/axelar-examples).

To view current transactions and live stats about the Axelar network, please visit the [Axelarscan block explorer](https://axelarscan.io/).

### Bungee Exchange

[Bungee](https://www.bungee.exchange/) provides seamless swaps between any blockchain. With over
\$24B in volume and trusted by major wallets and dApps, Bungee makes moving assets between networks
efficient, secure, and accessible to everyone, powered by the SOCKET.

To learn more, check out the [docs](https://docs.bungee.exchange/).

### ChangeHero

[ChangeHero](https://changehero.io/) is a cross-chain swap platform enabling frictionless asset exchanges across a wide range of networks. Leveraging aggregated liquidity and optimized routing logic, it delivers fast settlement and consistent pricing for any supported pair. Its clean integration pathways and dependable execution make ChangeHero a straightforward tool for powering multi-chain swaps within decentralized applications.

To learn more, check out the [docs](https://api-docs.changehero.io/).

### Chainlink CCIP

[Chainlink](https://chain.link/) Cross-Chain Interoperability Protocol (CCIP) is the standard for cross-chain interoperability. CCIP enables developers to build secure cross-chain apps that can transfer tokens, send messages, and initiate actions across blockchains.

Through the [Cross-Chain Token (CCT)](https://blog.chain.link/ccip-v-1-5-upgrade/) standard, CCIP enables token developers to integrate new and existing tokens with CCIP in a self-serve manner in minutes, without requiring vendor lock-in, hard-coded functions, or external dependencies that may limit future optionality. CCTs support self-serve deployments, full control and ownership for developers, zero-slippage transfers, and enhanced programmability via configurable rate limits and reliability features such as Smart Execution. CCIP is powered by Chainlink decentralized oracle networks (DONs)—a proven standard with a track record of securing tens of billions of dollars and enabling over \$19 trillion in onchain transaction value.

Key CCIP developer tools:

* [CCIP official documentation](https://docs.chain.link/ccip): start integrating CCIP into your cross-chain application.
* [CCIP Token Manager](https://tokenmanager.chain.link/): an intuitive front-end web interface for the deployment of new and management of existing CCTs by their developers, including no-code guided deployments and configuration tools.
* [CCIP SDK](https://docs.chain.link/ccip/ccip-javascript-sdk): a software development kit that streamlines the process of integrating CCIP, allowing developers to use JavaScript to create a token transfer frontend dApp.

Contract Addresses:

* Router (testnet): [`0x5f16e51e3Dcb255480F090157DD01bA962a53E54`](https://testnet.monadvision.com/address/0x5f16e51e3Dcb255480F090157DD01bA962a53E54)
* Router (mainnet): `0x33566fE5976AAa420F3d5C64996641Fc3858CaDB`

### Circle CCTP

[Cross-Chain Transfer Protocol (CCTP)](https://www.circle.com/cross-chain-transfer-protocol) by Circle is a permissionless onchain utility that facilitates USDC transfers securely between supported blockchains via native burning and minting.

Circle created CCTP to improve capital efficiency and minimize trust assumptions when using USDC across blockchains.

CCTP enables developers to build multichain applications that allow users to perform 1:1 transfers of USDC securely across blockchains.

To get started, visit the [Circle CCTP documentation](https://developers.circle.com/cctp)

### deBridge

Build once, interoperate everywhere. deBridge enables secure, fast, and capital-efficient
connectivity across 20+ chains, so you can swap and transfer assets natively, trigger Cross-Chain
logic in seconds, all with chain abstraction and one unified protocol.

To get started, visit the deBridge [documentation](https://docs.debridge.com/) or check out the
[app](https://app.debridge.finance/).

### Flashnet

[Flashnet](https://flashnet.xyz/) builds Bitcoin exchange infrastructure. Its Orchestra API enables cross-chain swaps between stablecoins and native BTC with sub-10 second settlement and ultra-low-fees. Orchestra handles all routing, execution, and settlement, allowing applications on Monad to offer the best native Bitcoin swaps through a single integration.

To get started, visit the [documentation](https://docs.flashnet.xyz/products/orchestration/overview).

### Garden

[Garden](https://garden.finance/) is transforming Bitcoin interoperability with its next-gen bridge. It is built by the renBTC team using an intents based architecture with trustless settlement, enabling cross-chain Bitcoin swaps in as little as 30 seconds with zero custody risk.

In its first year, Garden processed over \$1 billion in volume—proving the market's demand for seamless, cost-effective Bitcoin bridging solutions.

Now, Garden is unlocking a new era of interoperability—supporting non-likewise assets, external liquidity, and a wallet-friendly API—to onboard the next wave of partners and users.

To get started, visit the [documentation](https://docs.garden.finance/).

### Gas.zip

[Gas.zip](https://www.gas.zip/) is a token bridge that enables seamless cross-chain asset transfers.

Contract Address:

* Deployment: `0x9E22ebeC84c7e4C4bD6D4aE7FF6f4D436D6D8390`

### Hyperlane

[Hyperlane](https://hyperlane.xyz/) is a permissionless interoperability protocol for cross-chain communication. It enables message passing and asset transfers across different chains without relying on centralized intermediaries or requiring any permissions.

To get started, visit the [Hyperlane documentation](https://docs.hyperlane.xyz/).

#### Hyperlane Explorer

To view status of your cross chain transactions, please visit the [Hyperlane Explorer](https://explorer.hyperlane.xyz/).

### LayerZero

[LayerZero](https://layerzero.network/) is an omnichain interoperability protocol that enables cross-chain messaging. Applications built on Monad can use the LayerZero protocol to connect to 35+ supported blockchains seamlessly.

To get started with integrating LayerZero, visit the LayerZero [documentation](https://docs.layerzero.network/v1/developers/evm/evm-guides/send-messages) and provided examples on [GitHub](https://github.com/LayerZero-Labs/endpoint-v1-solidity-examples).

### Li.fi

[LI.FI](https://li.fi/) delivers a seamless solution for multi-chain payments and swaps through a single unified API and SDK. By combining access to all liquidity sources—including DEX aggregators, bridges, and solvers—it ensures comprehensive coverage across ecosystems. Its smart routing technology identifies the cheapest and fastest path for any payment or trade, optimizing efficiency and cost.

Additionally, LI.FI offers a plug-and-play [widget](https://docs.li.fi/widget/overview) that enables instant, user-friendly payment flows, making integration simple for developers and intuitive for end users.

To get started, visit [Li.fi documentation](https://docs.li.fi/)

### Particle Network

Particle Network enables chain abstraction through its [Universal Accounts](https://developers.particle.network/universal-accounts/cha/overview) (UA) infrastructure. A UA provides each user with a single account and a combined balance across [multiple chains](https://developers.particle.network/universal-accounts/cha/chains) (EVM and non-EVM).

This allows users to interact with a dApp on Monad even if their assets are held on another network—without manual bridging or chain-switching.

Universal Accounts support:

* Cross-chain deposits and swaps without manual bridging  
* Unified balance aggregation across chains  
* Gas abstraction, allowing transaction fees to be paid in any [supported token](https://developers.particle.network/universal-accounts/cha/chains#primary-assets)

### Mayan

[Mayan](https://mayan.finance/) is a cross-chain swap protocol that enables fast and efficient token transfers across multiple blockchains.

Mayan provides seamless token bridging with optimized routing to ensure the best execution for cross-chain transfers.

To get started, visit the [Mayan documentation](https://docs.mayan.finance/) or explore transactions on the [Mayan Explorer](https://explorer.mayan.finance/).

### Polymer

[Polymer](https://www.polymerlabs.org/) is an interoperability protocol tailor made for multi-rollup applications. It places control in the hands of the builder, by combining cross-chain merkle proofs and a simple API to allow application builders to flexibly adopt Polymer's infrastructure for their own needs. Prove any action. Cross-chain.

To get started visit the [Polymer documentation](https://docs.polymerlabs.org/docs/build/start).

### Relay

[Relay](https://relay.link/bridge) is the fastest and cheapest way to bridge and transact across chains, offering a multichain payments network that makes swapping and transacting across hundreds of blockchains delightfully simple. Since its launch in 2024, Relay has served over 5 million users, processed 50 million transactions, and facilitated more than \$5 billion in volume across 85+ networks.

At its core, Relay combines two powerful components: instant, low-cost cross-chain intents powered by the Relay Protocol, and comprehensive DEX meta-aggregation spanning 85 chains (including Monad), ensuring users always get the best execution.

To get started, visit the [Relay documentation](https://docs.relay.link/what-is-relay)

### SimpleSwap

[SimpleSwap](https://simpleswap.io/) is a privacy-focused, self-custody crypto exchange aggregator with 3000+ currencies and cross-chain support across 130+ blockchains. It offers competitive rates and timing, significantly simplifying buying and exchanging crypto with sign-up-free solutions.

To learn more, check out the [docs](https://api.simpleswap.io/docs/getting-started/).

### Socket

[SOCKET Protocol](https://socket.tech) is the first chain-abstraction protocol, empowering
developers to build applications that seamlessly leverage multiple blockchains. It enables the
creation of chain-abstracted apps that interact across chains as if operating on a single one.

To get started, visit the SOCKET [documentation](https://docs.socket.tech/).

### Squid

[Squid](https://www.squidrouter.com/) creates unlimited access for anything in crypto. Squid can be used to seamlessly swap tokens from 100+ chains across including Monad.

Squid’s API, SDK, and Widgets offer ease of integration for projects building on any chain to enable cross-chain functionality in just 1 click.

### Stargate

[Stargate Finance](https://stargate.finance) is a cross-chain bridge protocol that enables users
to transfer native assets between different blockchains with instant guaranteed finality using
unified liquidity pools.

To get started, visit the Stargate [documentation](https://docs.stargate.finance/).

### Trails

[Trails](https://trails.build/) is the universal intents SDK for 1-click crypto transactions. Trails lets users transact with any wallet, any token, across any chain by orchestrating swaps, bridges, and payments behind the scenes. Developers can integrate pay, swap, fund, and checkout flows through a single SDK with cross-chain execution, gasless transactions, and the ability to pay gas with any token including USDC.

To get started, visit the [documentation](https://docs.trails.build/).

### Wormhole

[Wormhole](https://wormhole.com/) is a cross-chain interoperability protocol that provides secure communication between blockchains. Monad uses two Wormhole products: **Messaging** and **NTT (Native Token Transfers)**.

By integrating Wormhole, a Monad application can access users and liquidity on > 30 chains and > 7 different platforms.

#### Wormhole Messaging

Wormhole Messaging is a generic messaging protocol that enables secure cross-chain communication and arbitrary data transfer between blockchains.

To get started with Wormhole Messaging:

* [Quickstart Guide](https://wormhole.com/docs/products/messaging/get-started/)
* [GitHub Examples](https://github.com/wormhole-foundation/demo-wormhole-messaging)

#### Wormhole NTT (Native Token Transfers)

Wormhole NTT (Native Token Transfer) framework enables seamless cross-chain token movement without wrapping or liquidity pools, allowing projects to maintain token ownership and customize their cross-chain token deployment.

To get started with Wormhole NTT:

* [Quickstart Guide](https://wormhole.com/docs/products/token-transfers/native-token-transfers/get-started/)
* [GitHub Examples](https://github.com/wormhole-foundation/demo-ntt-connect)

For end-users looking to bridge assets, you can use [Wormhole Portal Bridge](https://portalbridge.com).

For more information on integrating Wormhole, visit their [documentation](https://wormhole.com/docs/).

Contract Addresses for Monad Testnet:

* Core: [`0xBB73cB66C26740F31d1FabDC6b7A46a038A300dd`](https://testnet.monadvision.com/address/0xBB73cB66C26740F31d1FabDC6b7A46a038A300dd)
* Relayer: [`0x362fca37E45fe1096b42021b543f462D49a5C8df`](https://testnet.monadvision.com/address/0x362fca37E45fe1096b42021b543f462D49a5C8df)


# Custody
Source: https://docs.monad.xyz/tooling-and-infra/custody



<Note>
  See also [Institutional Wallets](/tooling-and-infra/wallets/institutional-wallets).
</Note>

## Provider Summary

The Monad blockchain and MON token are supported by a number of leading custody providers.

<div>
  <table>
    <thead>
      <tr>
        <th>Service</th>
        <th>Supported (Mainnet)</th>
        <th>Docs</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>[Anchorage Digital](https://www.anchorage.com/)</td>
        <td>✅</td>

        <td />
      </tr>

      <tr>
        <td>[BitGo](https://www.bitgo.com/)</td>
        <td>✅</td>
        <td>[Docs](https://developers.bitgo.com/)</td>
      </tr>

      <tr>
        <td>[Coinbase Custody](https://www.coinbase.com/custody)</td>
        <td>✅</td>
        <td>[Docs](https://docs.cdp.coinbase.com/prime/introduction/welcome)</td>
      </tr>

      <tr>
        <td>[Fireblocks](https://www.fireblocks.com/)</td>
        <td>✅</td>
        <td>[Docs](https://developers.fireblocks.com/)</td>
      </tr>

      <tr>
        <td>[HexTrust](https://www.hextrust.com/)</td>
        <td>✅</td>

        <td />
      </tr>
    </tbody>
  </table>
</div>

## Provider Details

### Anchorage Digital

As the trusted custodian for leading institutions, Anchorage Digital offers a solution built to
deliver the highest standards of security, mitigating the risk of human error and attack vectors
while offering participation in digital assets through regulated entities.

Clients can access Anchorage Digital's custody services through Anchorage Digital Bank, the only
federally chartered crypto bank in the U.S. and an unequivocal qualified custodian, or Anchorage
Digital Singapore, a licensed Major Payment Institution by the Monetary Authority of Singapore (MAS).

Learn more at [anchorage.com](https://www.anchorage.com/).

### BitGo

BitGo is the digital asset infrastructure company, delivering custody, wallets, staking, trading,
financing, and settlement services from regulated cold storage. Since its founding in 2013, BitGo
has been focused on accelerating the transition of the financial system to a digital asset economy.
With a global presence and multiple regulated entities, BitGo serves thousands of institutions,
including many of the industry's top brands, exchanges, platforms, and millions of investors.

For more information, visit [bitgo.com](https://www.bitgo.com/).

### Coinbase Custody

Coinbase Custody provides a secure, institutional-grade cold storage solution for digital assets,
enabling institutions to safely store and manage crypto assets with advanced security measures and
operational controls.

Learn more at [coinbase.com/custody](https://www.coinbase.com/custody).

### Fireblocks

Fireblocks is the world's most trusted digital asset infrastructure company, empowering
organizations of all sizes to build, manage and grow their business on the blockchain.
Secure and manage your digital assets with cutting-edge security technology, execute day-to-day
treasury operations with automated workflows and connect seamlessly to exchanges, on/off-ramps,
and DeFi protocols to access liquidity and earn yield.

Learn more at [fireblocks.com](https://www.fireblocks.com/).

### HexTrust

Hex Trust is a licensed and regulated financial institution for digital assets, providing
institutional-grade Markets, Custody, and Staking solutions. Trusted by builders, investors, and
service providers, Hex Trust integrates directly with protocols and platforms to deliver secure,
compliant, and scalable digital asset infrastructure.

Learn more at [hextrust.com](https://www.hextrust.com/).


# Tooling and Infrastructure
Source: https://docs.monad.xyz/tooling-and-infra/index



Many leading Ethereum developer tools support Monad Testnet. The enclosing pages survey each category of tools and attempt a feature comparison.

See also the [`protocols`](https://github.com/monad-crypto/protocols) repo for a listing of contract addresses for each protocol.

<CardGroup>
  <Card title="Analytics" href="/tooling-and-infra/analytics">
    Tools for understanding app activity on Monad
  </Card>

  <Card title="Block Explorers" href="/tooling-and-infra/block-explorers">
    View accounts and transactions; read and write contracts
  </Card>

  <Card title="Cross-Chain" href="/tooling-and-infra/cross-chain">
    Bridges and protocols for cross-chain communication
  </Card>

  <Card title="Custody" href="/tooling-and-infra/custody">
    Institutional-grade custody solutions for secure asset management
  </Card>

  <Card title="Indexers" href="/tooling-and-infra/indexers">
    Common transformations for blockchain data + custom calculators
  </Card>

  <Card title="Onramps" href="/tooling-and-infra/onramps">
    Ways to convert between fiat and crypto
  </Card>

  <Card title="Oracles" href="/tooling-and-infra/oracles">
    Data feeds bringing off-chain information on-chain
  </Card>

  <Card title="RPC Providers" href="/tooling-and-infra/rpc-providers">
    Endpoints for interacting with Monad
  </Card>

  <Card title="Toolkits" href="/tooling-and-infra/toolkits">
    Development frameworks and tools for building on Monad
  </Card>

  <Card title="Wallets" href="/tooling-and-infra/wallets">
    Tools for storing private keys, signing transactions, and managing assets
  </Card>

  <Card title="Wallet Infrastructure" href="/tooling-and-infra/wallet-infra">
    Embedded wallets and smart accounts
  </Card>
</CardGroup>


# Common Data
Source: https://docs.monad.xyz/tooling-and-infra/indexers/common-data



## Features

In order to improve developer understanding of feature coverage, we have collected the most common features offered by providers:

| Feature         | Sub-Feature | Description                                                                                                                    |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Chain data**  |             | Raw data (blocks, transactions, logs, traces) in SQL-like format. Transactions and logs may optionally be decoded based on ABI |
| **Balances**    | Native      | Native token holdings of an address, real-time or snapshot. May include price annotations                                      |
|                 | ERC20       | ERC20 holdings of an address, real-time or snapshot. May include price annotations                                             |
|                 | NFT         | NFT (ERC721 or ERC1155) holdings of an address, real-time or snapshot                                                          |
| **Transfers**   | Native      | Native token transfers involving a particular address. May include price annotations                                           |
|                 | ERC20       | ERC20 transfers involving a particular address. May include price annotations                                                  |
|                 | NFT         | NFT transfers involving a particular address                                                                                   |
| **DEX trades**  |             | Normalized trade data across major DEXes                                                                                       |
| **Market data** |             | Market data for ERC20s                                                                                                         |

Balances are nontrivial because each ERC20 and NFT collection stores its balances in contract storage. Transfers are nontrivial because they frequently occur as subroutines. Annotating with prices and normalizing across DEXes add additional convenience.

## Access models

* **APl**: Data lives on provider's servers; make queries via API
* **Stream**: Data is replicated to your environment

## Provider Summary

<Tabs>
  <Tab title="Mainnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Supported services</th>
            <th>Access model</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Allium](https://www.allium.so/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.allium.so/)</td>
            <td>**Chain data** (blocks, transactions, logs, traces, contracts) (via [Explorer](https://docs.allium.so/app/overview) (historical) and [Datastreams](https://docs.allium.so/realtime/kafka-blockchains-70+) (realtime) products)<br />
            **Transfers** (native, ERC20, and NFTs) (via [Developer](https://docs.allium.so/data-products-real-time/allium-developer/wallet-apis/activities) (realtime) product)</td>
            <td>API, except streaming for Datastreams product</td>
          </tr>

          <tr>
            <td>[Birdeye Data Services](https://bds.birdeye.so/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.birdeye.so/)</td>
            <td>[**DEX trades**](https://docs.birdeye.so/reference/get-defi-price)<br />
            [**Market data**](https://docs.birdeye.so/reference/get-defi-v3-token-market-data) for tokens<br />
            [**Token metadata**](https://docs.birdeye.so/reference/get-defi-tokenlist) and analytics</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[Codex](https://www.codex.io/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.codex.io/)</td>
            <td>Token- and trading-centric data:<br />
            [Token](https://docs.codex.io/recipes/discover-tokens) charts, metadata, prices, events, and detailed stats<br />
            NFT metadata, events, and detailed stats</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[Dune Sim](https://sim.dune.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.sim.dune.com/)</td>
            <td>**Chain data:** Transactions, logs (raw or decoded)<br />
            **Balances:** Native, ERC20</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[GoldRush](https://goldrush.dev/) (by Covalent)</td>
            <td>✅</td>
            <td>[Docs](https://goldrush.dev/docs/overview)</td>
            <td>**Chain data:** Blocks, enriched transactions and logs (raw and decoded)<br />
            **Balances:** native, ERC20, NFTs & Portfolio<br />
            **Transactions:** Full historical with decoded transfer events</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[Goldsky](https://goldsky.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.goldsky.com/)</td>
            <td>**Chain data:** blocks, enriched transactions, logs, and traces via [Mirror](https://docs.goldsky.com/mirror/introduction). [Fast scan](https://docs.goldsky.com/mirror/sources/direct-indexing#backfill-vs-fast-scan) is supported</td>
            <td>API; Streaming</td>
          </tr>

          <tr>
            <td>[Mobula](https://mobula.io/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.mobula.io/introduction)</td>
            <td>**Chain data**<br />
            **Balances:** [native, ERC20](https://docs.mobula.io/rest-api-reference/endpoint/wallet-portfolio) and [NFT](https://docs.mobula.io/rest-api-reference/endpoint/wallet-nfts)<br />
            **Transfers:** [native, ERC20](https://docs.mobula.io/rest-api-reference/endpoint/wallet-transactions) and NFT<br />
            [**DEX trades**](https://docs.mobula.io/rest-api-reference/endpoint/market-trades-pair)<br />
            [**Market data**](https://docs.mobula.io/rest-api-reference/endpoint/market-data) for ERC20s</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[Moralis](https://moralis.com)</td>
            <td>✅</td>
            <td>[Docs](https://docs.moralis.com)</td>
            <td>**Chain Data:** [blocks](https://docs.moralis.com/web3-data-api/evm/reference/blockchain-api#get-blocks), [transactions](https://docs.moralis.com/web3-data-api/evm/reference/blockchain-api#get-transactions), [logs](https://docs.moralis.com/rpc-nodes/reference/eth_getLogs)<br />
            **Balances:** [native, ERC20,](https://docs.moralis.com/web3-data-api/evm/reference/wallet-api/get-wallet-token-balances-price?address=0xcB1C1FdE09f811B294172696404e88E658659905\&chain=eth\&token_addresses=\[]\&limit=50) [NFTs](https://docs.moralis.com/web3-data-api/evm/reference/wallet-api#get-wallet-nft-balances) (with metadata, logos, spam / low-liquidity filtering)<br />
            [**Token Prices**](https://docs.moralis.com/web3-data-api/evm/reference/price-api#get-token-prices): USD valuation included<br />
            **Transfers:** [native, ERC20](https://docs.moralis.com/web3-data-api/evm/reference/wallet-api/get-transactions-by-wallet?address=0x1f9090aaE28b8a3dCeaDf281B0F12828e676c326\&chain=eth\&limit=50\&order=DESC), and [NFTs](https://docs.moralis.com/web3-data-api/evm/reference/wallet-api/get-wallet-nft-transfers?address=0xcB1C1FdE09f811B294172696404e88E658659905\&chain=eth\&contract_addresses=\[]\&format=decimal\&limit=25\&order=DESC) (decoded events), [wallet history](https://docs.moralis.com/web3-data-api/evm/reference/wallet-api/get-wallet-history?address=0xcB1C1FdE09f811B294172696404e88E658659905\&chain=eth\&order=DESC\&limit=25) (categorized transfers + approvals)<br />
            [**Streams**](https://docs.moralis.com/streams-api/evm): real-time address/contract monitoring via webhooks<br />
            [**Datashare**](https://moralis.com/datashare/): Export massive crypto datasets<br />
            [**RPC Nodes**](https://docs.moralis.com/rpc-nodes): Raw blockchain data access</td>
            <td>APIs, Streaming (webhooks)</td>
          </tr>

          <tr>
            <td>[Quicknode](https://www.quicknode.com/)</td>
            <td>✅</td>
            <td>[Docs](https://www.quicknode.com/docs/streams/getting-started)</td>
            <td>[**Streams**](https://www.quicknode.com/streams), [**Webhooks**](https://www.quicknode.com/webhooks)</td>
            <td>Streams, Webhooks</td>
          </tr>

          <tr>
            <td>[Rarible](https://rarible.org/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.rarible.org/)</td>
            <td>[**NFT data**](https://docs.rarible.org/reference): metadata; holdings by address (current and historic); trade data; spam scoring</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[Sequence](https://sequence.xyz/)</td>
            <td>❓</td>
            <td>[Docs](https://docs.sequence.xyz/solutions/indexer/overview)</td>
            <td>**Balances**: native, ERC20, and NFT<br />
            **Transfers**: native, ERC20, and NFTs<br />
            **Other:** Transaction history; webhooks</td>
            <td>API; Streaming (webhooks)</td>
          </tr>

          <tr>
            <td>[SQD](https://sqd.ai/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.sqd.ai/)</td>
            <td>**Chain data:** blocks, transactions, logs, traces, state diffs (via [Portal](https://docs.sqd.dev/en/portal/evm/overview) and [Subsquid SDK](https://github.com/subsquid/squid-sdk))<br />
            **Other:** [MCP server](https://docs.sqd.dev/en/ai/mcp-server) for AI agent integration</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[SonarX](https://sonarx.com)</td>
            <td>✅</td>

            <td />

            <td>**Chain data:** blocks, transactions, logs, traces<br />
            **Transfers:** tokens, NFTs, internal transfers, net internal transfers (with/without pricing)<br />
            **Balances:** PIT and current balances<br />
            **DEX trades** and balances<br />
            **Other:** Approvals and failed transactions</td>
            <td>Cloud Platforms Data Shares (Snowflake, BigQuery, Azure, Databricks); Streaming (Kafka); File delivery (CSV, Parquet, Iceberg); API</td>
          </tr>

          <tr>
            <td>[thirdweb](https://thirdweb.com/)</td>
            <td>✅</td>
            <td>[Docs](https://insight-api.thirdweb.com/guide/getting-started)</td>
            <td>**Chain data:** [blocks](https://insight-api.thirdweb.com/reference#tag/blocks), [transactions](https://insight-api.thirdweb.com/guide/blueprints#transactions-blueprint), [logs](https://insight-api.thirdweb.com/guide/blueprints#events-blueprint), [contracts](https://insight-api.thirdweb.com/reference#tag/contracts)<br />
            [**Balances**](https://insight-api.thirdweb.com/guide/blueprints#tokens-blueprint): native, ERC20, NFTs<br />
            **Other:** [NFTs](https://insight-api.thirdweb.com/reference#tag/nfts)</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[Unmarshal](https://unmarshal.io/)</td>
            <td>❓</td>
            <td>[Docs](https://docs.unmarshal.io)</td>
            <td>[**Balances**](https://docs.unmarshal.io/reference/fungibleerc20tokenbalances): ERC20 and NFT<br />
            [**Transactions**](https://docs.unmarshal.io/reference/get-v3-chain-address-address-transactions) with price annotations<br />
            [**NFT API**](https://docs.unmarshal.io/reference/get-v2-chain-address-address-nft-transactions) (transactions and metadata)</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[Zerion](https://zerion.io/)</td>
            <td>✅</td>
            <td>[Docs](https://zerion.io/api)</td>
            <td>[**Wallet info**](https://developers.zerion.io/reference/wallets)<br />
            [**Balances**](https://developers.zerion.io/reference/listwalletpositions) (native, ERC20, and NFTs)<br />
            [**Transactions**](https://developers.zerion.io/reference/listwallettransactions) (multichain with prices)<br />
            **Other:** [Portfolio](https://developers.zerion.io/reference/getwalletportfolio), [PNL](https://developers.zerion.io/reference/getwalletpnl#/) and [Historical Positions](https://developers.zerion.io/reference/getwalletchart)<br />
            [Notification Webhooks](https://developers.zerion.io/v1.0-subscriptions/reference/createsubscriptionwallettransactions)</td>
            <td>API; Webhooks</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>

  <Tab title="Testnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Supported services</th>
            <th>Access model</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Allium](https://www.allium.so/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.allium.so/)</td>
            <td>**Chain data** (blocks, transactions, logs, traces, contracts) (via [Explorer](https://docs.allium.so/app/overview) (historical) and [Datastreams](https://docs.allium.so/realtime/kafka-blockchains-70+) (realtime) products)<br />
            **Transfers** (native, ERC20, and NFTs) (via [Developer](https://docs.allium.so/data-products-real-time/allium-developer/wallet-apis/activities) (realtime) product)</td>
            <td>API, except streaming for Datastreams product</td>
          </tr>

          <tr>
            <td>[Codex](https://www.codex.io/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.codex.io/)</td>
            <td>Token- and trading-centric data:<br />
            [Token](https://docs.codex.io/recipes/discover-tokens) charts, metadata, prices, events, and detailed stats (see [dashboard](https://www.defined.fi/tokens/discover?network=mon-test))<br />
            [NFT](https://docs.codex.io/api-reference/queries/getnftpool) metadata, events, and detailed stats</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[Dune Sim](https://sim.dune.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.sim.dune.com/)</td>
            <td>**Chain data:** Transactions, logs (raw or decoded)<br />
            **Balances:** Native, ERC20</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[GoldRush](https://goldrush.dev/) (by Covalent)</td>
            <td>✅</td>
            <td>[Docs](https://goldrush.dev/docs/overview)</td>
            <td>**Chain data:** Blocks, enriched transactions and logs (raw and decoded)<br />
            **Balances:** native, ERC20, NFTs & Portfolio<br />
            **Transactions:** Full historical with decoded transfer events</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[Goldsky](https://goldsky.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.goldsky.com/)</td>
            <td>**Chain data:** blocks, enriched transactions, logs, and traces via [Mirror](https://docs.goldsky.com/mirror/introduction). [Fast scan](https://docs.goldsky.com/mirror/sources/direct-indexing#backfill-vs-fast-scan) is supported</td>
            <td>API; Streaming</td>
          </tr>

          <tr>
            <td>[Mobula](https://mobula.io/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.mobula.io/introduction)</td>
            <td>**Chain data**<br />
            **Balances:** [native, ERC20](https://docs.mobula.io/rest-api-reference/endpoint/wallet-portfolio) and [NFT](https://docs.mobula.io/rest-api-reference/endpoint/wallet-nfts)<br />
            **Transfers:** [native, ERC20](https://docs.mobula.io/rest-api-reference/endpoint/wallet-transactions) and NFT<br />
            [**DEX trades**](https://docs.mobula.io/rest-api-reference/endpoint/market-trades-pair)<br />
            [**Market data**](https://docs.mobula.io/rest-api-reference/endpoint/market-data) for ERC20s</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[Moralis](https://moralis.com)</td>
            <td>❌</td>
            <td>[Docs](https://docs.moralis.com/)</td>
            <td>**Chain data**<br />
            **Balances:** [native, ERC20](https://docs.moralis.com/web3-data-api/evm/reference/wallet-api/get-wallet-token-balances-price?address=0xcB1C1FdE09f811B294172696404e88E658659905\&chain=eth\&token_addresses=\[]\&limit=50) and [NFT](https://docs.moralis.com/web3-data-api/evm/reference/wallet-api/get-nfts-by-wallet?address=0xff3879b8a363aed92a6eaba8f61f1a96a9ec3c1e\&chain=eth\&format=decimal\&limit=50\&token_addresses=\[]\&normalizeMetadata=true\&media_items=false\&include_prices=false)<br />
            **Transfers:** [native, ERC20](https://docs.moralis.com/web3-data-api/evm/reference/wallet-api/get-transactions-by-wallet?address=0x1f9090aaE28b8a3dCeaDf281B0F12828e676c326\&chain=eth\&limit=50\&order=DESC)<br /></td>
            <td>API</td>
          </tr>

          <tr>
            <td>[Quicknode](https://www.quicknode.com/)</td>
            <td>✅</td>
            <td>[Docs](https://www.quicknode.com/docs/streams/getting-started)</td>
            <td>[**Streams**](https://www.quicknode.com/streams), [**Webhooks**](https://www.quicknode.com/webhooks)</td>
            <td>Streams, Webhooks</td>
          </tr>

          <tr>
            <td>[Sequence](https://sequence.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.sequence.xyz/solutions/indexer/overview)</td>
            <td>**Balances**: native, ERC20, and NFT<br />
            **Transfers**: native, ERC20, and NFTs<br />
            **Other:** Transaction history; webhooks</td>
            <td>API; Streaming (webhooks)</td>
          </tr>

          <tr>
            <td>[SQD](https://sqd.ai/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.sqd.ai/)</td>
            <td>**Chain data:** blocks, transactions, logs, traces, state diffs (via [Portal](https://docs.sqd.dev/en/portal/evm/overview) and [Subsquid SDK](https://github.com/subsquid/squid-sdk))<br />
            **Other:** [MCP server](https://docs.sqd.dev/en/ai/mcp-server) for AI agent integration</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[SonarX](https://sonarx.com)</td>
            <td>✅</td>

            <td />

            <td>**Chain data:** blocks, transactions, logs, traces<br />
            **Transfers:** tokens, NFTs, internal transfers, net internal transfers (with/without pricing)<br />
            **Balances:** PIT and current balances<br />
            **DEX trades** and balances<br />
            **Other:** Approvals and failed transactions</td>
            <td>Cloud Platforms Data Shares (Snowflake, BigQuery, Azure, Databricks); Streaming (Kafka); File delivery (CSV, Parquet, Iceberg); API</td>
          </tr>

          <tr>
            <td>[thirdweb](https://thirdweb.com/)</td>
            <td>✅</td>
            <td>[Docs](https://insight-api.thirdweb.com/guide/getting-started)</td>
            <td>**Chain data:** [blocks](https://insight-api.thirdweb.com/reference#tag/blocks), [transactions](https://insight-api.thirdweb.com/guide/blueprints#transactions-blueprint), [logs](https://insight-api.thirdweb.com/guide/blueprints#events-blueprint), [contracts](https://insight-api.thirdweb.com/reference#tag/contracts)<br />
            [**Balances**](https://insight-api.thirdweb.com/guide/blueprints#tokens-blueprint): native, ERC20, NFTs<br />
            **Other:** [NFTs](https://insight-api.thirdweb.com/reference#tag/nfts)</td>
            <td>API</td>
          </tr>

          <tr>
            <td>[Zerion](https://zerion.io/)</td>
            <td>✅</td>
            <td>[Docs](https://zerion.io/api)</td>
            <td>[**Wallet info**](https://developers.zerion.io/reference/wallets)<br />
            [**Balances**](https://developers.zerion.io/reference/listwalletpositions) (native, ERC20, and NFTs)<br />
            [**Transactions**](https://developers.zerion.io/reference/listwallettransactions) (multichain with prices)<br />
            **Other:** [Portfolio](https://developers.zerion.io/reference/getwalletportfolio), [PNL](https://developers.zerion.io/reference/getwalletpnl#/) and [Historical Positions](https://developers.zerion.io/reference/getwalletchart)<br />
            [Notification Webhooks](https://developers.zerion.io/v1.0-subscriptions/reference/createsubscriptionwallettransactions)</td>
            <td>API; Webhooks</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>
</Tabs>

## Provider Details

### Allium

[Allium](https://www.allium.so/) is an Enterprise Data Platform that serves accurate, fast, and simple blockchain data. Allium offers near real-time Monad Testnet data for infrastructure needs and enriched Monad Testnet data (NFT, DEX, Decoded) for research and analytics.

Allium supports data delivery to multiple [destinations](https://docs.allium.so/integrations/overview), including Snowflake, Bigquery, Databricks, and AWS S3. To get started, contact Allium [here](https://www.allium.so/contact).

| Product                                                                          | Description / mechanism                            | Monad Testnet data supported                                                                                          |
| -------------------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| [Explorer](https://docs.allium.so/app/overview)                                  | Historical data (postgres/API)                     | Chain data: blocks, transactions, logs, traces, contracts                                                             |
| [Developer](https://docs.allium.so/data-products-real-time/allium-developer)     | Real-time data (postgres/API)                      | [Transfers](https://docs.allium.so/products/allium-developer/wallet-apis/activities) (native, ERC20, ERC721, ERC1155) |
| [Datastreams](https://docs.allium.so/data-products-real-time/allium-datastreams) | Real-time data (streaming - Kafka, PubSub, or SNS) | Chain data: blocks, transactions, logs, traces, contracts                                                             |

### Birdeye Data Services

[Birdeye Data Services](https://bds.birdeye.so/) (BDS) provides comprehensive multi-market data APIs for cryptocurrency tokens, pulling information from decentralized exchanges (DEX). BDS offers real-time and historical token prices, market data, OHLCV charts, trade history, and token metadata.

To get started, visit the [documentation](https://docs.birdeye.so/) or sign up at [bds.birdeye.so](https://bds.birdeye.so/).

### Codex

[Codex](https://www.codex.io/) API provides fast and accurate enriched data, meticulously structured to easily plug straight into your application.

To get started, visit the [documentation](https://docs.codex.io/) or sign up for an API key at [dashboard.codex.io](https://dashboard.codex.io/).

### Dune Sim

[Dune Sim](https://sim.dune.com/) makes building multi-chain application seamless. These APIs power
several of the best teams building on crypto.

Available APIs:

* **Token Balances**: Access accurate and fast real time balances of native and ERC20 tokens of
  accounts on EVM blockchains.
* **Transactions**: Access transactions for accounts in real time across EVM blockchains.

To get started, visit the [documentation](https://docs.sim.dune.com/).

### GoldRush (by Covalent)

[GoldRush](https://goldrush.dev/) provides multichain data APIs and toolkits for easy web3 development across 100+ chains including Monad.

GoldRush offers structured onchain data, including multichain wallet balances, full transaction histories and decoded log events, for building apps and powering AI Agents. Join hundreds of top teams that leverage GoldRush to cut down their development time and scale their multichain offerings with enterprise-grade onchain data.

To get started, visit the [documentation](https://goldrush.dev/docs/overview) or [sign up](https://goldrush.dev/platform/auth/register/) for an API key.

### Goldsky

[Goldsky](https://goldsky.com/) is the go-to data indexer for web3 builders, offering high-performance subgraph hosting and realtime data replication pipelines.

Goldsky offers two core self-serve products that can be used independently or in conjunction to power your data stack.

* **Subgraphs**: Flexible indexing with typescript, with support for webhooks and more.
* **Mirror**: Get live blockchain data in your database or message queues with a single yaml config.

To get started, visit the [documentation](https://docs.goldsky.com/) or follow the [quickstart](https://docs.goldsky.com/subgraphs/guides/create-a-no-code-subgraph) guide.

### Mobula

[Mobula](https://mobula.io/) provides curated datasets for builders: market data with Octopus, wallets data, metadata with Metacore, alongside with REST, GraphSQL & SQL interfaces to query them.

You can get started playing around with the [API endpoints](https://docs.mobula.io/rest-api-reference/introduction) for free, and sign-up to the API dashboard once you need API keys (queries without API keys aren’t production-ready).

To get started, visit the [documentation](https://docs.mobula.io/introduction).

### Moralis

[Moralis](https://moralis.com) is the unified way to fetch, stream, and export onchain data. Access fast, enriched Data APIs for wallets, tokens, prices, holders, NFTs, transfers, liquidity, and full transaction & wallet history - plus real-time Streams and RPC nodes. Teams use Moralis as their crypto data layer to get complete, reliable onchain data without running indexers or maintaining pipelines.

To get started, visit the [documentation](https://docs.moralis.com) or [sign up](https://admin.moralis.com/register) for a free API key.

### Quicknode

[Streams](https://www.quicknode.com/streams) is a managed, push-based service for blockchain data streaming with guaranteed delivery of live and sequential historical data. Receive raw or filtered data (e.g., specific contract events) pushed to your destination: webhook, S3, Postgres, or Snowflake.

To get started, visit the [documentation](https://www.quicknode.com/docs/streams) for detailed instructions.

[Webhooks](https://www.quicknode.com/webhooks) provide real-time notifications for blockchain events on Monad. Track smart contract activity, wallet transactions, and more using ready-to-use templates or your own custom JavaScript.

To get started, visit the [documentation](https://www.quicknode.com/docs/webhooks) for detailed instructions.

### Rarible

[Rarible](https://rarible.org) offers an comprehensive toolkit for anyone interacting with
NFTs, including marketplaces and wallets. Rarible's API for NFT data includes collection/item
metadata, trades, holdings by account (both current and historical), and spam scoring.

Rarible also offers aggregated order books from major NFT marketplaces like OpenSea, Rarible, and
Blur, as well as an NFT trading SDK.

To get started, check out the [documentation](https://docs.rarible.org/).

### Sequence

[Sequence](https://sequence.xyz) [Indexer](https://docs.sequence.xyz/solutions/indexer/overview)
offers real-time balances, transfers, NFTs, prices, and contract events across EVM chains with
webhooks and subscriptions and sub-300 ms queries. Use it as your production read layer for on-chain
apps.

Indexer gives you low-latency reads across EVM chains: balances and portfolio, token and NFT
ownership, transfers and logs, prices, and contract events. It is built for enterprise-grade
production and supports developers of all sizes. Cursor-based pagination, filters, webhooks,
and event subscriptions: All in a scalable, 99.99% uptime service.

To get started, visit the
[quickstart](https://docs.sequence.xyz/solutions/indexer/overview#quickstart) guide.

### SQD

[SQD](https://sqd.ai/) is a decentralized data indexing platform (formerly Subsquid) that provides access to onchain data through its permissionless data lake. SQD offers chain data (blocks, transactions, logs, traces, state diffs) for Monad via the [Portal API](https://docs.sqd.dev/en/portal/evm/overview) and the [Subsquid SDK](https://github.com/subsquid/squid-sdk) for building custom indexers.

SQD also offers a [Portal MCP server](https://docs.sqd.dev/en/ai/mcp-server) that enables AI agents to query onchain data directly.

To get started, visit the [documentation](https://docs.sqd.ai/) or explore the [Portal API](https://docs.sqd.dev/en/portal/evm/overview).

### SonarX

[SonarX](https://sonarx.com) delivers structured blockchain data with historical and real-time coverage across 100+ blockchains with a focus on data quality, in line with our proprietary Data Quality Framework.

Enterprises, Institutions and Builders can query full historical datasets in their preferred cloud warehouse (Snowflake, BigQuery, Azure), receive file drops in csv, parquet, iceberg formats, or run real-time pipelines with Kafka streaming. Supported services include chain data (blocks, transactions, logs, traces, decoded logs and traces), staking, and DEX trades and balances.

With ready-to-use tables and flexible delivery, SonarX helps power analytics, trading, accounting, and applications without the burden of maintaining indexing pipelines.

To get started, visit the console at [console.sonarx.com](https://console.sonarx.com).

### thirdweb

thirdweb [Insight](https://thirdweb.com/insight) is a fast, reliable and fully customizable way for developers to index, transform & query onchain data across 30+ chains. Insight includes out-of-the-box APIs for transactions, events, tokens. Developers can also define custom API schemas, or blueprints, without the need for ABIs, decoding, RPC, or web3 knowledge to fetch blockchain data.

thirdweb Insight can be used to fetch:

* all assets (ERC20, ERC721, ERC115) for a given wallet address
* all sales of skins on your in-game marketplace
* monthly protocol fees in the last 12 months
* the total cost of all accounts created using ERC-4337
* metadata for a given token (ERC20, ERC721, ERC115)
* daily active wallets for your application or game
* and so much more

To get started, sign up for a [free thirdweb account](https://thirdweb.com/team) and visit the [thirdweb Insight documentation](https://insight.thirdweb.com/reference)

### Unmarshal

[Unmarshal](https://unmarshal.io/) is a leading decentralized multi-chain data network, enabling Web3 projects to access accurate, real-time blockchain data across 55+ chains (including Monad Testnet).

Leveraging AI-driven solutions, Unmarshal enhances data accessibility and insights for RWA, DePIN, AI Agents, DeFi, NFT, and GameFi platforms. Through robust APIs, notification services, and no-code indexers, it empowers dApps to deliver seamless user experiences while ensuring transparency, scalability, and innovation at the forefront of Web3 advancements.

To get started, visit the [documentation](https://docs.unmarshal.io) or reach out at [support@unmarshal.io](mailto:support@unmarshal.io).

### Zerion

The [Zerion API](https://zerion.io/api) can be used to build feature-rich web3 apps, wallets, and protocols with ease. Across all major blockchains, you can access wallets, assets, and chain data for web3 portfolios. Zerion's infrastructure supports all major chains!

To get started, visit the [documentation](https://zerion.io/api).


# Indexers
Source: https://docs.monad.xyz/tooling-and-infra/indexers/index



<CardGroup>
  <Card title="Common Data" href="/tooling-and-infra/indexers/common-data">
    Raw transactional data and frequently-used derived data like balances, transfers, and DEX trades
  </Card>

  <Card title="Indexing Frameworks" href="/tooling-and-infra/indexers/indexing-frameworks">
    Tools that allow developers to build custom calculators in response to events
  </Card>
</CardGroup>

<br />

The blockchain can be thought of as a list of blocks, transactions, and logs, as well as a series of global states. Indexers compute common transformations on this data to save downstream consumers the cost and complexity of doing so.

There are two main types of indexer services:

1. **[Data for common use cases](/tooling-and-infra/indexers/common-data)**: raw data (blocks, transactions, logs, traces) and derived data for common use cases (token balances, NFT holdings, DEX trades), computed across the entire blockchain
2. **[Indexing Frameworks](/tooling-and-infra/indexers/indexing-frameworks)** enable devleopers to build custom calculators for a specific smart contract

## Data for common use cases

Data providers offer raw and transformed data for common use cases via API or by streaming to your local environment.

Raw data includes:

* blocks, transactions, logs, traces (potentially decoded using contract ABIs)

Transformed data includes:

* balances (native tokens, ERC20s, NFTs)
* transfers (native tokens, ERC20s, NFTs)
* DEX trades
* market data
* and more

See [Common Data](/tooling-and-infra/indexers/common-data) for a fuller list of features and providers.

## Indexing Frameworks

Smart contract indexers are custom off-chain calculators for a specific smart contract. They maintain additional off-chain state and perform additional computation. Since blockchain data is public, anyone may deploy a subgraph involving state or logs from any smart contract.

See [Indexing Frameworks](/tooling-and-infra/indexers/indexing-frameworks) for a list of features and providers.


# Indexing Frameworks
Source: https://docs.monad.xyz/tooling-and-infra/indexers/indexing-frameworks



## Background

**Smart contract indexers** are off-chain calculators that compute additional metrics specific to one smart contract. Calculators can be thought of as extensions to a smart contract that do additional off-chain computation and maintain additional off-chain state.

*Simple example:* the [UniswapV2Pair contract](https://github.com/Uniswap/v2-core/blob/master/contracts/UniswapV2Pair.sol) maintains minimal state for the pool and emits `Mint`, `Burn`, and `Swap` events. If we wanted to know the cumulative number and volume of swaps on the pair, we could write and deploy a custom indexer instead of adding additional state variables and computation to the contract.

Smart contract indexers typically produce object schemas using the [GraphQL](https://graphql.org/) schema language.

Smart contract indexing services usually provide a hosted service so that users can deploy their indexers without having to run their own infrastructure.

## Provider Summary

<Tabs>
  <Tab title="Mainnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Language</th>
            <th>Framework</th>
            <th>Known for</th>
            <th>Hosted service</th>
            <th>Decen- tralized hosted service</th>
            <th>Onchain & offchain data</th>
            <th>Web- socket subscr- iptions</th>
            <th>Query layer</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Envio](https://envio.dev/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.envio.dev/docs/HyperIndex/overview)</td>
            <td>JavaScript, TypeScript, Rescript</td>
            <td>[HyperIndex](https://github.com/enviodev/hyperindex)</td>
            <td>Performance and scale</td>
            <td>✅</td>
            <td>❌</td>
            <td>✅</td>
            <td>✅</td>
            <td>GraphQL</td>
          </tr>

          <tr>
            <td>[Ghost](https://tryghost.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.tryghost.xyz/ghostgraph/overview)</td>
            <td>Solidity</td>
            <td>GhostGraph</td>
            <td>Solidity development</td>
            <td>✅</td>
            <td>❌</td>
            <td>❌</td>
            <td>❌</td>
            <td>GraphQL</td>
          </tr>

          <tr>
            <td>[Goldsky](https://goldsky.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.goldsky.com/)</td>
            <td>AssemblyScript, SQL, TypeScript</td>
            <td>[subgraph](https://github.com/graphprotocol/graph-node), [ETL pipelines](https://docs.goldsky.com/mirror/introduction)</td>
            <td>Real-time data streaming</td>
            <td>✅</td>
            <td>❌</td>
            <td>✅ (with [Compose](https://docs.goldsky.com/compose/introduction))</td>
            <td>❌</td>
            <td>GraphQL and SQL ([in your db](https://docs.goldsky.com/mirror/sinks/postgres))</td>
          </tr>

          <tr>
            <td>[Ormi](https://ormilabs.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.ormilabs.com/)</td>
            <td>Assembly- Script</td>
            <td>[subgraph](https://github.com/graphprotocol/graph-node)</td>
            <td>High performance and custom environments</td>
            <td>✅</td>
            <td>❌</td>
            <td>❌</td>
            <td>❌</td>
            <td>Custom GraphQL</td>
          </tr>

          <tr>
            <td>[Sentio](https://www.sentio.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.sentio.xyz/docs/quickstart)</td>
            <td>JavaScript, TypeScript</td>
            <td>[sentio-sdk](https://github.com/sentioxyz/sentio-sdk)</td>
            <td>Performance; integrated alerting and visualization</td>
            <td>✅</td>
            <td>❌</td>
            <td>✅</td>
            <td>❌</td>
            <td>GraphQL & SQL</td>
          </tr>

          <tr>
            <td>[SQD](https://sqd.ai/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.sqd.ai)</td>
            <td>TypeScript</td>
            <td>[squid-sdk](https://github.com/subsquid/squid-sdk)</td>
            <td>Performance, decentralization</td>
            <td>✅</td>
            <td>Partial[^1]</td>
            <td>✅</td>
            <td>✅</td>
            <td>GraphQL</td>
          </tr>

          <tr>
            <td>[Streamingfast](https://thegraph.market/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.substreams.dev/tutorials/intro-to-tutorials/monad)</td>
            <td>Rust</td>
            <td>[Substreams](https://substreams.dev)</td>
            <td>Performance, low latency and custom sinks</td>
            <td>✅</td>
            <td>❌</td>
            <td>❌</td>
            <td>✅ (gRPC subscription)</td>
            <td>gRPC, 20+ db types supported</td>
          </tr>

          <tr>
            <td>[SubQuery](https://subquery.network/)</td>
            <td>✅</td>
            <td>[Docs](https://academy.subquery.network/)</td>
            <td>TypeScript</td>
            <td>[subql](https://github.com/subquery/subql)</td>
            <td>Decentral- ization</td>
            <td>✅</td>
            <td>✅</td>
            <td>✅</td>
            <td>❌</td>
            <td>GraphQL</td>
          </tr>

          <tr>
            <td>[The Graph](https://thegraph.com/)</td>
            <td>✅</td>
            <td>[Docs](https://thegraph.com/docs/en/subgraphs/quick-start/)</td>
            <td>Assembly- Script</td>
            <td>[subgraph](https://github.com/graphprotocol/graph-node)</td>
            <td>The original indexer</td>
            <td>✅</td>
            <td>✅</td>
            <td>❌</td>
            <td>❌</td>
            <td>Custom GraphQL</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*

    [^1]: SQD hosted service is semi-decentralized: the data lake is decentralized, but indexers run on proprietary infra.
  </Tab>

  <Tab title="Testnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Language</th>
            <th>Framework</th>
            <th>Known for</th>
            <th>Hosted service</th>
            <th>Decen- tralized hosted service</th>
            <th>Onchain & offchain data</th>
            <th>Web- socket subscr- iptions</th>
            <th>Query layer</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Envio](https://envio.dev/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.envio.dev/docs/HyperIndex/overview)</td>
            <td>JavaScript, TypeScript, Rescript</td>
            <td>[HyperIndex](https://github.com/enviodev/hyperindex)</td>
            <td>Performance and scale</td>
            <td>✅</td>
            <td>❌</td>
            <td>✅</td>
            <td>✅</td>
            <td>GraphQL</td>
          </tr>

          <tr>
            <td>[Ghost](https://tryghost.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.tryghost.xyz/ghostgraph/overview)</td>
            <td>Solidity</td>
            <td>GhostGraph</td>
            <td>Solidity development</td>
            <td>✅</td>
            <td>❌</td>
            <td>❌</td>
            <td>❌</td>
            <td>GraphQL</td>
          </tr>

          <tr>
            <td>[Goldsky](https://goldsky.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.goldsky.com/)</td>
            <td>AssemblyScript, SQL, TypeScript</td>
            <td>[subgraph](https://github.com/graphprotocol/graph-node), [ETL pipelines](https://docs.goldsky.com/mirror/introduction)</td>
            <td>Real-time data streaming</td>
            <td>✅</td>
            <td>❌</td>
            <td>✅ (with [Compose](https://docs.goldsky.com/compose/introduction))</td>
            <td>❌</td>
            <td>GraphQL and SQL ([in your db](https://docs.goldsky.com/mirror/sinks/postgres))</td>
          </tr>

          <tr>
            <td>[Ormi](https://ormilabs.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.ormilabs.com/)</td>
            <td>Assembly- Script</td>
            <td>[subgraph](https://github.com/graphprotocol/graph-node)</td>
            <td>High performance and custom environments</td>
            <td>✅</td>
            <td>❌</td>
            <td>❌</td>
            <td>❌</td>
            <td>Custom GraphQL</td>
          </tr>

          <tr>
            <td>[SQD](https://sqd.ai/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.sqd.ai)</td>
            <td>TypeScript</td>
            <td>[squid-sdk](https://github.com/subsquid/squid-sdk)</td>
            <td>Performance, decentralization</td>
            <td>✅</td>
            <td>Partial[^1]</td>
            <td>✅</td>
            <td>✅</td>
            <td>GraphQL</td>
          </tr>

          <tr>
            <td>[SubQuery](https://subquery.network/)</td>
            <td>✅</td>
            <td>[Docs](https://academy.subquery.network/)</td>
            <td>TypeScript</td>
            <td>[subql](https://github.com/subquery/subql)</td>
            <td>Decentral- ization</td>
            <td>✅</td>
            <td>✅</td>
            <td>✅</td>
            <td>❌</td>
            <td>GraphQL</td>
          </tr>

          <tr>
            <td>[The Graph](https://thegraph.com/)</td>
            <td>✅</td>
            <td>[Docs](https://thegraph.com/docs/en/subgraphs/quick-start/)</td>
            <td>Assembly- Script</td>
            <td>[subgraph](https://github.com/graphprotocol/graph-node)</td>
            <td>The original indexer</td>
            <td>✅</td>
            <td>✅</td>
            <td>❌</td>
            <td>❌</td>
            <td>Custom GraphQL</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*

    [^1]: SQD hosted service is semi-decentralized: the data lake is decentralized, but indexers run on proprietary infra.
  </Tab>
</Tabs>

## Provider Details

### Envio

[Envio](https://envio.dev/) 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 Monad Testnet. The indexed data is easily accessible through custom GraphQL queries, providing developers with the flexibility and power to retrieve specific information.

[Envio HyperSync](https://docs.envio.dev/docs/HyperIndex/hypersync) is an indexed layer of the Monad Testnet blockchain for the hyper-speed syncing of historical data (JSON-RPC bypass). What would usually take hours to sync \~100,000 events can now be done in the order of less than a minute.

Designed to optimize the user experience, Envio offers automatic code generation, flexible language support, multi-chain data aggregation, and a reliable, cost-effective hosted service.

To get started, visit the [documentation](https://docs.envio.dev/docs/HyperIndex/overview) or follow the [quickstart](https://docs.envio.dev/docs/HyperIndex/contract-import) guide.

### Ghost

With [GhostGraph](https://tryghost.xyz/graph), you can write your indexers in the same language as your contracts: Solidity. This means less context switching and faster time to market.

To get started, visit the [documentation](https://docs.tryghost.xyz/ghostgraph/overview/) or check out the [tutorial](/guides/indexers/ghost).

Services supported:

* GhostGraph

### Goldsky

[Goldsky](https://goldsky.com/) handles the hard parts of building on crypto rails: real-time data and reliable connectivity, so you can ship better products, faster.

Goldsky offers two core self-serve products that can be used independently or in conjunction to power your data stack.

* [**Subgraphs**](https://docs.goldsky.com/subgraphs/deploying-subgraphs): Instant GraphQL APIs for Monad data with zero maintenance.
* [**Mirror**](https://docs.goldsky.com/mirror/create-a-pipeline): Stream realtime Monad data directly into your database.

To take your app to the next level, build using Goldsky’s next gen data pipeline engine:

* [**Turbo**](https://docs.goldsky.com/turbo-pipelines/introduction): *Really fast decoding*, infinite filters, dynamic tables, and live data inspection.

To get started, visit the [documentation](https://docs.goldsky.com/introduction) for guided walkthroughs.

### Ormi

[Ormi](https://ormilabs.com/) delivers real-time blockchain data that is fast, accurate, and ready for production.

It keeps data synced to the tip of the chain and makes it instantly accessible through Subgraphs and APIs without the need to manage indexing infrastructure.

Ormi provides two core products:

* **Subgraphs**: Smart contract data at sub-second latency with zero throttling.
* **Data API**: Real-time and historical blockchain data delivered through flexible, high-speed API endpoints.

Ormi supports shared, dedicated, and fully custom environments that provide isolated performance for high-demand workloads.

Start building by exploring the [documentation](https://docs.ormilabs.com/) or following the [Quickstart Guide](https://docs.ormilabs.com/subgraphs/quickstart).

### Sentio

[Sentio](https://www.sentio.xyz/) offers blazing-fast native processors and seamless subgraph hosting on Monad. With powerful database capabilities, intuitive dashboards, and comprehensive API functionalities, Sentio is built to provide an exceptional developer experience.

To get started, check out the [docs](https://docs.sentio.xyz/docs/readme) or visit the [quickstart](https://docs.sentio.xyz/docs/quickstart) guide.

### SQD

[SQD](https://sqd.ai/) enables permissionless, cost-efficient access to petabytes of high-value Web3 data.

SQD is a decentralized hyper-scalable data platform optimized for providing efficient, permissionless access to large volumes of data. It currently serves historical on-chain data, including event logs, transaction receipts, traces, and per-transaction state diffs.

To get started, visit the [documentation](https://docs.sqd.ai) or see this [quickstart](https://docs.sqd.ai/sdk/quickstart/) with [examples](https://docs.sqd.ai/sdk/examples) on how to easily create subgraphs via Subsquid.

### Streamingfast

[Streamingfast](https://thegraph.market/) builds massively scalable software
for processing and indexing blockchain data. StreamingFast has built two
foundational technologies:

* [Firehose](https://firehose.streamingfast.io/): a blockchain data extraction layer designed to
  process complete blockchain histories using a files-based and streaming-first approach.
* [Substreams](https://docs.substreams.dev/): a data transformation layer which   allows developers
  to write rust modules that can be composed like building blocks, building upon community-developed
  modules. Substreams can output data to various destinations including PosgreSQL, MongoDB\< Kafka,
  and flat files.

To get started, check out the [docs](https://docs.substreams.dev/), or visit the
[tutorial](https://docs.substreams.dev/tutorials/intro-to-tutorials/monad) for generating your
first substream on Monad.

### SubQuery

[SubQuery](https://subquery.network/) is a leading blockchain data indexer that provides developers with fast, flexible, universal, open source and decentralised APIs for web3 projects. SubQuery SDK allows developers to get rich indexed data and build intuitive and immersive decentralised applications in a faster and more efficient way. SubQuery supports many ecosystems including Monad, Ethereum, Cosmos, Near, Polygon, Polkadot, Algorand, and more.

One of SubQuery's advantages is the ability to aggregate data not only within a chain but across multiple blockchains all within a single project. This allows the creation of feature-rich dashboard analytics and multi-chain block scanners.

#### Useful resources:

* [SubQuery Academy (Documentation)](https://academy.subquery.network/)
* [Monad Testnet Starter](https://github.com/subquery/ethereum-subql-starter/tree/main/Monad/monad-testnet-starter)
* [Monad Testnet Quick Start Guide](https://academy.subquery.network/indexer/quickstart/quickstart_chains/monad.html)

For technical questions and support reach out to us `start@subquery.network`

### The Graph

[The Graph](https://thegraph.com/) is an indexing protocol that provides an easy way to query blockchain data through APIs known as subgraphs.

With The Graph, you can benefit from:

* **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.
* **Customization**: Define your own logic for transforming & storing blockchain data. Reuse subgraphs published by other developers on The Graph Network.

Follow this [quick-start](https://thegraph.com/docs/en/subgraphs/quick-start/) guide to create, deploy, and query a subgraph within 5 minutes.


# Onramps
Source: https://docs.monad.xyz/tooling-and-infra/onramps



Onramps are services that allow users to convert fiat currency into cryptocurrency. They serve
as an entrypoint for users who want to participate in the Monad ecosystem.

## Provider Summary

<div>
  <table>
    <thead>
      <tr>
        <th>Provider</th>
        <th>Status</th>
        <th>Docs</th>
        <th>Support notes</th>
        <th>Regions supported</th>
        <th>Currencies & Countries Supported</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>[AhoraCrypto](https://ahoracrypto.com/)</td>
        <td>✅</td>
        <td>[Docs](https://ahoracrypto.gitbook.io/ahoracrypto)</td>
        <td>[Onramp API](https://ahoracrypto.gitbook.io/ahoracrypto/api/payment-intent)<br />
        Offramp docs coming soon<br />
        [Widget](https://ahoracrypto.gitbook.io/ahoracrypto/widget/web-widget)</td>
        <td>Africa, APAC, Europe, LATAM, Middle East, North America, South Asia</td>
        <td>14+ local payment methods, 50+ cryptocurrencies, 50+ countries</td>
      </tr>

      <tr>
        <td>[Alchemy Pay](https://alchemypay.org/)</td>
        <td>✅</td>
        <td>[Docs](https://alchemypay.readme.io/)</td>
        <td>[Onramp](https://alchemypay.readme.io/docs/alchemypay-on-ramp)<br />
        [NFT Checkout](https://alchemypay.readme.io/docs/alchemy-pay-nft-checkout)<br />
        [Crypto Payment](https://alchemypay.readme.io/docs/alchemy-pay-crypto-payment)</td>
        <td>APAC, Africa, LATAM</td>
        <td>[Payment Methods](https://alchemypay.notion.site/Payment-Methods-Coverages-Other-Details-Table-fb3b4f5c68c04b9b8619c48aad31277d)</td>
      </tr>

      <tr>
        <td>[alfred](https://www.alfredpay.io/)</td>
        <td>⌛️</td>
        <td>[Docs](https://alfredpay.readme.io/docs/overview)</td>
        <td>[API Endpoints](https://alfredpay.readme.io/reference/customers-1)</td>
        <td>LATAM, US, EU, APAC</td>
        <td>[Supported Currencies](https://alfredpay.readme.io/docs/payment-methods-supported)</td>
      </tr>

      <tr>
        <td>[Banxa](https://banxa.com/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.banxa.com/)</td>
        <td>[Onramp API](https://docs.banxa.com/docs/tutorial)<br />
        [Offramp API](https://docs.banxa.com/docs/off-ramp)</td>
        <td>US, Canada, UK, EU, Australia</td>
        <td>[Supported Currencies](https://support.banxa.com/en/support/solutions/articles/44002280809-which-fiat-currencies-does-banxa-support-)<br />
        [Supported Countries](https://support.banxa.com/en/support/solutions/articles/44002216505-what-countries-are-supported-by-banxa-)</td>
      </tr>

      <tr>
        <td>[Brale](https://brale.xyz/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.brale.xyz/)</td>
        <td>[Onramp](https://docs.brale.xyz/guides/fiat-to-stablecoin-onramp)<br />
        [Offramp](https://docs.brale.xyz/guides/stablecoin-to-fiat-offramp)</td>

        <td />

        <td>[Supported Currencies](https://docs.brale.xyz/coverage/value-types)</td>
      </tr>

      <tr>
        <td>[BTC Direct](https://onramp.btcdirect.eu/)</td>
        <td>✅</td>
        <td>[Docs](https://developer.btcdirect.eu/)</td>
        <td>[Onramp](https://developer.btcdirect.eu/api/v1/#/Buy)<br />
        [Offramp](https://developer.btcdirect.eu/api/v1/#/Sell)<br />
        [Widget](https://developer.btcdirect.eu/widget/getting-started)</td>
        <td>SEPA / Europe</td>
        <td>EUR<br />
        [Supported Cryptocurrencies](https://developer.btcdirect.eu/widget/supported-cryptocurrencies.html)</td>
      </tr>

      <tr>
        <td>[Capa](https://capa.fi/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.capa.fi/docs/getting-started)</td>
        <td>[Onramp API](https://docs.capa.fi/docs/on-ramp)<br />
        [Offramp API](https://docs.capa.fi/docs/off-ramp)</td>
        <td>LATAM</td>
        <td>[Supported Currencies](https://docs.capa.fi/docs/on-ramp#select-the-fiat-currency%3A)</td>
      </tr>

      <tr>
        <td>[Chainrails](https://chainrails.io)</td>
        <td>✅</td>
        <td>[Docs](https://docs.chainrails.io)</td>
        <td>[API Endpoints](https://docs.chainrails.io/api-reference/introduction)</td>
        <td>Africa, APAC, LATAM, EU, US, Australia</td>
        <td>[Supported Currencies](https://docs.chainrails.io/essentials/integrations)</td>
      </tr>

      <tr>
        <td>[Coinbase Onramp & Offramp](https://docs.cdp.coinbase.com/onramp/introduction/welcome)</td>
        <td>✅</td>
        <td>[Docs](https://docs.cdp.coinbase.com/onramp/introduction/welcome)</td>
        <td>[Onramp API](https://docs.cdp.coinbase.com/onramp-&-offramp/onramp-apis/onramp-overview)<br />
        [Offramp API](https://docs.cdp.coinbase.com/onramp-&-offramp/offramp-apis/offramp-overview)</td>
        <td>US, Canada, Brazil, EU, Singapore, Australia, New Zealand</td>
        <td>ACH, debit cards, Apple Pay, and cash/crypto balances are supported in the US. Debit cards and cash/crypto balances are supported everywhere else.</td>
      </tr>

      <tr>
        <td>[Coindisco](https://coindisco.com/)</td>
        <td>✅</td>
        <td>[Docs](https://coindisco.gitbook.io/coindisco)</td>
        <td>[Buy|Sell Widget](https://coindisco.gitbook.io/coindisco/widget-integration/widget-integration-methods)<br />
        [White Label API](https://coindisco.gitbook.io/coindisco/widget-integration/white-label-api-integration)</td>
        <td>240+ countries and territories</td>
        <td>[Supported Payment Methods](https://coindisco.gitbook.io/coindisco/platform-support/supported-payment-methods)<br />
        [Supported Fiat Currencies](https://coindisco.gitbook.io/coindisco/supported-fiat-currencies)<br />
        [Supported Countries](https://coindisco.gitbook.io/coindisco/supported-countries)</td>
      </tr>

      <tr>
        <td>[Coinflow](https://coinflow.cash/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.coinflow.cash/)</td>
        <td>[API Endpoints](https://docs.coinflow.cash/guides/getting-started/getting-started-with-checkout)</td>
        <td>APAC, LATAM, US, EU</td>
        <td>[Supported Countries - Withdraw](https://docs.coinflow.cash/guides/payouts/available-countries)<br />
        [Supported Countries - Global Push Card](https://docs.coinflow.cash/guides/payouts/available-countries/supported-countries-for-global-push-to-card)</td>
      </tr>

      <tr>
        <td>[Daimo](https://daimo.com/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.daimo.com/introduction)</td>
        <td>[Quickstart](https://docs.daimo.com/quickstart)</td>
        <td>Canada, US</td>
        <td>[Payment Methods](https://docs.daimo.com/guides/fiat#supported-rails)</td>
      </tr>

      <tr>
        <td>[El Dorado](https://eldorado.io/)</td>
        <td>✅</td>
        <td>[Docs](https://api.eldorado.io/)</td>
        <td>[API Overview](https://api.eldorado.io/#api-overview)</td>
        <td>LATAM</td>
        <td>[Supported Countries](https://api.eldorado.io/concepts/countries)<br />
        [Supported Currencies](https://api.eldorado.io/concepts/currencies)</td>
      </tr>

      <tr>
        <td>[FinchPay](https://finchpay.io/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.finchpay.io/)</td>
        <td>[Widget URL](https://docs.finchpay.io/docs/url-structure)<br />
        [API](https://docs.finchpay.io/docs/partners-api)</td>
        <td>EU, 150+ countries</td>
        <td>Local payment methods: Brazil (PicPay, PIX), Mexico (SPEI and OXXO), Indonesia (virtual accounts BRI & Mandiri, e-wallets DANA/OVO)</td>
      </tr>

      <tr>
        <td>[Flashnet](https://flashnet.xyz/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.flashnet.xyz/products/orchestration/overview)</td>

        <td />

        <td>US Only, no NY</td>
        <td>[Supported Chains & Assets](https://docs.flashnet.xyz/products/orchestration/overview#which-chains-and-assets-are-supported)</td>
      </tr>

      <tr>
        <td>[Fonbnk](https://www.fonbnk.com/)</td>
        <td>⌛️</td>
        <td>[Docs](https://docs.fonbnk.com/)</td>
        <td>[Onramp](https://docs.fonbnk.com/on-ramp)<br />
        [Offramp](https://docs.fonbnk.com/off-ramp)</td>
        <td>Africa, LATAM</td>
        <td>[Supported Countries & Payment Methods](https://www.fonbnk.com/)</td>
      </tr>

      <tr>
        <td>[Fun.xyz](https://fun.xyz/)</td>
        <td>✅</td>
        <td>[Contact](https://fun.xyz/contact)</td>

        <td />

        <td>✅</td>

        <td />
      </tr>

      <tr>
        <td>[Guardarian](https://guardarian.com/)</td>
        <td>✅</td>
        <td>[Docs](https://guardarian.com/api-doc)</td>
        <td>[API](https://guardarian.com/api-doc)</td>
        <td>LATAM, EU, Africa, APAC</td>
        <td>[Supported Countries & Payment Methods](https://guardarian.com/payment-methods)<br />
        [Supported Countries Fees](https://guardarian.notion.site/guardarian-supported-countries-fees)<br />
        [Supported Currencies](https://guardarian.com/currencies)</td>
      </tr>

      <tr>
        <td>[Halliday](https://halliday.xyz/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.halliday.xyz/pages/home)</td>
        <td>[API Quickstart](https://docs.halliday.xyz/pages/api-quickstart)<br />
        [Payments SDK](https://docs.halliday.xyz/pages/payments-sdk-docs)</td>
        <td>US, EU, LATAM, APAC</td>
        <td>Credit or debit card, ACH, Apple Pay, Google Pay, or a CEX balance</td>
      </tr>

      <tr>
        <td>[HoneyCoin](https://honeycoin.app/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.honeycoin.app/reference/welcome)</td>
        <td>[Onramp](https://docs.honeycoin.app/reference/onramp)<br />
        [Offramp](https://docs.honeycoin.app/reference/crypto-off-ramp)</td>
        <td>Africa</td>
        <td>[Supported Countries & Limits](https://docs.honeycoin.app/docs/supported-countries-limits)</td>
      </tr>

      <tr>
        <td>[Koywe](https://koywe.com/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.koywe.com/crypto/introduction/%F0%9F%91%8B-welcome-to-koywe-%F0%9F%8C%B3)</td>
        <td>[Widget Ramp Demo](https://widget.koywe.com/)</td>
        <td>LATAM</td>
        <td>[Supported Currencies](https://docs.koywe.com/documentation/supported-currencies-payment-methods#supported-currencies-by-country)<br />
        [Supported Countries](https://docs.koywe.com/documentation/supported-currencies-payment-methods#supported-payment-methods-by-country)</td>
      </tr>

      <tr>
        <td>[Meld](https://www.meld.io/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.meld.io/docs/getting-started) (pw protected)</td>

        <td />

        <td>225+ Countries</td>

        <td />
      </tr>

      <tr>
        <td>[Mercuryo](https://mercuryo.io/)</td>
        <td>✅</td>
        <td>[Docs](https://oor-redirect.redoc.ly/)</td>
        <td>[Onramp API Endpoints](https://oor-redirect.redoc.ly/#section/On-Ramp.-Crypto-Purchase)<br />
        [Offramp API Endpoints](https://oor-redirect.redoc.ly/#section/Off-Ramp.-Crypto-Sell.)</td>
        <td>US, EU</td>
        <td>[Supported Currencies](https://help.mercuryo.io/hc/en-gb/articles/14495507502749-Which-fiat-currencies-are-supported)<br />
        [Supported Countries](https://help.mercuryo.io/hc/en-gb/articles/15265851177245-Where-does-Mercuryo-operate)</td>
      </tr>

      <tr>
        <td>[MoonPay](https://www.moonpay.com/)</td>
        <td>✅</td>
        <td>[Docs](https://dev.moonpay.com/)</td>
        <td>[Onramp](https://dev.moonpay.com/docs/on-ramp-overview)<br />
        [Offramp](https://dev.moonpay.com/docs/off-ramp-overview)</td>
        <td>US, EU, Canada, LATAM, APAC, Africa</td>
        <td>[Supported Currencies](https://support.moonpay.com/en/articles/362475-moonpay-s-supported-currencies)<br />
        [Supported Payment Methods](https://support.moonpay.com/en/articles/380823-moonpay-s-supported-payment-methods)<br />
        [Unsupported Countries](https://support.moonpay.com/en/articles/380968-moonpay-s-unsupported-countries)</td>
      </tr>

      <tr>
        <td>[Onramp Money](https://onramp.money/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.onramp.money/onramp/)</td>

        <td />

        <td>APAC, Africa, EU, US, LATAM</td>

        <td />
      </tr>

      <tr>
        <td>[Onramper](https://www.onramper.com/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.onramper.com/docs/getting-started)</td>
        <td>[API Endpoints](https://docs.onramper.com/reference/get_supported)</td>
        <td>190+ Countries</td>
        <td>[Payment Methods](https://docs.onramper.com/docs/supported-payment-methods)</td>
      </tr>

      <tr>
        <td>[OSL Pay](https://www.osl-pay.com/)</td>
        <td>✅</td>
        <td>[Docs](https://www.osl-pay.com/api-doc/startHere/quickStart)</td>
        <td>[Onramp](https://www.osl-pay.com/api-doc/product/onRamp)</td>
        <td>134+ Countries</td>
        <td>[Supported Currencies & Countries](https://docs.pay.osl.com/docs/overview)</td>
      </tr>

      <tr>
        <td>[Paj](https://paj.cash/)</td>
        <td>✅</td>
        <td>[Docs](https://github.com/paj-cash/paj_ramp/tree/main/examples)</td>
        <td>[Support notes](https://github.com/paj-cash/paj_ramp)</td>
        <td>Africa</td>
        <td>[Supported Currencies & Countries](https://github.com/paj-cash/paj_ramp)</td>
      </tr>

      <tr>
        <td>[Peer](https://peer.xyz/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.peer.xyz/)</td>
        <td>[Onramp](https://docs.peer.xyz/developer/integrate-zkp2p/integrate-redirect-onramp)<br />
        [Offramp](https://docs.peer.xyz/developer/developer/offramp)</td>
        <td>US, EU, Africa, LATAM, APAC</td>
        <td>Venmo, Cash App, Wise, Revolut, PayPal, Mercado Pago, etc.</td>
      </tr>

      <tr>
        <td>[Ramp Network](https://rampnetwork.com/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.rampnetwork.com/)</td>
        <td>[Getting Started](https://docs.rampnetwork.com/getting-started)</td>
        <td>US, EU, LATAM, APAC & 150+ countries</td>
        <td>[Supported Currencies & Countries](https://support.rampnetwork.com/en/articles/433-which-countries-and-us-states-are-unsupported-for-buying-and-selling-crypto)</td>
      </tr>

      <tr>
        <td>[Rampnow](https://app.rampnow.io)</td>
        <td>✅</td>
        <td>[Docs](https://docs.rampnow.io)</td>

        <td />

        <td>US, EU, EEA, LATAM, ASIA, South Africa, Nigeria</td>
        <td>[Payment Methods](https://docs.rampnow.io/quickstart/onramp/payment-methods)</td>
      </tr>

      <tr>
        <td>[Suby](https://suby.fi)</td>
        <td>✅</td>
        <td>[Docs](https://documentation.suby.fi/)</td>
        <td>[Crypto Payment Link](https://documentation.suby.fi/docs/payment/stablecoins)</td>
        <td>Global</td>
        <td>[Supported Countries](https://documentation.suby.fi/docs/merchants/supported-countries)</td>
      </tr>

      <tr>
        <td>[Swapped](https://swapped.com/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.swapped.com/)</td>
        <td>[Onramp Endpoints](https://docs.swapped.com/swapped-ramp/endpoints/onramp-endpoints)<br />
        [Offramp Endpoints](https://docs.swapped.com/swapped-ramp/endpoints/offramp-endpoints)</td>
        <td>150+ countries</td>
        <td>[Supported Payment Methods](https://swapped.com/payment-methods)<br />
        [Supported Countries](https://swapped.com/supported-countries)</td>
      </tr>

      <tr>
        <td>[Swapper Finance](https://swapper.finance/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.swapper.finance/)</td>
        <td>[Onramp Widget SDK](https://docs.swapper.finance/quick-start)</td>
        <td>Global</td>
        <td>ACH, credit cards, Apple Pay, Google Pay, UnionPay, and other major payment methods</td>
      </tr>

      <tr>
        <td>[Transak](https://transak.com/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.transak.com/)</td>
        <td>[API endpoints](https://docs.transak.com/reference/end-points)</td>
        <td>US, UK, EU, Australia, Canada, APAC</td>
        <td>[Supported Countries](https://transak.com/global-coverage)</td>
      </tr>

      <tr>
        <td>[Unlimit](https://www.unlimit.com/)</td>
        <td>⌛️</td>
        <td>[Docs](https://integration.unlimit.com/doc-guides/mylvyrw7nxiom-homepage)</td>
        <td>[API Endpoints](https://integration.unlimit.com/api-reference/6nk7rnnwnafo0-environments)</td>
        <td>LATAM, Africa, India, EU, UK, APAC</td>
        <td>[Payment Methods](https://integration.unlimit.com/doc-guides/ci8k5zm86k3ny-card-methods)<br />
        [Payout Methods](https://integration.unlimit.com/doc-guides/m2mtijltdzphg-card-methods)</td>
      </tr>

      <tr>
        <td>[UR](https://ur.app/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.ur.app/hc/en-us)</td>

        <td />

        <td>APAC, EU</td>
        <td>[Supported Countries](https://docs.ur.app/hc/en-us/articles/12862724456207-Countries-and-Territories-Supported-By-UR)<br />
        [Restricted Countries](https://docs.ur.app/hc/en-us/articles/13249954658447-Restricted-Payment-Countries)</td>
      </tr>

      <tr>
        <td>[Walapay](https://www.walapay.io/)</td>
        <td>⌛️</td>
        <td>[Docs](https://docs.walapay.io/docs/introduction)</td>

        <td />

        <td>Africa, APAC, EU, US, Canada, LATAM</td>
        <td>[Supported Countries & Currencies](https://docs.walapay.io/docs/countries-and-rails)<br />
        [Prohibited Countries](https://docs.walapay.io/docs/onboarding-regions)</td>
      </tr>

      <tr>
        <td>[zerohash](https://zerohash.com/)</td>
        <td>✅</td>
        <td>[Docs](https://docs.zerohash.com/)</td>
        <td>[On and Off Ramps](https://docs.zerohash.com/docs/convert-withdraw-1)</td>
        <td>US, Canada, EU, Africa, Australia, APAC</td>
        <td>[Supported Countries](https://docs.zerohash.com/docs/supported-regions)</td>
      </tr>
    </tbody>
  </table>
</div>

## Provider details

### AhoraCrypto

[AhoraCrypto](https://ahoracrypto.com/) is the crypto infrastructure built around the best-in-market UX: fast compliant KYC, responsive checkout, and 14+ local payment methods to maximize conversion. Revenue share is settled instantly to your wallet on every transaction, with no minimums, waiting periods, or fees. Supporting 14 blockchains, 50+ cryptocurrencies, and 50+ countries, go live in hours via white-label widget or REST API.

To get started, visit the [documentation](https://ahoracrypto.gitbook.io/ahoracrypto).

### Alchemy Pay

[Alchemy Pay](https://alchemypay.org/) is a payment gateway that seamlessly connects crypto with traditional fiat currencies for businesses, developers, and end users. With its offerings including On & Off Ramp, Crypto Card, Web3 Digital Bank, NFT Checkout, and Crypto Payments, Alchemy Pay supports payments in 173 countries.

To get started, visit the [documentation](https://alchemypay.readme.io/docs/alchemypay-on-ramp).

### alfred

With [alfred](https://www.alfredpay.io/), settle international payments in real time. Move money over stablecoin rails and give your business global coverage without the use of intermediary banks resulting in faster transfers at lower costs compared to traditional banking.

To get started, visit the [documentation](https://alfredpay.readme.io/docs/overview).

### Banxa

[Banxa](https://banxa.com/) powers one of the largest digital asset platforms by providing payments infrastructure and regulatory compliance across global markets. Banxa's mission and vision is to build the bridge that provides people in every part of the world access to a fairer and more equitable financial system.

To get started, visit the [documentation](https://docs.banxa.com/).

### Brale

[Brale](https://brale.xyz) is a stablecoin infrastructure platform that enables developers to onramp fiat to stablecoins, offramp stablecoins back to fiat, swap between [stablecoins](https://docs.brale.xyz/coverage/value-types) and [networks](https://docs.brale.xyz/coverage/transfer-types), and issue branded stablecoins, all through a single unified API. Brale handles regulatory compliance, reserves, and multi-chain orchestration so builders can focus on their product.

To get started, visit the [Brale documentation](https://docs.brale.xyz/).

### BTC Direct

[BTC Direct](https://onramp.btcdirect.eu/) provides a suite of tools to integrate cryptocurrency services into your platform. Their API supports [buying (onramp)](https://developer.btcdirect.eu/api/v1/#/Buy) and [selling (offramp)](https://developer.btcdirect.eu/api/v1/#/Sell) digital assets, with support for EUR via SEPA across Europe.

To get started, visit the [documentation](https://developer.btcdirect.eu/).

### Capa

[Capa](https://capa.fi/) is your one-stop solution to send and receive payments between Latin America and the world through their all-in-one API, making cross-border transactions fast, simple, and cost-effective.

To get started, visit the [documentation](https://docs.capa.fi/docs/getting-started).

### Chainrails

[Chainrails](https://chainrails.io) enables you to accept crypto payments/deposits from any chain, in any token or currency, instantly.

To get started, visit the [documentation](https://docs.chainrails.io).

### Coinbase Onramp & Offramp

[Coinbase Onramp & Offramp](https://docs.cdp.coinbase.com/onramp/introduction/welcome) by [Coinbase Developer Platform (CDP)](https://www.coinbase.com/developer-platform) empowers enterprises and developers with seamless onchain solutions. The Onramp & Offramp APIs and SDKs enable developers to move money seamlessly between fiat and onchain economies.

To get started, visit the [documentation](https://docs.cdp.coinbase.com/onramp/introduction/welcome).

### Coindisco

[Coindisco](https://coindisco.com/) is an onramp aggregator that provides access to crypto purchases across 240+ countries and territories through a unified widget and white label API integration.

To get started, visit the [documentation](https://coindisco.gitbook.io/coindisco).

### Coinflow

[Coinflow](https://coinflow.cash/) enables businesses to grow faster with instant settlement, fraud & chargeback indemnity, global pay-in, multi-currency FX, and unified payouts---all in one intuitive platform.

To get started, visit the [documentation](https://docs.coinflow.cash/).

### Daimo

[Daimo](https://daimo.com/) is the ramp for stablecoin apps. Integrate once, accept deposits from any wallet, any chain, any token. Funds arrive as the stablecoin you want, on the chain you want.

To get started, visit the [documentation](https://docs.daimo.com/introduction).

### El Dorado

[El Dorado](https://eldorado.io/) is an on/off ramp solution for Latin America, enabling seamless conversion between fiat currencies and cryptocurrency in the LATAM region.

To get started, visit the [documentation](https://api.eldorado.io/).

### FinchPay

[FinchPay](https://finchpay.io/) is an EU-regulated global fiat on-ramp and payment infrastructure for Web3, that lets users buy crypto with cards or local payment methods in 150+ countries.

To get started, visit the [documentation](https://docs.finchpay.io/).

### Flashnet

[Flashnet](https://flashnet.xyz/) builds Bitcoin exchange infrastructure. Its Orchestra product enables Bitcoin orchestration, moving Bitcoin to/from any asset/chain. Orchestra also powers a novel CashApp onramp, which can pull fiat and push stables on the other side. It's instant, low-cost, and the best onramp UX for US persons.

To get started, visit the [documentation](https://docs.flashnet.xyz/products/orchestration/overview).

### Fonbnk

[Fonbnk](https://www.fonbnk.com/) bridges mobile-first, cash-based economies to Web3 by converting prepaid payments into stablecoins, enabling frictionless FX, cross-border treasury flows, and instant liquidity.

To get started, visit the [documentation](https://docs.fonbnk.com/).

### Fun.xyz

[Fun.xyz](https://fun.xyz/)'s platform provides API-driven deposit and withdraw flows for secure, cross-chain, programmable experiences.

To get started, [contact](https://fun.xyz/contact) Fun.xyz.

### Guardarian

[Guardarian](https://guardarian.com/) is a fully licensed, non-custodial crypto payment infrastructure provider that enables both individuals and businesses to seamlessly buy, sell, and swap 1000+ cryptocurrencies using popular payment methods like Visa, Mastercard, Apple Pay, and Google Pay, offering fast low-KYC processing and support for 50+ fiat currencies across 150+ countries.

To get started, visit the [documentation](https://guardarian.com/api-doc).

### Halliday

With [Halliday](https://halliday.xyz/) Payments, users can acquire any token on any chain with minimal effort. Seamlessly onramp from fiat, cross arbitrary bridges, and swap assets from an existing wallet (e.g., MetaMask), into whatever form. Connect with an exchange account (e.g., Coinbase, Binance) to transfer digital assets onto any chain.

To get started, visit the [documentation](https://docs.halliday.xyz/pages/home).

### HoneyCoin

[HoneyCoin](https://honeycoin.app/) is a crypto onramp and offramp service focused on Africa, enabling seamless conversion between fiat currencies and cryptocurrency across the African continent.

To get started, visit the [documentation](https://docs.honeycoin.app/reference/welcome).

### Koywe

[Koywe](https://koywe.com/) is services and interface that make it easier and simpler to buy and sell crypto in Latin America for the fairest price while using local currency and payment methods.

To get started, visit the [documentation](https://docs.koywe.com/crypto/introduction/%F0%9F%91%8B-welcome-to-koywe-%F0%9F%8C%B3).

### Meld

[Meld](https://www.meld.io/) is an infrastructure to move money across Web2 and Web3 rails. fiat \<> fiat | fiat \<> crypto

To get started, [contact](https://www.meld.io/contact) Meld.

### Mercuryo

[Mercuryo](https://mercuryo.io/) enables efficient capital flow within the DeFi ecosystem and consolidates various payment and banking solutions into a single, user-centric interface.

To get started, visit the [documentation](https://oor-redirect.redoc.ly/).

### MoonPay

[MoonPay](https://www.moonpay.com/) simplifies access to buy, sell and trade crypto using everyday payment methods like cards, Apple Pay, PayPal and Venmo, while also providing simple tools to send, receive and manage stablecoins.

To get started, visit the [documentation](https://dev.moonpay.com/).

### Onramp Money

[Onramp Money](https://onramp.money/) is a comprehensive fiat-to-crypto infrastructure that empowers businesses and their users to buy and sell crypto using local fiat, swap crypto-to-crypto, spend crypto on gift cards instantly, and more.

To get started, visit the [documentation](https://docs.onramp.money/onramp/).

### Onramper

[Onramper](https://www.onramper.com/) is a fiat onramp aggregator. All fiat onramps in a single integration, unlocking the lowest fees and highest transaction success rates on the market.

To get started, visit the [documentation](https://docs.onramper.com/docs/getting-started).

### OSL Pay

[OSL Pay](https://www.osl-pay.com/) is the payment infrastructure arm of OSL Group, providing licensed and compliant solutions for seamless conversion between digital assets and fiat currencies.

To get started, visit the [documentation](https://www.osl-pay.com/api-doc/startHere/quickStart).

### Paj

[Paj](https://paj.cash/) abstracts global payments into wallet addresses by representing user bank accounts on-chain. Deterministic wallet addresses derived from users' bank accounts enable users to receive any crypto token converted directly into fiat automatically in their local bank account. This means that any bank account can receive on-chain money and anyone can send crypto to a bank account.

To get started, visit the [documentation](https://github.com/paj-cash/paj_ramp/tree/main/examples).

### Peer

[Peer](https://peer.xyz/) (formerly ZKP2P) is the first trustless P2P on/offramping bulletin board powered by zero-knowledge proofs. This enables a fast, cheap, and DeFi-composable buying and selling crypto experience. Peer supports multiple payment methods including Venmo, Cash App, Wise, Revolut, PayPal, and Mercado Pago across 20+ chains.

To get started, visit the [documentation](https://docs.peer.xyz/).

### Ramp Network

[Ramp Network](https://rampnetwork.com/) is a non-custodial fiat\<>crypto infrastructure that makes it easy for users to jump on and off of Web3 from anywhere.

To get started, visit the [documentation](https://docs.rampnetwork.com/).

### Rampnow

[Rampnow](https://app.rampnow.io) is a global blockchain on-ramp and off-ramp infrastructure provider connecting fiat and blockchain liquidity for businesses, developers, and end users. It supports 125+ blockchains, 20,000+ tokens, and major payment methods across multiple regions through a single API and widget.

To get started, visit the [documentation](https://docs.rampnow.io).

### Suby

[Suby](https://suby.fi) enables merchants to accept stablecoin payments through crypto checkout payment links, with global coverage.

To get started, visit the [documentation](https://documentation.suby.fi/).

### Swapped

[Swapped](https://swapped.com/) offers On-Ramp, Connect, and Commerce solutions, enabling customers to move funds onchain, receive crypto payments, and build full financial platforms, games, and consumer experiences.

To get started, visit the [documentation](https://docs.swapped.com/).

### Swapper Finance

[Swapper Finance](https://swapper.finance/) is the fiat-to-DeFi infrastructure for one-click onboarding to any protocol. Built to bring 3.5+ billion users to DeFi.

To get started, visit the [documentation](https://docs.swapper.finance/).

### Transak

[Transak](https://transak.com/) is a developer integration toolkit that enables you as an app developer to onboard your users to buy/sell crypto in any blockchain app, website or web plugin. With Transak you can onboard mainstream users into your dApp, protocol, game or wallet app and also increase your revenue.

To get started, visit the [documentation](https://docs.transak.com/docs/what-is-transak).

### Unlimit

[Unlimit](https://www.unlimit.com/)'s mission is to provide innovators with a convenient and simple financial interface that enables payments to flow freely and invisibly across borders. They offer a wide range of services, including payment gateway, card acquiring, business accounts, card issuing, alternative payment methods, and more.

To get started, visit the [documentation](https://integration.unlimit.com/doc-guides/mylvyrw7nxiom-homepage).

### UR

[UR](https://ur.app/) is a borderless smart money app built on the blockchain. Your go-to unified crypto and fiat account with 0 off-ramp fees and access to multiple currencies.

To get started, visit the [documentation](https://docs.ur.app/hc/en-us).

### Walapay

[Walapay](https://www.walapay.io/) is a global money movement platform that is building the future of cross-border payments.

To get started, visit the [documentation](https://www.walapay.io/).

### zerohash

[zerohash](https://zerohash.com/) is a B2B2C embedded infrastructure platform that provides APIs and SDKs, enabling businesses to integrate digital asset trading, custody, and fiat-to-crypto on-ramps directly into their applications.

To get started, visit the [documentation](https://docs.zerohash.com/).


# Oracles
Source: https://docs.monad.xyz/tooling-and-infra/oracles



Oracles make off-chain data accessible on chain.

## Definitions

| Term                             | Description                                                          |
| -------------------------------- | -------------------------------------------------------------------- |
| Push oracle                      | Provider regularly pushes price data to the oracle contract on chain |
| Pull (on-demand) oracle          | User triggers price data update while calling a smart contract       |
| Custom oracle                    | A custom calculator                                                  |
| VRF (Verifiable Random Function) | Provides random numbers on chain                                     |

## Provider Summary

<Tabs>
  <Tab title="Mainnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Contract addresses</th>
            <th>Live data</th>
            <th>Support notes</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Chainlink](https://chain.link/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.chain.link/)</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/chainlink.jsonc)</td>
            <td>[Live data](https://data.chain.link/streams)</td>

            <td>
              * Push oracle ([Price Feeds](https://docs.chain.link/data-feeds/price-feeds))
              * Pull oracle ([Data Streams](https://docs.chain.link/data-streams))
            </td>
          </tr>

          <tr>
            <td>[Chronicle](https://chroniclelabs.org/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.chroniclelabs.org/)</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/chronicle.jsonc)</td>

            <td />

            <td>Push oracle; custom oracles</td>
          </tr>

          <tr>
            <td>[eOracle](https://eo.app/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.eo.app/docs)</td>

            <td />

            <td>[Dashboard](https://data.eo.app/)</td>
            <td>Push oracle</td>
          </tr>

          <tr>
            <td>[Pyth](https://www.pyth.network/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.pyth.network/)</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/pyth.jsonc)</td>
            <td>[Live data](https://www.pyth.network/price-feeds)</td>
            <td>[Pull oracle](https://docs.pyth.network/price-feeds/pull-updates);<br />
            [VRF](https://docs.pyth.network/entropy)</td>
          </tr>

          <tr>
            <td>[Redstone](https://www.redstone.finance/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.redstone.finance/)</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/redstone.jsonc)</td>
            <td>[Live data](https://app.redstone.finance/app/tokens/)</td>
            <td>[Push oracle](https://app.redstone.finance/app/feeds/?networks=10143);<br />
            [pull oracle](https://app.redstone.finance/app/pull-model/redstone-primary-prod)</td>
          </tr>

          <tr>
            <td>[Stork](https://stork.network/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.stork.network/)</td>

            <td>
              * See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/stork.jsonc)<br />
              * [Addresses](https://docs.stork.network/resources/contract-addresses/evm); [APIs](https://docs.stork.network/api-reference/contract-apis/evm); [Asset ID Registry](https://docs.stork.network/resources/asset-id-registry)
            </td>

            <td>[Live Data](https://data.stork.network)</td>
            <td>[Push oracle](https://docs.stork.network/resources/stork-pushed-assets);<br />[Pull oracle](https://docs.stork.network/introduction/core-concepts)</td>
          </tr>

          <tr>
            <td>[Supra](https://supra.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.supra.com/)</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/supra_oracles.jsonc)</td>
            <td>[Live data](https://supra.com/data)</td>
            <td>[Push oracle](https://docs.supra.com/oracles/data-feeds/push-oracle);<br />[Pull oracle](https://docs.supra.com/oracles/data-feeds/pull-oracle);<br />[dVRF](https://docs.supra.com/oracles/dvrf)</td>
          </tr>

          <tr>
            <td>[Switchboard](https://switchboard.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.switchboard.xyz/)</td>

            <td>
              * See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/switchboard.jsonc)
              * More info: [Deployments](https://docs.switchboard.xyz/docs-by-chain/evm)
            </td>

            <td />

            <td>[Pull oracle](https://docs.switchboard.xyz/docs-by-chain/evm);<br />
            [Oracle aggregator](https://docs.switchboard.xyz/custom-feeds/advanced-feed-configuration/oracle-aggregator);<br />
            [VRF](https://docs.switchboard.xyz/docs-by-chain/evm/randomness)</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>

  <Tab title="Testnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Contract addresses</th>
            <th>Live data</th>
            <th>Support notes</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Chainlink](https://chain.link/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.chain.link/)</td>

            <td>
              Price Feeds \[push oracle]:<br />

              * BTC / USD: [`0x2Cd9D7E85494F68F5aF08EF96d6FD5e8F71B4d31`](https://testnet.monadvision.com/address/0x2Cd9D7E85494F68F5aF08EF96d6FD5e8F71B4d31)
              * ETH / USD: [`0x0c76859E85727683Eeba0C70Bc2e0F5781337818`](https://testnet.monadvision.com/address/0x0c76859E85727683Eeba0C70Bc2e0F5781337818)
              * LINK / USD: [`0x4682035965Cd2B88759193ee2660d8A0766e1391`](https://testnet.monadvision.com/address/0x4682035965Cd2B88759193ee2660d8A0766e1391)
              * USDC / USD: [`0x70BB0758a38ae43418ffcEd9A25273dd4e804D15`](https://testnet.monadvision.com/address/0x70BB0758a38ae43418ffcEd9A25273dd4e804D15)
              * USDT / USD: [`0x14eE6bE30A91989851Dc23203E41C804D4D71441`](https://testnet.monadvision.com/address/0x14eE6bE30A91989851Dc23203E41C804D4D71441)
              * [general reference](https://docs.chain.link/data-feeds/price-feeds/addresses?page=1\&testnetPage=1\&network=monad) <br /><br />

              Data Streams \[pull oracle]:<br />

              * Data stream verifier proxy address: [`0xC539169910DE08D237Df0d73BcDa9074c787A4a1`](https://testnet.monadvision.com/address/0xC539169910DE08D237Df0d73BcDa9074c787A4a1)
            </td>

            <td>[Live data](https://data.chain.link/streams)</td>

            <td>
              * Push oracle ([Price Feeds](https://docs.chain.link/data-feeds/price-feeds))
              * Pull oracle ([Data Streams](https://docs.chain.link/data-streams))
            </td>
          </tr>

          <tr>
            <td>[Chronicle](https://chroniclelabs.org/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.chroniclelabs.org/)</td>
            <td>[Address reference](https://docs.chroniclelabs.org/Developers/testnet)</td>
            <td>[Dashboard](https://chroniclelabs.org/dashboard/oracles?blockchain=MON-TESTNET) (toggle dev mode)</td>
            <td>Push oracle; custom oracles</td>
          </tr>

          <tr>
            <td>[eOracle](https://eo.app/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.eo.app/docs)</td>

            <td>
              * Update conditions: 0.5% deviation & 24h heartbeat
            </td>

            <td>[Dashboard](https://data.eo.app/)</td>
            <td>Push oracle</td>
          </tr>

          <tr>
            <td>[Gelato VRF](https://docs.gelato.network/web3-services/vrf/quick-start)</td>
            <td>✅</td>
            <td>[Docs](https://docs.gelato.network/web3-services/vrf/quick-start)</td>

            <td />

            <td />

            <td>VRF</td>
          </tr>

          <tr>
            <td>[Pyth](https://www.pyth.network/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.pyth.network/)</td>

            <td>
              * Price feeds: [`0x2880aB155794e7179c9eE2e38200202908C17B43`](https://testnet.monadvision.com/address/0x2880aB155794e7179c9eE2e38200202908C17B43)<br /><br />
              * Beta price feeds (incl MON/USDC): [`0xad2B52D2af1a9bD5c561894Cdd84f7505e1CD0B5`](https://testnet.monadvision.com/address/0xad2B52D2af1a9bD5c561894Cdd84f7505e1CD0B5)<br /><br />
              * Entropy: [`0x36825bf3Fbdf5a29E2d5148bfe7Dcf7B5639e320`](https://testnet.monadvision.com/address/0x36825bf3Fbdf5a29E2d5148bfe7Dcf7B5639e320)
            </td>

            <td>[Live data](https://www.pyth.network/price-feeds)<br /><br />
            [Beta live data](https://www.pyth.network/developers/price-feed-ids#beta) (includes MON / USDC)</td>
            <td>[Pull oracle](https://docs.pyth.network/price-feeds/pull-updates);<br />
            [VRF](https://docs.pyth.network/entropy)</td>
          </tr>

          <tr>
            <td>[Redstone](https://www.redstone.finance/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.redstone.finance/)</td>

            <td>
              * Push oracle [addresses](https://app.redstone.finance/app/feeds/?networks=10143)<br />
              * Update conditions for all: 0.5% deviation & 6h heartbeat
            </td>

            <td>[Live data](https://app.redstone.finance/app/tokens/)</td>
            <td>[Push oracle](https://app.redstone.finance/app/feeds/?networks=10143);<br />
            [pull oracle](https://app.redstone.finance/app/pull-model/redstone-primary-prod)</td>
          </tr>

          <tr>
            <td>[Stork](https://stork.network/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.stork.network/)</td>

            <td>
              * Pull oracle (includes MON/USD): [`0xacC0a0cF13571d30B4b8637996F5D6D774d4fd62`](https://testnet.monadvision.com/address/0xacC0a0cF13571d30B4b8637996F5D6D774d4fd62)<br />
              * [Addresses](https://docs.stork.network/resources/contract-addresses/evm); [APIs](https://docs.stork.network/api-reference/contract-apis/evm); [Asset ID Registry](https://docs.stork.network/resources/asset-id-registry)
            </td>

            <td>[Live Data](https://data.stork.network)</td>
            <td>[Pull oracle](https://docs.stork.network/introduction/core-concepts)</td>
          </tr>

          <tr>
            <td>[Supra](https://supra.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.supra.com/)</td>

            <td>
              * Storage: [`0xf0e852BC3F940447862D6b67e5B9807E64B433F6`](https://testnet.monadvision.com/address/0xf0e852BC3F940447862D6b67e5B9807E64B433F6)
              * Pull: [`0xF8522B7fcE37439b98A2be282d413A44269028bE`](https://testnet.monadvision.com/address/0xF8522B7fcE37439b98A2be282d413A44269028bE)
              * Router: [`0x5CbC3Dfa33223884E7752a833Fa6aD28Ee015FC4`](https://testnet.monadvision.com/address/0x5CbC3Dfa33223884E7752a833Fa6aD28Ee015FC4)
              * Deposit: [`0x95bfe6e94D5ff9e9d087647bc589acC9E3D31619`](https://testnet.monadvision.com/address/0x95bfe6e94D5ff9e9d087647bc589acC9E3D31619)
            </td>

            <td>[Live data](https://supra.com/data)</td>
            <td>[Push oracle](https://docs.supra.com/oracles/data-feeds/push-oracle);<br />[Pull oracle](https://docs.supra.com/oracles/data-feeds/pull-oracle);<br />[dVRF](https://docs.supra.com/oracles/dvrf)</td>
          </tr>

          <tr>
            <td>[Switchboard](https://switchboard.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.switchboard.xyz/)</td>

            <td>
              * Pull oracle: [`0xD3860E2C66cBd5c969Fa7343e6912Eff0416bA33`](https://testnet.monadvision.com/address/0xD3860E2C66cBd5c969Fa7343e6912Eff0416bA33)<br /><br />
              * More info: [Deployments](https://docs.switchboard.xyz/docs-by-chain/evm)
            </td>

            <td>[Live data](https://explorer.switchboardlabs.xyz/)</td>
            <td>[Pull oracle](https://docs.switchboard.xyz/docs-by-chain/evm);<br />
            [Oracle aggregator](https://docs.switchboard.xyz/custom-feeds/advanced-feed-configuration/oracle-aggregator);<br />
            [VRF](https://docs.switchboard.xyz/docs-by-chain/evm/randomness)</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>
</Tabs>

## Provider Details

### Chainlink

#### Chainlink Data Streams

[Chainlink Data Streams](https://docs.chain.link/data-streams) deliver low-latency market data offchain, which can be verified onchain. This approach provides decentralized applications (dApps) with on-demand access to high-frequency market data backed by decentralized, fault-tolerant, and transparent infrastructure.

Traditional push-based oracles update onchain data at set intervals or when certain price thresholds are met. In contrast, Chainlink Data Streams uses a pull-based design that preserves trust-minimization with onchain verification.

To get started, check out the [documentation](https://docs.chain.link/data-streams).

#### Chainlink Price Feeds

[Chainlink Price Feeds](https://docs.chain.link/data-feeds) are the quickest way to connect your smart contracts to real-world data such as asset prices.

Data Feeds aggregate many data sources and publish them onchain using a combination of the [Decentralized Data Model](https://docs.chain.link/architecture-overview/architecture-decentralized-model?parent=dataFeeds) and [Offchain Reporting](https://docs.chain.link/architecture-overview/off-chain-reporting?parent=dataFeeds).

To get started, check out the [documentation](https://docs.chain.link/data-feeds).

### Chronicle

Chronicle's decentralized oracle network was originally built within MakerDAO for the development of DAI and is now available to builders on Monad.

* **Data Feeds**: Builders can choose from 90+ data feeds, including crypto assets, yield rates, and RWAs. Chronicle's data is sourced via custom-built data models, only utilizing Tier 1 sources.
* **Transparency & Integrity**: Chronicle's oracle network is fully transparent and verifiable via the [Chronicle dashboard](https://chroniclelabs.org/dashboard/oracles?blockchain=MON-TESTNET). Users can cryptographically challenge the integrity of every oracle update using the 'verify' feature. Data is independently sourced by a [community of Validators](https://chroniclelabs.org/validators) including Gitcoin, Etherscan, Infura, DeFi Saver, and MakerDAO.
* **Gas Efficiency**: Pioneering the Schnorr-based oracle architecture, Chronicle's oracles use 60-80% less gas per update than other oracle providers. This lowest cost per update allows Push oracle updates to be made more frequently, enabling granular data reporting.
* Every oracle implementation is customized to fit your needs. Implement one of our existing data models or contact Chronicle to develop custom oracle data feeds via [Discord](https://discord.gg/CjgvJ9EspJ).

Developers can dive deeper into Chronicle Protocol's architecture and unique design choices via the [docs](https://docs.chroniclelabs.org/).

### eOracle

[eOracle](https://eo.app/) is an open infrastructure platform that empowers developers to build secure blockchain oracles backed by Ethereum's battle-tested security model. eOracle creates a foundation for specialized data services that combine deep domain expertise with unmatched cryptoeconomic security.

To get started, visit the [eOracle documentation](https://docs.eo.app/docs).

### Pyth

The [Pyth Network](https://www.pyth.network/) is one of the largest first-party oracle networks, delivering real-time data across a number of chains. Pyth introduces a low-latency [pull oracle](https://docs.pyth.network/price-feeds/pull-updates) design. Data providers push price updates to [Pythnet](https://docs.pyth.network/price-feeds/how-pyth-works/pythnet) every 400 ms. Users pull aggregated prices from Pythnet onto Monad when needed, enabling everyone in the onchain environment to access that data point most efficiently.

Pyth Price Feeds features:

* 400ms latency
* [First-party](https://www.pyth.network/publishers) data sourced directly from financial institutions
* [Price feeds](https://www.pyth.network/developers/price-feed-ids) ranging from crypto, stocks, FX, and metals
  * See also: [beta price feeds](https://www.pyth.network/developers/price-feed-ids#beta) (testnet MON/USD is a beta price feed)
* Available on [many](https://docs.pyth.network/price-feeds/contract-addresses) major chains

Contract Addresses for Monad Testnet:

* Price feeds: [`0x2880aB155794e7179c9eE2e38200202908C17B43`](https://testnet.monadvision.com/address/0x2880aB155794e7179c9eE2e38200202908C17B43)
  * Beta price feeds: [`0xad2B52D2af1a9bD5c561894Cdd84f7505e1CD0B5`](https://testnet.monadvision.com/address/0xad2B52D2af1a9bD5c561894Cdd84f7505e1CD0B5) (testnet MON/USD is a beta price feed)
* Entropy: [`0x36825bf3Fbdf5a29E2d5148bfe7Dcf7B5639e320`](https://testnet.monadvision.com/address/0x36825bf3Fbdf5a29E2d5148bfe7Dcf7B5639e320)

<Note>
  The testnet `MON/USD` price feed is currently a beta feed on Pyth Network. To use the MON/USD feed, integrate the [beta price feed](https://testnet.monadvision.com/address/0xad2B52D2af1a9bD5c561894Cdd84f7505e1CD0B5) contract instead of the primary price feed contract.

  To get the MON/USD price feed offchain, use the beta hermes endpoint: [https://hermes-beta.pyth.network](https://hermes-beta.pyth.network)
</Note>

### Redstone

[RedStone](https://www.redstone.finance/) is the fastest-growing modular oracle, specializing in yield-bearing collateral for lending markets, such as LSTs, LRTs and BTCFi.

To get started, visit the [Redstone documentation](https://docs.redstone.finance/docs/introduction).

### Stork

[Stork](https://stork.network/) is an oracle protocol that enables ultra low latency connections between data providers and both on and off-chain applications. The most common use-case for Stork is pulling and consuming market data in the form of real time price feeds for DeFi.

Stork is implemented as a [pull oracle](https://docs.stork.network/introduction/core-concepts#docs-internal-guid-4b312e7b-7fff-1147-c04b-bbaadec1a82a). Stork continuously aggregates, verifies, and audits data from trusted publishers, and makes that aggregated data available at sub-second latency and frequency. This data can then be pulled into any on or off-chain application as often as needed.

To learn more about how Stork works, visit [Core Concepts](https://docs.stork.network/introduction/core-concepts) and [How It Works](https://docs.stork.network/introduction/how-it-works).

### Supra

[Supra](https://supra.com) provides VRF and decentralized oracle price feeds (push and pull based) that can be used for onchain and offchain use-cases such as spot and perpetual DEXes, lending protocols, and payments protocols.

To get started, visit the [Supra documentation](https://docs.supra.com)

### Switchboard

[Switchboard](https://switchboard.xyz/) is a permissionless oracle protocol that enables developers to bring any off-chain or cross-chain data onto Monad through verifiable, ultra-low-latency feeds.

Switchboard features:

* Fully permissionless feed creation via the [Feed Builder](https://explorer.switchboardlabs.xyz/feed-builder): deploy custom oracles in minutes
* [Switchboard Surge](https://docs.switchboard.xyz/docs-by-chain/evm/surge): Low-latency data feeds with sub-10 ms updates for high-performance applications
* Enterprise-grade reliability
* [Aggregator](https://docs.switchboard.xyz/custom-feeds/advanced-feed-configuration/oracle-aggregator): access multiple oracle sources (like the ones on this page) in a single transaction
* [Data Feed Variables](https://docs.switchboard.xyz/product-documentation/data-feeds/designing-feeds/data-feed-variable-overrides): bring API-gated or confidential data on-chain without exposing API keys
* Customizable feeds: adjust feed parameters (confidence intervals, deviation thresholds, and more) to your dapp's needs
* Decentralized oracle network secured by globally distributed validator set
* Verifiable Randomness: generate secure, verifiable random numbers for games, lotteries, and more
* Supports any data type: prices, prediction markets, sports, weather, RWAs, etc

Contract Address for Monad Mainnet: [`0xB7F03eee7B9F56347e32cC71DaD65B303D5a0E67`](https://monadvision.com/address/0xB7F03eee7B9F56347e32cC71DaD65B303D5a0E67)

For more details, check out [Switchboard's detailed EVM documentation](https://docs.switchboard.xyz/docs-by-chain/evm).


# RPC Providers
Source: https://docs.monad.xyz/tooling-and-infra/rpc-providers



<Note>
  See also: [API reference](/reference/json-rpc)
</Note>

## Provider Summary

<Tabs>
  <Tab title="Mainnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Notes</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Alchemy](https://www.alchemy.com/)</td>
            <td>✅</td>
            <td>Alchemy Monad [docs](https://www.alchemy.com/docs/reference/monad-api-quickstart)</td>
          </tr>

          <tr>
            <td>[Ankr](https://www.ankr.com/)</td>
            <td>✅</td>
            <td>Ankr Monad [docs](https://www.ankr.com/web3-api/chains-list/monad/)</td>
          </tr>

          <tr>
            <td>[Blockdaemon](https://www.blockdaemon.com)</td>
            <td>✅</td>
            <td>Blockdaemon Monad [docs](https://www.blockdaemon.com/protocols/monad)</td>
          </tr>

          <tr>
            <td>[BlockPI](https://blockpi.io/)</td>
            <td>✅</td>
            <td>BlockPI Monad [docs](https://blockpi.io/chain/monad)</td>
          </tr>

          <tr>
            <td>[Chainstack](https://chainstack.com/build-better-with-monad/)</td>
            <td>✅</td>
            <td>Chainstack Monad [docs](https://docs.chainstack.com/reference/monad-getting-started)</td>
          </tr>

          <tr>
            <td>[dRPC NodeCloud](https://drpc.org/)</td>
            <td>✅</td>
            <td>dRPC NodeCloud Monad [docs](https://drpc.org/chainlist/monad-mainnet-rpc)</td>
          </tr>

          <tr>
            <td>[Dwellir](https://dwellir.com/)</td>
            <td>✅</td>
            <td>Dwellir Monad [docs](https://dwellir.com/networks/monad)</td>
          </tr>

          <tr>
            <td>[Envio](https://envio.dev/)</td>
            <td>✅</td>
            <td>HyperRPC is a performant read-only RPC. See [docs](https://docs.envio.dev/docs/HyperRPC/overview-hyperrpc)</td>
          </tr>

          <tr>
            <td>[GetBlock](https://getblock.io/)</td>
            <td>✅</td>
            <td>GetBlock Monad [docs](https://getblock.io/nodes/monad/)</td>
          </tr>

          <tr>
            <td>[OnFinality](https://onfinality.io/)</td>
            <td>✅</td>
            <td>OnFinality Monad [docs](https://onfinality.io/en/networks/monad-mainnet)</td>
          </tr>

          <tr>
            <td>[Quicknode](https://www.quicknode.com/)</td>
            <td>✅</td>
            <td>Quicknode Monad [docs](https://www.quicknode.com/chains/monad)</td>
          </tr>

          <tr>
            <td>[Spectrum](https://spectrumnodes.com/)</td>
            <td>✅</td>

            <td />
          </tr>

          <tr>
            <td>[Tatum](https://tatum.io)</td>
            <td>✅</td>
            <td>Tatum Monad [docs](https://tatum.io/exclusive/monad)</td>
          </tr>

          <tr>
            <td>[thirdweb](https://thirdweb.com)</td>
            <td>✅</td>
            <td>thirdweb RPC Edge [docs](https://portal.thirdweb.com/infrastructure/rpc-edge/overview)</td>
          </tr>

          <tr>
            <td>[Triton One](https://triton.one/)</td>
            <td>✅</td>
            <td>Triton One Monad [docs](https://docs.triton.one/chains/monad)</td>
          </tr>

          <tr>
            <td>[Validation Cloud](https://validationcloud.io/)</td>
            <td>✅</td>
            <td>Validation Cloud Monad [docs](https://docs.validationcloud.io/monad)</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>

  <Tab title="Testnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Notes</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Alchemy](https://www.alchemy.com/)</td>
            <td>✅</td>
            <td>Alchemy Monad [docs](https://www.alchemy.com/docs/reference/monad-api-quickstart)</td>
          </tr>

          <tr>
            <td>[Ankr](https://www.ankr.com/)</td>
            <td>✅</td>
            <td>Ankr Monad [docs](https://www.ankr.com/web3-api/chains-list/monad/)</td>
          </tr>

          <tr>
            <td>[Blockdaemon](https://www.blockdaemon.com)</td>
            <td>✅</td>
            <td>Blockdaemon Monad [docs](https://www.blockdaemon.com/protocols/monad)</td>
          </tr>

          <tr>
            <td>[BlockPI](https://blockpi.io/)</td>
            <td>✅</td>
            <td>BlockPI Monad [docs](https://blockpi.io/chain/monad)</td>
          </tr>

          <tr>
            <td>[Chainstack](https://chainstack.com/build-better-with-monad/)</td>
            <td>✅</td>
            <td>Chainstack Monad [docs](https://docs.chainstack.com/reference/monad-getting-started)</td>
          </tr>

          <tr>
            <td>[dRPC NodeCloud](https://drpc.org/)</td>
            <td>✅</td>
            <td>dRPC NodeCloud Monad [docs](https://drpc.org/chainlist/monad-testnet-rpc)</td>
          </tr>

          <tr>
            <td>[Dwellir](https://dwellir.com/)</td>
            <td>✅</td>
            <td>Dwellir Monad [docs](https://dwellir.com/networks/monad)</td>
          </tr>

          <tr>
            <td>[Envio](https://envio.dev/)</td>
            <td>✅</td>
            <td>HyperRPC is a performant read-only RPC. See [docs](https://docs.envio.dev/docs/HyperRPC/overview-hyperrpc)</td>
          </tr>

          <tr>
            <td>[GetBlock](https://getblock.io/)</td>
            <td>✅</td>
            <td>GetBlock Monad [docs](https://getblock.io/nodes/monad/)</td>
          </tr>

          <tr>
            <td>[OnFinality](https://onfinality.io/)</td>
            <td>✅</td>
            <td>OnFinality Monad [docs](https://onfinality.io/en/networks/monad-mainnet)</td>
          </tr>

          <tr>
            <td>[Quicknode](https://www.quicknode.com/)</td>
            <td>✅</td>
            <td>Quicknode Monad [docs](https://www.quicknode.com/chains/monad)</td>
          </tr>

          <tr>
            <td>[Spectrum](https://spectrumnodes.com/)</td>
            <td>✅</td>

            <td />
          </tr>

          <tr>
            <td>[Tatum](https://tatum.io)</td>
            <td>✅</td>
            <td>Tatum Monad [docs](https://tatum.io/chain/monad)</td>
          </tr>

          <tr>
            <td>[thirdweb](https://thirdweb.com)</td>
            <td>✅</td>
            <td>thirdweb RPC Edge [docs](https://portal.thirdweb.com/infrastructure/rpc-edge/overview)</td>
          </tr>

          <tr>
            <td>[Validation Cloud](https://validationcloud.io/)</td>
            <td>✅</td>
            <td>Validation Cloud Monad [docs](https://docs.validationcloud.io/monad)</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>
</Tabs>

## Provider Details

### Alchemy

[Alchemy](https://www.alchemy.com/) is a popular API provider and developer platform. Its robust, free tier offers access to JSON-RPC APIs, and hosted testnet nodes for Monad Testnet.

### Ankr

[Ankr](https://www.ankr.com/web3-api/) provides private and public RPC endpoints for Monad, powered by a globally distributed and decentralized network of nodes.

### Blockdaemon

[Blockdaemon](https://www.blockdaemon.com/) provides enterprise-grade web3 infrastructure, including dedicated nodes, APIs, staking, liquid staking, MPC wallets, and more.

To get started, visit the [Blockdaemon documentation](https://docs.blockdaemon.com/).

### BlockPI

[BlockPI](https://blockpi.io/) provides enterprise-grade, high-performance RPC services for both Monad Mainnet and Testnet. Whatever you're building on Monad, we offer this premium service at a fraction of the market average price, making high-quality RPC access affordable for everyone.

To get started, visit [BlockPI's Monad page](https://blockpi.io/chain/monad).

### Chainstack

[Chainstack](https://chainstack.com/build-better-with-monad/) provides low-latency, highly reliable, and scalable RPC infrastructure for Monad.

You can deploy robust Monad Mainnet and Testnet nodes and access [geo-balanced RPC endpoints](https://chainstack.com/global-nodes/) on a secure, SOC 2–certified platform.

To get started, create a free account with a [Monad RPC node](https://chainstack.com/).

### dRPC NodeCloud

[dRPC NodeCloud](https://drpc.org/) delivers robust, low-latency RPC for Monad. Free accounts & paid plans from \$10. Full speed. No limits, build confidently.

To get started, visit the [dRPC's Monad page](https://drpc.org/chainlist/monad-testnet-rpc).

### Dwellir

[Dwellir](https://dwellir.com/) supports Monad Mainnet and Testnet endpoints as well as over 100+ other blockchain networks. And best of all: every response costs the same—no compute units.

To get started, visit the [Dwellir Monad page](https://dwellir.com/networks/monad).

### Envio

[Envio](https://envio.dev) has a free read only RPC that supports a subset of data intensive [methods](https://docs.envio.dev/docs/HyperRPC/overview-hyperrpc#supported-methods), Envio's purpose built rust node supports historical data allowing you to query past 10,000 blocks into the past.

To get started, visit the [Envio documentation](https://docs.envio.dev/docs/HyperRPC/overview-hyperrpc)

### GetBlock

[GetBlock](https://getblock.io/) provides reliable RPC endpoints for Monad, offering shared and dedicated nodes with high availability and performance.

To get started, visit the [GetBlock Monad page](https://getblock.io/nodes/monad/).

### OnFinality

[OnFinality](https://onfinality.io/) provides high performance RPC for Monad Mainnet and Testnet, along with support for many other leading networks so teams can build cross chain from Monad with ease. OnFinality infrastructure delivers 99.99% uptime, fast response times, and pricing that is friendly for teams of every size.

Start building on Monad today with reliable and scalable RPC from [OnFinality](https://onfinality.io/en/networks/monad-mainnet).

### Quicknode

[Quicknode](https://www.quicknode.com/) offers access to their [Core RPC API](https://www.quicknode.com/core-api) for both Monad Testnet and Mainnet. Quicknode provides managed, high-performance RPC endpoints with instant access.

To get started, visit [Quicknode's Monad page](https://www.quicknode.com/chains/monad).

### Spectrum

[Spectrum](https://spectrumnodes.com/) is an enterprise-grade RPC Infrastructure provider that
makes it easy to deploy and manage dedicated RPC endpoints to over 150 networks.  Sign up today
to get started on Monad.

To get started, visit the [Spectrum dashboard](https://dashboard.spectrumnodes.com/auth/signup).

### Tatum

[Tatum](https://tatum.io/) provides RPC nodes, blockchain data, and real-time notifications.

To get started, visit the [Tatum documentation](https://docs.tatum.io/).

### thirdweb

[thirdweb](https://thirdweb.com/)'s [RPC Edge](https://portal.thirdweb.com/infrastructure/rpc-edge/overview) provides an RPC endpoint for developers building on Monad.

To get started, visit the [Thirdweb RPC Edge documentation](https://portal.thirdweb.com/infrastructure/rpc-edge/overview).

### Triton One

[Triton One](https://triton.one/triton-rpc/) is a reliable, globally distributed Monad RPC provider built
for teams that need consistent performance under load, high throughput, and uninterrupted uptime.

To get started, visit the Triton One Monad [docs](https://docs.triton.one/chains/monad).

### Validation Cloud

[Validation Cloud](https://validationcloud.io/) is the world's fastest node provider according to Compare Nodes. With 50 million compute units available for use without a credit card and a scale tier that never has rate limits, Validation Cloud is built to support your most rigorous and low-latency workloads.

To get started, visit the [Validation Cloud Monad documentation](https://docs.validationcloud.io/monad).


# Hardhat
Source: https://docs.monad.xyz/tooling-and-infra/toolkits/hardhat



[Hardhat](https://hardhat.org/docs) is a Solidity development framework paired with a JavaScript testing framework.

When configuring your Hardhat project for Monad, set the EVM version to `prague` in your `hardhat.config.js`:

```javascript theme={null}
module.exports = {
  solidity: {
    version: "0.8.28",
    settings: {
      evmVersion: "prague",
    },
  },
};
```

For deployment and verification guides using Hardhat, see:

* [Deploy a Contract with Hardhat](/guides/deploy-smart-contract/hardhat)
* [Verify a Contract with Hardhat](/guides/verify-smart-contract/hardhat)


# Toolkits
Source: https://docs.monad.xyz/tooling-and-infra/toolkits/index



Development toolkits for building on Monad.

## Summary

| Toolkit                                                    | Description                                                                                                                                     |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| [Monad Foundry](/tooling-and-infra/toolkits/monad-foundry) | Custom fork of Foundry with Monad EVM, staking precompile support, and human-readable trace decoding. **Recommended for Solidity development.** |
| [Hardhat](/tooling-and-infra/toolkits/hardhat)             | JavaScript-based Solidity development framework with Monad compatibility.                                                                       |
| [Monad Solonet](/tooling-and-infra/toolkits/monad-solonet) | Run a local Monad network for development and testing.                                                                                          |


# Monad Foundry
Source: https://docs.monad.xyz/tooling-and-infra/toolkits/monad-foundry



[Monad Foundry](https://github.com/category-labs/foundry/tree/monad) is a custom fork of [Foundry](https://book.getfoundry.sh/) that integrates Monad features directly into the familiar Foundry developer workflow. It uses [monad-revm](https://github.com/category-labs/monad-revm), to ensure that `forge test`, `forge script`, `cast`, `anvil`, and `chisel` all execute with Monad's gas model, opcode pricing, and precompile behavior — so your local development environment matches Monad's on-chain behavior.

For general Foundry usage (writing tests, scripts, deployments, configuration, cheatcodes), refer to the [Foundry Docs](https://book.getfoundry.sh/).

## Installation

Install the Monad Foundry installer:

```sh theme={null}
curl -L https://foundry.category.xyz | bash
```

Then install Monad Foundry:

```sh theme={null}
foundryup --network monad
```

This installs all four binaries — `forge`, `cast`, `anvil`, and `chisel` — with Monad support.

<Note>
  The same installer also supports standard Foundry. Running `foundryup` without `--network monad` will install the official upstream Foundry release, so you can use both side by side.
</Note>

## Features

| Feature                   | Description                                                                    |
| ------------------------- | ------------------------------------------------------------------------------ |
| **Monad EVM Execution**   | Monad gas model, 128KB code size limit, no gas refunds, repriced precompiles   |
| **Staking Precompile**    | All staking view functions work locally at address `0x1000`                    |
| **Human-Readable Traces** | Staking calls decoded with function names; address labeled "Staking" in traces |
| **Anvil with Monad**      | `anvil --monad` for a local Monad EVM node                                     |
| **Contract Verification** | `forge verify-contract` uses Monad EVM for bytecode comparison                 |

## Monad EVM Execution

`forge test` and `forge script` execute with Monad EVM by default. The following differences from Ethereum are applied automatically:

* **Gas charging**: Gas is charged based on `gas_limit`, not `gas_used`. There are no gas refunds. See [Gas Pricing](/developer-essentials/gas-pricing) for details.
* **Contract size**: Max contract size is 128KB
* **Initcode size**: Max initcode size is 256KB
* **Precompile gas costs**: See [Opcode Pricing](/developer-essentials/opcode-pricing).
* **No blob transactions**: EIP-4844 (type 3) transactions are not supported.

For the complete list of differences, see [Differences between Monad and Ethereum](/developer-essentials/differences).

## Staking Precompile Support

All [staking precompile](/reference/staking/api) view functions work in `forge test` at address `0x1000`:

### Trace Decoding

When running tests with verbose output (`forge test -vvvv`), staking calls are decoded with human-readable function names and parameters. The address `0x1000` is labeled as **"Staking"** in trace output.

All staking state-changing functions (`addValidator`, `delegate`, `undelegate`, `withdraw`, `compound`, `claimRewards`, `changeCommission`, `externalReward`) and events (`ValidatorRewarded`, `Delegate`, `Undelegate`, `Withdraw`, `ClaimRewards`, `CommissionChanged`, `EpochChanged`, `ValidatorStatusChanged`) are decoded in traces.

Example trace output:

```
├─ [16200] Staking::getEpoch()
│   └─ ← [Return] 42, false
```

## Anvil with Monad EVM

Use `anvil --monad` to run a local development node with Monad EVM:

```sh theme={null}
# Local Monad node
anvil --monad

# Fork Monad Testnet
anvil --fork-url https://testnet-rpc.monad.xyz

# Fork Monad Mainnet
anvil --fork-url https://rpc.monad.xyz
```

Monad EVM activates automatically when forking a Monad RPC endpoint (detected via chain ID), so you don't need the `--monad` flag when forking.

## Cast & Chisel

`cast` and `chisel` execute with Monad EVM by default. All standard commands work the same as upstream Foundry.

## CI Integration

Use the [Monad Foundry GitHub Action](https://github.com/category-labs/foundry-toolchain) to install Monad Foundry in your CI workflows:

```yaml theme={null}
- name: Install Monad Foundry
  uses: category-labs/foundry-toolchain@v1
```

This installs the latest stable Monad Foundry (`stable-monad`) by default. You can also pin a specific version:

```yaml theme={null}
- name: Install Monad Foundry
  uses: category-labs/foundry-toolchain@v1
  with:
    version: v1.5.0-monad.0.1.0
```

Full workflow example:

```yaml theme={null}
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          submodules: recursive

      - name: Install Monad Foundry
        uses: category-labs/foundry-toolchain@v1

      - name: Run tests
        run: forge test -vvv
```

The action supports caching and works on all platforms (Linux, macOS, Windows). See the [foundry-toolchain repo](https://github.com/category-labs/foundry-toolchain) for all available options.

## Releases & Versioning

Monad Foundry uses a `v{upstream}-monad.{monad_version}` versioning scheme. For example, `v1.5.0-monad.0.1.0` is based on upstream Foundry v1.5.0 with Monad fork version 0.1.0.

See the [GitHub Releases](https://github.com/category-labs/foundry/releases) for full release history.


# Monad Solonet
Source: https://docs.monad.xyz/tooling-and-infra/toolkits/monad-solonet



[Monad Solonet](https://github.com/monad-crypto/monad-solonet) is an official tool for running a local Monad network. Unlike `anvil --monad`, which simulates Monad EVM behavior, Solonet runs actual Monad nodes — giving you a local environment that more closely matches testnet and mainnet.

Use Solonet when you need full node behavior locally: consensus, staking, or accurate block production timing.

## Installation & usage

See the [Monad Solonet README](https://github.com/monad-crypto/monad-solonet#readme) for setup instructions and configuration options.


# Account Abstraction Providers
Source: https://docs.monad.xyz/tooling-and-infra/wallet-infra/account-abstraction



Account Abstraction Providers provide bundler and paymaster services, enabling features like
sponsored transactions or payment via custom tokens.

## Definitions

| Service   | Description                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------- |
| Bundler   | Operates a custom mempool for UserOperations; simulates and assembles bundles of UserOperations |
| Paymaster | Enables sponsored transactions; enables users to pay for gas with a custom token                |

## Provider Summary

<Tabs>
  <Tab title="Mainnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Supported services</th>
            <th>How to get started</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Alchemy](https://www.alchemy.com/smart-wallets)</td>
            <td>✅</td>
            <td>[Docs](https://accountkit.alchemy.com/)</td>
            <td>[Gas Manager](https://docs.alchemy.com/docs/gas-manager-services) (aka Paymaster)<br />
            [Bundler](https://docs.alchemy.com/docs/bundler-services)</td>
            <td>[Dashboard](https://dashboard.alchemy.com/accounts?a=smart-wallets\&utm_source=chain_partner\&utm_medium=referral\&utm_campaign=monad)</td>
          </tr>

          <tr>
            <td>[Biconomy](https://biconomy.io)</td>
            <td>✅</td>
            <td>[Docs](https://docs.biconomy.io)</td>
            <td>[Orchestration Infrastructure](https://docs.biconomy.io/new/learn-about-biconomy/what-is-mee)</td>
            <td>[Getting started](https://docs.biconomy.io/supertransaction-api/getting-started)</td>
          </tr>

          <tr>
            <td>[FastLane](https://www.fastlane.xyz/)</td>
            <td>❓</td>
            <td>[Docs](https://docs.shmonad.xyz/)</td>
            <td>[Paymaster and Bundler](https://github.com/FastLane-Labs/4337-bundler-paymaster-script/tree/main)</td>
            <td>[Dashboard](https://shmonad.xyz/)</td>
          </tr>

          <tr>
            <td>[Openfort](https://openfort.io/)</td>
            <td>✅</td>
            <td>[Docs](https://www.openfort.io/docs)</td>
            <td>[Paymaster and Bundler](https://www.openfort.io/docs/overview)</td>
            <td>[Quickstart](https://www.openfort.io/docs/overview/start)</td>
          </tr>

          <tr>
            <td>[Pimlico](https://pimlico.io/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.pimlico.io/)</td>
            <td>[Paymaster](https://docs.pimlico.io/infra/paymaster)<br />
            [Bundler](https://docs.pimlico.io/infra/bundler)</td>
            <td>[Tutorial](https://docs.pimlico.io/permissionless/tutorial/tutorial-1)</td>
          </tr>

          <tr>
            <td>[Sequence](https://sequence.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.sequence.xyz/solutions/infrastructure/transaction-api)</td>
            <td>Relayer: gasless, batched, parallelized transactions</td>
            <td>[Quickstart](https://docs.sequence.xyz/solutions/builder/gas-sponsorship)</td>
          </tr>

          <tr>
            <td>[thirdweb](https://thirdweb.com/)</td>
            <td>✅</td>
            <td>[Docs](https://portal.thirdweb.com/)</td>
            <td>[Paymaster and Bundler](https://portal.thirdweb.com/connect/account-abstraction/infrastructure)</td>
            <td>[Quickstart](https://portal.thirdweb.com/typescript/v5/account-abstraction/get-started)</td>
          </tr>

          <tr>
            <td>[ZeroDev](https://zerodev.app/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.zerodev.app/)</td>
            <td>[Meta AA infrastructure](https://docs.zerodev.app/meta-infra/intro) for bundlers and paymasters</td>
            <td>[Dashboard](https://dashboard.zerodev.app/)</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>

  <Tab title="Testnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Supported services</th>
            <th>How to get started</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Alchemy](https://www.alchemy.com/smart-wallets)</td>
            <td>✅</td>
            <td>[Docs](https://accountkit.alchemy.com/)</td>
            <td>[Gas Manager](https://docs.alchemy.com/docs/gas-manager-services) (aka Paymaster)<br />
            [Bundler](https://docs.alchemy.com/docs/bundler-services)</td>
            <td>[Dashboard](https://dashboard.alchemy.com/accounts?a=smart-wallets\&utm_source=chain_partner\&utm_medium=referral\&utm_campaign=monad)</td>
          </tr>

          <tr>
            <td>[Biconomy](https://biconomy.io)</td>
            <td>✅</td>
            <td>[Docs](https://docs.biconomy.io)</td>
            <td>[Orchestration Infrastructure](https://docs.biconomy.io/new/learn-about-biconomy/what-is-mee)</td>
            <td>[Getting started](https://docs.biconomy.io/supertransaction-api/getting-started)</td>
          </tr>

          <tr>
            <td>[FastLane](https://www.fastlane.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.shmonad.xyz/)</td>
            <td>[Paymaster and Bundler](https://github.com/FastLane-Labs/4337-bundler-paymaster-script/tree/main)</td>
            <td>[Dashboard](https://shmonad.xyz/)</td>
          </tr>

          <tr>
            <td>[Gelato](https://docs.gelato.cloud/paymaster-&-bundler/introduction/overview)</td>
            <td>✅</td>
            <td>[Docs](https://docs.gelato.cloud/paymaster-&-bundler/introduction/overview)</td>
            <td>[Paymaster and Bundler](https://docs.gelato.cloud/paymaster-&-bundler/introduction/overview)</td>
            <td>[Quickstart](https://docs.gelato.cloud/paymaster-&-bundler/how-to-guides/overview)</td>
          </tr>

          <tr>
            <td>[Openfort](https://openfort.io/)</td>
            <td>✅</td>
            <td>[Docs](https://www.openfort.io/docs)</td>
            <td>[Paymaster and Bundler](https://www.openfort.io/docs/overview)</td>
            <td>[Quickstart](https://www.openfort.io/docs/overview/start)</td>
          </tr>

          <tr>
            <td>[Pimlico](https://pimlico.io/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.pimlico.io/)</td>
            <td>[Paymaster](https://docs.pimlico.io/infra/paymaster)<br />
            [Bundler](https://docs.pimlico.io/infra/bundler)</td>
            <td>[Tutorial](https://docs.pimlico.io/permissionless/tutorial/tutorial-1)</td>
          </tr>

          <tr>
            <td>[Sequence](https://sequence.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.sequence.xyz/solutions/infrastructure/transaction-api)</td>
            <td>Relayer: gasless, batched, parallelized transactions</td>
            <td>[Quickstart](https://docs.sequence.xyz/solutions/builder/gas-sponsorship)</td>
          </tr>

          <tr>
            <td>[thirdweb](https://thirdweb.com/)</td>
            <td>✅</td>
            <td>[Docs](https://portal.thirdweb.com/)</td>
            <td>[Paymaster and Bundler](https://portal.thirdweb.com/connect/account-abstraction/infrastructure)</td>
            <td>[Quickstart](https://portal.thirdweb.com/typescript/v5/account-abstraction/get-started)</td>
          </tr>

          <tr>
            <td>[ZeroDev](https://zerodev.app/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.zerodev.app/)</td>
            <td>[Meta AA infrastructure](https://docs.zerodev.app/meta-infra/intro) for bundlers and paymasters</td>
            <td>[Dashboard](https://dashboard.zerodev.app/)</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>
</Tabs>

## Provider Details

### Alchemy

Alchemy powers the [#1 most used](https://www.bundlebear.com/erc4337-overview/all) smart accounts today with account abstraction that eliminates gas fees and signing for users. Their accounts support ERC-4337, EIP-7702, and ERC-6900, a modular account standard co-authored with the Ethereum Foundation, Circle, and Trust Wallet.

To get started, sign up for an [Alchemy account](https://dashboard.alchemy.com/accounts?utm_source=chain_partner\&utm_medium=referral\&utm_campaign=monad), visit the [documentation](https://accountkit.alchemy.com/), follow the [quickstart](https://accountkit.alchemy.com/react/quickstart) guide. To learn more, check out their [smart wallets](https://www.alchemy.com/smart-wallets) and demo [here](https://demo.alchemy.com/).

### Biconomy

[Biconomy](https://biconomy.io) is the most comprehensive smart account and execution infrastructure platform that enables seamless, user-friendly experiences across single or multiple chains. With Biconomy, developers can build superior onchain UX through gas abstraction, sessions, batching, and one-click signatures for complex actions on any number of networks.

To get started, visit the [documentation](https://docs.biconomy.io/).

### FastLane

[FastLane](https://www.fastlane.xyz/) is an MEV protocol for validators + apps with an integrated 4337 bundler, an on-chain task scheduler, and the first holistic LST.

To get started, vist the [shMonad](https://docs.shmonad.xyz/) Documentation or try the shMonad bundler using the following example [project](https://github.com/FastLane-Labs/4337-bundler-paymaster-script/tree/main).

### Gelato

[Gelato](https://docs.gelato.cloud/paymaster-&-bundler/introduction/overview) provides Paymaster and Bundler services that enable sponsored transactions and Account Abstraction, allowing you to cover gas costs on behalf of users and enable seamless onchain experiences.

To get started, visit the [documentation](https://docs.gelato.cloud/paymaster-&-bundler/introduction/overview) or follow the [quickstart](https://docs.gelato.cloud/paymaster-&-bundler/how-to-guides/overview) guide.

### Openfort

[Openfort](https://openfort.io) is a developer platform that helps projects onboard and and activates wallets. It does so by creating wallets with it’s SSS and passkeys,sending transactions via sponsored paymasters and session keys or directly using backend wallets for automated onchain actions.

To get started, visit the [documentation](https://www.openfort.io/docs/overview/start) or follow the [quickstart](https://www.openfort.io/docs/guides/react) guide.

### Pimlico

[Pimlico](https://pimlico.io/) is the world's most advanced ERC-4337 account abstraction infrastructure platform. Pimlico provides a suite of tools and services to help you build, deploy, and manage smart accounts on Ethereum and other EVM-compatible chains.

To get started, visit the [documentation](https://docs.pimlico.io/) or follow the [quickstart](https://docs.pimlico.io/permissionless/tutorial/tutorial-1) guide.

### Sequence

The [Sequence](https://sequence.xyz)
[Transaction API](https://docs.sequence.xyz/solutions/infrastructure/transaction-api) is a unified
relayer that dispatches transactions on EVM chains with:

* Gas sponsorship
* Fee abstraction
* Batching
* Parallel processing

It manages nonces, estimates optimal gas, and resubmits transactions when needed, so you can focus
on your business logic. [Sequence Builder](https://sequence.build/) offers a Gas Sponsorship feature
that allows project owners to easily sponsor gas for their users in web3 apps. By covering
transaction fees, users can enjoy a seamless experience without worrying about obtaining crypto
for fees which is seamlessly integrated with our suite of smart contract wallets.

To get started, visit the gas sponsorship [docs](https://docs.sequence.xyz/solutions/builder/gas-sponsorship).

### thirdweb

[thirdweb](https://portal.thirdweb.com/connect/account-abstraction/overview) offers a complete platform to leverage account abstraction.

Remove the clunky user experience of requiring gas & signatures for every onchain action:

* Abstract away gas
* Pre-audited account factory contracts
* Built-in infra:
* Sponsorship policies

To get started:

1. Sign up for a [free thirdweb account](https://thirdweb.com/team)
2. Visit [Account Abstraction Documentation](https://portal.thirdweb.com/connect/account-abstraction/how-it-works) and [Account Abstraction Playground](https://playground.thirdweb.com/connect/account-abstraction/connect)

### Zerodev

[ZeroDev](https://zerodev.app) is the most powerful smart account development platform. With ZeroDev, you can build Web3 experiences without gas, confirmations, seed phrases, and bridging.

To get started, visit the [documentation](https://docs.zerodev.app/) or follow the [quickstart](https://docs.zerodev.app/sdk/getting-started/quickstart) guide.


# Embedded Wallets
Source: https://docs.monad.xyz/tooling-and-infra/wallet-infra/embedded-wallets



## Background

Some developers want to "embed" a wallet into their application. Here are a few possible reasons
they might want to do this:

* to allow users to sign in with email or another social sign-in method
* to allow users to take actions within the app without signing a new transaction each time.

Generally speaking, embedded wallet services provide this by utilizing advanced cryptographic
techniques to shard keys. Some keys are stored user-side while others are stored on
the application developer's server or the embedded wallet provider's server.

This page attempts a toplogy of authentication and key management features over the set of
providers supporting Monad.

### Authentication Features

| Features        | Description                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------- |
| Passkey sign-in | Authentication with [WebAuthn](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) (passkey) |
| Social sign-in  | Authentication with social accounts (google, X, etc)                                                              |
| Email sign-in   | Authentication with OTP via email                                                                                 |
| SMS sign-in     | Authentication with OTP via SMS                                                                                   |

### Key Management Features

| Features                 | Description                                                                                     |
| ------------------------ | ----------------------------------------------------------------------------------------------- |
| MPC                      | Multi-party computation                                                                         |
| SSS                      | Shamir's Secret Sharing                                                                         |
| TEE                      | Storage of private keys in a cloud-based Trusted Execution Environment, like AWS Nitro Enclaves |
| TSS                      | Threshold Signature Scheme                                                                      |
| Embedded wallet          | A wallet interface local to a website or mobile app, utilizing browser session keys for signing |
| Server-delegated actions | Allow app to request permission to sign on the user's behalf                                    |
| Session keys             | Scoped keys that grant access only for specific apps, useful for bots/AI agents                 |

## Provider Summary

<Tabs>
  <Tab title="Mainnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Supported services</th>
            <th>Security Method</th>
            <th>How to get started</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Alchemy](https://www.alchemy.com/smart-wallets)</td>
            <td>✅</td>
            <td>[Docs](https://accountkit.alchemy.com/)</td>
            <td>[Embedded wallets](https://accountkit.alchemy.com/react/quickstart)<br />
            Auth: [passkey](https://accountkit.alchemy.com/signer/authentication/passkey-signup), [social](https://accountkit.alchemy.com/signer/authentication/social-login), [email](https://accountkit.alchemy.com/signer/authentication/email-otp) sign-in</td>

            <td />

            <td>[Quickstart](https://accountkit.alchemy.com/react/quickstart)</td>
          </tr>

          <tr>
            <td>[Coinbase Developer Platform (CDP)](https://www.coinbase.com/developer-platform/products/embeddedwallets)</td>
            <td>✅</td>
            <td>[Docs](https://docs.cdp.coinbase.com/embedded-wallets/welcome)</td>
            <td>[Embedded wallets](https://docs.cdp.coinbase.com/embedded-wallets/welcome)<br />
            Auth: [email/social/SMS](https://docs.cdp.coinbase.com/embedded-wallets/authentication-methods)</td>
            <td>Device-based secure enclaves</td>
            <td>[Quickstart](https://docs.cdp.coinbase.com/embedded-wallets/quickstart)</td>
          </tr>

          <tr>
            <td>[Dynamic](https://dynamic.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.dynamic.xyz/)</td>
            <td>[Embedded wallets](https://docs.dynamic.xyz/wallets/embedded-wallets/dynamic-embedded-wallets)<br />
            Auth: [passkey](https://docs.dynamic.xyz/wallets/v1-embedded/transactional-mfa/passkeys#passkeys), [email/social/SMS](https://docs.dynamic.xyz/authentication-methods/email-social-sms) sign-in</td>
            <td>TEE; TSS-MPC (just added)</td>
            <td>[Get started](https://www.dynamic.xyz/get-started)</td>
          </tr>

          <tr>
            <td>[Fordefi](https://fordefi.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.fordefi.com/)</td>
            <td>[Products and Services](https://docs.fordefi.com/user-guide/welcome/products-and-services)</td>
            <td>MPC</td>
            <td>[Quickstart](https://docs.fordefi.com/user-guide/quickstart)</td>
          </tr>

          <tr>
            <td>[MetaMask Embedded Wallet](https://docs.metamask.io/embedded-wallets/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.metamask.io/embedded-wallets/)</td>
            <td>Embedded wallet<br />
            Auth: [passkey](https://docs.metamask.io/embedded-wallets/authentication/), [social](https://docs.metamask.io/embedded-wallets/authentication/social-logins/google/), [email](https://docs.metamask.io/embedded-wallets/authentication/basic-logins/email-passwordless/), [SMS](https://docs.metamask.io/embedded-wallets/authentication/basic-logins/sms-otp/)</td>
            <td>MPC-SSS/TSS</td>
            <td>[Quickstart](https://docs.metamask.io/embedded-wallets/connect-blockchain/evm/monad)</td>
          </tr>

          <tr>
            <td>[Openfort](https://openfort.io/)</td>
            <td>✅</td>
            <td>[Docs](https://www.openfort.io/docs)</td>
            <td>[Embedded wallets](https://www.openfort.io/docs/guides/react/configuration), [Backend wallets](https://www.openfort.io/docs/guides/server/dev), [Ecosystem wallets](https://www.openfort.io/docs/guides/ecosystem)<br />
            Auth: [passkeys](https://www.openfort.io/docs/products/embedded-wallet/react/auth), [social](https://www.openfort.io/docs/products/embedded-wallet/react/auth), [email](https://www.openfort.io/docs/products/embedded-wallet/react/auth)</td>
            <td>SSS</td>
            <td>[Quickstart](https://www.openfort.io/docs/guides/react)</td>
          </tr>

          <tr>
            <td>[Para](https://www.getpara.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.getpara.com/)</td>
            <td>[Embedded wallets](https://docs.getpara.com/getting-started/initial-setup/react-nextjs); robust policy engine for sessions<br />
            Auth: [email and phone](https://docs.getpara.com/v2/swift/guides/email-phone-login#email-and-phone-login), [social](https://docs.getpara.com/customize-para/oauth-social-logins), [SMS](https://docs.getpara.com/customize-para/phone-login) sign-in</td>
            <td>MPC + DKG</td>
            <td>[Quickstart](https://docs.getpara.com/v1/web/guides/evm/overview#evm-overview)</td>
          </tr>

          <tr>
            <td>[Portal](https://www.portalhq.io/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.portalhq.io/)</td>
            <td>[Integration overview](https://docs.portalhq.io/integrations)</td>
            <td>TSS MPC</td>
            <td>[API Quickstart](https://docs.portalhq.io/apis/quickstart), [SDK Quickstart](https://docs.portalhq.io/sdks/quickstart)</td>
          </tr>

          <tr>
            <td>[Privy](https://privy.io/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.privy.io/)</td>
            <td>[Embedded wallets](https://docs.privy.io/guide/embedded-wallets), [server wallets](https://docs.privy.io/guide/overview-server-wallets), server-delegated actions<br />
            Auth: [passkey](https://docs.privy.io/guide/authentication), [social](https://docs.privy.io/guide/authentication), [email](https://docs.privy.io/guide/authentication), [SMS](https://docs.privy.io/guide/authentication)</td>
            <td>TEE + SSS</td>
            <td>[Quickstart](https://docs.privy.io/guide/react/quickstart)</td>
          </tr>

          <tr>
            <td>[Reown](https://reown.com/) (formerly WalletConnect)</td>
            <td>✅</td>
            <td>[Docs](https://docs.reown.com/)</td>
            <td>Popular UI component for selecting a wallet<br />
            Embedded wallet with social/email sign-in</td>

            <td />

            <td>[Overview](https://docs.reown.com/appkit/overview)</td>
          </tr>

          <tr>
            <td>[Sequence](https://sequence.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.sequence.xyz/solutions/wallets/overview)</td>
            <td>[Embedded wallets](https://docs.sequence.xyz/solutions/wallets/developers/embedded-wallet/overview),
            [ecosystem wallets](https://docs.sequence.xyz/solutions/wallets/developers/overview)<br />Auth: Passkey, Google, Apple, Twitter, email, Facebook, Twitch, Epic Games, Playfab, Stych, Standard OAuth</td>
            <td>TEE; Sandboxed Smart Sessions</td>
            <td>[Ecosystem quickstart](https://docs.sequence.xyz/solutions/wallets/developers/overview)<br /><br />
            [Embedded quickstart](https://docs.sequence.xyz/solutions/wallets/developers/embedded-wallet/quickstart)</td>
          </tr>

          <tr>
            <td>[thirdweb](https://thirdweb.com/)</td>
            <td>✅</td>
            <td>[Docs](https://portal.thirdweb.com/connect/wallet/overview)</td>
            <td>Embedded wallets<br />
            Auth: [passkey](https://portal.thirdweb.com/connect/wallet/sign-in-methods/configure), [social](https://portal.thirdweb.com/connect/wallet/sign-in-methods/configure), [email](https://portal.thirdweb.com/connect/wallet/sign-in-methods/configure), [SMS](https://portal.thirdweb.com/connect/wallet/sign-in-methods/configure), OIDC, or generic auth</td>

            <td />

            <td>[Quickstart](https://portal.thirdweb.com/connect/wallet/get-started)</td>
          </tr>

          <tr>
            <td>[Turnkey](https://www.turnkey.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.turnkey.com/)</td>
            <td>[Embedded wallet](https://docs.turnkey.com/reference/embedded-wallet-kit), [policy engine](https://docs.turnkey.com/concepts/policies/overview), [delegated access](https://docs.turnkey.com/concepts/policies/delegated-access-frontend), [signing automation](https://docs.turnkey.com/signing-automation/overview), [sessions](https://docs.turnkey.com/authentication/sessions)<br />
            [Server-side SDKs](https://docs.turnkey.com/sdks/introduction) for auth, wallet management, and policies<br />
            Auth: [passkey](https://docs.turnkey.com/authentication/passkeys/introduction), [social](https://docs.turnkey.com/authentication/social-logins), [email](https://docs.turnkey.com/authentication/email), [SMS](https://docs.turnkey.com/authentication/sms) login</td>
            <td>TEE</td>
            <td>[Quickstart](https://docs.turnkey.com/getting-started/quickstart)</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>

  <Tab title="Testnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Supported services</th>
            <th>Security Method</th>
            <th>How to get started</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Alchemy](https://www.alchemy.com/smart-wallets)</td>
            <td>✅</td>
            <td>[Docs](https://accountkit.alchemy.com/)</td>
            <td>[Embedded wallets](https://accountkit.alchemy.com/react/quickstart)<br />
            Auth: [passkey](https://accountkit.alchemy.com/signer/authentication/passkey-signup), [social](https://accountkit.alchemy.com/signer/authentication/social-login), [email](https://accountkit.alchemy.com/signer/authentication/email-otp) sign-in</td>

            <td />

            <td>[Quickstart](https://accountkit.alchemy.com/react/quickstart)</td>
          </tr>

          <tr>
            <td>[Coinbase Developer Platform (CDP)](https://www.coinbase.com/developer-platform/products/embeddedwallets)</td>
            <td>✅</td>
            <td>[Docs](https://docs.cdp.coinbase.com/embedded-wallets/welcome)</td>
            <td>[Embedded wallets](https://docs.cdp.coinbase.com/embedded-wallets/welcome)<br />
            Auth: [email/social/SMS](https://docs.cdp.coinbase.com/embedded-wallets/authentication-methods)</td>
            <td>Device-based secure enclaves</td>
            <td>[Quickstart](https://docs.cdp.coinbase.com/embedded-wallets/quickstart)</td>
          </tr>

          <tr>
            <td>[Dynamic](https://dynamic.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.dynamic.xyz/)</td>
            <td>[Embedded wallets](https://docs.dynamic.xyz/wallets/embedded-wallets/dynamic-embedded-wallets)<br />
            Auth: [passkey](https://docs.dynamic.xyz/wallets/v1-embedded/transactional-mfa/passkeys#passkeys), [email/social/SMS](https://docs.dynamic.xyz/authentication-methods/email-social-sms) sign-in</td>
            <td>TEE; TSS-MPC (just added)</td>
            <td>[Get started](https://www.dynamic.xyz/get-started)</td>
          </tr>

          <tr>
            <td>[Fordefi](https://fordefi.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.fordefi.com/)</td>
            <td>[Products and Services](https://docs.fordefi.com/user-guide/welcome/products-and-services)</td>
            <td>MPC</td>
            <td>[Quickstart](https://docs.fordefi.com/user-guide/quickstart)</td>
          </tr>

          <tr>
            <td>[MetaMask Embedded Wallet](https://docs.metamask.io/embedded-wallets/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.metamask.io/embedded-wallets/)</td>
            <td>Embedded wallet<br />
            Auth: [passkey](https://docs.metamask.io/embedded-wallets/authentication/), [social](https://docs.metamask.io/embedded-wallets/authentication/social-logins/google/), [email](https://docs.metamask.io/embedded-wallets/authentication/basic-logins/email-passwordless/), [SMS](https://docs.metamask.io/embedded-wallets/authentication/basic-logins/sms-otp/)</td>
            <td>MPC-SSS/TSS</td>
            <td>[Quickstart](https://docs.metamask.io/embedded-wallets/connect-blockchain/evm/monad)</td>
          </tr>

          <tr>
            <td>[Openfort](https://openfort.io/)</td>
            <td>✅</td>
            <td>[Docs](https://www.openfort.io/docs)</td>
            <td>[Embedded wallets](https://www.openfort.io/docs/guides/react/configuration), [Backend wallets](https://www.openfort.io/docs/guides/server/dev), [Ecosystem wallets](https://www.openfort.io/docs/guides/ecosystem)<br />
            Auth: [passkeys](https://www.openfort.io/docs/products/embedded-wallet/react/auth), [social](https://www.openfort.io/docs/products/embedded-wallet/react/auth), [email](https://www.openfort.io/docs/products/embedded-wallet/react/auth)</td>
            <td>SSS</td>
            <td>[Quickstart](https://www.openfort.io/docs/guides/react)</td>
          </tr>

          <tr>
            <td>[Para](https://www.getpara.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.getpara.com/)</td>
            <td>[Embedded wallets](https://docs.getpara.com/getting-started/initial-setup/react-nextjs); robust policy engine for sessions<br />
            Auth: [email and phone](https://docs.getpara.com/v2/swift/guides/email-phone-login#email-and-phone-login), [social](https://docs.getpara.com/customize-para/oauth-social-logins), [SMS](https://docs.getpara.com/customize-para/phone-login) sign-in</td>
            <td>MPC + DKG</td>
            <td>[Quickstart](https://docs.getpara.com/v1/web/guides/evm/overview#evm-overview)</td>
          </tr>

          <tr>
            <td>[Phantom](https://phantom.com/learn/developers)</td>
            <td>✅</td>
            <td>[Docs](https://docs.phantom.com/)</td>
            <td>[Embedded wallets](https://github.com/phantom/wallet-sdk) (Web SDK & Native Mobile SDK)<br />
            Auth: [Google](https://phantom.com/learn/blog/deep-dive-log-in-to-phantom-with-email) sign-in</td>
            <td>SSS</td>
            <td>[Quickstart](https://docs.phantom.com/introduction)</td>
          </tr>

          <tr>
            <td>[Portal](https://www.portalhq.io/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.portalhq.io/)</td>
            <td>[Integration overview](https://docs.portalhq.io/integrations)</td>
            <td>TSS MPC</td>
            <td>[API Quickstart](https://docs.portalhq.io/apis/quickstart), [SDK Quickstart](https://docs.portalhq.io/sdks/quickstart)</td>
          </tr>

          <tr>
            <td>[Privy](https://privy.io/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.privy.io/)</td>
            <td>[Embedded wallets](https://docs.privy.io/guide/embedded-wallets), [server wallets](https://docs.privy.io/guide/overview-server-wallets), server-delegated actions<br />
            Auth: [passkey](https://docs.privy.io/guide/authentication), [social](https://docs.privy.io/guide/authentication), [email](https://docs.privy.io/guide/authentication), [SMS](https://docs.privy.io/guide/authentication)</td>
            <td>TEE + SSS</td>
            <td>[Quickstart](https://docs.privy.io/guide/react/quickstart)</td>
          </tr>

          <tr>
            <td>[Reown](https://reown.com/) (formerly WalletConnect)</td>
            <td>✅</td>
            <td>[Docs](https://docs.reown.com/)</td>
            <td>Popular UI component for selecting a wallet<br />
            Embedded wallet with social/email sign-in</td>

            <td />

            <td>[Overview](https://docs.reown.com/appkit/overview)</td>
          </tr>

          <tr>
            <td>[Sequence](https://sequence.xyz/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.sequence.xyz/solutions/wallets/overview)</td>
            <td>[Embedded wallets](https://docs.sequence.xyz/solutions/wallets/developers/embedded-wallet/overview),
            [ecosystem wallets](https://docs.sequence.xyz/solutions/wallets/developers/overview)<br />Auth: Passkey, Google, Apple, Twitter, email, Facebook, Twitch, Epic Games, Playfab, Stych, Standard OAuth</td>
            <td>TEE; Sandboxed Smart Sessions</td>
            <td>[Ecosystem quickstart](https://docs.sequence.xyz/solutions/wallets/developers/overview)<br /><br />
            [Embedded quickstart](https://docs.sequence.xyz/solutions/wallets/developers/embedded-wallet/quickstart)</td>
          </tr>

          <tr>
            <td>[thirdweb](https://thirdweb.com/)</td>
            <td>✅</td>
            <td>[Docs](https://portal.thirdweb.com/connect/wallet/overview)</td>
            <td>Embedded wallets<br />
            Auth: [passkey](https://portal.thirdweb.com/connect/wallet/sign-in-methods/configure), [social](https://portal.thirdweb.com/connect/wallet/sign-in-methods/configure), [email](https://portal.thirdweb.com/connect/wallet/sign-in-methods/configure), [SMS](https://portal.thirdweb.com/connect/wallet/sign-in-methods/configure), OIDC, or generic auth</td>

            <td />

            <td>[Quickstart](https://portal.thirdweb.com/connect/wallet/get-started)</td>
          </tr>

          <tr>
            <td>[Turnkey](https://www.turnkey.com/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.turnkey.com/)</td>
            <td>[Embedded wallet](https://docs.turnkey.com/reference/embedded-wallet-kit), [policy engine](https://docs.turnkey.com/concepts/policies/overview), [delegated access](https://docs.turnkey.com/concepts/policies/delegated-access-frontend), [signing automation](https://docs.turnkey.com/signing-automation/overview), [sessions](https://docs.turnkey.com/authentication/sessions)<br />
            [Server-side SDKs](https://docs.turnkey.com/sdks/introduction) for auth, wallet management, and policies<br />
            Auth: [passkey](https://docs.turnkey.com/authentication/passkeys/introduction), [social](https://docs.turnkey.com/authentication/social-logins), [email](https://docs.turnkey.com/authentication/email), [SMS](https://docs.turnkey.com/authentication/sms) login</td>
            <td>TEE</td>
            <td>[Quickstart](https://docs.turnkey.com/getting-started/quickstart)</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>
</Tabs>

## Providers Offering Subsidized Usage

These WaaS providers are subsidizing usage on Monad Testnet:

| Provider                            | How to access                                                                                                     |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| [Privy](https://privy.io/)          | Sign up, then email the Privy team at `monad@privy.io`                                                            |
| [Para](https://www.getpara.com/)    | Sign up via the [Developer Portal](https://developer.getpara.com/) and reach out to the team at `ops@getpara.com` |
| [Turnkey](https://www.turnkey.com/) | Turnkey is free for developers building on Monad Testnet. All you need to do is sign up!                          |

## Provider Details

### Alchemy

[Account Kit](https://accountkit.alchemy.com/) is a complete solution for account abstraction. Using Account Kit, you can create a smart contract wallet for every user that leverages account abstraction to simplify every step of your app's onboarding experience. It also offers Gas Manager and Bundler APIs for sponsoring gas and batching transactions.

To get started, sign up for an [Alchemy account](https://www.alchemy.com/), visit the [documentation](https://accountkit.alchemy.com/), follow the [quickstart](https://accountkit.alchemy.com/react/quickstart) guide or check out the demo [here](https://demo.alchemy.com/).

Alchemy helps you to replace 3rd-party pop-up wallets with native in-app auth. Drop in branded sign-in modals for email, passkeys, and social logins with plug-n-play components.

To get started, sign up for an [Alchemy account](https://dashboard.alchemy.com/accounts?utm_source=chain_partner\&utm_medium=referral\&utm_campaign=monad), visit the [documentation](https://accountkit.alchemy.com/), follow the [quickstart](https://accountkit.alchemy.com/react/quickstart) guide. To further streamline UX with no gas fees or signing for users, see Alchemy's [AA infra offering](/tooling-and-infra/wallet-infra/account-abstraction#alchemy) and a demo [here](https://demo.alchemy.com/).

### Coinbase Developer Platform

[Coinbase Developer Platform](https://www.coinbase.com/developer-platform/) allows developers to
build next-gen on-chain apps. CDP simplifies development by providing services for creating smart
wallets, processing payments, and integrating crypto into existing apps.

With CDP Embedded Wallets, your users can access the full power of blockchains through familiar
authentication methods like email and social logins (no seed phrases, browser extensions, or
pop-ups required).

To get started, visit the [documentation](https://docs.cdp.coinbase.com/embedded-wallets/welcome)
or follow the [quickstart](https://docs.cdp.coinbase.com/embedded-wallets/quickstart) guide.

### Dynamic

[Dynamic](https://dynamic.xyz/) offers smart and beautiful login flows for crypto-native users, simple onboarding flows for everyone else, and powerful developer tools that go beyond authentication.

To get started, visit the [documentation](https://docs.dynamic.xyz/) or follow the [quickstart](https://docs.dynamic.xyz/docs/quickstart) guide.

### Fordefi

[Fordefi](https://fordefi.com/) is the first institutional MPC wallet and security platform built for decentralized finance (DeFi), offering MPC key management, self-serve DeFi policy controls, time-of-transaction smart contract insights, transaction simulation, and real-time risk alerts, alongside a full-stack developer suite of native APIs and SDKs.

To get started, visit the [documentation](https://docs.fordefi.com/) or follow the [quickstart](https://docs.fordefi.com/user-guide/quickstart) guide.

### MetaMask Embedded Wallet

[MetaMask Embedded Wallets](https://docs.metamask.io/embedded-wallets/) brings one-click, OAuth-based onboarding to Monad.

Users can log in with Google or Apple and get a non-custodial wallet instantly connected to the network — with no setup or seed phrase required.

Setup is entirely handled in the MetaMask Dashboard — developers just enable Monad, and it works out of the box.

Learn more at [docs.metamask.io/embedded-wallets](https://docs.metamask.io/embedded-wallets/).

To get started, visit the [Monad integration guide](https://docs.metamask.io/embedded-wallets/connect-blockchain/evm/monad).

### Para

<Info>
  Para is free for developers building on Monad Testnet!

  Sign up via the [Developer Portal](https://developer.getpara.com/) and reach out to the team via the below email.

  `ops@getpara.com`
</Info>

[Para](https://www.getpara.com/) is the easiest and most secure way to onboard all your users and support them throughout their crypto journey. We support projects throughout their growth, ranging from personal projects to many of the most trusted teams in crypto and beyond.

Para's cross-app embedded wallets work universally across apps, chains, and ecosystem, so whether users start transacting on EVM, Solana, or Cosmos, they can onboard once and transact forever, all with the same wallet.

To get started, visit the [documentation](https://docs.getpara.com/v1/introduction/welcome#welcome) or follow the [quickstart](https://docs.getpara.com/v2/introduction/welcome) guide.

### Phantom

[Phantom](https://phantom.com/) is the world's leading crypto wallet for managing digital assets and accessing decentralized applications.

Phantom embedded wallets enable seamless, seedless onboarding with in-app, non-custodial access--no app switching or seed phrases required.

To get started, visit the [documentation](https://docs.phantom.com/) or follow the [Introduction](https://docs.phantom.com/introduction) guide.

### Portal

[Portal](https://www.portalhq.io/) is a fast, flexible, and secure stablecoin finance developer platform. Create wallets, move stablecoins, and scale on-chain operations — all with simple SDKs and APIs.

To get started, visit the [documentation](https://docs.portalhq.io/) or follow the [quickstart](https://docs.portalhq.io/apis/quickstart) guide.

### Privy

<Info>
  Privy is subsidizing all Monad Testnet usage!

  For more details reach out to the Privy team via the below email.

  `monad@privy.io`
</Info>

[Privy](https://privy.io/) helps you onboard any user to crypto no matter how familiar they are with the space. Power flexible, powerful wallets under the hood for any application, securely.

To get started, visit the [documentation](https://docs.privy.io/) or follow the [quickstart](https://docs.privy.io/guide/react/quickstart) guide.

### Reown

[Reown](https://reown.com/) gives developers the tools to build user experiences that make digital ownership effortless, intuitive, and secure.

#### AppKit

AppKit is a powerful, free, and fully open-source SDK for developers looking to integrate wallet connections and other Web3 functionalities into their apps on any EVM and non-EVM chain. In just a few simple steps, you can provide your users with seamless wallet access, one-click authentication, social logins, and notifications—streamlining their experience while enabling advanced features like on-ramp functionality, in-app token swaps and smart accounts.

To get started, visit the [documentation](https://docs.reown.com/) or follow the [quickstart](https://reown.com/blog/how-to-get-started-with-reown-appkit-on-monad-testnet) guide.

### Sequence

[Sequence](https://sequence.xyz) provides the industry gold standard in robust open-source,
non-custodial [Embedded](https://docs.sequence.xyz/solutions/wallets/developers/embedded-wallet/overview)
and [Ecosystem](https://docs.sequence.xyz/solutions/wallets/developers/overview)
Wallets.Sequence is the originator of non-custodial smart contract wallets, and authors of
ERC-1271 and ERC-6492.

Embedded and Ecosystem Wallets enable seamless onboarding with user-friendly
email, social, passkey, and guest account logins. Invisible onchain transactions; secure and
compliant non-custodial sovereignty; and cross-platform integrations with SDKs for Unity, Unreal,
Web, and mobile. Fully customizable for developers and ecosystems.

To get started, visit the [Ecosystem Wallet Quickstart](https://docs.sequence.xyz/solutions/wallets/developers/overview#ecosystem-wallet-quickstarts).

### thirdweb

[thirdweb](https://thirdweb.com/) provides client-side SDKs for user onboarding, identity and transactions.

* Onboard new users to your apps with every wallet & login method
* create a complete picture of all your users via user analytics & identity linking
* facilitate onchain transactions via onramps, swaps & bridging

To get started:

1. Sign up for a [free thirdweb account](https://thirdweb.com/team)
2. Visit [Connect Documentation](https://portal.thirdweb.com/connect/sign-in/ConnectButton) and [Connect Playground](https://playground.thirdweb.com/connect/sign-in/button)

### Turnkey

<Info>
  Turnkey is free for developers building on Monad Testnet!
</Info>

[Turnkey](https://www.turnkey.com/) is secure, flexible, and scalable wallet infrastructure. Create millions of embedded wallets, eliminate manual transaction flows, and automate onchain actions - all without compromising on security.

To get started, visit the [documentation](https://docs.turnkey.com/) or follow the [quickstart](https://docs.turnkey.com/getting-started/embedded-wallet-quickstart) guide.


# Wallet Infrastructure
Source: https://docs.monad.xyz/tooling-and-infra/wallet-infra/index



## Summary

Monad features excellent support for developers looking to refine their users' experience
by utilizing modular wallet infrastructure.

These pages survey the supported infrastructure:

* [Embedded Wallets](/tooling-and-infra/wallet-infra/embedded-wallets)
* [Account Abstraction Providers](/tooling-and-infra/wallet-infra/account-abstraction)
* [Smart Account Implementations](/tooling-and-infra/wallet-infra/smart-accounts)

The landscape can be confusing, even to an experienced developer; therefore we include a
rough topology below.

## Background

Wallets allow users to store private keys and sign transactions. The basic setup involves
separation between the wallet and the application: the application presents a transaction
to the wallet for signing, and the wallet submits the transaction to the network, paying
for inclusion and execution with native tokens deducted from its balance.

However, increasingly, developers wish to customize their users' experience, for example by
sponsoring gas for their users or by allowing users to pay fees in an alternate currency. Other
developers want to embed the "wallet" into the app and give the app signing power over that
wallet, so that users don't have to sign a transaction with each action that they take.
Modular wallet infrastructure enables these and other features.

A number of providers are solving for this experience. To simplify understanding of the options,
we suggest the following two-dimensional matrix:

|                   | Freestanding                                                                                                                                                                                                                      | Embedded                                                                                                                                    |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **EOA**           | See [Simple Wallets](/tooling-and-infra/wallets)                                                                                                                                                                                  | See [Embedded Wallets](/tooling-and-infra/wallet-infra/embedded-wallets).<br />Typically utilizes key sharding, e.g. using MPC, SSS, or TEE |
| **Smart Account** | Utilizes Account Abstraction, i.e. developer needs to choose:<br /><ul><li>[AA Providers](/tooling-and-infra/wallet-infra/account-abstraction)</li><li>[Smart Accounts](/tooling-and-infra/wallet-infra/smart-accounts)</li></ul> | See [Embedded Wallets](/tooling-and-infra/wallet-infra/embedded-wallets) and look for "Embedded Smart Accounts"                             |

## EOA-based approach

**(EOA, freestanding)** is the traditional wallet experience powered by browser extension wallets,
mobile wallets, and hardware wallets. It involves a single private key stored within the wallet.
See [Wallets](/tooling-and-infra/wallets) for a survey.

**(EOA, embedded)**: typically uses cryptographic techniques (MPC, SSS, etc) to shard the
signing keys, implementing additional authorization or access control features off-chain, while
presenting to the blockchain as an ordinary EOA. See [Embedded Wallets](/tooling-and-infra/wallet-infra/embedded-wallets)
for a list of providers.

## Smart account (account abstraction) approach

Account Abstraction means using smart contracts in place of simple EOAs. The smart contract
implements the authorization / access control logic, i.e. the logic is on chain.

Historically, smart contracts could not pay for their own transaction costs (although EIP-7702
introduces an exception to this rule). Therefore, the account abstraction path requires
users to sign pseudo-transactions (UserOperations) and submit them to a custom mempool.
Then, a service called the Bundler/Relayer submits UserOperations in a normal Monad transaction
and pays for the execution.

Thus, there are at least two considerations for developers building with smart accounts:

* the Bundler/Relayer service; see [Account Abstraction Providers](/tooling-and-infra/wallet-infra/account-abstraction)
  for a list
* the [Smart Account Implementation](/tooling-and-infra/wallet-infra/smart-accounts)

Some embedded wallet providers support smart accounts. See [Embedded Wallets](/tooling-and-infra/wallet-infra/embedded-wallets)
and look out for "Embedded Smart Accounts".


# Smart Account Implementations
Source: https://docs.monad.xyz/tooling-and-infra/wallet-infra/smart-accounts



## Background

Under ERC-4337, smart wallets perform authentication (signature verification) inside of a smart
contract.  Depending on the signature scheme, signing may be done locally (on the user's computer)
or in a remote environment (e.g. TEEs).

This page lists notable smart account implementations deployed to Monad.

## Provider Summary

<Tabs>
  <Tab title="Mainnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Supported services</th>
            <th>How to get started</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Biconomy](https://biconomy.io)</td>
            <td>✅</td>
            <td>[Docs](https://docs.biconomy.io)</td>
            <td>[Nexus: Smartest & most gas-efficient smart account](https://docs.biconomy.io/new/learn-about-biconomy/nexus)<br />
            [External Wallets](https://docs.biconomy.io/new/quickstart/external-wallets-quickstart)<br />
            Auth: [privy](https://docs.biconomy.io/new/integration-guides/wallets-and-signers/privy), [turnkey](https://docs.biconomy.io/new/integration-guides/wallets-and-signers/turnkey); [session keys](https://docs.biconomy.io/new/smart-sessions/introduction)</td>
            <td>[Quickstart](https://docs.biconomy.io/new/getting-started/getting-started)</td>
          </tr>

          <tr>
            <td>[MetaMask Smart Accounts Kit](https://docs.metamask.io/smart-accounts-kit)</td>
            <td>✅</td>
            <td>[Embedded Smart Accounts (4337 & 7702)](https://docs.metamask.io/smart-accounts-kit#smart-account-implementation-types)<br />
            Auth: Signer agnostic, bring any signer<br />
            Features: WebAuthn, Multisig, [ERC-7710 delegations support](https://eips.ethereum.org/EIPS/eip-7710)</td>

            <td />

            <td>[Quickstart](https://docs.metamask.io/smart-accounts-kit/get-started/smart-account-quickstart/)</td>
          </tr>

          <tr>
            <td>[Pimlico](https://pimlico.io/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.pimlico.io/)</td>
            <td>[permissionless.js](https://docs.pimlico.io/permissionless), a flexible SDK for interfacing with various smart accounts, bundlers/paymasters, and signers.</td>
            <td>[Tutorial](https://docs.pimlico.io/permissionless/tutorial/tutorial-1)</td>
          </tr>

          <tr>
            <td>[ZeroDev](https://zerodev.app/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.zerodev.app/)</td>
            <td>[Smart contract accounts](https://docs.zerodev.app/sdk/core-api/create-account)<br />
            [Session keys](https://docs.zerodev.app/sdk/permissions/intro) with several options for signature schemes (ECDSA, Passkey, Multisig), policies, and actions.</td>
            <td>[Quickstart](https://docs.zerodev.app/sdk/getting-started/quickstart)</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>

  <Tab title="Testnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Provider</th>
            <th>Status</th>
            <th>Docs</th>
            <th>Supported services</th>
            <th>How to get started</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Biconomy](https://biconomy.io)</td>
            <td>✅</td>
            <td>[Docs](https://docs.biconomy.io)</td>
            <td>[Nexus: Smartest & most gas-efficient smart account](https://docs.biconomy.io/new/learn-about-biconomy/nexus)<br />
            [External Wallets](https://docs.biconomy.io/new/quickstart/external-wallets-quickstart)<br />
            Auth: [privy](https://docs.biconomy.io/new/integration-guides/wallets-and-signers/privy), [turnkey](https://docs.biconomy.io/new/integration-guides/wallets-and-signers/turnkey); [session keys](https://docs.biconomy.io/new/smart-sessions/introduction)</td>
            <td>[Quickstart](https://docs.biconomy.io/new/getting-started/getting-started)</td>
          </tr>

          <tr>
            <td>[MetaMask Smart Accounts Kit](https://docs.metamask.io/smart-accounts-kit)</td>
            <td>✅</td>
            <td>[Embedded Smart Accounts (4337 & 7702)](https://docs.metamask.io/smart-accounts-kit#smart-account-implementation-types)<br />
            Auth: Signer agnostic, bring any signer<br />
            Features: WebAuthn, Multisig, [ERC-7710 delegations support](https://eips.ethereum.org/EIPS/eip-7710)</td>

            <td />

            <td>[Quickstart](https://docs.metamask.io/smart-accounts-kit/get-started/smart-account-quickstart/)</td>
          </tr>

          <tr>
            <td>[Pimlico](https://pimlico.io/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.pimlico.io/)</td>
            <td>[permissionless.js](https://docs.pimlico.io/permissionless), a flexible SDK for interfacing with various smart accounts, bundlers/paymasters, and signers.</td>
            <td>[Tutorial](https://docs.pimlico.io/permissionless/tutorial/tutorial-1)</td>
          </tr>

          <tr>
            <td>[ZeroDev](https://zerodev.app/)</td>
            <td>✅</td>
            <td>[Docs](https://docs.zerodev.app/)</td>
            <td>[Smart contract accounts](https://docs.zerodev.app/sdk/core-api/create-account)<br />
            [Session keys](https://docs.zerodev.app/sdk/permissions/intro) with several options for signature schemes (ECDSA, Passkey, Multisig), policies, and actions.</td>
            <td>[Quickstart](https://docs.zerodev.app/sdk/getting-started/quickstart)</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>
</Tabs>

## Provider Details

### Biconomy

[Biconomy](https://biconomy.io) is the most comprehensive smart account and execution infrastructure platform that enables seamless, user-friendly experiences across single or multiple chains. With Biconomy, developers can build superior onchain UX through gas abstraction, sessions, batching, and one-click signatures for complex actions on any number of networks.

Additionally, you can use Biconomy's [Nexus](https://docs.biconomy.io/new/learn-about-biconomy/nexus):

* Directly as a smart account with passkeys or embedded wallets
* [Directly via 7702 with embedded wallets](https://docs.biconomy.io/new/quickstart/embedded-wallets-quickstart)
* [With all EOA wallets such as Metamask, Rabby and more](https://docs.biconomy.io/new/quickstart/external-wallets-quickstart)

[Session keys](https://docs.biconomy.io/new/smart-sessions/introduction) are available for all the above methods.

To get started, visit the [documentation](https://docs.biconomy.io/).

### MetaMask Smart Accounts Kit

The [MetaMask Smart Accounts Kit](https://docs.metamask.io/smart-accounts-kit) enables developers to create and interact with MetaMask Smart Accounts, unlocking new programmable account behaviors and granular permission sharing. The toolkit allows developers to build on embedded MetaMask Smart Accounts and request Advanced Permissions ([ERC-7715](https://eips.ethereum.org/EIPS/eip-7715)) from MetaMask users.

To get started, visit the [documentation](https://docs.metamask.io/smart-accounts-kit) or follow the [quickstart](https://docs.metamask.io/smart-accounts-kit/get-started/smart-account-quickstart/) guide.

### Pimlico

[Pimlico](https://pimlico.io/) is the world's most advanced ERC-4337 account abstraction infrastructure platform. Pimlico provides a suite of tools and services to help you build, deploy, and manage smart accounts on Ethereum and other EVM-compatible chains.

To get started, visit the [documentation](https://docs.pimlico.io/) or follow the [quickstart](https://docs.pimlico.io/permissionless/tutorial/tutorial-1) guide.

### Zerodev

[ZeroDev](https://zerodev.app) is the most powerful smart account development platform. With ZeroDev, you can build Web3 experiences without gas, confirmations, seed phrases, and bridging.

To get started, visit the [documentation](https://docs.zerodev.app/) or follow the [quickstart](https://docs.zerodev.app/sdk/getting-started/quickstart) guide.


# Hardware Wallets
Source: https://docs.monad.xyz/tooling-and-infra/wallets/hardware-wallets



## Provider Summary

<Tabs>
  <Tab title="Mainnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Wallet</th>
            <th>Status</th>
            <th>Other Features</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Ledger](https://www.ledger.com)</td>
            <td>✅</td>

            <td />
          </tr>

          <tr>
            <td>[Safepal](https://www.safepal.com)</td>
            <td>✅</td>
            <td>Support for multiple cryptocurrencies, Secure element chip</td>
          </tr>

          <tr>
            <td>[Tangem](https://tangem.com/en/)</td>
            <td>✅</td>
            <td>Card-shaped, self-custodial hardware wallet designed for secure, offline storage of cryptocurrencies.</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>

  <Tab title="Testnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Wallet</th>
            <th>Status</th>
            <th>Other Features</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[D'Cent Wallet](https://dcentwallet.com)</td>
            <td>✅</td>
            <td>Biometric authentication, Bluetooth connectivity</td>
          </tr>

          <tr>
            <td>[Ledger](https://www.ledger.com)</td>
            <td>❌</td>

            <td />
          </tr>

          <tr>
            <td>[Safepal](https://www.safepal.com)</td>
            <td>✅</td>
            <td>Support for multiple cryptocurrencies, Secure element chip</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>
</Tabs>

## Provider Details

### D'Cent Wallet

[D'Cent Wallet](https://dcentwallet.com) is a hardware wallet featuring biometric authentication for enhanced security. It uses a secure chip to protect private keys and offers Bluetooth connectivity for convenient mobile device pairing. D'Cent provides a balance of security and usability with its fingerprint recognition technology and support for multiple cryptocurrencies.

To get started, learn more about D'Cent Wallet [here](https://store.dcentwallet.com/) or visit the [user guide](https://userguide.dcentwallet.com/).

### Ledger

Ledger is a leading company in cryptocurrency security, best known for its hardware wallets that
keep digital assets safe through offline (cold) storage. These wallets use a secure element chip
and custom operating system to protect private keys, while requiring users to confirm transactions
directly on the device for added safety.

Learn more about Ledger [here](https://www.ledger.com/).

### Safepal

[Safepal](https://www.safepal.com) offers hardware wallet solutions that combine security with user-friendly features. Their hardware wallets utilize secure element chips to protect private keys and support a wide range of cryptocurrencies. Safepal hardware wallets are designed to be affordable while maintaining high security standards, making them accessible to both new and experienced crypto users.

To get started, learn more about Safepal hardware wallets [here](https://www.safepal.com/s1) or visit the [documentation](https://docs.safepal.io).

### Tangem

[Tangem Wallet](https://tangem.com/en/) is a card-shaped, self-custodial hardware wallet designed for secure, offline storage of cryptocurrencies. It is roughly the size of a standard credit card and uses NFC (Near Field Communication) to connect to a smartphone.


# Wallets
Source: https://docs.monad.xyz/tooling-and-infra/wallets/index



<CardGroup>
  <Card title="Software Wallets" href="/tooling-and-infra/wallets/software-wallets">
    Browser extension wallets and mobile wallets
  </Card>

  <Card title="Hardware Wallets" href="/tooling-and-infra/wallets/hardware-wallets">
    Offline wallets
  </Card>

  <Card title="Institutional Wallets" href="/tooling-and-infra/wallets/institutional-wallets" />

  <Card title="Multisig Wallets" href="/tooling-and-infra/wallets/multisig-wallets" />
</CardGroup>

<br />

For developers looking for advanced functionality such as embedded wallets or account
abstraction, see [Wallet Infrastructure](/tooling-and-infra/wallet-infra).


# Institutional Wallets
Source: https://docs.monad.xyz/tooling-and-infra/wallets/institutional-wallets



<Note>
  See also [Custody](/tooling-and-infra/custody).
</Note>

## Provider Summary

<Tabs>
  <Tab title="Mainnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Wallet</th>
            <th>Status</th>
            <th>Contract addresses</th>
            <th>Other Features</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Porto by Anchorage Digital](https://www.anchorage.com/platform/self-custody)</td>
            <td>✅</td>

            <td />

            <td />
          </tr>

          <tr>
            <td>[Utila](https://utila.io/)</td>
            <td>✅</td>

            <td />

            <td />
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>
</Tabs>

## Provider Details

### Porto by Anchorage Digital

[Porto](https://www.anchorage.com/platform/self-custody) by Anchorage Digital empowers institutions to confidently engage with a wide variety of DeFi protocols, execute native swaps, and deploy sophisticated on-chain strategies directly from a self-custody wallet.

### Utila

Securely build, manage, and scale digital asset operations with [Utila](https://utila.io/)'s enterprise-grade wallet platform. Trusted by leading institutions to power stablecoin payments, treasury, trading, and beyond.

To get started, visit the [documentation](https://docs.utila.io/reference/api-overview) or follow the [quickstart](https://support.utila.io/en/collections/13931663-getting-started) guide.


# Multisig Wallets
Source: https://docs.monad.xyz/tooling-and-infra/wallets/multisig-wallets



## Provider Summary

<Tabs>
  <Tab title="Mainnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Wallet</th>
            <th>Status</th>
            <th>Contract addresses</th>
            <th>Other Features</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Safe](https://safe.global/wallet)</td>
            <td>✅</td>
            <td>See [contract addresses](https://github.com/monad-crypto/protocols/blob/main/mainnet/safe.jsonc)</td>

            <td />
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>

  <Tab title="Testnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Wallet</th>
            <th>Status</th>
            <th>Other Features</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Safe](https://safe.global/wallet)</td>
            <td>✅</td>

            <td />
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>
</Tabs>

## Provider Details

### Safe Wallet

[Safe Wallet](https://safe.global/wallet) is a secure, non-custodial cryptocurrency wallet that
allows users to manage, store, and interact with digital assets like tokens and NFTs. It is built
on the Safe (formerly Gnosis Safe) smart contract infrastructure, offering advanced features like
multisig control, transaction batching, and custom permissions. Designed for both individuals and
organizations, Safe Wallet emphasizes security, transparency, and decentralized asset management.

Access Safe Wallet [here](https://safe.global/wallet).

<Tip>
  [safe-tx-hashes-util](https://github.com/pcaversaccio/safe-tx-hashes-util) is a tool for
  independently computing Safe transaction hashes based on transaction details from the
  Safe transaction service UI.

  [safe-tx-hashes-util](https://github.com/pcaversaccio/safe-tx-hashes-util) supports Monad.
</Tip>


# Software Wallets
Source: https://docs.monad.xyz/tooling-and-infra/wallets/software-wallets



## Provider Summary

<Tabs>
  <Tab title="Mainnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Wallet</th>
            <th>Status</th>
            <th>Available on</th>
            <th>Autodetect Tokens and NFTs</th>
            <th>AA</th>
            <th>[Blinks](/guides/blinks-guide)</th>
            <th>Other Features</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Phantom](https://phantom.com)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>Tokens, NFTs</td>
            <td>❌</td>
            <td>✅</td>
            <td>NFT support, DApp browser, Token swaps, cross-chain swaps, staking options</td>
          </tr>

          <tr>
            <td>[Atomic Wallet](https://atomicwallet.io)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>❌</td>
            <td>❌</td>
            <td>❌</td>
            <td>Cross-chain swaps, Portfolio tracking, Staking, DApp support, Futures trading</td>
          </tr>

          <tr>
            <td>[Backpack](https://backpack.app)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>Tokens, NFTs</td>
            <td>❌</td>
            <td>✅</td>
            <td>DApp browser, Built-in exchange, Futures trading, Portfolio tracking</td>
          </tr>

          <tr>
            <td>[Binance Wallet](https://www.binance.com/en/web3wallet)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>Tokens, NFTs</td>
            <td>❌</td>
            <td>❌</td>

            <td />
          </tr>

          <tr>
            <td>[Bitget Wallet](https://web3.bitget.com/en?source=bitget)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>❌</td>
            <td>❌</td>
            <td>❌</td>
            <td>DApp browser, NFT Market, DApp Browser, and Launchpad</td>
          </tr>

          <tr>
            <td>[HaHa](https://www.haha.me)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>✅</td>
            <td>✅</td>
            <td>❌</td>
            <td>DeFi integrations, AA, Monad Native, trading, hardware wallet support</td>
          </tr>

          <tr>
            <td>[Keplr](https://www.keplr.app)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>❌</td>
            <td>❌</td>
            <td>❌</td>
            <td>Multi-chain support, Open source, Portfolio tracking, Transaction History, In-app browser</td>
          </tr>

          <tr>
            <td>[MetaMask](https://metamask.io)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>NFTs</td>
            <td>❌</td>
            <td>❌</td>
            <td>NFT support, DApp browser, Open source, Token swaps, portfolio tracking</td>
          </tr>

          <tr>
            <td>[OKX Wallet](https://web3.okx.com/)</td>
            <td>⌛️</td>
            <td>Desktop, Mobile</td>
            <td>✅</td>
            <td>✅</td>
            <td>✅</td>
            <td>DApp browser, Portfolio tracking, Cross-chain swaps, Biometric Login</td>
          </tr>

          <tr>
            <td>[Rabby Wallet](https://rabby.io/)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>✅</td>
            <td>✅</td>
            <td>❌</td>
            <td>Portfolio tracking, Biometric login</td>
          </tr>

          <tr>
            <td>[Safepal](https://www.safepal.com)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>✅</td>
            <td>❌</td>
            <td>❌</td>
            <td>NFT support, DApp browser, Token swaps, Hardware wallet support</td>
          </tr>

          <tr>
            <td>[Trust Wallet](https://trustwallet.com)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>Tokens, NFTs</td>
            <td>✅</td>
            <td>❌</td>
            <td>Multi-chain support, NFT support, DApp browser, Token swaps, Staking, Buy crypto</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>

  <Tab title="Testnet">
    <div>
      <table>
        <thead>
          <tr>
            <th>Wallet</th>
            <th>Status</th>
            <th>Available on</th>
            <th>Autodetect Tokens and NFTs</th>
            <th>AA</th>
            <th>[Blinks](/guides/blinks-guide)</th>
            <th>Other Features</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>[Phantom](https://phantom.com)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>Tokens, NFTs</td>
            <td>❌</td>
            <td>✅</td>
            <td>NFT support, DApp browser, Token swaps, cross-chain swaps, staking options</td>
          </tr>

          <tr>
            <td>[Backpack](https://backpack.app)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>Tokens, NFTs</td>
            <td>❌</td>
            <td>✅</td>
            <td>DApp browser, Built-in exchange, Futures trading, Portfolio tracking</td>
          </tr>

          <tr>
            <td>[Bitget Wallet](https://web3.bitget.com/en?source=bitget)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>❌</td>
            <td>❌</td>
            <td>❌</td>
            <td>DApp browser, NFT Market, DApp Browser, and Launchpad</td>
          </tr>

          <tr>
            <td>[Coin98 Wallet](https://coin98.com)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>✅</td>
            <td>❌</td>
            <td>❌</td>
            <td>Multi-chain support, DApp browser, Cross-chain swaps, NFT Gallery</td>
          </tr>

          <tr>
            <td>[Crypto.com Web3 Wallet](https://crypto.com/defi-wallet)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>✅</td>
            <td>❌</td>
            <td>❌</td>
            <td>DApp browser, DeFi integrations, Token swaps, Staking</td>
          </tr>

          <tr>
            <td>[HaHa](https://www.haha.me)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>✅</td>
            <td>✅</td>
            <td>❌</td>
            <td>DeFi integrations, AA, Monad Native, trading, hardware wallet support</td>
          </tr>

          <tr>
            <td>[Kucoin Web3 Wallet](https://www.kucoin.com/web3)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>✅</td>
            <td>❌</td>
            <td>❌</td>
            <td>DApp browser, Multi-chain support, Portfolio tracking</td>
          </tr>

          <tr>
            <td>[MetaMask](https://metamask.io)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>NFTs</td>
            <td>❌</td>
            <td>❌</td>
            <td>NFT support, DApp browser, Open source, Token swaps, portfolio tracking</td>
          </tr>

          <tr>
            <td>[OKX Wallet](https://www.okx.com/en-us/help/section/faq-web3-wallet)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>✅</td>
            <td>✅</td>
            <td>✅</td>
            <td>DApp browser, Portfolio tracking, Cross-chain swaps, Biometric Login</td>
          </tr>

          <tr>
            <td>[Rabby Wallet](https://rabby.io/)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>✅</td>
            <td>✅</td>
            <td>❌</td>
            <td>Portfolio tracking, Biometric login</td>
          </tr>

          <tr>
            <td>[Safepal](https://www.safepal.com)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>✅</td>
            <td>❌</td>
            <td>❌</td>
            <td>NFT support, DApp browser, Token swaps, Hardware wallet support</td>
          </tr>

          <tr>
            <td>[Trust Wallet](https://trustwallet.com)</td>
            <td>✅</td>
            <td>Desktop, Mobile</td>
            <td>Tokens, NFTs</td>
            <td>✅</td>
            <td>❌</td>
            <td>Multi-chain support, NFT support, DApp browser, Token swaps, Staking, Buy crypto</td>
          </tr>
        </tbody>
      </table>
    </div>

    *✅ = supported, ⌛️ = in progress, ❓ = unknown, ❌ = won't support*
  </Tab>
</Tabs>

## Provider Details

### Phantom

[Phantom](https://phantom.com) is a secure and easy-to-use wallet for the Monad Testnet.

To get started, download the phantom wallet [here](https://phantom.com/download) or visit the [documentation](https://phantom.com/learn/developers).

### Atomic Wallet

[Atomic Wallet](https://atomicwallet.io) is a non-custody multichain crypto wallet trusted by 15M+ users worldwide. In Atomic you can swap, buy & hold thousands of tokens, manage NFTs, stake your crypto, and trade perps! All in one app: fast, secure, simple.

To get started, download Atomic Wallet [here](https://atomicwallet.io/downloads).

### Backpack

[Backpack](https://backpack.app) is a next-level wallet and exchange. Buy tokens, trade futures, and explore on-chain apps—seamlessly and securely. 🎒

To get started, download the Backpack wallet [here](https://backpack.app) or visit the [documentation](https://docs.backpack.app/).

### Bitget Wallet

[Bitget Wallet](https://web3.bitget.com/en?source=bitget) is a non-custodial wallet with advanced multi-chain capabilities and powerful swap function

To get started, download the Bitget wallet [here](https://web3.bitget.com/en/wallet-download?type=2) or visit the [documentation](https://web3.bitget.com/en/docs/).

### Coin98 Wallet

[Coin98 Wallet](https://coin98.com) is a multi-chain wallet that connects users to numerous blockchains, allowing for seamless asset management and DeFi interactions. It features cross-chain swaps, an integrated DApp browser, and comprehensive portfolio tracking across multiple networks.

To get started, download Coin98 Wallet [here](https://coin98.com/wallet) or visit the [documentation](https://docs.coin98.com).

### Crypto.com Web3 Wallet

[Crypto.com Web3 Wallet](https://crypto.com/defi-wallet) (formerly DeFi Wallet) is a non-custodial wallet that gives users full control of their crypto and private keys. It supports multiple blockchains, offers seamless DeFi integrations, token swaps, and staking capabilities, all while maintaining high security standards.

To get started, download Crypto.com Web3 Wallet [here](https://crypto.com/defi-wallet) or visit the [documentation](https://help.crypto.com/en/collections/2221157-crypto-com-defi-wallet).

### HaHa Wallet

[HaHa](https://www.haha.me) is a next-gen smart wallet with DeFi capabilities.

To get started, download the HaHa wallet [here](https://www.haha.me).

### Keplr Wallet

[Keplr Wallet](https://www.keplr.app/) is an open-source, multichain wallet supporting Cosmos, Bitcoin, Ethereum, Starknet, and more.

Download Keplr [here](https://www.keplr.app/get) or visit the [documentation](https://docs.keplr.app/api/intro).

### Kucoin Web3 Wallet

[Kucoin Web3 Wallet](https://www.kucoin.com/web3) is a non-custodial multi-chain wallet developed by KuCoin, one of the leading cryptocurrency exchanges. It provides secure access to DeFi protocols, supports multiple blockchains, and includes features for portfolio tracking and DApp interactions.

To get started, download Kucoin Web3 Wallet [here](https://www.kucoin.com/web3/download) or visit the [documentation](https://docs.kuweb3.net/).

### MetaMask

[MetaMask](https://metamask.io) is a secure and easy-to-use wallet for the Monad Testnet.

To get started, download the MetaMask wallet [here](https://metamask.io/download) or visit the [documentation](https://docs.metamask.io).

### OKX Wallet

[OKX Wallet](https://www.okx.com/en-us/help/section/faq-web3-wallet) is your all-in-one gateway to the Web3 world.

To get started, download the OKX Wallet [here](https://chromewebstore.google.com/detail/okx-wallet/mcohilncbfahbmgdjkbpemcciiolgcge) or visit the [documentation](https://www.okx.com/web3/build/docs/sdks/okx-wallet-integration-introduction).

### Rabby Wallet

[Rabby Wallet](https://rabby.io/) is a non-custodial, multi-chain Web3 wallet created by DeBank that makes using decentralized apps easier and safer. It supports Monad and many other blockchains, automatically detects networks, and shows transaction simulations with risk alerts to help prevent mistakes or scams. Users keep full control of their keys.

Download Rabby wallet and learn more about it [here](https://rabby.io/).

### Safepal

[Safepal](https://www.safepal.com) is a cryptocurrency wallet that offers both software and hardware wallet solutions. It provides secure storage for digital assets with features like token swaps, NFT management, and DApp browsing. Safepal emphasizes security while maintaining user-friendly access to DeFi and Web3 applications.

To get started, download the Safepal wallet [here](https://www.safepal.com/download) or visit the [documentation](https://docs.safepal.io).

### Trust Wallet

[Trust Wallet](https://trustwallet.com) is a popular multi-chain cryptocurrency wallet that supports millions of assets and blockchains. It provides a secure, decentralized platform for storing, sending, and receiving cryptocurrencies, with built-in features for staking, NFT management, and accessing DApps.

To get started, download Trust Wallet [here](https://trustwallet.com/download) or visit the [documentation](https://developer.trustwallet.com).