Skip to content

docs: request blockchains, assets support guides #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: docs/v0_5_0
Choose a base branch
from
Open

docs: request blockchains, assets support guides #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e8cfeaa
fix(docs): replace enable with disable for blockchain config example
nksazonov Nov 20, 2025
db914f5
docs: add request chains, assets support guides
nksazonov Nov 20, 2025
8c4ce70
feat: address comments
nksazonov Nov 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 169 additions & 0 deletions docs/manuals/request-asset-support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
---
title: Requesting Asset Support
description: Guide for requesting asset and token support in Clearnode Sandbox or Production environments
sidebar_label: Request Asset Support
keywords: [clearnode, asset, token, configuration, ERC20, production, sandbox]
---

# Requesting Asset Support

This guide is primarily for **project teams, token issuers, and integration partners** who need to add support for new assets or tokens in the Clearnode infrastructure. Following this process will enable Clearnode to recognize and process transfers of your asset across supported blockchain networks.

## What Happens When Support is Added

Once an asset is supported in Clearnode:

- Users can deposit and withdraw the asset through Clearnode's state channels
- The asset becomes available for instant, off-chain transfers via the Nitrolite protocol
- The asset can be used in cross-chain operations (deposit on one chain, withdraw on another) for blockchains it was configured on
- Applications built on Yellow Network can integrate the asset for payments and settlements
- The asset's unified balance is tracked across all supported blockchains

:::info ERC20 Compatibility
Adding support for ERC20 tokens is straightforward and requires only configuration changes. Non-standard token implementations may require additional development work and testing.
:::

:::warning Liquidity Requirements for Withdrawals
For a token to be immediately withdrawable on a specific blockchain, Clearnode must be provided with sufficient liquidity on that chain. Without liquidity, users can deposit tokens but cannot withdraw them until liquidity is available. Please contact our Business team to arrange liquidity provision before requesting asset support.
:::

## Understanding Environments

Clearnode operates in two distinct environments with separate asset configurations:

| Environment | Purpose | Typical Assets |
|-------------|---------|----------------|
| **Sandbox** | Development, testing, and experimentation | Testnet tokens (Sepolia USDC, Amoy ETH, test tokens, etc.) |
| **Production** | Live operations with real assets | Mainnet tokens (USDC, USDT, DAI, etc.) |

**Configuration file location:** `clearnode/chart/config/<sandbox_or_prod>/assets.yaml`

**Important Considerations:**

- **Production will not support test network tokens** - mainnet tokens only
- **Sandbox will not support mainnet tokens** - testnet tokens only
- You must decide which environment needs the asset support based on your use case
- If you need support in both environments (e.g., testnet token for development, mainnet token for production), you must submit configuration changes to both files

## How to Request Support

Asset support is requested by creating or modifying a configuration file in the [nitrolite](https://github.com/erc7824/nitrolite) repository:

1. **Fork the repository**: `https://github.com/erc7824/nitrolite`
2. **Navigate to the appropriate configuration file**:
- For Sandbox: `clearnode/chart/config/sandbox/assets.yaml`
- For Production: `clearnode/chart/config/prod/assets.yaml`
3. **Add your asset configuration** at the end of the list (see next section for structure)
4. **Submit a Pull Request** with a clear description of the asset being added
5. **Wait for review** by the development team

The next section provides detailed guidance on the configuration structure and whether you need to add a new asset or just a token.

## Asset Configuration Structure

### Understanding Assets vs Tokens

In Clearnode's configuration model:

- An **asset** represents a logical currency or token type (e.g., "USDC", "ETH")
- A **token** is a specific implementation of that asset on a particular blockchain

**Example:** USDC is an asset that has different token implementations:

- USDC on Polygon at address `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`
- USDC on Base at address `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- USDC on Ethereum at address `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`

### Before You Start: Check if the Asset Exists

Before adding a new asset, check if Clearnode already supports the asset on other blockchains. If the asset exists but your target blockchain is not listed, you only need to add a **token entry** to the existing asset. If the asset doesn't exist at all, you need to add both the **asset** and its **token(s)**.

#### Scenario 1: Asset exists, add a token to a new blockchain

```yaml
assets:
- name: "USD Coin"
symbol: "usdc"
tokens:
- blockchain_id: 137
address: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"
decimals: 6
# Add your new token here
- blockchain_id: 8453 # Base
address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
decimals: 6
```

#### Scenario 2: New asset, add both asset and token(s)

```yaml
assets:
- name: "My New Token"
symbol: "mnt"
tokens:
- blockchain_id: 137
address: "0xYourTokenAddressOnPolygon"
decimals: 18
```

### Configuration Fields

#### Asset Level

Each asset entry requires the following fields:

```yaml
assets:
- name: "USD Coin" # Human-readable name
symbol: "usdc" # Ticker symbol (lowercase)
disabled: false # If set to `true`, then it is not loaded into configuration
tokens: [...] # Array of token implementations
```

| Field | Required | Description |
|-------|----------|-------------|
| `name` | No | Human-readable name of the asset (e.g., "USD Coin"). If omitted, defaults to the symbol. |
| `symbol` | **Yes** | Ticker symbol for the asset (must be lowercase, e.g., "usdc", "eth") |
| `disabled` | No | Set to `true` to temporarily disable processing this asset (default: `false`) |
| `tokens` | **Yes** | Array of blockchain-specific token implementations |

#### Token Level

Each token within an asset requires the following fields:

```yaml
tokens:
- name: "USD Coin on Polygon" # Token-specific name
symbol: "usdc" # Token-specific symbol
blockchain_id: 137 # Chain ID
disabled: false # Skip processing (default: false)
address: "0x3c499c542cEF..." # Contract address
decimals: 6 # Token decimals
```

| Field | Required | Description |
|-------|----------|-------------|
| `name` | No | Token name on this blockchain (inherits from asset if not specified) |
| `symbol` | No | Token symbol on this blockchain (inherits from asset if not specified) |
| `blockchain_id` | **Yes** | Chain ID where this token is deployed (must match a supported blockchain) |
| `disabled` | No | Set to `true` to temporarily disable this token (default: `false`) |
| `address` | **Yes** | Token's smart contract address (must be a valid address on the specified chain) |
| `decimals` | **Yes** | Number of decimal places the token uses (e.g., 6 for USDC, 18 for ETH) |

### Prerequisites for Adding Assets

Before submitting your configuration:

1. **Blockchain Support**: Ensure the blockchain (by `blockchain_id`) is already supported in `blockchains.yaml`
2. **Token Deployment**: The token contract must be deployed and verified on the target blockchain
3. **ERC20 Compliance**: Token should follow the standard ERC20 interface for seamless integration
4. **Correct Decimals**: Verify the token's decimal places (commonly 6 or 18, but varies by token)
5. **Valid Address**: Double-check the contract address is correct and matches the intended blockchain

:::warning Blockchain Must Be Supported First
You cannot add a token on a blockchain that is not yet supported in Clearnode. If your target blockchain is not in the `blockchains.yaml` configuration, you must first follow the [Request Blockchain Support](./request-blockchain-support.md) guide before requesting asset support.
:::

## Need Help?

If you have questions about asset support requests, encounter issues during configuration, or need clarification on any part of this process, please don't hesitate to contact the development team.
166 changes: 166 additions & 0 deletions docs/manuals/request-blockchain-support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
---
title: Requesting Blockchain Support
description: Guide for requesting blockchain network support in Clearnode Sandbox or Production environments
sidebar_label: Request Blockchain Support
keywords: [clearnode, blockchain, configuration, EVM, production, sandbox]
---

# Requesting Blockchain Support

This guide is primarily for **blockchain integrators, infrastructure teams, and project partners** who need to add support for new blockchain networks in the Clearnode infrastructure. Following this process will enable Clearnode to connect to your blockchain and provide off-chain clearing and settlement services.

## What Happens When Support is Added

Once a blockchain is supported in Clearnode:

- Clearnode can establish RPC connections to the specified blockchain network
- The Nitrolite protocol smart contracts (custody, adjudicator, and balance checker) will be monitored on that chain
- Users can deposit and withdraw assets on that blockchain through Clearnode
- State channels can leverage that blockchain for on-chain settlement when needed
- Assets deployed on the supported blockchain become available for cross-chain clearing

:::warning Non-EVM and Limited Infrastructure Support
If your blockchain support request concerns a **non-EVM blockchain** or a blockchain with **limited infrastructure support** (e.g., scarce RPC providers, incomplete tooling, experimental networks), **you must contact the development team before proceeding** with this guide. These cases require custom development and cannot be handled through standard configuration.

Contact the dev team via [GitHub Issues](https://github.com/layer-3/nitrolite/issues).
:::

## Understanding Environments

Clearnode operates in two distinct environments with separate configurations:

| Environment | Purpose | Typical Networks |
|-------------|---------|------------------|
| **Sandbox** | Development, testing, and experimentation | Testnets (Sepolia, Polygon Amoy, etc.) |
| **Production** | Live operations with real assets | Mainnets (Ethereum, Polygon, Base, Linea, etc.) |

**Configuration file location:** `clearnode/chart/config/<sandbox_or_prod>/blockchains.yaml`

**Important Considerations:**

- **Production will not support test networks** - mainnet blockchains only
- **Sandbox will not support mainnet networks** - testnet blockchains only
- You must decide which environment needs the blockchain support based on your use case
- If you need support in both environments (e.g., testnet for development, mainnet for production), you must submit configuration changes to both files

## How to Request Support

Blockchain support is requested by creating or modifying a configuration file in the [nitrolite](https://github.com/erc7824/nitrolite) repository:

1. **Fork the repository**: `https://github.com/erc7824/nitrolite`
2. **Navigate to the appropriate configuration file**:
- For Sandbox: `clearnode/chart/config/sandbox/blockchains.yaml`
- For Production: `clearnode/chart/config/prod/blockchains.yaml`
3. **Add your blockchain configuration** at the end of the `blockchains` list (see next section for structure)
4. **Submit a Pull Request** with a clear description of the blockchain being added
5. **Wait for review** by the development team

The next section provides detailed guidance on the configuration structure.

## Blockchain Configuration Structure

### Overview

The `blockchains.yaml` file contains two main sections:

- `default_contract_addresses`: Default smart contract addresses applied to all blockchains (unless overridden)
- `blockchains`: Array of blockchain configurations

### Configuration Fields

Each blockchain entry requires the following fields:

```yaml
blockchains:
- name: polygon # Blockchain name (lowercase, underscores allowed)
id: 137 # Chain ID for validation
disabled: false # Whether to disable (default: false)
block_step: 10000 # Block range for scanning (default: 10000)
contract_addresses: # Override default contract addresses
custody: "0x..."
adjudicator: "0x..."
balance_checker: "0x..."
```

**Field Descriptions:**

| Field | Required | Description |
|-------|----------|-------------|
| `name` | **Yes** | Unique identifier for the blockchain (lowercase, underscores allowed, e.g., `polygon`, `base`, `arbitrum_one`) |
| `id` | **Yes** | Chain ID used for validation (must match the blockchain's official chain ID) |
| `disabled` | No | Set to `true` to disable or `false` to enable (default: `false`) |
| `block_step` | No | Number of blocks to scan per query when monitoring events (default: `10000`). Adjust based on blockchain or RPC provider performance. |
| `contract_addresses` | No | Override default contract addresses for this specific blockchain |

### Contract Deployment

When requesting the addition of a new blockchain, addresses of the infrastructure smart contracts must be provided:

- **Custody Contract**: Manages user deposits and withdrawals
- **Adjudicator Contract**: Handles dispute resolution for state channels
- **Balance Checker Contract**: Provides efficient balance queries

:::info Smart contract deployment
For now, you don't need to deploy these contracts yourself. The development team will handle contract deployment on the new blockchain as part of the support process.

You can submit your request with smart contract addresses set to placeholder values (e.g., `0x0000000000000000000000000000000000000000`). The team will replace them with the actual deployed addresses during integration.
:::

:::info Coming Soon: Cross-Chain Contract Deployment Tool
We are developing a tool to simplify the deployment of Nitrolite protocol smart contracts across multiple blockchains with deterministic addresses. This will enable deploying contracts to the same address on different chains, making configuration management significantly easier.
:::

Read on to learn how to specify contract addresses in the configuration.

You have two options for providing contract addresses:

#### Option 1: Using Default Contract Addresses

If you deploy contracts at the addresses specified in the `default_contract_addresses`, you don't need to specify `contract_addresses` in each blockchain entry.

```yaml
default_contract_addresses:
custody: "0x490fb189DdE3a01B00be9BA5F41e3447FbC838b6"
adjudicator: "0xcbbc03a873c11beeFA8D99477E830be48d8Ae6D7"
balance_checker: "0x2352c63A83f9Fd126af8676146721Fa00924d7e4"

blockchains:
- name: polygon
id: 137
enabled: true
- name: base
id: 8453
enabled: true
```

This approach is cleaner when contracts are deployed at identical addresses.

#### Option 2: Blockchain-Specific Contract Addresses

If contract addresses differ on your blockchain, specify them individually:

```yaml
blockchains:
- name: polygon
id: 137
enabled: true
contract_addresses:
custody: "0xPolygonCustodyAddress..."
adjudicator: "0xPolygonAdjudicatorAddress..."
balance_checker: "0xPolygonBalanceCheckerAddress..."
- name: base
id: 8453
enabled: true
contract_addresses:
custody: "0xBaseCustodyAddress..."
adjudicator: "0xBaseAdjudicatorAddress..."
balance_checker: "0xBaseBalanceCheckerAddress..."
```

:::warning Contract Address Requirements
Each blockchain **must have all three contract addresses configured** either through `default_contract_addresses` or blockchain-specific `contract_addresses`. If defaults are not provided, every blockchain must explicitly define all three addresses. Missing contract addresses will cause Clearnode to fail on startup.
:::

## Need Help?

If you have questions about blockchain support requests, encounter issues during integration, or need clarification on any part of this process, please don't hesitate to contact the development team.
6 changes: 3 additions & 3 deletions docs/manuals/running-clearnode-locally.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,11 @@ default_contract_addresses:
blockchains:
- name: polygon
id: 137
enabled: true
disabled: false
block_step: 10000
- name: base
id: 8453
enabled: false
disabled: true
```

### 4. Configure Assets
Expand Down Expand Up @@ -129,7 +129,7 @@ docker compose down
- **blockchains**: Array of blockchain configurations
- `name`: Blockchain name (required; lowercase, underscores allowed)
- `id`: Chain ID for validation (required)
- `disabled`: Whether to connect to this blockchain (optional, default: false)
- `disabled`: Whether to disable this blockchain (optional, default: false)
- `block_step`: Block range for scanning (optional, default: 10000)
- `contract_addresses`: Override default addresses for this specific blockchain (optional)
- `custody`: Custody contract address
Expand Down