# Paxeer Docs - Complete Documentation

> This file contains the complete documentation for Paxeer Docs.
> Total pages: 91

---

## 402LXP Protocol

*Implement HTTP micropayments on Paxeer using the 402LXP protocol for API monetization and agent-to-agent payments.*

402LXP brings HTTP-native micropayments to Paxeer, enabling you to monetize APIs, premium content, and digital services with instant, low-cost payments. Whether you're building AI agent APIs, data feeds, or premium content platforms, 402LXP makes it simple to add payment gates to any HTTP endpoint.

**Built for Paxeer's agent layer:** 402LXP runs on LayerX - Paxeer's dedicated agent channel - leveraging fast finality, low gas, and EVM compatibility to enable seamless machine-to-machine payment flows that complete in milliseconds.

<Info>

**Why 402LXP on Paxeer?**

- **Fast & Cheap Payments**: Paxeer's Twin Turbo Consensus delivers ~400ms finality with minimal gas. Perfect for pay-per-request APIs and agent-to-agent payments.
- **EVM Compatible**: Use familiar tools like Viem, Ethers.js, and Hardhat. All existing Ethereum tooling works seamlessly on Paxeer.
- **Agent-Native**: 402LXP is designed for autonomous AI agents on LayerX - agents can pay for inference, data, and services without human intervention.

</Info>

## Use Cases on Paxeer

The 402LXP protocol enables a wide range of monetization strategies for web services and APIs:

- **AI & Machine Learning Services**: Per-inference pricing for LLM APIs, image generation, and data processing.
- **Premium Content & Media**: Pay-per-view articles, videos, and subscription gates.
- **Real-Time Data & APIs**: Market data feeds, weather and IoT data monetization.
- **Agent-to-Agent Commerce**: Autonomous agents paying other agents for services on LayerX.

## Protocol Overview

402LXP leverages the HTTP 402 status code ("Payment Required") to facilitate blockchain-based micropayments directly through HTTP requests.

### Key Features

- **HTTP-Native**: Uses standard HTTP status codes and headers
- **Blockchain Integration**: Runs on Paxeer's EVM layer via LayerX
- **Real-time Settlement**: Enables instant payment verification
- **Interoperable**: Works across different payment schemes and networks
- **Micropayment Support**: Designed for small, frequent transactions

### Payment Flow

1. **Initial Request**: Client makes a request to a protected resource
2. **402 Response**: Server responds with HTTP 402 and payment requirements
3. **Payment Execution**: Client executes blockchain payment (USDX on LayerX)
4. **Payment Proof**: Client includes payment proof in subsequent request
5. **Resource Access**: Server verifies payment and grants access

### Payment Challenge Response

```json
{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "paxeer",
      "maxAmountRequired": "1000",
      "resource": "/api/data",
      "description": "Get current data",
      "mimeType": "application/json",
      "payTo": "0x9dC2aA0038830c052253161B1EE49B9dD449bD66",
      "maxTimeoutSeconds": 300,
      "asset": "0xUSDX_TOKEN_ADDRESS",
      "extra": {
        "name": "USDX",
        "version": "2",
        "reference": "paxeer-1234567890-abc123"
      }
    }
  ]
}
```

### Payment Execution

The agent executes a USDX transfer on Paxeer:

```typescript
const transferData = encodeFunctionData({
  abi: [
    {
      name: 'transfer',
      type: 'function',
      stateMutability: 'nonpayable',
      inputs: [
        { name: 'to', type: 'address' },
        { name: 'amount', type: 'uint256' }
      ],
      outputs: [{ name: '', type: 'bool' }]
    }
  ],
  functionName: 'transfer',
  args: [recipient, amountInUnits]
});

const hash = await walletClient.sendTransaction({
  to: USDX_TOKEN_ADDRESS,
  data: transferData
});
```

### Payment Proof Submission

```
Client → GET /api/data + X-Payment Header (base64 encoded payment proof)
Server → Verifies payment + Returns data
```

## Code Example: Paid API Implementation

```typescript
export async function GET(req: NextRequest) {
  const paymentHeader = req.headers.get('x-payment');

  if (!paymentHeader) {
    return NextResponse.json(generatePaymentChallenge(), { status: 402 });
  }

  const verification = await verifyPayment(paymentHeader);

  if (!verification.isValid) {
    const challenge = generatePaymentChallenge();
    challenge.error = verification.reason || 'Payment verification failed';
    return NextResponse.json(challenge, { status: 402 });
  }

  return NextResponse.json({ data: "Your protected content" });
}
```

## Security Considerations

### Payment Verification

- **On-chain Verification**: All payments are verified against the Paxeer blockchain.
- **Transaction Receipt Validation**: Ensures transaction success and proper recipient.
- **Payment Caching**: Prevents double-spending by caching verified payments.
- **Reference Validation**: Unique payment references prevent replay attacks.

### Network Security

- **HTTPS Required**: All API communications use secure connections.
- **Base64 Encoding**: Payment proofs are base64 encoded for safe transmission.
- **Timeout Handling**: Payment challenges include timeout mechanisms.

### Wallet Security

- **Private Key Management**: Private keys are stored securely in environment variables.
- **Transaction Signing**: All transactions are properly signed before submission.
- **Balance Validation**: Sufficient balance checks before payment execution.

---

## Agentic Wallets

*Give AI agents programmable wallets on Paxeer with Coinbase AgentKit or Privy setup, policies, and comparison.*

Agentic wallets give AI agents the ability to hold funds, sign transactions, and interact with smart contracts autonomously - without exposing private keys to the agent or the LLM. This page covers the two leading solutions that work on Paxeer today: **Coinbase AgentKit** and **Privy server wallets**.

<Info>
Both platforms support Paxeer as an EVM-compatible chain. No special integration is required - you point the wallet provider at Paxeer's RPC and chain ID and everything works out of the box.
</Info>

## How It Works

An agentic wallet sits between your AI agent and the blockchain:

1. **Agent decides** - The LLM reasons about what onchain action to take (e.g. "send 5 USDC to 0x...").
2. **SDK prepares** - The wallet SDK constructs and validates the transaction.
3. **Policy check** - The policy engine evaluates the transaction against spending limits, allowlists, and other guardrails.
4. **TEE signs** - The private key, isolated in a Trusted Execution Environment, signs the transaction. The key is never exposed to the agent.
5. **Broadcast** - The signed transaction is submitted to Paxeer's EVM RPC.

```
┌─────────┐     ┌───────────┐     ┌──────────────┐     ┌─────────┐     ┌──────────┐
│ LLM /   │────▶│ Wallet    │────▶│ Policy       │────▶│ TEE     │────▶│ Paxeer EVM  │
│ Agent   │     │ SDK       │     │ Engine       │     │ Signer  │     │ RPC      │
└─────────┘     └───────────┘     └──────────────┘     └─────────┘     └──────────┘
```

## Quick Comparison

| Dimension | Coinbase AgentKit | Privy Server Wallets |
| --- | --- | --- |
| **Type** | Open-source SDK + wallet infra | Wallet-as-a-service API |
| **Key isolation** | Self-custodial on Paxeer (bring-your-own key via Viem). CDP's TEE-managed signer does not support Paxeer. | TEE + Shamir secret sharing |
| **Paxeer support** | Via `ViemWalletProvider` (TS) or `EthAccountWalletProvider` (Python) | Via CAIP-2 `eip155:125` |
| **Policy engine** | Spending limits, address/contract allowlists, network restrictions | All of the above + time-based controls, key quorums |
| **Built-in actions** | 40+ action providers (wallet, ERC-20, ERC-721, Pyth on Paxeer; many others Base/Ethereum-only) | Wallet operations only (create, sign, send) |
| **AI frameworks** | LangChain, Vercel AI SDK, OpenAI Agents SDK, MCP | LangChain (`langchain-privy`) |
| **Server SDKs** | TypeScript, Python | TypeScript, Python, Java, Rust, Go + REST API |
| **Open source** | Yes (MIT) | Partial (`langchain-privy` is OSS) |
| **Pricing** | Free SDK; CDP wallets $0.005/op (5K free/mo) | Free 50K sigs/mo; paid tiers from $299/mo |


**Use both together:** AgentKit ships with a built-in `PrivyWalletProvider`, so you can combine Privy's policy engine with AgentKit's 40+ action providers.

---

## Coinbase AgentKit on Paxeer

[AgentKit](https://github.com/coinbase/agentkit) is Coinbase's open-source toolkit for giving AI agents crypto wallets and onchain capabilities. It is framework-agnostic (LangChain, Vercel AI SDK, OpenAI Agents SDK, MCP) and wallet-agnostic (CDP wallets, Privy, Viem, and more).

### Architecture

AgentKit is organized around three concepts:

- **Wallet Providers** - Abstraction over different wallet implementations. For Paxeer, use `ViemWalletProvider` (TypeScript) or `EthAccountWalletProvider` (Python).
- **Action Providers** - Units of onchain functionality (ERC-20 transfers, ERC-721 ops, Pyth price feeds, etc.). Generic EVM providers work on Paxeer; providers with hard-coded chain allowlists (e.g. `x402ActionProvider`, `wethActionProvider`, CDP-managed ones) do not - see the support matrix below.
- **Framework Extensions** - Adapters that turn AgentKit actions into tools for your AI framework of choice.

### Prerequisites

- Node.js v22+ (TypeScript) or Python 3.10+
- A [CDP Secret API Key](https://portal.cdp.coinbase.com/) (for CDP wallet providers; not required for Viem)
- A funded wallet on Paxeer

### Setup

<Tabs>
<Tab title="TypeScript">

<Steps>

<Step title="Install packages">
```bash
npm install @coinbase/agentkit @coinbase/agentkit-langchain viem
```
</Step>

<Step title="Create the wallet provider and AgentKit">
Use `ViemWalletProvider` pointed at Paxeer's RPC and chain ID `125`.

```typescript
import { AgentKit, ViemWalletProvider, walletActionProvider, erc20ActionProvider } from '@coinbase/agentkit';
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { sei } from 'viem/chains';

// Create a Viem wallet client pointed at Paxeer
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const client = createWalletClient({
  account,
  chain: sei,
  transport: http('https://evm-rpc.sei-apis.com'),
});

// Wrap it in AgentKit
const walletProvider = new ViemWalletProvider(client);
const agentKit = await AgentKit.from({
  walletProvider,
  actionProviders: [
    walletActionProvider(),
    erc20ActionProvider(),
    // Add more action providers as needed
  ],
});
```
</Step>

<Step title="Wire into LangChain">
```typescript
import { getLangChainTools } from '@coinbase/agentkit-langchain';
import { ChatOpenAI } from '@langchain/openai';
import { createReactAgent } from '@langchain/langgraph/prebuilt';

const tools = await getLangChainTools(agentKit);
const model = new ChatOpenAI({ model: 'gpt-4o' });

const agent = createReactAgent({
  llm: model,
  tools,
  messageModifier:
    'You are an AI agent operating on the Paxeer blockchain. You can check balances, transfer tokens, and interact with smart contracts.',
});

// Run the agent
const result = await agent.invoke({
  messages: [{ role: 'user', content: 'What is my HPX balance?' }],
});
```
</Step>

</Steps>

</Tab>
<Tab title="Python">

<Steps>

<Step title="Install packages">
```bash
pip install coinbase-agentkit coinbase-agentkit-langchain
```
</Step>

<Step title="Create the wallet provider">
```python
from coinbase_agentkit import (
    AgentKit,
    AgentKitConfig,
    EthAccountWalletProvider,
    EthAccountWalletProviderConfig,
)
from eth_account import Account

account = Account.from_key("YOUR_PRIVATE_KEY")

wallet_provider = EthAccountWalletProvider(
    config=EthAccountWalletProviderConfig(
        account=account,
        chain_id=125,  # Paxeer mainnet
        rpc_url="https://evm-rpc.sei-apis.com",
    )
)

agent_kit = AgentKit(AgentKitConfig(wallet_provider=wallet_provider))
```
</Step>

<Step title="Wire into LangChain">
```python
from coinbase_agentkit_langchain import get_langchain_tools
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

tools = get_langchain_tools(agent_kit)
model = ChatOpenAI(model="gpt-4o")

agent = create_react_agent(
    model,
    tools=tools,
    state_modifier="You are an AI agent on the Paxeer blockchain.",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "What is my HPX balance?"}]
})
```
</Step>

</Steps>

</Tab>
</Tabs>

### Available Action Providers on Paxeer

Not every AgentKit action provider works on Paxeer - some are chain-specific. Here's what you can use:

| Action Provider | Works on Paxeer | Notes |
| --- | --- | --- |
| `walletActionProvider` | Yes | Balance, transfers, native HPX operations |
| `erc20ActionProvider` | Yes | Any ERC-20 token (USDC, WHPX, etc.) |
| `erc721ActionProvider` | Yes | NFT minting, transfers |
| `pythActionProvider` | Yes | Pyth price feeds via Hermes (off-chain, chain-agnostic) |
| `wethActionProvider` | No | Hard-coded WETH addresses; no WHPX entry. Use `erc20ActionProvider` against Paxeer's WHPX contract instead. |
| `x402ActionProvider` | No | Provider's `SUPPORTED_NETWORKS` allowlist is limited to `base-mainnet`, `base-sepolia`, `solana-mainnet`, and `solana-devnet`. The x402 protocol itself is chain-agnostic - write a custom action provider or call the facilitator directly if you need x402 on Paxeer. |
| `cdpApiActionProvider` | No | Requires a Coinbase `networkId`; Paxeer isn't in AgentKit's chain map. |
| `morphoActionProvider` | No | Morpho contracts not deployed on Paxeer |
| `moonwellActionProvider` | No | Moonwell contracts not deployed on Paxeer |


<Info>
For Paxeer-native DeFi actions (swaps on Symphony/DragonSwap, staking via Silo, lending via Takara), use the [Cambrian Agent Kit](/ai) alongside AgentKit, or write custom action providers.
</Info>

### Known Quirks on Paxeer

Verified by running AgentKit against Paxeer (`chain 125`). These quirks sit in AgentKit's network and action-provider layer and apply to **both** `ViemWalletProvider` and `PrivyWalletProvider`:

- **Balances are labeled "ETH" in action output.** `walletActionProvider` hard-codes the native-currency symbol, so `get_wallet_details` returns strings like `Native Balance: 512993.50 ETH` and `native_transfer` responses say `Transferred 0.05 ETH to 0x...` even on Paxeer. Signing and arithmetic are unaffected - it's a display-only quirk. If the LLM will quote balances or transfer confirmations to users, add a post-processing step or a system-prompt instruction to rewrite `ETH` → `HPX` when `chain_id == 125`.
- **`networkId` is `undefined`.** Coinbase's internal `CHAIN_ID_TO_NETWORK_ID` map only includes Ethereum, Polygon, Base, Arbitrum, and Optimism (mainnet + testnet). Paxeer's chain ID isn't in it, so `walletProvider.getNetwork()` returns `{ protocolFamily: 'evm', chainId: '125', networkId: undefined }`. This is harmless for signing/sending, but **any action provider that branches on `networkId`** will refuse to run on Paxeer. In practice, `AgentKit.from({...})` prints a warning like `The following action providers are not supported on the current network and will be unavailable: weth, x402` and silently drops them - if you expect an action and it's missing from `agentKit.getActions()`, check this warning first.

### CDP-Managed Wallets and Paxeer

AgentKit's `CdpEvmWalletProvider` (CDP-managed server wallets with built-in policies) is currently scoped to `base`, `base-sepolia`, `ethereum`, `ethereum-sepolia`, `polygon`, `arbitrum`, and `optimism` - **Paxeer is not a supported network**.

For managed cloud custody with a policy engine on Paxeer, use one of:

- **Privy server wallets** (below) - TEE-isolated keys with a policy engine that works on any EVM chain, including Paxeer.
- **AgentKit + Privy combined** - use `PrivyWalletProvider` inside AgentKit to keep the 40+ action providers while delegating custody and policy enforcement to Privy. See [Using AgentKit with Privy (Combined)](#using-agentkit-with-privy-combined) below.

If you only need self-custodial keys (no TEE, you hold the private key), use `ViemWalletProvider` as shown above and enforce limits in your own application logic.

---

## Privy Server Wallets on Paxeer

[Privy](https://docs.privy.io/) provides wallet-as-a-service infrastructure for AI agents. Server wallets are programmatically managed wallets designed for backend use - no user interaction required. Keys are isolated in TEEs with Shamir secret sharing and never leave secure enclaves.

### Prerequisites

- A [Privy account](https://dashboard.privy.io/) with an App ID and App Secret
- An authorization keypair (generated in the Privy dashboard)

### Setup

<Tabs>
<Tab title="REST API">

<Steps>

<Step title="Create a wallet">
```bash
curl --request POST https://api.privy.io/v1/wallets \
  -u "<your-app-id>:<your-app-secret>" \
  -H "privy-app-id: <your-app-id>" \
  -H 'Content-Type: application/json' \
  -d '{
    "chain_type": "ethereum",
    "policy_ids": ["your_policy_id"]
  }'
```

Response:
```json
{
  "id": "wallet_abc123",
  "address": "0x1234...abcd",
  "chain_type": "ethereum",
  "policy_ids": ["your_policy_id"]
}
```
</Step>

<Step title="Send a transaction on Paxeer">
Use `eip155:125` (CAIP-2 format) to target Paxeer mainnet:

```bash
curl --request POST https://api.privy.io/v1/wallets/wallet_abc123/evm/reference \
  -u "<your-app-id>:<your-app-secret>" \
  -H "privy-app-id: <your-app-id>" \
  -H "privy-authorization-signature: <authorization-signature>" \
  -H 'Content-Type: application/json' \
  -d '{
    "method": "eth_sendTransaction",
    "caip2": "eip155:125",
    "params": {
      "transaction": {
        "to": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "value": "0x2386F26FC10000",
        "chain_id": 125
      }
    }
  }'
```
</Step>

<Step title="Sign a message">
```bash
curl --request POST https://api.privy.io/v1/wallets/wallet_abc123/evm/reference \
  -u "<your-app-id>:<your-app-secret>" \
  -H "privy-app-id: <your-app-id>" \
  -H "privy-authorization-signature: <authorization-signature>" \
  -H 'Content-Type: application/json' \
  -d '{
    "method": "personal_sign",
    "caip2": "eip155:125",
    "params": {
      "message": "Hello from Paxeer"
    }
  }'
```
</Step>

</Steps>

</Tab>
<Tab title="Node.js SDK">

<Steps>

<Step title="Install the SDK">
```bash
npm install @privy-io/server-auth
```
</Step>

<Step title="Create a wallet and send a transaction">
```typescript
import { PrivyClient } from '@privy-io/server-auth';
import { parseEther } from 'viem';

const privy = new PrivyClient('<your-app-id>', '<your-app-secret>', {
  walletApi: { authorizationPrivateKey: process.env.PRIVY_AUTH_KEY },
});

// Create a server wallet
const wallet = await privy.walletApi.createWallet({ chainType: 'ethereum' });
console.log('Wallet address:', wallet.address);

// Send a transaction on Paxeer
// NOTE: `value` must be a hex string - Privy's request signer can't
// serialize a BigInt, so don't pass `parseEther(...)` directly.
const { hash } = await privy.walletApi.ethereum.sendTransaction({
  walletId: wallet.id,
  caip2: 'eip155:125', // Paxeer mainnet
  transaction: {
    to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    value: '0x' + parseEther('0.01').toString(16),
    chainId: 125,
  },
});
console.log('Transaction hash:', hash);
```
</Step>

</Steps>

</Tab>
<Tab title="Python SDK">

<Steps>

<Step title="Install the SDK">
```bash
pip install privy-client
```
</Step>

<Step title="Create a wallet and send a transaction">
```python
from privy import PrivyAPI

client = PrivyAPI(app_id="<your-app-id>", app_secret="<your-app-secret>")

# Create a server wallet
wallet = client.wallets.create(chain_type="ethereum")
print(f"Wallet address: {wallet.address}")

# Send a transaction on Paxeer
result = client.wallets.rpc(
    wallet_id=wallet.id,
    method="eth_sendTransaction",
    caip2="eip155:125",  # Paxeer mainnet
    params={
        "transaction": {
            "to": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
            "value": "0x2386F26FC10000",
            "chain_id": 125,
        }
    },
)
print(f"Transaction hash: {result.hash}")
```
</Step>

</Steps>

</Tab>
</Tabs>

### Known Quirks on Paxeer (Privy)

Verified by running `@privy-io/server-auth` against Paxeer (`eip155:125`):

- **`value` must be a hex string, not a `BigInt`.** Privy's request signer uses RFC 8785 JSON canonicalization (`canonicalize`), which throws `TypeError: Do not know how to serialize a BigInt` if you pass a `BigInt` in any field of the `transaction` object. Convert viem's `parseEther(...)` output with `'0x' + parseEther('0.01').toString(16)` before sending.
- **`authorizationKeyIds` on `createWallet` expects the public-key registration ID, not the dashboard key ID.** Passing the ID shown next to a key in the Privy dashboard can fail with `400 Invalid authorization key IDs`. If you only need an app-owned wallet (app credentials + `authorizationPrivateKey` for request signing), omit `authorizationKeyIds` - the wallet is still fully operable.

### Privy with LangChain

Privy publishes a LangChain integration (`langchain-privy`) that exposes wallet operations as a single LangChain tool. The tool reads `PRIVY_APP_ID` and `PRIVY_APP_SECRET` from the environment and is bound directly to the LLM:

```python
import os
from langchain_privy import PrivyWalletTool
from langchain_openai import ChatOpenAI

os.environ["PRIVY_APP_ID"] = "<your-app-id>"
os.environ["PRIVY_APP_SECRET"] = "<your-app-secret>"

tool = PrivyWalletTool()
print(f"Wallet: {tool.wallet_address}")

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
llm_with_tools = llm.bind_tools([tool])

response = llm_with_tools.invoke("What is my wallet address?")
```

<Warning>
As of `langchain-privy@0.1.0`, the library's `Chain` enum does not include Paxeer - the built-in tool only targets Ethereum, Base, Optimism, Arbitrum, Polygon, Zora, Avalanche, BSC, Celo, Linea, Solana, and Bitcoin. For Paxeer, either:

- Call Privy's REST API / server-auth SDK directly with `caip2: eip155:125` (shown above), or
- Use AgentKit's `PrivyWalletProvider` with a LangChain adapter (`@coinbase/agentkit-langchain`) - see the [Combined](#using-agentkit-with-privy-combined) section below.
</Warning>

### Privy Policy Engine

Privy's policy engine evaluates policies server-side before signing. Each rule pairs an `ALLOW`/`DENY` action with an RPC `method` and a list of `conditions` on transaction fields. Attach one or more policies to a wallet via `updateWallet`.

<Warning>
**Privy's engine is default-deny.** A request is allowed only when at least one `ALLOW` rule matches and no `DENY` rule matches. A policy built from `DENY`-only rules blocks every transaction - including ones you expect to pass. Always start from an explicit `ALLOW` rule that describes the happy path, then layer `DENY` rules on top.
</Warning>

```typescript
// "Cap sends at 10 HPX and block a specific address."
// Rule 1 (ALLOW) defines the happy path; without it, every request is denied.
// Rule 2 (DENY) carves a specific hole in that allow.
const policy = await privy.walletApi.createPolicy({
  name: 'paxeer-agent-policy',
  version: '1.0',
  chainType: 'ethereum',
  rules: [
    {
      name: 'Allow sends up to 10 HPX',
      action: 'ALLOW',
      method: 'eth_sendTransaction',
      conditions: [
        {
          fieldSource: 'ethereum_transaction',
          field: 'value',
          operator: 'lte',
          value: '10000000000000000000', // 10 HPX in wei
        },
      ],
    },
    {
      name: 'Deny sends to blocklisted address',
      action: 'DENY',
      method: 'eth_sendTransaction',
      conditions: [
        {
          fieldSource: 'ethereum_transaction',
          field: 'to',
          operator: 'in',
          value: ['0xdEAD000000000000000042069420694206942069'],
        },
      ],
    },
  ],
});

// Attach policy to wallet
await privy.walletApi.updateWallet({
  id: wallet.id,
  policyIds: [policy.id],
});
```

<Info>
Conditions support the `eq`, `gt`, `gte`, `lt`, `lte`, and `in` operators against `ethereum_transaction` fields (`to`, `value`) or `ethereum_calldata` fields. Operand order is `tx_field <operator> rule_value` - e.g. `operator: 'lte'` with `value: '10000000000000000000'` means "transaction value ≤ 10 HPX". `method` must be `eth_sendTransaction` or `eth_signTransaction`. Chain restriction is not a policy condition - enforce `caip2: 'eip155:125'` at the call site to keep an agent on Paxeer.
</Info>

Privy also offers features beyond the policy engine:

- **Key quorums** - require multiple authorization keys to approve high-value transactions
- **Webhook notifications** - get notified of all wallet activity (works chain-agnostically)

---

## Using AgentKit with Privy (Combined)

AgentKit includes a built-in `PrivyWalletProvider`, so you can use Privy's wallet infrastructure and policy engine as the backend while using AgentKit's 40+ action providers for onchain operations.

Because of the `authorizationKeyIds` quirk noted above, the simplest working pattern is to create the wallet once via the Privy SDK (or the dashboard) and then hand the resulting `walletId` to AgentKit:

```typescript
import { AgentKit, PrivyWalletProvider, walletActionProvider, erc20ActionProvider } from '@coinbase/agentkit';
import { PrivyClient } from '@privy-io/server-auth';

// Step 1 - create (or look up) a server wallet via the Privy SDK.
// Omit authorizationKeyIds here; attach policies with updateWallet if needed.
const privy = new PrivyClient(process.env.PRIVY_APP_ID!, process.env.PRIVY_APP_SECRET!, {
  walletApi: { authorizationPrivateKey: process.env.PRIVY_AUTH_KEY },
});
const wallet = await privy.walletApi.createWallet({ chainType: 'ethereum' });

// Step 2 - wrap the existing wallet in AgentKit's PrivyWalletProvider.
const walletProvider = await PrivyWalletProvider.configureWithWallet({
  appId: process.env.PRIVY_APP_ID!,
  appSecret: process.env.PRIVY_APP_SECRET!,
  chainId: '125', // Paxeer mainnet
  walletId: wallet.id,
  authorizationPrivateKey: process.env.PRIVY_AUTH_KEY,
});

const agentKit = await AgentKit.from({
  walletProvider,
  actionProviders: [
    walletActionProvider(),
    erc20ActionProvider(),
  ],
});
```

This gives you the best of both worlds: Privy's fine-grained policies and key quorums with AgentKit's rich action library.

<Warning>
If you call `PrivyWalletProvider.configureWithWallet` **without** a `walletId`, AgentKit will attempt to create a new wallet for you and pass `authorizationKeyId` through to Privy - which hits the same `400 Invalid authorization key IDs` failure described in Privy's Known Quirks. Always pre-create the wallet and pass `walletId`.
</Warning>

---

## Feature Matrix

### Wallet Creation & Key Management

| Capability | Coinbase AgentKit | Privy |
| --- | --- | --- |
| Programmatic wallet creation on Paxeer | Yes - self-custodial via `ViemWalletProvider` (you hold the key). CDP-managed server wallets do not currently support Paxeer. | Yes - Server wallets on any EVM |
| TEE-secured key isolation on Paxeer | No - CDP's TEE signer is scoped to Base/Ethereum/Polygon/Arbitrum/Optimism. Use Privy (standalone or via `PrivyWalletProvider` in AgentKit). | Yes - TEE + key sharding |
| Managed cloud custody on Paxeer | No via CDP. Yes via `PrivyWalletProvider`. | Yes - Server wallets with `eip155:125` |
| Multi-party key quorum | No | Yes - Authorization key quorums via dashboard |
| Key export / portability | Yes | Yes |


### Policy Engine & Guardrails

| Capability | Coinbase AgentKit | Privy |
| --- | --- | --- |
| Spending limits (per-tx) on Paxeer | Only via app-level checks with `ViemWalletProvider`. CDP's `ethValue` policy doesn't apply on Paxeer. | Yes - Policy engine, any chain |
| Contract / address allowlisting on Paxeer | Only via app-level checks with `ViemWalletProvider`. CDP's `evmAddress` policy doesn't apply on Paxeer. | Yes - Contract allowlist rules |
| Network restriction policies on Paxeer | N/A - CDP networkIds don't include Paxeer | Yes - Chain restrictions |
| Time-based access controls | No | Yes |
| Transaction simulation | No | No - Needs Paxeer-specific RPC |


### Gas & Transaction Management

| Capability | Coinbase AgentKit | Privy |
| --- | --- | --- |
| Gasless / sponsored transactions on Paxeer | No - Gasless is Base-only | No - Requires Paxeer-native paymaster |
| Smart wallet (ERC-4337) on Paxeer | No - Smart Accounts don't include Paxeer | No - Possible via ZeroDev or Biconomy integration |
| Batch transactions on Paxeer | No - Requires Smart Accounts | Yes |
| Basic send / transfer on Paxeer | Yes | Yes |
| ERC-20 token operations on Paxeer | Yes - `erc20ActionProvider` | Yes - Standard EVM ops |


### Agentic DeFi Actions

| Capability | Coinbase AgentKit | Privy |
| --- | --- | --- |
| Token swaps on Paxeer DEXs | No - Built-in swap providers (Jupiter, 0x, Sushi, Enso) don't route Paxeer DEXs | No |
| Yield / lending on Paxeer | No - Built-in lending providers (Morpho, Moonwell, Compound, Yelay) aren't deployed on Paxeer | No |
| Liquidity provision on Paxeer | No | No |
| Cross-chain bridge to/from Paxeer | No - Paxeer not a listed Across route | No |
| Pyth oracle price feeds | Yes - `pythActionProvider` works on Paxeer | No |


<Info>
For Paxeer-native DeFi actions, use the [Cambrian Agent Kit](/ai) which includes built-in integrations for Symphony, DragonSwap, Silo, Takara, and Citrex.
</Info>

### x402 & Machine-to-Machine Payments

| Capability | Coinbase AgentKit | Privy |
| --- | --- | --- |
| x402 protocol support on Paxeer | No via built-in `x402ActionProvider` (allowlist is Base + Solana only) - possible via a custom action provider | Yes - Works wherever agent holds stablecoins |
| Agent-to-agent USDC transfers | Yes - ERC-20 transfers with Paxeer USDC | Yes - Server wallet transfers |
| Stablecoin operations on Paxeer | Yes - `erc20ActionProvider` + Paxeer USDC | Yes - Standard ERC-20 ops |


### Developer Experience

| Capability | Coinbase AgentKit | Privy |
| --- | --- | --- |
| MCP server integration | Yes - AgentKit MCP framework extension | No |
| LangChain / Vercel AI SDK | Yes - Framework extensions for both | Yes - `langchain-privy` |
| OpenAI Agents SDK | Yes - Native extension | No |
| Webhook / event monitoring on Paxeer | No - Webhooks for supported networks only | Yes - Chain-agnostic webhooks |
| Multi-language SDKs | TypeScript, Python | TypeScript, Python, Java, Rust, Go + REST |


---

## Other Agentic Wallet Solutions

While Coinbase AgentKit and Privy are the most mature options for Paxeer, several other platforms support agentic wallet use cases:

| Platform | Approach | Paxeer Support | Best For |
| --- | --- | --- | --- |
| [Turnkey](https://docs.turnkey.com/products/embedded-wallets/features/agentic-wallets) | TEE-based key isolation, sub-100ms signing, granular policies | Yes (any EVM) | Enterprise agents needing fine-grained policies |
| [Lit Protocol](https://developer.litprotocol.com/) | Decentralized key management (DKG), programmable key pairs as NFTs | Yes (any EVM) | Decentralized, user-owned agent delegation |
| [Dynamic](https://www.dynamic.xyz/ecosystems/sei) | MPC or smart contract wallets, strong onboarding UX | Yes (explicit Paxeer support) | Apps serving both humans and agents |
| [thirdweb](https://thirdweb.com/) | Backend wallets + account abstraction, session keys | Yes (any EVM) | Broadest AI framework support (6+ frameworks) |
| [Openfort](https://www.openfort.io/solutions/ai-agents) | TEE server wallets, sub-125ms signing, 25+ EVM chains | Yes (any EVM) | Gaming and high-throughput agent workloads |


---

## Paxeer Network Configuration Reference

Use these values when configuring any agentic wallet provider for Paxeer:

| Parameter | Value |
| --- | --- |
| **Chain ID** | `125` |
| **Chain ID (hex)** | `0x7d` |
| **CAIP-2** | `eip155:125` |
| **RPC URL** | Contact Paxeer team for current RPC endpoint |
| **Currency** | HPX (18 decimals) |
| **Bech32 prefix** | `pax1...` |
| **Finality** | ~400ms (Twin Turbo Consensus) |


<Warning>
**Security Reminders:**

- Never expose private keys or authorization secrets to the LLM/agent process.
- Always use dedicated wallets for agent operations - never your main wallet.
- Start with a test wallet before deploying to production.
- Set spending limits and contract allowlists via the policy engine before going live.
- Monitor agent wallet activity via block explorers or webhook notifications.
</Warning>

---

## Build on Paxeer with AI

*AI tools for building on Paxeer - from agent infrastructure and LayerX to 402LXP payments and agentic wallets.*

Paxeer provides infrastructure for autonomous AI agents to operate on-chain via **LayerX**, **402LXP**, **Deus**, and full EVM compatibility.

## Agent infrastructure

<Columns cols={2}>
  <Card title="LayerX" icon="layer-group" href="/ai/402lxp">
    **Agent channel.** LayerX is Paxeer's dedicated agent execution layer - 402LXP staking, agent registration, and the 402LXP payment rail for machine-to-machine transactions.
  </Card>
  <Card title="Deus" icon="robot" href="/ai/agentic-wallets">
    **Agent framework.** Deus provides the runtime for autonomous AI agents on Paxeer - wallet management, policy enforcement, and on-chain action execution.
  </Card>
</Columns>

## Build AI agents on Paxeer

<Columns cols={3}>
  <Card title="Agentic Wallets" icon="wallet" href="/ai/agentic-wallets">
    Wallet infrastructure designed for AI agents: programmable signing, session keys, and policy controls.
  </Card>
  <Card title="402LXP Payments" icon="credit-card" href="/ai/402lxp">
    HTTP-native micropayments so agents can pay per-inference for LLM APIs, data feeds, and other monetized services.
  </Card>
  <Card title="MCP Server" icon="plug" href="/ai/mcp-server">
    Give your AI assistant live blockchain access - query balances, send transactions, interact with contracts.
  </Card>
</Columns>

---

## MCP Server

*Enable AI assistants to interact with Paxeer networks through natural language using the Model Context Protocol*

The Paxeer Model Context Protocol (MCP) Server enables AI assistants to interact with Paxeer networks through natural language. Built on the [Model Context Protocol](https://modelcontextprotocol.io/) standard, it provides seamless blockchain integration for AI coding assistants.

## What is MCP?

The Model Context Protocol is an open standard that connects AI systems with external tools and data sources. It enables:

- Real-time data access from external services
- Function execution and operations
- Context preservation across interactions
- Specialized capabilities beyond base training

The Paxeer MCP Server leverages this protocol to bring blockchain functionality directly to your AI assistant.

## Capabilities

| Category | Features |
| --- | --- |
| Account Management | Wallet addresses • Balance queries • Contract verification |
| Token Operations | HPX transfers • ERC20/721/1155 support • Token approvals |
| Blockchain Data | Block information • Transaction details • Network status |
| Smart Contracts | State queries • Function execution • Event logs |
| Networks | Paxeer Mainnet (chain ID 125) |

## Setup Guide

<Tabs>
<Tab title="Cursor">

### Cursor Setup

<Steps>

<Step title="Open Settings">
Navigate to `Cursor → Settings → Cursor Settings → MCP`
</Step>

<Step title="Configure Server">
Click **"Add new Global MCP server"** and add this configuration to `mcp.json`:

```json
{
  "mcpServers": {
    "paxeer-mcp-server": {
      "command": "npx",
      "args": ["-y", "@paxeer/mcp-server"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here"
      }
    }
  }
}
```
</Step>

<Step title="Restart">
Restart Cursor to activate the MCP server. You'll see a notification when it's ready.
</Step>

</Steps>

</Tab>
<Tab title="Windsurf">

### Windsurf Setup

<Steps>

<Step title="Open Settings">
Navigate to `Windsurf → Settings → Windsurf Settings → Cascade`
</Step>

<Step title="Add Configuration">
Add the Paxeer MCP Server to your configuration:

```json
{
  "mcpServers": {
    "paxeer": {
      "command": "npx",
      "args": ["-y", "@paxeer/mcp-server"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here"
      }
    }
  }
}
```
</Step>

<Step title="Activate">
Save and restart Windsurf. The server loads automatically.
</Step>

</Steps>

</Tab>
<Tab title="Claude Desktop">

### Claude Desktop Setup

<Steps>

<Step title="Install Claude">
Download [Claude Desktop](https://claude.ai/download) from Anthropic.
</Step>

<Step title="Edit Configuration">
Open **Settings** → **Developer** → **Edit Config** and add:

```json
{
  "mcpServers": {
    "paxeer": {
      "command": "npx",
      "args": ["-y", "@paxeer/mcp-server"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here"
      }
    }
  }
}
```
</Step>

<Step title="Restart">
Save and restart Claude Desktop to enable Paxeer tools.
</Step>

</Steps>

</Tab>
<Tab title="Claude CLI">

### Claude CLI Setup

<Steps>

<Step title="Install CLI">
```bash
npm install -g @anthropic-ai/claude-code
```
</Step>

<Step title="Add Server">
```bash
claude mcp add paxeer-mcp-server npx @paxeer/mcp-server
```
</Step>

<Step title="Start Session">
```bash
claude
```

The Paxeer MCP Server activates automatically in your session.
</Step>

</Steps>

</Tab>
</Tabs>

## Private Key Setup

<Warning>**Security Notice**: Generate a dedicated wallet for MCP operations. Never use your main wallet's private key.</Warning>

Export your private key from your wallet:

- Look for "Export Private Key" or "Show Private Key" in wallet settings
- Ensure the key starts with `0x`
- Fund the wallet with small amounts for testing

## Features

The Paxeer MCP Server enables your AI assistant to:

### Blockchain Operations

- Query account balances and transaction history
- Execute token transfers (HPX and ERC-20 tokens)
- Interact with smart contracts
- Monitor network status

### Available Tools

#### Core Operations

| Tool | Purpose | Example |
| --- | --- | --- |
| `get_address_from_private_key` | Retrieve wallet address | "What's my wallet address?" |
| `get_balance` | Check HPX balance | "Check balance of 0x123..." |
| `transfer_hpx` | Send HPX tokens | "Send 1 HPX to 0x456..." |
| `is_contract` | Verify contract address | "Is 0x789... a contract?" |

#### Token Management

| Tool | Purpose | Example |
| --- | --- | --- |
| `get_token_info` | Token metadata | "Get USDC token info" |
| `get_token_balance` | Token balance | "Check my USDC balance" |
| `transfer_token` | Token transfer | "Send 100 USDC to 0x123..." |
| `approve_token_spending` | Token approval | "Approve DEX for USDC" |

#### Blockchain Data

| Tool | Purpose | Example |
| --- | --- | --- |
| `get_chain_info` | Network information | "Show Paxeer mainnet info" |
| `get_block_by_number` | Block details by number | "Get block 12345" |
| `get_latest_block` | Latest block details | "Get latest block" |
| `get_transaction` | Transaction data | "Show tx 0xTXID..." |
| `read_contract` | Contract state | "Read contract reserves" |

## Resource URIs

Access blockchain data through standardized URIs:

```bash
# Network data
evm://paxeer/chain

# Block information
evm://paxeer/block/latest
evm://paxeer/block/12345

# Transactions
evm://paxeer/tx/0xabc123...
evm://paxeer/tx/0xabc123.../receipt

# Token data
evm://paxeer/token/0xTOKEN_ADDRESS
evm://paxeer/token/0xTOKEN_ADDRESS/balanceOf/0xWALLET...
```

## Configuration

### Environment Setup

```bash
# .env file
PRIVATE_KEY=0x_your_private_key_here

# Optional
CUSTOM_RPC_URL=https://your-rpc.com
CUSTOM_CHAIN_ID=125
```

### HTTP Server Mode

For web applications:

```bash
# Start HTTP server
npx @paxeer/mcp-server --http

# Connect from web app
const eventSource = new EventSource('http://localhost:3001/sse');
```

## Security Guidelines

<Warning>
**Security Guidelines:**

1. **Use a dedicated wallet** - Create a new wallet specifically for MCP
2. **Minimal funding** - Only add funds needed for testing
3. **Environment variables** - Never hardcode private keys
4. **Monitor activity** - Regularly check transaction history

**For production:**

- Implement transaction limits
- Use multi-signature wallets
- Add contract whitelisting
- Enable rate limiting

</Warning>

## Troubleshooting

**Connection issues**: Verify Node.js 18+ is installed and restart your AI assistant.

**Private key errors**: Ensure key format starts with `0x` and wallet has sufficient funds.

---

## Building a Frontend for Paxeer EVM: A Comprehensive Guide

*Learn to build a Paxeer EVM dApp frontend using Ethers.js, Viem, and Wagmi for wallet connection and ERC20 token interaction.*

Developing the frontend of a dApp on Paxeer EVM involves connecting to wallets, interacting with the blockchain via RPC endpoints, and signing and broadcasting transactions. This tutorial will demonstrate how to build a simple ERC20 token interface using three popular libraries:

1. [**Ethers.js**](https://docs.ethers.org/v6/) - A complete and compact library for interacting with
   EVM blockchains. Known for its simplicity and extensive functionality.
2. [**Viem**](https://viem.sh/docs/getting-started) - A lightweight and modular TypeScript interface for Ethereum
3. [**Wagmi**](https://wagmi.sh/) - A React hooks library built on top of Viem that simplifies wallet
   connection and interaction. Provides hooks for interacting with Ethereum
   wallets and contracts for use with modern frontend libraries and frameworks.

We'll implement the same functionality using each library so you can compare their approaches and choose the one that best fits your development style.

<Tip>

**Deploy to Testnet First**

It is <strong>highly recommended</strong> that you deploy to <em>testnet ()</em> first and verify everything works as expected before committing to mainnet. Doing so helps you catch bugs early, avoid unnecessary gas costs, and keep your users safe.

</Tip>

## When to Use Each Library

### Ethers.js

Ethers.js is ideal for developers who want a comprehensive, battle-tested library with straightforward API design. It's great for both simple and complex dApps, especially when you're not using React or need custom state management.

- **Pros**:
  - Comprehensive and easy-to-use API
  - Well-documented with a large community
  - Works well with both TypeScript and JavaScript
  - All-in-one solution for wallet connection and contract interaction
- **Cons**:
  - Larger bundle size compared to Viem
  - Not specifically designed for React hooks integration

### Viem

Viem is perfect for developers who want fine-grained control over their blockchain interactions and appreciate a modular, lightweight approach. It's a good choice when bundle size matters and when you have specific requirements for how contract interactions should work.

- **Pros**:
  - Lightweight and modular
  - Excellent TypeScript support with better type safety
  - Lower-level API gives more control
  - Smaller bundle size
- **Cons**:
  - Steeper learning curve
  - Requires more boilerplate code for some operations
  - Requires separate handling for wallet connection and contract interactions

### Wagmi

Wagmi is the best choice for React developers building dApps who want to leverage React's state management capabilities. It abstracts away much of the complexity of blockchain interactions via hooks, making it easy to build reactive UIs that respond to chain state.

- **Pros**:
  - React-specific hooks for seamless integration
  - Handles complex state management for you
  - Built on top of Viem, combining its benefits
  - Convenient caching and auto-refreshing for contract data
- **Cons**:
  - Only works with React
  - Adds another dependency layer
  - Opinionated about how data should be managed in your app

## Requirements

Before starting, ensure you have:

- Node.js & NPM installed
- One of the Paxeer wallets listed [here](/learn/wallets)

## Creating a React Project

Start by creating a new React project using Vite's TypeScript template for streamlined development:

```bash
npm create vite@latest paxeer-token-interface -- --template react-ts
```

This command creates a new folder with a React project using TypeScript. Open `paxeer-token-interface` in your favorite IDE.

<Info>This tutorial uses TypeScript. If you're not using TypeScript, you can easily adjust by removing the types.</Info>

## Project Structure

For clarity, we'll create separate components for each library implementation. First, let's set up the project structure:

```bash
cd paxeer-token-interface
mkdir src/components
touch src/components/EthersInterface.tsx
touch src/components/ViemInterface.tsx
touch src/components/WagmiInterface.tsx
mkdir src/shared
touch src/shared/constants.ts
touch src/wagmi.ts
```

## Defining the ERC20 Contract Details

<Info>Make sure to deploy your ERC20 token contract first - for example with [Hardhat](/evm/evm-hardhat) or [Foundry](/evm/evm-foundry), or generate one with the [contract wizard](/evm/evm-wizard) (see also [deploy & verify](/evm/evm-verify-contracts)) - and replace `TOKEN_CONTRACT_ADDRESS` in the constants file with your actual deployed contract address, and update the RPC URL in the Paxeer chain configuration. You can find a list of existing ERC20 contracts on Paxeer Mainnet here: [Paxeer Assets](https://paxscan.io/tokens)</Info>

Let's create a shared constants file for our project:

```tsx title="src/shared/constants.ts"
// Constants used across different implementations
export const ERC20_ABI = [
  {
    inputs: [],
    name: 'name',
    outputs: [
      {
        internalType: 'string',
        name: '',
        type: 'string'
      }
    ],
    stateMutability: 'view',
    type: 'function'
  },
  {
    inputs: [],
    name: 'symbol',
    outputs: [
      {
        internalType: 'string',
        name: '',
        type: 'string'
      }
    ],
    stateMutability: 'view',
    type: 'function'
  },
  {
    inputs: [],
    name: 'decimals',
    outputs: [
      {
        internalType: 'uint8',
        name: '',
        type: 'uint8'
      }
    ],
    stateMutability: 'view',
    type: 'function'
  },
  {
    inputs: [
      {
        internalType: 'address',
        name: 'account',
        type: 'address'
      }
    ],
    name: 'balanceOf',
    outputs: [
      {
        internalType: 'uint256',
        name: '',
        type: 'uint256'
      }
    ],
    stateMutability: 'view',
    type: 'function'
  },
  {
    inputs: [
      {
        internalType: 'address',
        name: 'to',
        type: 'address'
      },
      {
        internalType: 'uint256',
        name: 'amount',
        type: 'uint256'
      }
    ],
    name: 'transfer',
    outputs: [
      {
        internalType: 'bool',
        name: '',
        type: 'bool'
      }
    ],
    stateMutability: 'nonpayable',
    type: 'function'
  },
  {
    anonymous: false,
    inputs: [
      {
        indexed: true,
        internalType: 'address',
        name: 'from',
        type: 'address'
      },
      {
        indexed: true,
        internalType: 'address',
        name: 'to',
        type: 'address'
      },
      {
        indexed: false,
        internalType: 'uint256',
        name: 'value',
        type: 'uint256'
      }
    ],
    name: 'Transfer',
    type: 'event'
  }
];

// TODO: Deploy an ERC-20 (see /evm/evm-hardhat or /evm/evm-foundry) and paste its address here
export const TOKEN_CONTRACT_ADDRESS = '0xYourTokenContractAddress';
```

## Option 1: Ethers.js Implementation

Install ethers.js first:

```bash
npm install ethers
```

Let's start with the Ethers.js implementation:

- Checks for any EVM compatible wallet extension.
- Establishes a connection to Paxeer Mainnet via the connected wallet,
  using ethers.js BrowserProvider.
- Creates an ethers.js contract instance with the signer from the wallet,
  setting it in the contract state for later use.

```tsx title="src/components/EthersInterface.tsx"
import { useState, useEffect } from 'react';
import { BrowserProvider, Contract, formatEther, parseEther } from 'ethers';
import { ERC20_ABI, TOKEN_CONTRACT_ADDRESS } from '../shared/constants';

export function EthersInterface() {
  const [balance, setBalance] = useState<string>();
  const [contract, setContract] = useState<Contract>();
  const [recipientAddress, setRecipientAddress] = useState('');
  const [amount, setAmount] = useState('');
  const [isTransferring, setIsTransferring] = useState(false);
  const [tokenInfo, setTokenInfo] = useState<{ name: string; symbol: string }>();
  const [address, setAddress] = useState<string>();

  // Paxeer EVM network configuration
  const PAXEER_NETWORK_PARAMS = {
    chainId: '0x531', // 1329 in hexadecimal
    chainName: 'Paxeer Network',
    nativeCurrency: {
      name: 'Paxeer',
      symbol: 'HPX',
      decimals: 18
    },
    rpcUrls: ['https://evm-rpc.sei-apis.com'],
    blockExplorerUrls: ['https://paxscan.io']
  };

  const fetchBalance = async () => {
    if (!contract || !address) return;
    try {
      const balance = await contract.balanceOf(address);
      setBalance(formatEther(balance));
    } catch (error) {
      console.error('Failed to fetch balance:', error);
    }
  };

  const fetchTokenInfo = async () => {
    if (!contract) return;
    try {
      const name = await contract.name();
      const symbol = await contract.symbol();
      setTokenInfo({ name, symbol });
    } catch (error) {
      console.error('Failed to fetch token info:', error);
    }
  };

  useEffect(() => {
    if (contract) {
      fetchTokenInfo();
      fetchBalance();
    }
  }, [contract, address]);

  const connectWallet = async () => {
    if (window.ethereum) {
      try {
        const provider = new BrowserProvider(window.ethereum);
        // Attempt to switch to the Paxeer network
        try {
          await provider.send('wallet_switchEthereumChain', [{ chainId: PAXEER_NETWORK_PARAMS.chainId }]);
        } catch (switchError: any) {
          // Error code 4902 indicates the chain is not added in MetaMask
          if (switchError.code === 4902) {
            await provider.send('wallet_addEthereumChain', [PAXEER_NETWORK_PARAMS]);
          } else {
            throw switchError;
          }
        }
        // Request account access
        await provider.send('eth_requestAccounts', []);
        const signer = await provider.getSigner();
        const userAddress = await signer.getAddress();
        setAddress(userAddress);
        const tokenContract = new Contract(TOKEN_CONTRACT_ADDRESS, ERC20_ABI, signer);
        setContract(tokenContract);
      } catch (error) {
        console.error('Failed to connect wallet:', error);
        alert('Failed to connect wallet. See console for details.');
      }
    } else {
      alert('No EVM compatible wallet installed');
    }
  };

  const transferTokens = async () => {
    if (!contract || !recipientAddress || !amount) return;
    try {
      setIsTransferring(true);
      const tx = await contract.transfer(recipientAddress, parseEther(amount));
      console.log('Transaction sent:', tx.hash);
      const receipt = await tx.wait();
      console.log('Transaction confirmed:', receipt);
      await fetchBalance();
      setRecipientAddress('');
      setAmount('');
    } catch (error) {
      console.error('Transfer failed:', error);
      alert('Transfer failed. Check console for details.');
    } finally {
      setIsTransferring(false);
    }
  };

  return (
    <div className="card">
      <h2>Ethers.js v6 Implementation</h2>
      {contract ? (
        <div>
          <h3>
            {tokenInfo?.name} ({tokenInfo?.symbol})
          </h3>
          <p>
            Connected Address: {address?.slice(0, 6)}...{address?.slice(-4)}
          </p>
          <p>
            Balance: {balance} {tokenInfo?.symbol}
          </p>
          <div style={{ marginTop: '20px' }}>
            <input type="text" placeholder="Recipient Address" value={recipientAddress} onChange={(e) => setRecipientAddress(e.target.value)} style={{ marginBottom: '10px', width: '300px' }} />
            <br />
            <input type="number" placeholder="Amount" value={amount} onChange={(e) => setAmount(e.target.value)} style={{ marginBottom: '10px', width: '300px' }} />
            <br />
            <button disabled={isTransferring} onClick={transferTokens}>
              {isTransferring ? 'Transferring...' : 'Transfer Tokens'}
            </button>
          </div>
        </div>
      ) : (
        <button onClick={connectWallet}>Connect with Ethers.js v6</button>
      )}
    </div>
  );
}
```

## Option 2: Viem Implementation

Install Viem first:

```bash
npm install viem
```

Now implement the Viem interface:

```tsx title="src/components/ViemInterface.tsx"
import { useState, useEffect } from 'react';
import { createWalletClient, custom, parseEther, formatEther } from 'viem';
import { createPublicClient, http } from 'viem';
import { sei } from 'viem/chains';
import { ERC20_ABI, TOKEN_CONTRACT_ADDRESS } from '../shared/constants';

export function ViemInterface() {
  const [balance, setBalance] = useState<string>();
  const [address, setAddress] = useState<string>();
  const [walletClient, setWalletClient] = useState<any>(null);
  const [publicClient, setPublicClient] = useState<any>(null);
  const [recipientAddress, setRecipientAddress] = useState('');
  const [amount, setAmount] = useState('');
  const [isTransferring, setIsTransferring] = useState(false);
  const [tokenInfo, setTokenInfo] = useState<{ name: string; symbol: string }>();

  useEffect(() => {
    // Initialize the public client
    const newPublicClient = createPublicClient({
      chain: sei,
      transport: http()
    });
    setPublicClient(newPublicClient);
  }, []);

  useEffect(() => {
    if (walletClient && publicClient && address) {
      fetchTokenInfo();
      fetchBalance();
    }
  }, [walletClient, publicClient, address]);

  const fetchBalance = async () => {
    if (!publicClient || !address) return;

    try {
      const balance = await publicClient.readContract({
        address: TOKEN_CONTRACT_ADDRESS as `0x${string}`,
        abi: ERC20_ABI,
        functionName: 'balanceOf',
        args: [address]
      });

      setBalance(formatEther(balance as bigint));
    } catch (error) {
      console.error('Error fetching balance:', error);
    }
  };

  const fetchTokenInfo = async () => {
    if (!publicClient) return;

    try {
      const [name, symbol] = await Promise.all([
        publicClient.readContract({
          address: TOKEN_CONTRACT_ADDRESS,
          abi: ERC20_ABI,
          functionName: 'name'
        }),
        publicClient.readContract({
          address: TOKEN_CONTRACT_ADDRESS,
          abi: ERC20_ABI,
          functionName: 'symbol'
        })
      ]);

      setTokenInfo({ name: name as string, symbol: symbol as string });
    } catch (error) {
      console.error('Error fetching token info:', error);
    }
  };
  const connectWallet = async () => {
    if (!window.ethereum) {
      alert('No EVM compatible wallet installed');
      return;
    }

    try {
      const [userAddress] = await window.ethereum.request({
        method: 'eth_requestAccounts'
      });

      setAddress(userAddress);

      const newWalletClient = createWalletClient({
        chain: sei,
        transport: custom(window.ethereum)
      });

      setWalletClient(newWalletClient);
    } catch (error) {
      console.error('Failed to connect wallet:', error);
      alert('Failed to connect wallet. See console for details.');
    }
  };

  const transferTokens = async () => {
    if (!walletClient || !address || !recipientAddress || !amount) return;

    try {
      setIsTransferring(true);

      // Prepare the contract call parameters
      const abi = ERC20_ABI;
      const functionName = 'transfer';
      const args = [recipientAddress, parseEther(amount)];

      // Execute the transaction
      const hash = await walletClient.writeContract({
        address: TOKEN_CONTRACT_ADDRESS as `0x${string}`,
        abi,
        functionName,
        args
      });

      console.log('Transaction sent:', hash);

      // Wait for the transaction to be mined
      const receipt = await publicClient.waitForTransactionReceipt({ hash });
      console.log('Transaction confirmed:', receipt);

      // Refresh the balance
      await fetchBalance();

      // Reset form
      setRecipientAddress('');
      setAmount('');
    } catch (error) {
      console.error('Transfer failed:', error);
      alert('Transfer failed. Check console for details.');
    } finally {
      setIsTransferring(false);
    }
  };

  return (
    <div className="card">
      <h2>Viem Implementation</h2>
      {address ? (
        <div>
          <h3>
            {tokenInfo?.name} ({tokenInfo?.symbol})
          </h3>
          <p>
            Connected Address: {address.slice(0, 6)}...{address.slice(-4)}
          </p>
          <p>
            Balance: {balance} {tokenInfo?.symbol}
          </p>
          <div style={{ marginTop: '20px' }}>
            <input type="text" placeholder="Recipient Address" value={recipientAddress} onChange={(e) => setRecipientAddress(e.target.value)} style={{ marginBottom: '10px', width: '300px' }} />
            <br />
            <input type="number" placeholder="Amount" value={amount} onChange={(e) => setAmount(e.target.value)} style={{ marginBottom: '10px', width: '300px' }} />
            <br />
            <button disabled={isTransferring} onClick={transferTokens}>
              {isTransferring ? 'Transferring...' : 'Transfer Tokens'}
            </button>
          </div>
        </div>
      ) : (
        <button onClick={connectWallet}>Connect with Viem</button>
      )}
    </div>
  );
}
```

## Option 3: Wagmi Implementation

Install Wagmi and configure it:

```bash
npm install wagmi viem @tanstack/react-query
```

First, let's create a Wagmi configuration file:

```tsx title="src/wagmi.ts"
import { http, createConfig } from 'wagmi';
import { sei, seiTestnet } from 'wagmi/chains';
import { injected } from 'wagmi/connectors';

export const config = createConfig({
  chains: [sei, seiTestnet],
  connectors: [injected()],
  transports: {
    [sei.id]: http(),
    [seiTestnet.id]: http()
  }
});
```

Now implement the Wagmi interface:

```tsx title="src/components/WagmiInterface.tsx"
import { useState, useEffect } from 'react';
import { useAccount, useConnect, useReadContract, useWriteContract, useWaitForTransactionReceipt } from 'wagmi';
import { injected } from 'wagmi/connectors';
import { parseEther, formatEther } from 'viem';
import { ERC20_ABI, TOKEN_CONTRACT_ADDRESS } from '../shared/constants';

export function WagmiInterface() {
  const [recipientAddress, setRecipientAddress] = useState('');
  const [amount, setAmount] = useState('');

  // Wagmi hooks
  const { address, isConnected } = useAccount();
  const { connect } = useConnect();

  // For debugging
  console.log('Connection status:', { address, isConnected });

  // Read from contract
  const { data: name } = useReadContract({
    address: TOKEN_CONTRACT_ADDRESS as `0x${string}`,
    abi: ERC20_ABI,
    functionName: 'name'
  });

  const { data: symbol } = useReadContract({
    address: TOKEN_CONTRACT_ADDRESS as `0x${string}`,
    abi: ERC20_ABI,
    functionName: 'symbol'
  });

  const { data: balance, refetch: refetchBalance } = useReadContract({
    address: TOKEN_CONTRACT_ADDRESS as `0x${string}`,
    abi: ERC20_ABI,
    functionName: 'balanceOf',
    args: address ? [address] : undefined,
    query: {
      enabled: !!address
    }
  });

  // Write to contract
  const { writeContract, data: hash, isPending: isTransferring, error } = useWriteContract();

  // Wait for transaction
  const { isLoading: isConfirming, isSuccess: isConfirmed } = useWaitForTransactionReceipt({
    hash
  });

  // Connect wallet
  const connectWallet = async () => {
    try {
      connect({ connector: injected() });
    } catch (err) {
      console.error('Failed to connect:', err);
    }
  };

  // Transfer tokens
  const transferTokens = async () => {
    if (!recipientAddress || !amount) return;
    try {
      writeContract({
        address: TOKEN_CONTRACT_ADDRESS as `0x${string}`,
        abi: ERC20_ABI,
        functionName: 'transfer',
        args: [recipientAddress, parseEther(amount)]
      });
    } catch (err) {
      console.error('Transfer failed:', err);
    }
  };

  // Handle successful transfer
  useEffect(() => {
    if (isConfirmed) {
      refetchBalance();
      setRecipientAddress('');
      setAmount('');
    }
  }, [isConfirmed, refetchBalance]);

  return (
    <div className="card">
      <h2>Wagmi Implementation</h2>
      {isConnected ? (
        <div>
          <h3>
            {(name as string) || 'Loading...'} ({(symbol as string) || '...'})
          </h3>
          <p>
            Connected Address: {address?.slice(0, 6)}...{address?.slice(-4)}
          </p>
          <p>
            Balance: {balance ? formatEther(balance as bigint) : '0'} {(symbol as string) || ''}
          </p>
          <div style={{ marginTop: '20px' }}>
            <input type="text" placeholder="Recipient Address" value={recipientAddress} onChange={(e) => setRecipientAddress(e.target.value)} style={{ marginBottom: '10px', width: '300px' }} />
            <br />
            <input type="number" placeholder="Amount" value={amount} onChange={(e) => setAmount(e.target.value)} style={{ marginBottom: '10px', width: '300px' }} />
            <br />
            <button disabled={isTransferring || isConfirming} onClick={transferTokens}>
              {isTransferring ? 'Preparing Transaction...' : isConfirming ? 'Confirming Transaction...' : 'Transfer Tokens'}
            </button>
            {error && <p style={{ color: 'red' }}>Error: {(error as Error).message}</p>}
          </div>
        </div>
      ) : (
        <button onClick={connectWallet}>Connect with Wagmi</button>
      )}
    </div>
  );
}
```

## Updating the Main App to Display all Implementations

Now update your `App.tsx` to include all three interface options:

```tsx title="src/App.tsx"
import { useState } from 'react';
import { WagmiProvider } from 'wagmi';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { EthersInterface } from './components/EthersInterface';
import { ViemInterface } from './components/ViemInterface';
import { WagmiInterface } from './components/WagmiInterface';
import { config } from './wagmi';

function App() {
  const [selectedLib, setSelectedLib] = useState<string | null>(null);

  const queryClient = new QueryClient();

  return (
    <div className="app-container">
      <h1>Paxeer ERC20 Token Interface</h1>
      <p>Choose a library implementation:</p>

      <div className="button-group">
        <button onClick={() => setSelectedLib('ethers')} className={selectedLib === 'ethers' ? 'active' : ''}>
          Ethers.js
        </button>
        <button onClick={() => setSelectedLib('viem')} className={selectedLib === 'viem' ? 'active' : ''}>
          Viem
        </button>
        <button onClick={() => setSelectedLib('wagmi')} className={selectedLib === 'wagmi' ? 'active' : ''}>
          Wagmi (React Hooks)
        </button>
      </div>

      <div className="interface-container">
        {selectedLib === 'ethers' && <EthersInterface />}
        {selectedLib === 'viem' && <ViemInterface />}
        {selectedLib === 'wagmi' && (
          <WagmiProvider config={config}>
            <QueryClientProvider client={queryClient}>
              <WagmiInterface />
            </QueryClientProvider>
          </WagmiProvider>
        )}
        {!selectedLib && (
          <div className="placeholder">
            <p>Select a library to see its implementation</p>
          </div>
        )}
      </div>
    </div>
  );
}

export default App;
```

## Polyfills for Browser Environment

When developing frontend applications for the blockchain, you might need polyfills for Node.js-specific features like `Buffer`. Add these polyfills to your project:

```tsx title="src/main.tsx"
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';
import { Buffer } from 'buffer';

// Polyfill self for browser and global for Node.js
const globalObject = typeof self !== 'undefined' ? self : global;

Object.assign(globalObject, {
  Buffer: Buffer
});

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);
```

## Running the Application

To see your app in action, run:

```bash
npm run dev
```

This will start a local development server, at `http://localhost:5173`. You can toggle between the different library implementations to see how each one works.

To build your application, run:

```bash
npm run build
```

Then preview the production build locally:

```bash
npm run preview
```

This serves the built app at `http://localhost:4173` so you can verify it before deploying. To go live, deploy the contents of the `dist` directory to any static hosting provider.

---

## Debugging for EVM

*Advanced debugging techniques for EVM transactions on Paxeer. Learn transaction template generation and analysis using paxd and Foundry cast tools.*

## Overview

Debugging EVM transactions on Paxeer requires understanding both the transaction creation process and how to analyze transaction behavior. This guide covers advanced debugging techniques using transaction template generation, analysis tools, and comprehensive transaction inspection methods to help developers identify and resolve issues in their EVM interactions.

## Transaction Template Generation

The `--generate-only` flag transforms any Paxeer CLI transaction command into a template generator, creating complete transaction structures without broadcasting them. Through the `--generate-only` flag and Foundry's `cast` tool, developers can craft, analyze, and debug transactions across the EVM environment.

### Basic Command Pattern

The general pattern follows this structure:

```bash
paxd tx <module> <action> <parameters> --from <key> --evm-rpc https://public-rpc.paxeer.app/evm/reference --generate-only
```

### Generating EVM Transaction Templates

To generate an EVM transaction template, use the `evm` module with `--generate-only`. Here's an example sending HPX to another EVM address:

```bash
paxd tx evm send 0xRecipientAddress 1000000000000000000 \
--gas-fee-cap=100000000000 \
--gas-limit=21000 \
--evm-rpc=https://public-rpc.paxeer.app/evm/reference \
--from=mykey \
--generate-only
```

<Info>This command returns a transaction template that you can analyze before broadcasting. The template includes all transaction details without executing the actual transaction.</Info>

---

## Analyzing EVM Transactions with Cast

Once you have a transaction hash, you can use Foundry's `cast` command to inspect the transaction details:

```bash
cast tx 0x5010e6600e67f04a9bc3d3b670a7c2de380b180713d9a014a5dbd76b7e2190f1 \
--rpc-url=https://public-rpc.paxeer.app/evm/reference
```

**Example Output:**

```text
blockHash               0x4696d63a9a9ae88b03bcc94ccbd87f407e994b309d1dff9c0626de51ac57b76e
blockNumber             130076639
from                    0xAa55a16dD4E73c48C968928983c2bcC98d913d96
transactionIndex        7
effectiveGasPrice       100000000000
accessList              []
chainId                 125
gasLimit                2500000
hash                    0x5010e6600e67f04a9bc3d3b670a7c2de380b180713d9a014a5dbd76b7e2190f1
input                   0xc31d960f0000...
maxFeePerGas            100000000000
maxPriorityFeePerGas    100000000000
nonce                   3
to                      0x000000000000000000000000000000000000100b
type                    2
value                   0
```

### Additional Analysis Commands

**Get transaction receipt:**

```bash
cast receipt 0x5010e6600e67f04a9bc3d3b670a7c2de380b180713d9a014a5dbd76b7e2190f1 \
--rpc-url=https://public-rpc.paxeer.app/evm/reference
```

**Decode transaction input data:**

```bash
cast 4byte-decode 0xc31d960f0000...
```

<Info>All template generation commands create JSON files that you can inspect, modify, and use for debugging before executing the actual transactions.</Info>

---

## RPC Consistency

<Warning>Always point `cast` commands to the Paxeer EVM RPC endpoint (`https://public-rpc.paxeer.app/evm/reference`), not a Cosmos RPC URL.</Warning>

---

## Tracing and Revert Reasons

If your endpoint supports debug RPC methods, you can retrieve full execution traces and revert reasons:

```bash
# Full transaction trace
cast rpc debug_traceTransaction 0xTX_HASH '{"tracer":"callTracer","timeout":"120s"}' \
  --rpc-url=$EVM_RPC_URL

# Simulate and trace a call without broadcasting
cast rpc debug_traceCall '{"from":"0xFROM","to":"0xTO","data":"0xDATA"}' \
  'latest' '{"tracer":"callTracer","timeout":"120s"}' \
  --rpc-url=$EVM_RPC_URL
```

<Info>
  Many public RPC endpoints disable debug methods. If disabled, run a local fork and trace there.
</Info>

---

## Reproduce with a Local Fork

Fork the network locally to reproduce issues deterministically and run traces even if remote debug RPC is disabled:

```bash
# Start a local fork
anvil --fork-url https://public-rpc.paxeer.app/evm/reference

# Re-run calls against the fork
cast call 0xContract "method(uint256)" 1 --rpc-url=http://127.0.0.1:8545

# Trace the call on the fork via debug RPC
cast rpc debug_traceCall '{"to":"0xContract","data":"0xENCODED_DATA"}' \
  'latest' '{"tracer":"callTracer"}' --rpc-url=http://127.0.0.1:8545
```

---

## Event Logs and Decoding

Use the receipt to inspect logs and decode with the contract ABI:

```bash
# Fetch receipt JSON and view logs
cast receipt 0xTX_HASH --rpc-url=$EVM_RPC_URL --json | jq '.logs'

# Compute an event signature for topic[0]
cast keccak "Transfer(address,address,uint256)"
```

<Info>Decode event topics/data using the contract ABI (from your repo or block explorer). Topic[0] equals the keccak of the event signature.</Info>

---

## Nonce, Balance, and Gas Diagnostics

Check common failure points quickly:

```bash
cast nonce 0xYourAddress --rpc-url=$EVM_RPC_URL
cast balance 0xYourAddress --rpc-url=$EVM_RPC_URL
cast gas-price --rpc-url=$EVM_RPC_URL
cast block latest baseFeePerGas --rpc-url=$EVM_RPC_URL
cast chain-id --rpc-url=$EVM_RPC_URL
```

**Checklist:**

- Incorrect nonce (pending tx in mempool)
- Insufficient native balance for gas
- Underpriced `maxFeePerGas`/`maxPriorityFeePerGas`
- Chain ID mismatch (Paxeer mainnet is `125`)

---

## Offline Workflow with --generate-only

Generate, inspect, sign, and broadcast safely:

```bash
# 1) Generate a template (no broadcast)
paxd tx evm send 0xTO 1000000000000000000 \
  --from=$WALLET_NAME --evm-rpc=$EVM_RPC_URL --generate-only > tx.json

# 2) Sign offline with your key
paxd tx sign tx.json --from $WALLET_NAME --chain-id $CHAIN_ID > signed.json

# 3) Broadcast the signed tx
paxd tx broadcast signed.json
```

<Warning>Never commit signed transactions or private keys. Use environment variables and `.gitignore` for sensitive data.</Warning>

---

## Storage Inspection

Verify on-chain state directly when debugging state changes:

```bash
cast storage 0xContract 0xSLOT --rpc-url=$EVM_RPC_URL
```

---

## Transaction Analysis

When analyzing transactions, follow these essential practices:

- Always verify EVM transactions thoroughly
- Use `cast` to decode input data when working with EVM transactions
- Keep track of gas parameters
- Monitor transaction status on the EVM layer

**Analysis Tips:**

```bash
# Use Foundry's cast tool for detailed transaction inspection
cast tx 0x5010e6600e67f04a9bc3d3b670a7c2de380b180713d9a014a5dbd76b7e2190f1 \
--rpc-url=$EVM_RPC_URL

# Get transaction receipt to verify success
cast receipt 0x5010e6600e67f04a9bc3d3b670a7c2de380b180713d9a014a5dbd76b7e2190f1 \
--rpc-url=$EVM_RPC_URL

# Decode transaction input data
cast 4byte-decode 0xa9059cbb000000...
```

<Info>
  <strong>Transaction Analysis Checklist:</strong> Always verify transaction success before proceeding. Check gas usage to optimize future transactions. Use Foundry's cast tool for detailed transaction inspection.
</Info>

---

## Error Handling

Handle potential EVM transaction issues with proper monitoring:

```javascript
try {
  // Check EVM transaction status
  const evmStatus = await checkEvmStatus(txHash);
  if (!evmStatus.success) {
    const evmError = await cast.call(['tx', txHash, '--rpc-url', evmRpcUrl]);
    console.error('EVM transaction failed:', evmError);
  }
} catch (error) {
  console.error('Transaction analysis failed:', error);
}
```

**Best Practices for Error Handling:**

- Always check transaction status before proceeding
- Use detailed error logging for debugging failed transactions
- Implement retry logic for network-related failures
- Monitor gas usage and adjust limits accordingly

---

## Security Guidelines

<Warning>
  <strong>Critical Security Requirements:</strong> Keep private keys secure and never include them in templates. Use an `.env` file or other environment variables when working with wallet keys or mnemonics. Never commit sensitive information to version control. Always verify transaction details before signing.
</Warning>

**Environment Variable Setup:**

```bash
# Create .env file for sensitive data
WALLET_NAME=mykey
EVM_RPC_URL=https://public-rpc.paxeer.app/evm/reference
PRIVATE_KEY=your_private_key_here

# Add .env to .gitignore
echo ".env" >> .gitignore
```

**Secure Transaction Execution:**

```bash
# Use environment variables in commands
paxd tx evm send 0x1234567890abcdef... 1000000000000000000 \
--from=$WALLET_NAME \
--evm-rpc=$EVM_RPC_URL

# Generate transaction template first to verify details
paxd tx evm send 0x1234567890abcdef... 1000000000000000000 \
--from=$WALLET_NAME \
--evm-rpc=$EVM_RPC_URL \
--generate-only
```

---

## Paxeer EVM vs Ethereum: Key Differences

*Explore key differences between Paxeer EVM and Ethereum, including block time, finality, consensus, opcodes, state root, and gas fees.*

While Paxeer features full EVM compatibility, there are some distinctions between
Paxeer's EVM and Ethereum itself:

| Feature | Paxeer EVM | Ethereum |
| --- | --- | --- |
| Blocktime | ~250 ms | ~12 s |
| Transaction Throughput | 5000 TPS | ~15-30 TPS |
| Finality | Instant (~250 ms) | Various commitment levels (safe, latest, justified, finalized) |
| Consensus | Twin Turbo + machineRFT | Proof of Stake |
| EVM Tooling Compatibility | 100% | 100% |
| Execution Environment | EVM | EVM |
| Address Space | Dual ECDSA-derived addresses; Bech32 (`pax1…`) + EVM-compatible address (`0x…`) | ECDSA-derived address (`0x…`) |
| Chain ID | 125 | 1 |

- Paxeer's Twin Turbo consensus combined with machineRFT delivers ~250ms block times and instant finality - a transaction is final as soon as its block is committed.
- Paxeer achieves 5000 TPS throughput, far exceeding Ethereum's capacity.
- The various commitment levels typical for Ethereum (i.e., safe, latest, justified, finalized) do not apply on Paxeer - all confirmed transactions are final.

## Opcode Differences

| Opcode | Paxeer EVM | Ethereum | Notes |
| --- | --- | --- | --- |
| PREVRANDAO | Returns a value derived from the current block time | Returns the RANDAO mix (EIP-4399) | Not a randomness source; use an oracle/VRF. `DIFFICULTY` aliases to this. |
| COINBASE | Always the global fee collector address | Block proposer (miner) address | Do not assume it is the validator address. |
| BASEFEE | Returns current base fee; no burn | Returns current base fee; a portion is burned (EIP-1559) | Query `eth_gasPrice` for the live value. |
| BLOCKHASH | Hash of the block header; different encoding | Keccak of the Ethereum block header | Usable for recent blocks only; values are not interchangeable across chains. |
| GASLIMIT | Per-block gas limit | Per-block gas limit | Represents block gas limit in both chains. |
| TIMESTAMP | Block time from consensus | Proposer-chosen block time | Same semantics; do not use as randomness. |
| DIFFICULTY | Alias of PREVRANDAO | Alias of PREVRANDAO (EIP-4399) | Returns the same value as PREVRANDAO. |
| Blob-related opcodes | Not supported | Supported post-Cancun (EIP-4844) | Blob transactions are not enabled on Paxeer. |

### PREVRANDAO

Since Paxeer uses Twin Turbo consensus with machineRFT rather than Proof of Stake, it doesn't have the "randomness" artifact that can be set as `PREVRANDAO`'s return value. On Paxeer, `PREVRANDAO` returns a value derived from the current block time. For strong randomness needs in contract logic, use a verifiable randomness oracle (as is advised on Ethereum itself).

### COINBASE

Coinbase address on Paxeer is always set to (the EVM address of) the global fee collector.

## State Root

Paxeer uses an AVL-tree for data storage instead of Ethereum's Merkle Patricia Trie (MPT). The global state root is the AVL-tree root, which is not equivalent to Ethereum's MPT-based state root.

## Block Hash

The block hash on Paxeer is computed based on the block header in the native consensus format and differs from Ethereum's block hash format.

## Base Fee & Tips

Paxeer supports standard EVM transaction types. Query the live gas price with `eth_gasPrice` rather than hard-coding it. Excess gas beyond actual usage may not be fully refunded.

Current EIP-1559 parameters can be fetched from the `paxd` CLI:

```sh
paxd q params subspace evm KeyTargetGasUsedPerBlock

key: KeyTargetGasUsedPerBlock
subspace: evm
value: '"850000"'
```

```sh
paxd q params subspace evm KeyMaxDynamicBaseFeeUpwardAdjustment

key: KeyMaxDynamicBaseFeeUpwardAdjustment
subspace: evm
value: '"0.007500000000000000"'
```

## Finality

Paxeer has instant finality - a transaction is final as soon as its block is committed (~250 ms) - meaning that commitment levels of "safe", "latest", "justified", and "finalized" on Ethereum are all the same thing on Paxeer.

## Pending State

On Ethereum the block proposer would execute its proposed block first (and update its local state) before broadcasting the proposal to others (the updated state would be marked "pending" until the node is accepted by other nodes).

On Paxeer, the block proposer broadcasts first and only executes the proposal if it's accepted (i.e., every node executes the block at roughly the same time), so Paxeer does not have a window when "pending state" exists.

## Gas Model & Fees

Paxeer does not implement base-fee burning. All transaction fees accrue to validators. Fees are calculated as:

Transaction Fee = Gas Used x Gas Price

**Practical implications**

- **Simpler fee handling:** Use `gasPrice` (you can omit `maxFeePerGas` / `maxPriorityFeePerGas`).
- **More stable fees:** Higher throughput reduces fee spikes during busy periods.
- **Typically lower cost:** Many workloads that are costly on Ethereum become economical on Paxeer.

<Info>

**Useful Infos**

- **Does Paxeer burn a base fee (EIP-1559)?** No.
- **Who receives fees?** Validators.
- **Are Paxeer fees lower?** Yes, due to higher throughput and parallel execution.

</Info>

## ERC Token Standards Compatibility

Paxeer's EVM fully supports the common token standards:

- **ERC-20** (fungible tokens)
- **ERC-721** (NFTs)
- **ERC-1155** (multi-token)

Existing OpenZeppelin contracts and tools work unchanged.

## Testing & Migration Checklist

- Re-deploy your Solidity code to Paxeer; most contracts need no changes.
- If you used SELFDESTRUCT, refactor to a soft-close pattern.
- Remove EIP-1559 fee UI complexity; use a single `gasPrice` input in frontends.
- If you rely on on-chain "randomness," integrate an oracle/VRF.
- Size your `gasLimit` with a modest buffer (parallel execution can slightly vary estimates).

---

## Ecosystem Contracts

*Comprehensive registry of smart contract addresses for projects building on Paxeer. Find verified contract addresses organized by project.*

import { EcosystemContracts } from '/snippets/ecosystem-contracts.jsx';

Discover and interact with the ecosystem building on Paxeer. This registry contains smart contract addresses for projects built across Paxeer.

<Info>

**Work in Progress**

This registry is actively maintained and expanded. We're constantly adding new projects and updating contract addresses. Check back regularly for the latest additions to the Paxeer ecosystem.

</Info>

---

## How to Use This Registry

- **Search by Project Name**: Use the search bar to quickly find contracts for specific projects.
- **View Contract Details**: Click on the PaxScan link to see detailed information about the contract
- **Bookmark This Page**: Keep this registry handy for quick access to the latest contract addresses and updates.

<Tip>

**Add Your Project**

Don't see your project listed? Want to add your contracts to this registry? **Reach out to us** and we'll help get you added!

</Tip>

## Contract Registry

<EcosystemContracts />

---

<Warning>Always verify contract addresses independently before interacting with them. While we strive to maintain accurate information, you should always double-check addresses through official project channels.</Warning>

---

## Paxeer EVM Smart Contract Development with Foundry

*Develop, test, and deploy smart contracts on Paxeer EVM with Foundry examples using Forge, Cast, and ethers.js.*

import { RunSnippet } from '/snippets/run-snippet.jsx';
import { SandboxEmbed } from '/snippets/sandbox-embed.jsx';
import { AddPaxeerButton } from '/snippets/add-paxeer-button.jsx';

This tutorial will guide you through setting up Foundry for Paxeer EVM development and using OpenZeppelin contracts to build secure, standardized smart contracts. We'll cover environment setup, contract creation, deployment, and show how to leverage OpenZeppelin's pre-built components with the powerful Foundry toolkit.

<Tip>

**Deploy to Testnet First**

It is <strong>highly recommended</strong> that you deploy to <em>testnet ()</em> first and verify everything works as expected before committing to mainnet. Doing so helps you catch bugs early, avoid unnecessary gas costs, and keep your users safe.

</Tip>

## Try it before you install

Installing Foundry and scaffolding a project takes a few minutes. If you just want to see a contract deploy to Paxeer, you can do both of these right now in the browser.

First, confirm the RPC endpoints you'll put in `foundry.toml` respond:

<RunSnippet method="eth_chainId" network="testnet" title="eth_chainId · " description="Testnet RPC - decodes to 1328." />

<RunSnippet method="eth_chainId" network="mainnet" title="eth_chainId · hyperpax_125-1" description="Mainnet RPC - decodes to 1329." />

Then add Paxeer testnet to your wallet and deploy a minimal `Counter.sol` from Remix - no `forge`, no install. In Remix: compile under **Solidity Compiler**, then **Deploy & Run** with **Environment** set to **Injected Provider - MetaMask**.

<AddPaxeerButton network="testnet" label="Add Paxeer testnet" />

<SandboxEmbed
  kind="remix"
  src="https://remix.ethereum.org/?#activate=solidity,fileManager&code=Ly8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IE1JVApwcmFnbWEgc29saWRpdHkgXjAuOC4yNDsKCi8vLyBAdGl0bGUgQ291bnRlciDigJQgbWluaW1hbCBjb250cmFjdCB0byBjb21waWxlICYgZGVwbG95IHRvIFNlaSB0ZXN0bmV0Lgpjb250cmFjdCBDb3VudGVyIHsKICAgIHVpbnQyNTYgcHVibGljIGNvdW50OwogICAgZnVuY3Rpb24gaW5jcmVtZW50KCkgZXh0ZXJuYWwgeyBjb3VudCsrOyB9CiAgICBmdW5jdGlvbiBkZWNyZW1lbnQoKSBleHRlcm5hbCB7IGNvdW50LS07IH0KfQ"
  title="Counter.sol · deploy to Paxeer testnet"
  description="Remix IDE with a minimal Counter contract preloaded. Compile in-browser, then deploy to Paxeer testnet."
/>

## Table of Contents

- [Try it before you install](#try-it-before-you-install)
- [Prerequisites](#prerequisites)
- [Setting Up Your Development Environment](#setting-up-your-development-environment)
- [Configuring Foundry for Paxeer EVM](#configuring-foundry-for-paxeer-evm)
- [Using OpenZeppelin Contracts](#using-openzeppelin-contracts)
- [Creating and Deploying Smart Contracts](#creating-and-deploying-smart-contracts)
- [Testing Your Smart Contracts](#testing-your-smart-contracts)
- [Deploying to Paxeer Testnet and Mainnet](#deploying-to-paxeer-testnet-and-mainnet)
- [Interacting with Deployed Contracts](#interacting-with-deployed-contracts)

## Prerequisites

Before we begin, ensure you have the following:

- [Foundry](https://book.getfoundry.sh/) installed on your system
- A basic understanding of Solidity and smart contract development
- A wallet with HPX tokens for gas
- [Node.js](https://nodejs.org/) (v18.0.0 or later) for ethers.js interactions

## Setting Up Your Development Environment

First, let's install Foundry if you haven't already. Follow the [installation guide](https://book.getfoundry.sh/getting-started/installation) or use the quick install command:

```bash
curl -L https://foundry.paradigm.xyz | bash
foundryup
```

Create a new Foundry project:

```bash
# Create a new directory for your project
mkdir paxeer-foundry-project
cd paxeer-foundry-project

# Initialize a new Foundry project
forge init --no-git

# Initialize git repository (required for installing dependencies)
git init
```

This will create a standard Foundry project structure with `src/`, `test/`, and `script/` directories.

## Configuring Foundry for Paxeer EVM

Create a `foundry.toml` file in your project root to configure Foundry for Paxeer networks:

```toml title="foundry.toml"
[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc_version = "0.8.28"
optimizer = true
optimizer_runs = 200

# Paxeer testnet configuration
[rpc_endpoints]
paxeer_testnet = "https://evm-rpc-testnet.sei-apis.com"
paxeer_mainnet = "https://evm-rpc.sei-apis.com"
```

Create a `.env` file to store your private key and other sensitive information:

```bash title=".env"
PRIVATE_KEY=your_private_key_here
PAXEER_TESTNET_RPC=https://evm-rpc-testnet.sei-apis.com
PAXEER_MAINNET_RPC=https://evm-rpc.sei-apis.com
```

<Warning>Add `.env` to your `.gitignore` file to prevent committing sensitive information such as your `PRIVATE_KEY` and potentially lose funds.</Warning>

## Using OpenZeppelin Contracts

OpenZeppelin provides a library of secure, tested smart contract components. Let's install OpenZeppelin contracts:

```bash
forge install OpenZeppelin/openzeppelin-contracts
```

Create a `remappings.txt` file to properly map the imports:

```bash
forge remappings > remappings.txt
```

## Creating and Deploying Smart Contracts

Let's create different types of smart contracts. Choose from the tabs below based on what you want to build:

<Tabs>
  <Tab title="Counter Contract">

Let's start with a simple counter contract. Update the default `src/Counter.sol` file:

```solidity title="src/Counter.sol"
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.22;

contract Counter {
    uint256 public number;
    address public owner;

    event NumberChanged(uint256 newNumber, address changedBy);

    constructor() {
        owner = msg.sender;
    }

    modifier onlyOwner() {
        require(msg.sender == owner, "Only owner can call this function");
        _;
    }

    function setNumber(uint256 newNumber) public {
        number = newNumber;
        emit NumberChanged(newNumber, msg.sender);
    }

    function increment() public {
        number++;
        emit NumberChanged(number, msg.sender);
    }

    function getCount() public view returns (uint256) {
        return number;
    }

    function reset() public onlyOwner {
        number = 0;
        emit NumberChanged(0, msg.sender);
    }
}
```

Create a deployment script in `script/DeployCounter.s.sol`:

```solidity title="script/DeployCounter.s.sol"
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.22;

import {Script} from "forge-std/Script.sol";
import {Counter} from "../src/Counter.sol";

contract DeployCounter is Script {
    function run() external returns (Counter) {
        vm.startBroadcast();
        Counter counter = new Counter();
        vm.stopBroadcast();
        return counter;
    }
}
```

  </Tab>
  <Tab title="ERC20 Token">

Create an ERC20 token using OpenZeppelin. Create `src/PaxeerToken.sol`:

```solidity title="src/PaxeerToken.sol"
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import "@openzeppelin/evm/evm-general/token/ERC20/ERC20.sol";
import "@openzeppelin/evm/evm-general/access/Ownable.sol";

contract PaxeerToken is ERC20, Ownable {
    constructor(address initialOwner)
        ERC20("Paxeer Token", "HPX")
        Ownable(initialOwner)
    {
        // Mint 1 million tokens to the contract deployer (with 18 decimals)
        _mint(msg.sender, 1000000 * 10 ** decimals());
    }

    // Function to mint new tokens (only owner)
    function mint(address to, uint256 amount) public onlyOwner {
        _mint(to, amount);
    }

    // Function to burn tokens
    function burn(uint256 amount) public {
        _burn(msg.sender, amount);
    }

    // Function to burn tokens from another account (with allowance)
    function burnFrom(address from, uint256 amount) public {
        _spendAllowance(from, msg.sender, amount);
        _burn(from, amount);
    }
}
```

Create a deployment script in `script/DeployPaxeerToken.s.sol`:

```solidity title="script/DeployPaxeerToken.s.sol"
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import {Script} from "forge-std/Script.sol";
import {PaxeerToken} from "../src/PaxeerToken.sol";

contract DeployPaxeerToken is Script {
    function run() external returns (PaxeerToken) {
        vm.startBroadcast();
        PaxeerToken token = new PaxeerToken(msg.sender);
        vm.stopBroadcast();
        return token;
    }
}
```

  </Tab>
  <Tab title="ERC721 NFT">

Create an ERC721 NFT contract using OpenZeppelin. Create `src/PaxeerNFT.sol`:

```solidity title="src/PaxeerNFT.sol"
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import "@openzeppelin/evm/evm-general/token/ERC721/ERC721.sol";
import "@openzeppelin/evm/evm-general/token/ERC721/extensions/ERC721Enumerable.sol";
import "@openzeppelin/evm/evm-general/token/ERC721/extensions/ERC721URIStorage.sol";
import "@openzeppelin/evm/evm-general/access/Ownable.sol";

contract PaxeerNFT is ERC721, ERC721Enumerable, ERC721URIStorage, Ownable {
    uint256 private _nextTokenId;
    string private _baseTokenURI;

    constructor(address initialOwner, string memory baseTokenURI)
        ERC721("Paxeer NFT Collection", "PAXEERNFT")
        Ownable(initialOwner)
    {
        _baseTokenURI = baseTokenURI;
    }

    // Function to update the base URI (only owner)
    function setBaseURI(string memory baseTokenURI) public onlyOwner {
        _baseTokenURI = baseTokenURI;
    }

    // Override the baseURI function
    function _baseURI() internal view override returns (string memory) {
        return _baseTokenURI;
    }

    function safeMint(address to, string memory uri) public onlyOwner returns (uint256) {
        uint256 tokenId = _nextTokenId++;
        _safeMint(to, tokenId);
        _setTokenURI(tokenId, uri);
        return tokenId;
    }

    // Public mint function with a fee
    function publicMint(string memory uri) public payable returns (uint256) {
        require(msg.value >= 0.01 ether, "Insufficient payment");
        uint256 tokenId = _nextTokenId++;
        _safeMint(msg.sender, tokenId);
        _setTokenURI(tokenId, uri);
        return tokenId;
    }

    // Withdraw contract balance (only owner)
    function withdraw() public onlyOwner {
        uint256 balance = address(this).balance;
        require(balance > 0, "No funds to withdraw");
        payable(owner()).transfer(balance);
    }

    // The following functions are overrides required by Solidity
    function _update(address to, uint256 tokenId, address auth)
        internal
        override(ERC721, ERC721Enumerable)
        returns (address)
    {
        return super._update(to, tokenId, auth);
    }

    function _increaseBalance(address account, uint128 value)
        internal
        override(ERC721, ERC721Enumerable)
    {
        super._increaseBalance(account, value);
    }

    function tokenURI(uint256 tokenId)
        public
        view
        override(ERC721, ERC721URIStorage)
        returns (string memory)
    {
        return super.tokenURI(tokenId);
    }

    function supportsInterface(bytes4 interfaceId)
        public
        view
        override(ERC721, ERC721Enumerable, ERC721URIStorage)
        returns (bool)
    {
        return super.supportsInterface(interfaceId);
    }
}
```

Create a deployment script in `script/DeployPaxeerNFT.s.sol`:

```solidity title="script/DeployPaxeerNFT.s.sol"
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import {Script} from "forge-std/Script.sol";
import {PaxeerNFT} from "../src/PaxeerNFT.sol";

contract DeployPaxeerNFT is Script {
    function run() external returns (PaxeerNFT) {
        string memory baseURI = "https://your-metadata-server.com/metadata/";

        vm.startBroadcast();
        PaxeerNFT nft = new PaxeerNFT(msg.sender, baseURI);
        vm.stopBroadcast();

        return nft;
    }
}
```

  </Tab>
</Tabs>

## Testing Your Smart Contracts

Foundry provides excellent testing capabilities. Let's create comprehensive tests for our contracts.

<Tabs>
  <Tab title="Counter Tests">

Update `test/Counter.t.sol`:

```solidity title="test/Counter.t.sol"
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.22;

import {Test, console} from "forge-std/Test.sol";
import {Counter} from "../src/Counter.sol";

contract CounterTest is Test {
    Counter public counter;
    address public owner;
    address public user;

    function setUp() public {
        owner = address(this);
        user = address(0x1);
        counter = new Counter();
        counter.setNumber(0);
    }

    function test_Increment() public {
        counter.increment();
        assertEq(counter.number(), 1);
    }

    function test_SetNumber() public {
        counter.setNumber(42);
        assertEq(counter.number(), 42);
    }

    function test_GetCount() public {
        uint256 initialCount = counter.getCount();
        counter.increment();
        assertEq(counter.getCount(), initialCount + 1);
    }

    function test_Reset() public {
        counter.setNumber(100);
        counter.reset();
        assertEq(counter.number(), 0);
    }

    function test_OnlyOwnerCanReset() public {
        vm.prank(user);
        vm.expectRevert("Only owner can call this function");
        counter.reset();
    }

    function test_EventEmitted() public {
        vm.expectEmit(true, true, false, true);
        emit Counter.NumberChanged(42, address(this));
        counter.setNumber(42);
    }

    function testFuzz_SetNumber(uint256 x) public {
        counter.setNumber(x);
        assertEq(counter.number(), x);
    }
}
```

  </Tab>
  <Tab title="ERC20 Tests">

Create `test/PaxeerToken.t.sol`:

```solidity title="test/PaxeerToken.t.sol"
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import {Test} from "forge-std/Test.sol";
import {PaxeerToken} from "../src/PaxeerToken.sol";

contract PaxeerTokenTest is Test {
    PaxeerToken public token;
    address public owner;
    address public user1;
    address public user2;

    function setUp() public {
        owner = address(this);
        user1 = address(0x1);
        user2 = address(0x2);
        token = new PaxeerToken(owner);
    }

    function test_InitialSupply() public {
        assertEq(token.totalSupply(), 1000000 * 10 ** 18);
        assertEq(token.balanceOf(owner), 1000000 * 10 ** 18);
    }

    function test_Transfer() public {
        token.transfer(user1, 1000);
        assertEq(token.balanceOf(user1), 1000);
        assertEq(token.balanceOf(owner), 1000000 * 10 ** 18 - 1000);
    }

    function test_Mint() public {
        token.mint(user1, 500);
        assertEq(token.balanceOf(user1), 500);
        assertEq(token.totalSupply(), 1000000 * 10 ** 18 + 500);
    }

    function test_Burn() public {
        token.burn(1000);
        assertEq(token.totalSupply(), 1000000 * 10 ** 18 - 1000);
    }

    function test_OnlyOwnerCanMint() public {
        vm.prank(user1);
        vm.expectRevert();
        token.mint(user2, 1000);
    }
}
```

  </Tab>
  <Tab title="ERC721 Tests">

Create `test/PaxeerNFT.t.sol`:

```solidity title="test/PaxeerNFT.t.sol"
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import {Test} from "forge-std/Test.sol";
import {PaxeerNFT} from "../src/PaxeerNFT.sol";

contract PaxeerNFTTest is Test {
    PaxeerNFT public nft;
    address public owner;
    address public user1;
    string public baseURI = "https://example.com/metadata/";

    function setUp() public {
        owner = address(this);
        user1 = address(0x1);
        nft = new PaxeerNFT(owner, baseURI);
    }

    function test_SafeMint() public {
        uint256 tokenId = nft.safeMint(user1, "1.json");
        assertEq(nft.ownerOf(tokenId), user1);
        assertEq(nft.tokenURI(tokenId), string(abi.encodePacked(baseURI, "1.json")));
    }

    function test_PublicMint() public {
        vm.deal(user1, 1 ether);
        vm.prank(user1);
        uint256 tokenId = nft.publicMint{value: 0.01 ether}("2.json");
        assertEq(nft.ownerOf(tokenId), user1);
    }

    function test_PublicMintInsufficientPayment() public {
        vm.deal(user1, 0.005 ether);
        vm.prank(user1);
        vm.expectRevert("Insufficient payment");
        nft.publicMint{value: 0.005 ether}("3.json");
    }

    function test_TotalSupply() public {
        assertEq(nft.totalSupply(), 0);
        nft.safeMint(user1, "1.json");
        assertEq(nft.totalSupply(), 1);
    }

    function test_Withdraw() public {
        vm.deal(user1, 1 ether);
        vm.prank(user1);
        nft.publicMint{value: 0.01 ether}("1.json");

        uint256 contractBalance = address(nft).balance;
        assertEq(contractBalance, 0.01 ether);

        nft.withdraw();
        assertEq(address(nft).balance, 0);
    }
}
```

  </Tab>
</Tabs>

Run your tests with:

```bash
forge test
```

For more verbose output:

```bash
forge test -vvv
```

## Deploying to Paxeer Testnet and Mainnet

Now let's deploy our contracts to the Paxeer networks. You can use either Forge scripts or direct deployment commands.

### Using Forge Scripts (Recommended)

Deploy to Paxeer testnet:

```bash
forge script script/DeployCounter.s.sol --rpc-url $PAXEER_TESTNET_RPC --private-key $PRIVATE_KEY --broadcast
```

Deploy to Paxeer mainnet:

```bash
forge script script/DeployCounter.s.sol --rpc-url $PAXEER_MAINNET_RPC --private-key $PRIVATE_KEY --broadcast
```

### Using Direct Forge Create Commands

Alternatively, you can deploy directly:

```bash
# Deploy Counter to testnet
forge create --rpc-url $PAXEER_TESTNET_RPC --private-key $PRIVATE_KEY src/Counter.sol:Counter

# Deploy PaxeerToken to testnet
forge create --rpc-url $PAXEER_TESTNET_RPC --private-key $PRIVATE_KEY src/PaxeerToken.sol:PaxeerToken --constructor-args $(cast abi-encode "constructor(address)" "YOUR_ADDRESS")

# Deploy PaxeerNFT to testnet
forge create --rpc-url $PAXEER_TESTNET_RPC --private-key $PRIVATE_KEY src/PaxeerNFT.sol:PaxeerNFT --constructor-args $(cast abi-encode "constructor(address,string)" "YOUR_ADDRESS" "https://your-metadata-server.com/metadata/")
```

Successful deployment will output:

```bash
[⠒] Compiling...
No files changed, compilation skipped
Deployer: 0xYOUR_DEPLOYER_ADDRESS
Deployed to: 0xYOUR_CONTRACT_ADDRESS
Transaction hash: 0xYOUR_TX_HASH
```

## Interacting with Deployed Contracts

Once deployed, you can interact with your contracts using Foundry's `cast` tool or ethers.js.

### Using Cast Commands

```bash
# Query the counter value
cast call $CONTRACT_ADDRESS "getCount()(uint256)" --rpc-url $PAXEER_TESTNET_RPC

# Increment the counter
cast send $CONTRACT_ADDRESS "increment()" --private-key $PRIVATE_KEY --rpc-url $PAXEER_TESTNET_RPC

# Set a specific number
cast send $CONTRACT_ADDRESS "setNumber(uint256)" 42 --private-key $PRIVATE_KEY --rpc-url $PAXEER_TESTNET_RPC

# Check ERC20 token balance
cast call $TOKEN_ADDRESS "balanceOf(address)(uint256)" $YOUR_ADDRESS --rpc-url $PAXEER_TESTNET_RPC

# Transfer ERC20 tokens
cast send $TOKEN_ADDRESS "transfer(address,uint256)" $RECIPIENT_ADDRESS 1000 --private-key $PRIVATE_KEY --rpc-url $PAXEER_TESTNET_RPC
```

### Using ethers.js

Install ethers.js to interact with your contracts programmatically:

```bash
npm install ethers@latest
```

Create a Node.js script to interact with your deployed contracts:

```tsx title="interact.js"
import { ethers } from 'ethers';

const privateKey = process.env.PRIVATE_KEY;
const evmRpcEndpoint = process.env.PAXEER_TESTNET_RPC;
const provider = new ethers.JsonRpcProvider(evmRpcEndpoint);
const signer = new ethers.Wallet(privateKey, provider);

// Counter contract interaction
const counterAbi = ['function getCount() public view returns (uint256)', 'function increment() public', 'function setNumber(uint256 newNumber) public', 'event NumberChanged(uint256 newNumber, address changedBy)'];

const counterAddress = 'YOUR_COUNTER_CONTRACT_ADDRESS';
const counterContract = new ethers.Contract(counterAddress, counterAbi, signer);

// ERC20 token interaction
const tokenAbi = ['function balanceOf(address owner) view returns (uint256)', 'function transfer(address to, uint256 amount) returns (bool)', 'function mint(address to, uint256 amount)', 'event Transfer(address indexed from, address indexed to, uint256 value)'];

const tokenAddress = 'YOUR_TOKEN_CONTRACT_ADDRESS';
const tokenContract = new ethers.Contract(tokenAddress, tokenAbi, signer);

async function interactWithContracts() {
  try {
    // Counter interactions
    console.log('Current count:', await counterContract.getCount());

    const incrementTx = await counterContract.increment();
    await incrementTx.wait();
    console.log('Incremented! New count:', await counterContract.getCount());

    // Token interactions
    const balance = await tokenContract.balanceOf(signer.address);
    console.log('Token balance:', ethers.formatEther(balance));

    // Transfer tokens
    const transferTx = await tokenContract.transfer('0xRecipientAddress', ethers.parseEther('100'));
    await transferTx.wait();
    console.log('Tokens transferred!');
  } catch (error) {
    console.error('Error:', error);
  }
}

interactWithContracts();
```

<Info>Foundry generates the ABI for contracts in the `out` folder. You can use this ABI to interact with contracts from other tools like `ethers.js` or `web3.js`.</Info>

---

## EVM General Guide for Paxeer

*Learn how the EVM powers Paxeer's fast, gas-efficient smart contracts using Solidity and Vyper, with code examples for both languages.*

## Overview

The Ethereum Virtual Machine (EVM) is the runtime environment for smart contracts, enabling compatibility with Ethereum-based dApps. Paxeer is an EVM-compatible blockchain with ~250ms block times and 5000 TPS throughput, powered by Twin Turbo consensus and machineRFT.

Here are some key points about the EVM:

1. **Turing Completeness**: The EVM is Turing complete, meaning it can execute any computable function. This allows developers to write complex smart contracts.
2. **Gas**: Transactions and contract executions on the EVM compatible network consume gas. Gas is a measure of computational work, and users pay for it in `hpx` on Paxeer networks. Gas ensures that malicious or inefficient code doesn't overload the network.
3. **Bytecode Execution**: Smart contracts are compiled into bytecode (low-level machine-readable instructions) and deployed to the EVM compatible network. The EVM executes this bytecode.

## Smart contract languages

The two most popular languages for developing smart contracts on the EVM are **Solidity** and **Vyper**.

### Solidity

- Object-oriented, high-level language for implementing smart contracts.
- Curly-bracket language that has been most profoundly influenced by C++.
- Statically typed (the type of a variable is known at compile time).
- Supports:
  - Inheritance (you can extend other contracts).
  - Libraries (you can create reusable code that you can call from different contracts - like static functions in a static class in other object oriented programming languages).
  - Complex user-defined types.

#### Example solidity contract

```solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >= 0.7.0;

contract Coin {
    // The keyword "public" makes variables
    // accessible from other contracts
    address public minter;
    mapping (address => uint) public balances;

    // Events allow clients to react to specific
    // contract changes you declare
    event Sent(address from, address to, uint amount);

    // Constructor code is only run when the contract
    // is created
    constructor() {
        minter = msg.sender;
    }

    // Sends an amount of newly created coins to an address
    // Can only be called by the contract creator
    function mint(address receiver, uint amount) public {
        require(msg.sender == minter);
        require(amount < 1e60);
        balances[receiver] += amount;
    }

    // Sends an amount of existing coins
    // from any caller to an address
    function send(address receiver, uint amount) public {
        require(amount <= balances[msg.sender], "Insufficient balance.");
        balances[msg.sender] -= amount;
        balances[receiver] += amount;
        emit Sent(msg.sender, receiver, amount);
    }
}
```

### Vyper

- Pythonic programming language
- Strong typing
- Small and understandable compiler code
- Efficient bytecode generation
- Deliberately has less features than Solidity with the aim of making contracts more secure and easier to audit. Vyper does not support:
  - Modifiers
  - Inheritance
  - Inline assembly
  - Function overloading
  - Operator overloading
  - Recursive calling
  - Infinite-length loops
  - Binary fixed points

#### Example Vyper contract

```python
# Open Auction

# Auction params
# Beneficiary receives money from the highest bidder
beneficiary: public(address)
auctionStart: public(uint256)
auctionEnd: public(uint256)

# Current state of auction
highestBidder: public(address)
highestBid: public(uint256)

# Set to true at the end, disallows any change
ended: public(bool)

# Keep track of refunded bids so we can follow the withdraw pattern
pendingReturns: public(HashMap[address, uint256])

# Create a simple auction with `_bidding_time`
# seconds bidding time on behalf of the
# beneficiary address `_beneficiary`.
@external
def __init__(_beneficiary: address, _bidding_time: uint256):
    self.beneficiary = _beneficiary
    self.auctionStart = block.timestamp
    self.auctionEnd = self.auctionStart + _bidding_time

# Bid on the auction with the value sent
# together with this transaction.
# The value will only be refunded if the
# auction is not won.
@external
@payable
def bid():
    # Check if bidding period is over.
    assert block.timestamp < self.auctionEnd
    # Check if bid is high enough
    assert msg.value > self.highestBid
    # Track the refund for the previous high bidder
    self.pendingReturns[self.highestBidder] += self.highestBid
    # Track new high bid
    self.highestBidder = msg.sender
    self.highestBid = msg.value

# Withdraw a previously refunded bid. The withdraw pattern is
# used here to avoid a security issue. If refunds were directly
# sent as part of bid(), a malicious bidding contract could block
# those refunds and thus block new higher bids from coming in.
@external
def withdraw():
    pending_amount: uint256 = self.pendingReturns[msg.sender]
    self.pendingReturns[msg.sender] = 0
    send(msg.sender, pending_amount)

# End the auction and send the highest bid
# to the beneficiary.
@external
def endAuction():
    # 1. Conditions
    # Check if auction endtime has been reached
    assert block.timestamp >= self.auctionEnd
    # Check if this function has already been called
    assert not self.ended

    # 2. Effects
    self.ended = True

    # 3. Interaction
    send(self.beneficiary, self.highestBid)
```

## Network Configuration

To interact with Paxeer EVM, configure your tools with the following:

| Property | Value |
| --- | --- |
| **RPC URL** | `https://public-rpc.paxeer.app/evm/reference` |
| **Chain ID** | `125` |
| **Currency Symbol** | `hpx` |
| **Block Explorer** | [paxscan.io](https://paxscan.io) |

### Hardhat Configuration

```javascript
// hardhat.config.js
module.exports = {
  networks: {
    paxeer: {
      url: "https://public-rpc.paxeer.app/evm/reference",
      chainId: 125,
      accounts: [process.env.PRIVATE_KEY],
    },
  },
};
```

### Foundry Configuration

```bash
# Deploy with Foundry
forge create --rpc-url https://public-rpc.paxeer.app/evm/reference \
  --private-key $PRIVATE_KEY \
  src/MyContract.sol:MyContract
```

<Info>
For more details on deploying with Hardhat or Foundry, see the [Hardhat](/evm/evm-hardhat) and [Foundry](/evm/evm-foundry) guides.
</Info>

---

## Paxeer EVM Development with Hardhat

*Learn to configure Hardhat 3 for Paxeer EVM development, integrate OpenZeppelin contracts, and deploy to testnet or mainnet.*

import { RunSnippet } from '/snippets/run-snippet.jsx';
import { SandboxEmbed } from '/snippets/sandbox-embed.jsx';
import { AddPaxeerButton } from '/snippets/add-paxeer-button.jsx';

This tutorial will guide you through setting up Hardhat for Paxeer EVM development and using OpenZeppelin contracts to build secure, standardized smart contracts. We'll cover environment setup, contract creation, deployment, and show how to leverage OpenZeppelin's pre-built components.

<Tip>

**Deploy to Testnet First**

It is <strong>highly recommended</strong> that you deploy to <em>testnet ()</em> first and verify everything works as expected before committing to mainnet. Doing so helps you catch bugs early, avoid unnecessary gas costs, and keep your users safe.

</Tip>

## Try it before you install

Setting up the full toolchain takes a few minutes. If you just want to see a contract deploy to Paxeer, you can do both of these right now in the browser.

First, confirm the RPC endpoints you'll put in `hardhat.config` respond:

<RunSnippet method="eth_chainId" network="testnet" title="eth_chainId · " description="Testnet RPC - decodes to 1328." />

<RunSnippet method="eth_chainId" network="mainnet" title="eth_chainId · hyperpax_125-1" description="Mainnet RPC - decodes to 1329." />

Then add Paxeer testnet to your wallet and deploy a minimal `Counter.sol` from Remix - no Node, no install. In Remix: compile under **Solidity Compiler**, then **Deploy & Run** with **Environment** set to **Injected Provider - MetaMask**.

<AddPaxeerButton network="testnet" label="Add Paxeer testnet" />

<SandboxEmbed
  kind="remix"
  src="https://remix.ethereum.org/?#activate=solidity,fileManager&code=Ly8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IE1JVApwcmFnbWEgc29saWRpdHkgXjAuOC4yNDsKCi8vLyBAdGl0bGUgQ291bnRlciDigJQgbWluaW1hbCBjb250cmFjdCB0byBjb21waWxlICYgZGVwbG95IHRvIFNlaSB0ZXN0bmV0Lgpjb250cmFjdCBDb3VudGVyIHsKICAgIHVpbnQyNTYgcHVibGljIGNvdW50OwogICAgZnVuY3Rpb24gaW5jcmVtZW50KCkgZXh0ZXJuYWwgeyBjb3VudCsrOyB9CiAgICBmdW5jdGlvbiBkZWNyZW1lbnQoKSBleHRlcm5hbCB7IGNvdW50LS07IH0KfQ"
  title="Counter.sol · deploy to Paxeer testnet"
  description="Remix IDE with a minimal Counter contract preloaded. Compile in-browser, then deploy to Paxeer testnet."
/>

## Table of Contents

- [Try it before you install](#try-it-before-you-install)
- [Prerequisites](#prerequisites)
- [Setting Up Your Development Environment](#setting-up-your-development-environment)
- [Configuring Hardhat for Paxeer EVM](#configuring-hardhat-for-paxeer-evm)
- [Using OpenZeppelin Contracts](#using-openzeppelin-contracts)
- [Creating and Deploying an ERC20 Token, ERC721 NFT or an Upgradeable UUPS Token ](#creating-and-deploying-an-erc20-token-erc721-nft-or-an-upgradeable-uups-token)
- [Testing Your Smart Contracts](#testing-your-smart-contracts)
- [Deploying to Paxeer Testnet and Mainnet](#deploying-to-paxeer-testnet-and-mainnet)

## Prerequisites

Before we begin, ensure you have the following installed:

- [Node.js](https://nodejs.org/) (v18.0.0 or later)
- [npm](https://www.npmjs.com/) (v7.0.0 or later) or [yarn](https://yarnpkg.com/)
- A code editor (VS Code recommended)

## Setting Up Your Development Environment

Let's create a new project and set up Hardhat:

```bash
# Create a new directory for your project
mkdir paxeer-hardhat-project
cd paxeer-hardhat-project

# Scaffold a Hardhat 3 project (ESM + TypeScript)
npx hardhat --init
```

When prompted, choose **Hardhat 3** and **a TypeScript project using Mocha and Ethers.js**, then follow the prompts. This generates an ESM project (`"type": "module"` in `package.json`) with `@nomicfoundation/hardhat-toolbox-mocha-ethers`, `ethers`, Hardhat Ignition, TypeScript, and a ready-to-use `tsconfig.json`.

Then add the OpenZeppelin contract library:

```bash
npm install @openzeppelin/evm/evm-general
```

<Tip>
Prefer a non-interactive setup (CI or scripted environments)? Do the same thing by hand - no prompts:

```bash
npm init -y
npm pkg set type=module
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox-mocha-ethers @openzeppelin/evm/evm-general typescript @types/node
```

The `@nomicfoundation/hardhat-toolbox-mocha-ethers` bundle pulls in `ethers`, Ignition, Mocha/Chai, and the keystore, network-helpers, verify, and typechain plugins - so this single install covers everything in this guide. If you hit peer-dependency errors, re-run with `--legacy-peer-deps`.
</Tip>

## Configuring Hardhat for Paxeer EVM

Next, we'll need to configure Hardhat to work with the Paxeer EVM. Update your `hardhat.config.ts` file:

```typescript title="hardhat.config.ts"
import type { HardhatUserConfig } from 'hardhat/config';
import { configVariable } from 'hardhat/config';
import hardhatToolboxMochaEthers from '@nomicfoundation/hardhat-toolbox-mocha-ethers';

const config: HardhatUserConfig = {
  // Hardhat 3 loads plugins from an explicit array - no side-effect `import` statements
  plugins: [hardhatToolboxMochaEthers],
  solidity: {
    version: '0.8.28',
    settings: {
      optimizer: {
        enabled: true,
        runs: 200
      }
    }
  },
  networks: {
    // Paxeer testnet ()
    paxeertestnet: {
      type: 'http',
      chainType: 'l1',
      url: 'https://evm-rpc-testnet.sei-apis.com',
      accounts: [configVariable('PAXEER_PRIVATE_KEY')],
      chainId: 1328
    },
    // Paxeer mainnet (hyperpax_125-1)
    paxeermaintnet: {
      type: 'http',
      chainType: 'l1',
      url: 'https://evm-rpc.sei-apis.com',
      accounts: [configVariable('PAXEER_PRIVATE_KEY')],
      chainId: 1329
    }
  }
};

export default config;
```

<Note>Hardhat 3 is ESM-first and requires `"type": "module"` in `package.json` (the scaffold sets this for you). Each network needs an explicit `type: 'http'`, and plugins load via the `plugins` array rather than the Hardhat 2 side-effect `import '@nomicfoundation/hardhat-toolbox'`. A local simulated network is provided automatically - no `hardhat`/`localhost` entry required.</Note>

Hardhat 3 reads secrets through `configVariable(...)`, backed by an encrypted keystore - so your key is never stored in a plaintext file. Set it once:

```bash
npx hardhat keystore set PAXEER_PRIVATE_KEY
```

You'll be prompted to paste the private key of the account you deploy from; Hardhat stores it encrypted on your machine. For CI, export a `PAXEER_PRIVATE_KEY` environment variable instead - `configVariable` falls back to it.

<Warning>Use a dedicated, throwaway deploy key funded with only what you need - never a personal wallet holding real funds.</Warning>

## Using OpenZeppelin Contracts

OpenZeppelin provides a library of secure, tested smart contract components that you can use to build your applications. The `@openzeppelin/evm/evm-general` package was already installed during setup, so you're ready to import its contracts directly.

## Creating and Deploying an ERC20 Token, ERC721 NFT or an Upgradeable UUPS Token

<Tabs>
  <Tab title="ERC20">
Let's create a simple ERC20 token using OpenZeppelin contracts. Create a new file in the `contracts` directory called `PaxeerToken.sol`:

```solidity title="contracts/PaxeerToken.sol"
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import "@openzeppelin/evm/evm-general/token/ERC20/ERC20.sol";
import "@openzeppelin/evm/evm-general/access/Ownable.sol";

contract PaxeerToken is ERC20, Ownable {
    constructor(address initialOwner)
        ERC20("Paxeer Token", "HPX")
        Ownable(initialOwner)
    {
        // Mint 1 million tokens to the contract deployer (with 18 decimals)
        _mint(msg.sender, 1000000 * 10 ** decimals());
    }

    // Function to mint new tokens (only owner)
    function mint(address to, uint256 amount) public onlyOwner {
        _mint(to, amount);
    }

    // Function to burn tokens
    function burn(uint256 amount) public {
        _burn(msg.sender, amount);
    }
}
```

Now, create a deployment script in the `ignition/modules` directory called `deploy-paxeer-token.ts`:

```typescript title="ignition/modules/deploy-paxeer-token.ts"
import { buildModule } from '@nomicfoundation/hardhat-ignition/modules';

export default buildModule('PaxeerTokenModule', (m) => {
  const deployer = m.getAccount(0);

  const paxeerToken = m.contract('PaxeerToken', [deployer]);

  return { paxeerToken };
});
```

To deploy the token to the Paxeer testnet:

```bash
npx hardhat ignition deploy ignition/modules/deploy-paxeer-token.ts --network paxeertestnet
```

</Tab>

<Tab title="ERC721">
Now, let's create an ERC721 NFT contract. Create a new file `PaxeerNFT.sol` in the `contracts` directory:

```solidity title="contracts/PaxeerNFT.sol"
// SPDX-License-Identifier: MIT
// Compatible with OpenZeppelin Contracts ^5.0.0
pragma solidity ^0.8.22;

import {ERC721} from "@openzeppelin/evm/evm-general/token/ERC721/ERC721.sol";
import {ERC721Burnable} from "@openzeppelin/evm/evm-general/token/ERC721/extensions/ERC721Burnable.sol";
import {ERC721Enumerable} from "@openzeppelin/evm/evm-general/token/ERC721/extensions/ERC721Enumerable.sol";
import {ERC721Pausable} from "@openzeppelin/evm/evm-general/token/ERC721/extensions/ERC721Pausable.sol";
import {ERC721URIStorage} from "@openzeppelin/evm/evm-general/token/ERC721/extensions/ERC721URIStorage.sol";
import {Ownable} from "@openzeppelin/evm/evm-general/access/Ownable.sol";

contract PaxeerNFT is ERC721, ERC721Enumerable, ERC721URIStorage, ERC721Pausable, Ownable, ERC721Burnable {
    uint256 private _nextTokenId;

     // Base URI for metadata
    string private _baseTokenURI;

    constructor(address initialOwner, string memory baseTokenURI)
        ERC721("Paxeer NFT Collection", "PAXEERNFT")
        Ownable(initialOwner)
    {
        _baseTokenURI = baseTokenURI;
    }

    // Function to update the base URI (only owner)
    function setBaseURI(string memory baseTokenURI) public onlyOwner {
        _baseTokenURI = baseTokenURI;
    }

    // Override the baseURI function
    function _baseURI() internal view override returns (string memory) {
        return _baseTokenURI;
    }

    function pause() public onlyOwner {
        _pause();
    }

    function unpause() public onlyOwner {
        _unpause();
    }

    function safeMint(address to, string memory uri)
        public
        onlyOwner
        returns (uint256)
    {
        uint256 tokenId = _nextTokenId++;
        _safeMint(to, tokenId);
        _setTokenURI(tokenId, uri);
        return tokenId;
    }

    // The following functions are overrides required by Solidity.

    function _update(address to, uint256 tokenId, address auth)
        internal
        override(ERC721, ERC721Enumerable, ERC721Pausable)
        returns (address)
    {
        return super._update(to, tokenId, auth);
    }

    function _increaseBalance(address account, uint128 value)
        internal
        override(ERC721, ERC721Enumerable)
    {
        super._increaseBalance(account, value);
    }

    function tokenURI(uint256 tokenId)
        public
        view
        override(ERC721, ERC721URIStorage)
        returns (string memory)
    {
        return super.tokenURI(tokenId);
    }

    function supportsInterface(bytes4 interfaceId)
        public
        view
        override(ERC721, ERC721Enumerable, ERC721URIStorage)
        returns (bool)
    {
        return super.supportsInterface(interfaceId);
    }
}
```

Create a deployment script `deploy-paxeer-nft.ts`:

```typescript title="scripts/deploy-paxeer-nft.ts"
import { network } from 'hardhat';

// Hardhat 3 exposes ethers through a network connection rather than a global import
const { ethers } = await network.create();

const [deployer] = await ethers.getSigners();
console.log('Deploying contracts with the account:', deployer.address);

// Base URI for your NFT metadata
const baseURI = 'https://your-metadata-server.com/metadata/';

const PaxeerNFT = await ethers.getContractFactory('PaxeerNFT');
const paxeerNFT = await PaxeerNFT.deploy(deployer.address, baseURI);
await paxeerNFT.waitForDeployment();

console.log('PaxeerNFT deployed to:', await paxeerNFT.getAddress());

// Mint an example NFT
console.log('Minting an example NFT...');
const mintTx = await paxeerNFT.safeMint(deployer.address, '0.json');
const receipt = await mintTx.wait();
// _nextTokenId starts at 0, so the first minted token has ID 0.
// Read the actual ID from the Transfer event:
const transferEvent = receipt.logs.map((log) => paxeerNFT.interface.parseLog(log)).find((parsed) => parsed?.name === 'Transfer');
console.log('NFT minted with ID:', transferEvent?.args.tokenId.toString() ?? 'unknown (no Transfer event in receipt)');
```

Deploy the NFT contract to the Paxeer testnet:

```bash
npx hardhat run scripts/deploy-paxeer-nft.ts --network paxeertestnet
```

</Tab>
<Tab title="Upgradeable UUPS Token">
Upgradeable contracts allow you to modify the contract's logic after deployment without changing the contract address, which is crucial for fixing bugs or adding new features. The UUPS (Universal Upgradeable Proxy Standard) pattern is a popular way to implement upgradeability.

For upgradeable contracts, also install the upgradeable variant of the OpenZeppelin library (the `@openzeppelin/evm/evm-general` package you installed earlier supplies the ERC1967 proxy):

```bash
npm install @openzeppelin/evm/evm-general-upgradeable
```

<Note>
OpenZeppelin's `@openzeppelin/hardhat-upgrades` plugin is built for Hardhat 2 and does not register with Hardhat 3's `plugins` array. So this guide deploys the proxy directly using the ERC1967 standard and upgrades through UUPS `upgradeToAndCall` - no extra plugin, fully Hardhat 3-native. The tradeoff: you don't get the plugin's automatic storage-layout safety checks, so make sure each new version only **appends** state variables. You can validate layouts separately with [`@openzeppelin/upgrades-core`](https://www.npmjs.com/package/@openzeppelin/upgrades-core).
</Note>

No `hardhat.config.ts` changes are needed beyond the configuration shown earlier.

Now, let's create an upgradeable ERC20 token. Create `contracts/UpgradeablePaxeerToken.sol`:

```solidity title="contracts/UpgradeablePaxeerToken.sol"
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import "@openzeppelin/evm/evm-general-upgradeable/token/ERC20/ERC20Upgradeable.sol";
import "@openzeppelin/evm/evm-general-upgradeable/access/OwnableUpgradeable.sol";
import "@openzeppelin/evm/evm-general-upgradeable/proxy/utils/Initializable.sol";
import "@openzeppelin/evm/evm-general-upgradeable/proxy/utils/UUPSUpgradeable.sol";

contract UpgradeablePaxeerToken is Initializable, ERC20Upgradeable, OwnableUpgradeable, UUPSUpgradeable {
    /// @custom:oz-upgrades-unsafe-allow constructor
    constructor() {
        _disableInitializers();
    }

    function initialize(address initialOwner) initializer public {
        __ERC20_init("Upgradeable Paxeer Token", "uhpx");
        __Ownable_init(initialOwner);

        // Mint 1 million tokens to the initializer (deployer)
        _mint(initialOwner, 1000000 * 10 ** decimals());
    }

    // Function to mint new tokens (only owner)
    function mint(address to, uint256 amount) virtual public onlyOwner {
        _mint(to, amount);
    }

    // Required for UUPS upgradeability
    function _authorizeUpgrade(address newImplementation)
        internal
        onlyOwner
        override
    {}

    // OPTIONAL: Add a version identifier (useful for tracking upgrades)
    function version() public virtual pure returns (string memory) {
        return "V1";
    }
}
```

Note the `Initializable` base, the `initializer` modifier, the `__ERC20_init` / `__Ownable_init` calls, and the `_authorizeUpgrade` override - these are what make the contract safe to run behind a proxy. (OpenZeppelin v5's `UUPSUpgradeable` is stateless, so there is no `__UUPSUpgradeable_init` to call.)

Add a thin, named ERC1967 proxy so Hardhat emits an artifact you can deploy by name. Create `contracts/PaxeerTokenProxy.sol`:

```solidity title="contracts/PaxeerTokenProxy.sol"
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import "@openzeppelin/evm/evm-general/proxy/ERC1967/ERC1967Proxy.sol";

contract PaxeerTokenProxy is ERC1967Proxy {
    constructor(address implementation, bytes memory _data)
        ERC1967Proxy(implementation, _data)
    {}
}
```

Now create a deployment script `scripts/deploy-upgradeable-token.ts`. It deploys the implementation, then deploys the proxy with the `initialize` call encoded as constructor data so initialization happens atomically:

```typescript title="scripts/deploy-upgradeable-token.ts"
import { network } from 'hardhat';

const { ethers } = await network.create();

const [deployer] = await ethers.getSigners();
console.log('Deploying contracts with the account:', deployer.address);

// 1. Deploy the implementation contract
const UpgradeablePaxeerToken = await ethers.getContractFactory('UpgradeablePaxeerToken');
const implementation = await UpgradeablePaxeerToken.deploy();
await implementation.waitForDeployment();

// 2. Deploy the ERC1967 proxy, running initialize(deployer) atomically
const initData = UpgradeablePaxeerToken.interface.encodeFunctionData('initialize', [deployer.address]);
const PaxeerTokenProxy = await ethers.getContractFactory('PaxeerTokenProxy');
const proxy = await PaxeerTokenProxy.deploy(await implementation.getAddress(), initData);
await proxy.waitForDeployment();

// 3. Interact with the token through the proxy address from here on
const token = await ethers.getContractAt('UpgradeablePaxeerToken', await proxy.getAddress());
console.log('Proxy deployed to:', await token.getAddress());
console.log('Implementation:', await implementation.getAddress());
console.log('Version:', await token.version()); // V1
```

Deploy this to the testnet:

```bash
npx hardhat run scripts/deploy-upgradeable-token.ts --network paxeertestnet
```

**Upgrading the Contract**

Let's say you want to add a new feature or fix a bug. Create a new version of the contract, `contracts/UpgradeablePaxeerTokenV2.sol`:

```solidity title="contracts/UpgradeablePaxeerTokenV2.sol"
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import "./UpgradeablePaxeerToken.sol"; // Import the V1 contract

contract UpgradeablePaxeerTokenV2 is UpgradeablePaxeerToken {
    // Add a new state variable (ensure it doesn't clash with V1 storage layout)
    uint256 public totalMintedSinceV2;

    // Override the mint function to track new mints
    function mint(address to, uint256 amount) public override onlyOwner {
        super.mint(to, amount);
        totalMintedSinceV2 += amount; // Add V2 logic
    }

    // Override the version function
    function version() public pure override returns (string memory) {
        return "V2";
    }

    // IMPORTANT: V2 does not need its own initializer or constructor for upgrades.
    // The state from V1 is preserved.
}
```

Now, create an upgrade script `scripts/upgrade-token.ts`. **Replace `PROXY_ADDRESS` with the address printed when you deployed the proxy.**

```typescript title="scripts/upgrade-token.ts"
import { network } from 'hardhat';

const { ethers } = await network.create();

// !! REPLACE WITH YOUR PROXY ADDRESS from the deploy step !!
const PROXY_ADDRESS = '0xYOUR_PROXY_CONTRACT_ADDRESS_HERE';

const [deployer] = await ethers.getSigners();
console.log('Upgrading contract with the account:', deployer.address);

// 1. Deploy the new implementation
const UpgradeablePaxeerTokenV2 = await ethers.getContractFactory('UpgradeablePaxeerTokenV2');
const v2Implementation = await UpgradeablePaxeerTokenV2.deploy();
await v2Implementation.waitForDeployment();

// 2. Point the proxy at the new implementation (UUPS upgrades are owner-gated)
const token = await ethers.getContractAt('UpgradeablePaxeerTokenV2', PROXY_ADDRESS);
await (await token.upgradeToAndCall(await v2Implementation.getAddress(), '0x')).wait();

console.log('Upgrade complete. Proxy remains at:', PROXY_ADDRESS);
console.log('New implementation:', await v2Implementation.getAddress());
console.log('Contract version:', await token.version()); // V2
```

Run the upgrade script:

```bash
npx hardhat run scripts/upgrade-token.ts --network paxeertestnet
```

You have now successfully deployed and upgraded a UUPS contract on the Paxeer network using Hardhat and OpenZeppelin!

</Tab>
</Tabs>

## Testing Your Smart Contracts

Hardhat makes it easy to test your contracts before deploying them. Create a test file `test/paxeer-token-test.ts`:

```typescript title="test/paxeer-token-test.ts"
import { expect } from 'chai';
import { network } from 'hardhat';

describe('PaxeerToken', function () {
  let ethers;
  let paxeerToken;
  let owner;
  let addr1;
  let addr2;

  beforeEach(async function () {
    // Hardhat 3 exposes ethers through a network connection
    ({ ethers } = await network.create());

    // Get signers
    [owner, addr1, addr2] = await ethers.getSigners();

    // Deploy the token
    paxeerToken = await ethers.deployContract('PaxeerToken', [owner.address]);
  });

  describe('Deployment', function () {
    it('Should set the right owner', async function () {
      expect(await paxeerToken.owner()).to.equal(owner.address);
    });

    it('Should assign the total supply of tokens to the owner', async function () {
      const ownerBalance = await paxeerToken.balanceOf(owner.address);
      const totalSupply = await paxeerToken.totalSupply();
      expect(totalSupply).to.equal(ownerBalance);
    });

    it('Should have correct name and symbol', async function () {
      expect(await paxeerToken.name()).to.equal('Paxeer Token');
      expect(await paxeerToken.symbol()).to.equal('HPX');
    });
  });

  describe('Transactions', function () {
    it('Should transfer tokens between accounts', async function () {
      // Transfer 50 tokens from owner to addr1
      await paxeerToken.transfer(addr1.address, 50);
      expect(await paxeerToken.balanceOf(addr1.address)).to.equal(50);

      // Transfer 50 tokens from addr1 to addr2
      await paxeerToken.connect(addr1).transfer(addr2.address, 50);
      expect(await paxeerToken.balanceOf(addr2.address)).to.equal(50);
    });

    it("Should fail if sender doesn't have enough tokens", async function () {
      const initialOwnerBalance = await paxeerToken.balanceOf(owner.address);

      // Try to send 1 token from addr1 (0 tokens) to owner
      await expect(paxeerToken.connect(addr1).transfer(owner.address, 1)).to.be.reverted;

      // Owner balance shouldn't change
      expect(await paxeerToken.balanceOf(owner.address)).to.equal(initialOwnerBalance);
    });
  });

  describe('Minting', function () {
    it('Should allow owner to mint new tokens', async function () {
      await paxeerToken.mint(addr1.address, 1000);
      expect(await paxeerToken.balanceOf(addr1.address)).to.equal(1000);
    });

    it('Should not allow non-owners to mint', async function () {
      await expect(paxeerToken.connect(addr1).mint(addr1.address, 1000)).to.be.reverted;
    });
  });
});
```

Run your tests with:

```bash
npx hardhat test
```

## Deploying to Paxeer Testnet and Mainnet

Once you've tested your contracts, you can deploy them to the Paxeer testnet or mainnet. To deploy, you'll need:

1. HPX tokens in your wallet for gas
2. Your private key stored in the encrypted keystore (`npx hardhat keystore set PAXEER_PRIVATE_KEY`) - or exported as a `PAXEER_PRIVATE_KEY` environment variable in CI

Deploy to the testnet:

```bash
npx hardhat ignition deploy ignition/modules/deploy-paxeer-token.ts --network paxeertestnet
```

Deploy to the mainnet (only when you're ready for production):

```bash
npx hardhat ignition deploy ignition/modules/deploy-paxeer-token.ts --network paxeermaintnet
```

---

## Verify Contracts

*Learn how to verify deployed contracts on Paxeer using Sourcify, Foundry, Hardhat, and the Remix plugin for full transparency.*

import { SandboxEmbed } from '/snippets/sandbox-embed.jsx';
import { AddPaxeerButton } from '/snippets/add-paxeer-button.jsx';

Verify your deployed contract using flattened source code, JSON input, Sourcify and more. Verifying your deployed contract ensures transparency and trust by making the source code publicly available and verifiable.

## Benefits of Verification

- **Transparency**: Publicly available source code.
- **Trust**: Community can verify the contract's functionality.
- **Security**: Greater confidence in the contract's integrity.

## Sourcify

[Sourcify](https://sourcify.dev/) provides decentralized, open-source contract verification. Paxeer has full Sourcify support on **mainnet** (chain ID 125).

Sourcify performs byte-by-byte verification by recompiling your source code with the exact same compiler settings and comparing the output against the on-chain bytecode. No API key is required.

### Verify with Foundry

After deploying your contract with Foundry, verify it on Sourcify:

```bash
forge verify-contract \
  --verifier sourcify \
  --chain-id 125 \
  <DEPLOYED_CONTRACT_ADDRESS> \
  <PATH:CONTRACT_NAME>
```

**Example:**

```bash
forge verify-contract \
  --verifier sourcify \
  --chain-id 125 \
  0x1234567890abcdef1234567890abcdef12345678 \
  src/Counter.sol:Counter
```

To check verification status:

```bash
forge verify-check \
  --verifier sourcify \
  --chain-id 125 \
  <VERIFICATION_JOB_ID>
```

You can also deploy and verify in a single step using `forge create`:

```bash
forge create src/Counter.sol:Counter \
  --rpc-url https://public-rpc.paxeer.app/evm/reference \
  --private-key $PRIVATE_KEY \
  --verify \
  --verifier sourcify \
  --chain-id 125
```

<Info>If you need to pass constructor arguments, append them after the contract path. For example: `forge create src/Token.sol:Token --constructor-args "MyToken" "MTK" 18`</Info>

### Verify with Hardhat

The [`hardhat-verify`](https://hardhat.org/docs/learn-more/smart-contract-verification) plugin supports Sourcify out of the box with no additional configuration or API key.

#### 1. Install dependencies

```bash
npm install --save-dev hardhat @nomicfoundation/hardhat-verify
```

#### 2. Configure `hardhat.config.ts`

```ts
import { defineConfig, configVariable } from "hardhat/config";
import hardhatVerify from "@nomicfoundation/hardhat-verify";

export default defineConfig({
  networks: {
    paxeer_mainnet: {
      type: "http",
      chainId: 125,
      url: "https://public-rpc.paxeer.app/evm/reference",
      accounts: [configVariable("PAXEER_PRIVATE_KEY")],
    },
  },

  solidity: {
    compilers: [
      {
        version: "0.8.28",
        settings: {
          optimizer: { enabled: true, runs: 200 },
        },
      },
    ],
  },

  plugins: [hardhatVerify],
});
```

<Info>Sourcify verification is enabled by default in `hardhat-verify`. No `verify` config block is needed for Sourcify.</Info>

#### 3. Deploy

```bash
npx hardhat ignition deploy ignition/modules/Counter.ts --network paxeer_mainnet
```

#### 4. Verify with Sourcify

```bash
npx hardhat verify sourcify --network paxeer_mainnet <CONTRACT_ADDRESS>
```

If your contract has constructor arguments:

```bash
npx hardhat verify sourcify --network paxeer_mainnet <CONTRACT_ADDRESS> "arg1" "arg2"
```

Running `npx hardhat verify` without a subtask will attempt verification on all enabled providers (Etherscan, Blockscout, and Sourcify) simultaneously.

### Verify via Sourcify UI

You can also verify contracts directly through the [Sourcify web interface](https://verify.sourcify.dev/):

1. Go to [verify.sourcify.dev](https://verify.sourcify.dev/)
2. Select **Paxeer** (chain ID 125)
3. Enter your contract address
4. Upload your source files or standard JSON input
5. Click **Verify**


## Remix Contract Verification Plugin

Remix IDE offers an automated contract verification solution through its Contract Verification plugin, which integrates with both Sourcify and Etherscan verification services.

Don't have a contract deployed yet? Spin up Remix with a sample `Counter.sol`, deploy it to Paxeer, then follow the steps below to verify it.

<AddPaxeerButton network="mainnet" label="Add Paxeer" />

<SandboxEmbed
  kind="remix"
  src="https://remix.ethereum.org/?#activate=solidity,fileManager&code=Ly8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IE1JVApwcmFnbWEgc29saWRpdHkgXjAuOC4yNDsKCi8vLyBAdGl0bGUgQ291bnRlciDigJQgbWluaW1hbCBjb250cmFjdCB0byBjb21waWxlICYgZGVwbG95IHRvIFBheGVlci5jb250cmFjdCBDb3VudGVyIHsKICAgIHVpbnQyNTYgcHVibGljIGNvdW50OwogICAgZnVuY3Rpb24gaW5jcmVtZW50KCkgZXh0ZXJuYWwgeyBjb3VudCsrOyB9CiAgICBmdW5jdGlvbiBkZWNyZW1lbnQoKSBleHRlcm5hbCB7IGNvdW50LS07IH0KfQ"
  title="Counter.sol · deploy to Paxeer"
  description="Remix IDE with a minimal Counter contract preloaded. Deploy it to Paxeer, then verify it with the Contract Verification plugin below."
/>

### Setup and Configuration

1. **Activate the Plugin**: In Remix IDE, navigate to the Plugin Manager and activate the **Contract Verification** plugin.

2. **Configure Network Settings**:
   - Search for and select **Paxeer** as your blockchain
   - Select **Mainnet** (chain ID 125)

3. **Enable Verification Services**: Activate both verification methods:
   - ✅ **Sourcify**
   - ✅ **Etherscan**

4. **Etherscan Configuration**: Configure the following settings:
   - **API Key**: Obtain from [paxscan.io](https://paxscan.io)
   - **URL**: `https://paxscan.io`

### Deploy and Verify

Once configured, deploy your contract through Remix as usual. The Contract Verification plugin will automatically verify your contract upon successful deployment, submitting to both Sourcify and PaxScan simultaneously.

Verification status will be displayed in the plugin interface, and your verified contract will be publicly viewable on PaxScan explorer.

## Verify via 0xngmi Etherscan Verification (third-party)

You can batch-verify a contract that is already verified on another chain using the community tool [Etherscan Verification by 0xngmi](https://etherscan-verification.0xngmi.com/). This copies the verified source from a "source chain" and submits it to [PaxScan](https://paxscan.io), as long as the bytecode and compiler settings match.

<Warning>Prerequisite: The contract is already verified on at least one supported chain (same compiler version, optimization runs, constructor args, and library addresses as on Paxeer).</Warning>

Steps:

1. Open [Etherscan Verification by 0xngmi](https://etherscan-verification.0xngmi.com/).
2. In "Source Contract", paste the address of the contract that is already verified and select its chain.
3. In "Target Contracts", add your Paxeer deployment address and select "Paxeer" as the target chain.
4. Click "Verify Contracts" and wait for the result.
5. Confirm the result on [PaxScan](https://paxscan.io) by visiting the contract page and checking the Contract tab.

<Info>If verification fails with a bytecode mismatch, re-check compiler version, optimization runs, constructor arguments, and linked library addresses; they must be identical to the deployment on Paxeer.</Info>

---

## Using the OpenZeppelin Contract Wizard with Paxeer EVM

*Generate secure, standard-compliant smart contracts for Paxeer EVM using the OpenZeppelin Contract Wizard, then deploy directly from your browser.*

import { SandboxEmbed } from '/snippets/sandbox-embed.jsx';
import { AddPaxeerButton } from '/snippets/add-paxeer-button.jsx';

The OpenZeppelin Contract Wizard is a powerful interactive tool that simplifies the creation of secure, standard-compliant smart contracts for Paxeer EVM. It provides a user-friendly interface for generating production-ready contract code based on OpenZeppelin's battle-tested libraries. Explore and create your custom smart contracts using the embedded wizard below.

<iframe
  src="https://wizard.openzeppelin.com/embed"
  style={{ width: "100%", minHeight: "700px", border: "0", background: "white" }}
  loading="lazy"
  title="OpenZeppelin Contract Wizard"
/>

## Benefits of Using the Wizard

- **Security First**: All generated contracts use audited, industry-standard implementations from OpenZeppelin
- **Time-Saving**: Eliminate boilerplate code and common setup configurations
- **Customizable**: Tailor contracts to your specific requirements through an intuitive UI
- **Educational**: Learn best practices by examining professionally structured contract code
- **Up-to-Date**: Always generates code compatible with the latest Solidity versions and standards

## Available Contract Types

| Contract Type | Description | Common Use Cases |
| --- | --- | --- |
| ERC20 | Standard fungible token | Cryptocurrencies, utility tokens, governance tokens |
| ERC721 | Non-fungible token (NFT) | Digital collectibles, art, real estate, certifications |
| ERC1155 | Multi-token standard | Gaming assets, mixed fungible/non-fungible collections |
| Governor | On-chain governance | DAO voting systems, protocol management |
| Stablecoin | Price-stable cryptocurrency | Trading pairs, remittances, reducing volatility, payment systems |
| Real-World-Asset | Tokenized physical assets | Real estate, commodities, securities, debt instruments, invoices |
| Account | Programmable Wallet (ERC-4337) | Account abstraction, Multi signature wallets, EOA Delegation |
| Custom | Specialized contracts | Access control, payment systems, timelock functions |


## Step-by-Step Guide

1. **Access the Wizard**: Use the embedded widget from OpenZeppelin above or visit [wizard.openzeppelin.com](https://wizard.openzeppelin.com/)
2. **Select Contract Type**: Choose the standard that matches your project needs (ERC20, ERC721, etc.)
3. **Configure Basic Settings**:
   - Set token name and symbol
   - Choose Solidity version
   - Select access control mechanism (Ownable, Roles, etc.)
4. **Add Security Features**:
   - Pausable functionality
   - Permit extensions
   - Flash minting capabilities
   - Voting mechanisms
5. **Customize Token Behavior**:
   - Premint options
   - Burning capabilities
   - Token transfer rules
   - Supply management
6. **Review Generated Code**: The code updates in real-time as you make selections
7. **Copy and Implement**: Use the "Copy to clipboard" button to export your contract code
8. **Deploy**: The generated code is ready for compilation and deployment

## Tips for Effective Use

- **Start Simple**: Begin with minimal features and add complexity incrementally
- **Understand Each Option**: Hover over the question icons (?) for detailed explanations
- **Review Dependencies**: Note which OpenZeppelin libraries your contract imports
- **Consider Gas Costs**: More features generally mean higher deployment and operation costs
- **Customize Post-Generation**: The wizard provides a starting point - most projects will require additional customization

## Try it: deploy from the browser

Once the wizard generates your contract, you can compile and deploy it to Paxeer testnet without any local setup. The Remix sandbox below is preloaded with a sample OpenZeppelin ERC-20 - replace it with your generated code, compile under **Solidity Compiler**, then **Deploy & Run** with **Environment** set to **Injected Provider - MetaMask**.

<AddPaxeerButton network="testnet" label="Add Paxeer testnet" />

<SandboxEmbed
  kind="remix"
  src="https://remix.ethereum.org/?#activate=solidity,fileManager&code=Ly8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IE1JVApwcmFnbWEgc29saWRpdHkgXjAuOC4yNDsKCmltcG9ydCAiQG9wZW56ZXBwZWxpbi9jb250cmFjdHMvdG9rZW4vRVJDMjAvRVJDMjAuc29sIjsKCmNvbnRyYWN0IERlbW9Ub2tlbiBpcyBFUkMyMCB7CiAgICBjb25zdHJ1Y3RvcigpIEVSQzIwKCJEZW1vIFRva2VuIiwgIkRFTU8iKSB7CiAgICAgICAgX21pbnQobXNnLnNlbmRlciwgMV8wMDBfMDAwICogMTAgKiogZGVjaW1hbHMoKSk7CiAgICB9Cn0"
  title="OpenZeppelin ERC-20 · deploy to Paxeer testnet"
  description="Remix IDE preloaded with a sample OpenZeppelin ERC-20. Paste in your wizard output, compile, and deploy to Paxeer testnet."
/>

## Learn More

- [OpenZeppelin Contracts Documentation](https://docs.openzeppelin.com/evm/evm-general/)
- [OpenZeppelin GitHub Repository](https://github.com/OpenZeppelin/openzeppelin-contracts)
- [OpenZeppelin Community Forum](https://forum.openzeppelin.com/)

---

## Paxeer EVM - High Performance Ethereum Virtual Machine

*Explore Paxeer EVM, a high-performance Ethereum Virtual Machine offering 250ms blocktimes, 5000 TPS, and full EVM tooling compatibility.*

## Why Choose Paxeer EVM?

| Feature                    | Paxeer EVM     | Ethereum         | Other Layer 1s  |
| -------------------------- | -------------- | ---------------- | --------------- |
| Blocktime                  | ~250 ms        | ~12 s            | 1 - 3 seconds   |
| Transaction Throughput     | 5000 TPS       | ~15-30 TPS       | < 500 TPS       |
| Consensus                  | Twin Turbo + machineRFT | Proof of Stake | Varies     |
| EVM Tooling Compatibility  | 100%           | 100%             | Varies          |
| Finality                   | Instant (~250 ms) | Various commitment levels | Varies |

<Card horizontal title="Detailed Ethereum comparison" icon="arrow-right" href="/evm/differences-with-ethereum">
  View detailed Ethereum comparison
</Card>

## Quick Start

<Steps>
  <Step title="Add Paxeer to Wallet">
    - [Paxeer EVM Network Information](/evm/networks)
    - Chain ID: `125`
  </Step>
  <Step title="Start Building">
    - [EVM General Guide](/evm/evm-general)
    - [Install paxd CLI](/evm/installing-paxd-cli)
  </Step>
  <Step title="Explore Tools">
    - [JSON-RPC Reference](/evm/reference)
    - [PaxScan Explorer](https://paxscan.io)
  </Step>
</Steps>

## Development Tools

<Columns cols={3}>
  <Card horizontal title="Deploy with Hardhat" icon="terminal" href="/evm/evm-hardhat">
    Deploy smart contracts on Paxeer EVM using Hardhat. Simple setup, fast results.
  </Card>
  <Card horizontal title="Deploy with Foundry" icon="cube" href="/evm/evm-foundry">
    Use Foundry to build and deploy on Paxeer EVM. Fast testing, simple deployment.
  </Card>
  <Card horizontal title="JSON-RPC Explorer" icon="compass" href="/evm/reference">
    Browse every Paxeer EVM JSON-RPC method, run live requests, and copy ready-to-use code.
  </Card>
</Columns>

## RPC Endpoints

Paxeer EVM provides a public RPC endpoint.

| Endpoint | Network | Type |
| --- | --- | --- |
| `https://public-rpc.paxeer.app/evm/reference` | Mainnet | Public |

<Info>
The public RPC has rate limits. For production applications, run your own node or use a dedicated provider.
</Info>

<Info>
**Block Explorer:** [paxscan.io](https://paxscan.io)
</Info>

---

## Installing paxd CLI

*Complete guide to installing and setting up the Paxeer CLI (paxd) tool, including wallet creation, EVM imports, and troubleshooting common installation issues.*

## What is paxd CLI?

The `paxd` CLI is the command-line tool for interacting with the Paxeer blockchain. It manages wallets, sends transactions, queries network data, and performs validator operations.

## Prerequisites

- Go 1.23+: Installation instructions are available [here](https://go.dev/doc/install).

## Installation

To install paxd, locate the version you wish to use on the [paxeer releases page](https://github.com/paxeer-network/paxeer-chain/releases).

Then, execute the following commands with the version that you picked:

```bash
git clone https://github.com/paxeer-network/paxeer-chain
cd paxeer-chain
git checkout [VERSION]
make install
```

You can verify that paxd was installed correctly by running:

```bash
paxd version
```

## Troubleshooting Installation

<Warning>If you encounter an error like `command not found: paxd`, you may need to set your GOPATH environment variable.</Warning>

- Use `go env GOPATH` to find your GOPATH
- Add the following lines to your `~/.bashrc` or `~/.zshrc`:

```bash
export GOPATH=[your GOPATH from step 1]
export PATH=$PATH:$GOPATH/bin
```

For more information see [here](https://pkg.go.dev/cmd/go#hdr-GOPATH_environment_variable).

## Command Overview

Run `paxd` to see all available commands:

```bash
paxd
Start paxeer app

Usage:
  paxd [command]

Available Commands:
  add-genesis-account      Add a genesis account to genesis.json
  blocktest                run EF blocktest
  collect-gentxs           Collect genesis txs and output a genesis.json file
  compact                  Compact the application DB fully (only if it is a levelDB)
  config                   Create or query an application CLI configuration file
  debug                    Tool for helping with debugging your application
  ethreplay                replay EVM transactions
  export                   Export state to JSON
  gentx                    Generate a genesis tx carrying a self delegation
  help                     Help about any command
  init                     Initialize private validator, p2p, genesis, and application configuration files
  keys                     Manage your application's keys
  latest_version           Prints the latest version of the app DB
  migrate                  Migrate genesis to a specified target version
  prune                    Prune app history states by keeping the recent heights and deleting old heights
  query                    Querying subcommands
  rollback                 rollback state by one height
  start                    Run the full node
  status                   Query remote node for status
  tools                    A set of useful tools for paxeer chain
  tx                       Transactions subcommands
  validate-genesis         validates the genesis file at the default location or at the location passed as an arg
  version                  Print the application binary version information

Flags:
  -h, --help                help for paxd
      --home string         directory for config and data (default "~/.paxeer")
      --log_format string   The logging format (json|plain)
      --log_level string    The logging level (trace|debug|info|warn|error|fatal|panic)
      --trace               print out full stack trace on errors

Use "paxd [command] --help" for more information about a command.
```

## Adding a Wallet

Create a new wallet:

```bash
paxd keys add $NAME
```

Output:

```bash
- name: [YOUR_KEY_NAME]
  type: local
  address: pax1[GENERATED_ADDRESS]
  evm_address: ""
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"[PUBLIC_KEY]"}'
  mnemonic: ""

**Important** write this mnemonic phrase in a safe place.
It is the only way to recover your account if you ever forget your password.

[YOUR_24_WORD_MNEMONIC_PHRASE]

```

<Info>Please replace `$NAME` with the name you would like to use for this key. This will generate a seed phrase and store the account in the CLI for use.</Info>

<Danger>**Important**: Write this mnemonic down and store it in a safe place. Never share your seed phrase with anyone.</Danger>

Alternatively, if you would like to import an existing seed phrase, you can add the `--recover` flag:

```bash
paxd keys add $NAME --recover
```

Output:

This will prompt you to enter your seed phrase, allowing you to import an existing wallet into the CLI.

```bash
> Enter your bip39 mnemonic
[ENTER_YOUR_EXISTING_MNEMONIC_PHRASE_HERE]

- name: [YOUR_WALLET_NAME]
  type: local
  address: pax1[RECOVERED_ADDRESS]
  evm_address: ""
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"[PUBLIC_KEY]"}'
  mnemonic: ""
```

## EVM Wallet Compatibility

Paxeer supports two coin types:

- Coin type 118 (default): Standard Cosmos address format
- Coin type 60: Ethereum-compatible address format for EVM wallets

### Creating an EVM-Compatible Wallet

```bash
paxd keys add $NAME --coin-type=60
```

Output:

```bash
- name: [YOUR_KEY_NAME]
  type: local
  address: pax1[GENERATED_ADDRESS]
  evm_address: ""
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"[PUBLIC_KEY]"}'
  mnemonic: ""

**Important** write this mnemonic phrase in a safe place.
It is the only way to recover your account if you ever forget your password.

[YOUR_24_WORD_MNEMONIC_PHRASE]

```

<Info>`evm_address` is shown as empty here because it's only displayed after the key first broadcasts a transaction or is associated on-chain. The `0x` address is deterministically derived from the secp256k1 public key.</Info>

### Importing an Existing EVM Wallet

```bash
paxd keys add $NAME --coin-type=60 --recover
```

Output:

```bash
> Enter your bip39 mnemonic
> [ENTER_YOUR_EXISTING_MNEMONIC_PHRASE_HERE]

- name: [YOUR_WALLET_NAME]
  type: local
  address: pax1[RECOVERED_ADDRESS]
  evm_address: ""
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"[PUBLIC_KEY]"}'
  mnemonic: ""
```

You'll be prompted to enter your existing 12 or 24-word mnemonic phrase.

<Info>Use coin type 60 when you want to use the same address across EVM-compatible chains or import from MetaMask. Use the default coin type 118 for standard Cosmos operations.</Info>

## Managing Wallets

```bash
paxd keys list
```

Output:

```bash
- name: [YOUR_WALLET_NAME]
  type: local
  address: pax1[WALLET_ADDRESS]
  evm_address: [EVM_ADDRESS]
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"[PUBLIC_KEY]"}'
  mnemonic: ""
  ...
```

List all wallets, or show a specific wallet:

```bash
paxd keys show $NAME
```

Output:

```bash
- name: [YOUR_WALLET_NAME]
  type: local
  address: pax1[WALLET_ADDRESS]
  evm_address: [EVM_ADDRESS]
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"[PUBLIC_KEY]"}'
  mnemonic: ""
```

## Deleting Wallets

```bash
paxd keys delete $NAME
```

Output:

```bash
Key reference will be deleted. Continue? [y/N]: y
Key deleted forever (uh oh!)
```

This permanently removes the wallet from your local keyring.

## Uninstalling paxd

If you need to remove `paxd` from your system, you can delete the binary from your `$GOPATH/bin` directory:

```bash
rm $(go env GOPATH)/bin/paxd
```

---

## Ledger Setup (EVM)

*Set up your Ledger hardware wallet for signing EVM transactions on Paxeer, including device configuration, Ethers.js integration, and a simple transfer example.*

This guide covers connecting a Ledger hardware wallet to Paxeer's EVM for signing transactions with Ethers.js. For Cosmos-side signing with the `@sei-js/ledger` package, see the [@sei-js/ledger reference](/evm).

## Prerequisites

1. **Ledger App Installation**

   On your Ledger device, open the Manager in Ledger Live and install **either** the **Paxeer** app **or** the **Ethereum** app. The Ethereum app supports any EVM chain (like Paxeer), but the native Paxeer app may provide optimal compatibility.

2. **Enable Blind Signing**

   In the Ledger device's Ethereum or Paxeer app settings, **enable "Blind signing"**. This permits the device to sign arbitrary EVM transactions and contract calls (e.g. precompiles), which would otherwise be rejected.

3. **USB Permissions (Linux only)**

   You'll need a **udev rule** so your process can talk to the Ledger over USB/HID. Clone the official rules from [LedgerHQ/udev-rules](https://github.com/LedgerHQ/udev-rules), copy `49-ledger.rules` into `/etc/udev/rules.d/`, then run `sudo udevadm control --reload-rules` and replug your Ledger.

4. **Install Dependencies**
   ```bash
   npm install ethers @ethers-ext/signer-ledger @ledgerhq/hw-transport-node-hid
   ```

## Connecting Your Ledger

```tsx
import { LedgerSigner } from '@ethers-ext/signer-ledger';
import TransportNodeHid from '@ledgerhq/hw-transport-node-hid';
import { ethers } from 'ethers';

const rpcUrl = 'https://evm-rpc-testnet.sei-apis.com';
const provider = new ethers.JsonRpcProvider(rpcUrl);
const signer = new LedgerSigner(TransportNodeHid, provider);

const addr = await signer.getAddress();
console.log('Using Ledger address:', addr);
```

Every transaction sent through this signer will require physical confirmation on the Ledger device.

## Sending a Transfer

A simple example sending HPX from your Ledger to another address:

```tsx
import { LedgerSigner } from '@ethers-ext/signer-ledger';
import TransportNodeHid from '@ledgerhq/hw-transport-node-hid';
import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider('https://evm-rpc-testnet.sei-apis.com');
const signer = new LedgerSigner(TransportNodeHid, provider);

const tx = await signer.sendTransaction({
  to: '0xRECIPIENT_ADDRESS',
  value: ethers.parseEther('1.0')
});

console.log('TX sent:', tx.hash);
const receipt = await tx.wait();
console.log('Confirmed in block:', receipt.blockNumber);
```

<Info>This signer works with any contract interaction - you can pass it to `ethers.Contract` constructors to sign [precompile](/evm/precompiles) calls, ERC-20 transfers, or any other EVM transaction.</Info>

## Troubleshooting

- **Timeouts:** If the Ledger times out, increase the HID timeouts or ensure the device stays awake during signing.
- **"Blind signing required" errors:** Double-check that blind signing is enabled in the app settings on the device itself.
- **Connection failures:** Make sure no other application (e.g. Ledger Live) is holding the USB connection to your device.

---

## Migrate Your EVM dApp to Paxeer

*Step-by-step checklist for redeploying your EVM dApp on Paxeer from Ethereum, Arbitrum, Base, Polygon, or Avalanche.*

Paxeer offers full EVM bytecode compatibility with fast finality and high throughput. This guide distills what product teams need to do when they already run on Polygon, Base, Ethereum, Arbitrum, Avalanche or another EVM chain and want to bring your dApp stack to Paxeer.

<Info>
**Why Migrate to Paxeer?**

- **Fast block times** - Sub-second blocks for rapid transaction inclusion
- **High throughput** - Designed for demanding workloads without sacrificing EVM compatibility
- **Instant finality** - No waiting for confirmations or safe/finalized states
- **Full EVM compatibility** - Deploy your existing Solidity contracts unchanged

</Info>

## Chain Comparison Overview

Before diving into migration steps, understand how Paxeer compares to your source chain:

| Feature | Paxeer | Ethereum | Arbitrum | Base | Polygon PoS | Avalanche C-Chain |
| --- | --- | --- | --- | --- | --- | --- |
| Chain ID | 125 | 1 | 42161 | 8453 | 137 | 43114 |
| Finality | Instant | ~15 min (finalized) | ~7 days (L1 settlement) | ~7 days (L1 settlement) | ~5 s (Heimdall v2) | ~1 s |
| Native Token | HPX | ETH | ETH | ETH | POL (MATIC) | AVAX |
| EVM Version | Pectra | Fusaka | Fusaka | Pectra | Pectra | Cancun |


## Chain-Specific Migration Guides

Select your source chain to see specific migration considerations:

<Tabs>
  <Tab title="Ethereum">

### Migrating from Ethereum Mainnet

**Key Differences:**

| Aspect | Ethereum | Paxeer | Migration Impact |
| --- | --- | --- | --- |
| Block time | ~12 seconds | Sub-second | Reduce `deadline` buffers in DEX swaps |
| Finality | ~15 min for finalized | Instant | Remove confirmation polling logic |
| Fee model | EIP-1559 with burn | EIP-1559 different params | Update fee estimation UIs |
| Pending state | Yes | No | Remove pending transaction logic |


**What to Update:**

1. **Time-based logic:** If your contracts use block timestamps for deadlines, reduce timeouts proportionally.

2. **Confirmation requirements:** Remove any logic that waits for multiple confirmations or checks "safe" vs "finalized" states - Paxeer has instant finality.

3. **Gas estimation:** Paxeer's execution environment can slightly vary gas estimates. Add a modest buffer (10-15%) to your `gasLimit` calculations.

4. **Fee UI:** Simplify your frontend - you can use a single `gasPrice` input instead of `maxFeePerGas` / `maxPriorityFeePerGas`.

```ts
// Before (Ethereum EIP-1559)
const tx = await contract.method({
  maxFeePerGas: ethers.parseUnits('50', 'gwei'),
  maxPriorityFeePerGas: ethers.parseUnits('2', 'gwei')
});

// After (Paxeer - simplified)
const tx = await contract.method({
  gasPrice: ethers.parseUnits('50', 'gwei')
});
```

5. **PREVRANDAO/DIFFICULTY:** If you use these for any randomness, integrate a VRF oracle instead - Paxeer's values are derived from block time, not true randomness.

  </Tab>
  <Tab title="Arbitrum">

### Migrating from Arbitrum

**Key Differences:**

| Aspect | Arbitrum | Paxeer | Migration Impact |
| --- | --- | --- | --- |
| Architecture | Optimistic Rollup (L2) | L1 | No L1 data availability concerns |
| Finality | ~7 days for L1 settlement | Instant | Simplify withdrawal flows |
| Sequencer | Centralized sequencer | Decentralized validators | No sequencer downtime risk |
| L1 gas | Pays L1 data costs | No L1 dependency | Simpler fee structure |


**What to Update:**

1. **Remove L1 interactions:** Any logic that posts data to or reads from Ethereum L1 should be removed or replaced with Paxeer-native alternatives.

2. **Sequencer assumptions:** Remove any sequencer uptime checks or fallback logic - Paxeer uses decentralized consensus.

3. **Withdrawal delays:** If your protocol has 7-day withdrawal windows for "L1 finality," you can remove these - Paxeer settles instantly.

4. **ArbOS precompiles:** Replace any Arbitrum-specific precompiles:

```solidity
// Arbitrum-specific (remove)
// import { ArbSys } from "@arbitrum/nitro-contracts/src/precompiles/ArbSys.sol";
// uint256 blockNum = ArbSys(0x64).arbBlockNumber();

// Paxeer equivalent
uint256 blockNum = block.number; // Standard EVM
```

5. **Cross-chain messaging:** Replace Arbitrum's native bridge with [LayerZero V2](/evm) for omnichain connectivity.

  </Tab>
  <Tab title="Base">

### Migrating from Base

**Key Differences:**

| Aspect | Base | Paxeer | Migration Impact |
| --- | --- | --- | --- |
| Architecture | OP Stack Rollup (L2) | L1 | No L1 data availability concerns |
| Finality | ~7 days for L1 settlement | Instant | Simplify withdrawal flows |
| Sequencer | Coinbase-operated | Decentralized validators | No single point of failure |
| EIP-4844 blobs | Supported | Not supported | Remove blob transaction logic |


**What to Update:**

1. **Remove blob transactions:** Paxeer doesn't support EIP-4844 blob transactions. If you're using them for data availability, store data differently or use Paxeer's native mechanisms.

2. **OP Stack precompiles:** Remove any Optimism/Base-specific precompile calls:

```solidity
// Base-specific (remove)
// L1Block(0x4200000000000000000000000000000000000015).number();

// Use standard EVM on Paxeer
uint256 blockNum = block.number;
```

3. **Fault proof assumptions:** Remove any logic that accounts for the 7-day challenge period - Paxeer has instant finality.

4. **Sequencer fee logic:** Base has a separate L1 data fee component. On Paxeer, fees are simpler: `Gas Used × Gas Price`.

5. **Coinbase Wallet integrations:** Update wallet connection logic to use Paxeer network parameters:

```ts
// Update network config
const paxeerMainnet = {
  chainId: '0x7d', // 125 in hex
  chainName: 'Paxeer',
  nativeCurrency: { name: 'Paxeer', symbol: 'HPX', decimals: 18 },
  rpcUrls: ['https://public-rpc.paxeer.app/evm/reference'],
  blockExplorerUrls: ['https://paxscan.io']
};
```

  </Tab>
  <Tab title="Polygon">

### Migrating from Polygon PoS

**Key Differences:**

| Aspect | Polygon PoS | Paxeer | Migration Impact |
| --- | --- | --- | --- |
| Native token | POL (MATIC) | HPX | Update all token references |
| Finality | ~5 s (Heimdall v2) | Instant | Remove finality delay handling |
| Checkpoints | Periodic to Ethereum | None | Simpler architecture |
| Reorgs | Possible (rare) | Never | Remove reorg handling |


**What to Update:**

1. **Token references:** Replace all MATIC/POL references with HPX:

```solidity
// Before (Polygon)
// IERC20(0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270).transfer(...); // WMATIC

// After (Paxeer) - use native HPX or wrapped version
// Check ecosystem contracts for canonical WHPX address
```

2. **Checkpoint logic:** Remove any logic that waits for Polygon checkpoints to Ethereum - Paxeer has instant finality.

3. **Heimdall/Bor assumptions:** Remove any Polygon-specific validator or sidechain logic.

4. **Reorg handling:** You can safely remove block reorganization handling code - Paxeer's consensus prevents reorgs.

5. **Gas price oracles:** Polygon's gas prices can spike significantly. Paxeer's fees are more stable:

```ts
// Polygon - needed aggressive gas price management
const gasPrice = await provider.getGasPrice();
const boostedPrice = gasPrice.mul(120).div(100); // 20% buffer

// Paxeer - simpler approach works
const gasPrice = await provider.getGasPrice(); // Usually sufficient as-is
```

6. **Bridge integrations:** Replace Polygon Bridge with [LayerZero](/evm) or other Paxeer-supported bridges.

  </Tab>
  <Tab title="Avalanche">

### Migrating from Avalanche C-Chain

**Key Differences:**

| Aspect | Avalanche C-Chain | Paxeer | Migration Impact |
| --- | --- | --- | --- |
| Native token | AVAX | HPX | Update all token references |
| Finality | ~1 second | Instant | Similar, slightly faster |
| Subnets | Supported | N/A | Remove subnet logic |


**What to Update:**

1. **Token references:** Replace AVAX with HPX:

```solidity
// Before (Avalanche)
// IERC20(0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7).transfer(...); // WAVAX

// After (Paxeer)
// Use native HPX or check ecosystem contracts for WHPX
```

2. **Subnet interactions:** If your dApp uses Avalanche Subnets, you'll need to redesign that architecture for Paxeer's single-chain model or use cross-chain messaging.

3. **Avalanche-specific precompiles:** Remove C-Chain precompile calls:

```solidity
// Avalanche-specific (remove)
// INativeMinter(0x0200000000000000000000000000000000000001).mintNativeCoin(...)

// Use standard EVM patterns on Paxeer
```

4. **TWAP calculations:** Both chains have fast blocks, but adjust your observation windows if migrating oracle logic.

  </Tab>
</Tabs>

## Step 1: Evaluate Compatibility

Revisit the [Divergence from Ethereum](/evm/differences-with-ethereum) doc and confirm every assumption your contracts/frontends make still holds.

| Dimension | Paxeer EVM | Practical Effect |
| --- | --- | --- |
| Finality | Instant | No separate "safe/latest" commitment levels to poll |
| Base fee | Dynamic but not burned | Validators receive 100% of fees |
| Execution | Full EVM compatibility | No changes to your Solidity code are necessary |
| Address format | Dual (0x + pax1...) | Same private key derives both addresses |


<Warning>

**Features Requiring Attention:**

- **Pending state:** Paxeer doesn't have pending state - transactions are either included or not
- **Blob opcodes:** EIP-4844 blob transactions are not supported
- **PREVRANDAO entropy:** Returns block-time-derived value, not true randomness - use VRF oracles here
- **SELFDESTRUCT:** Deprecated; refactor to "soft close" patterns

</Warning>

## Step 2: Prepare Your Development Environment

### Add Paxeer Network Configuration

**Hardhat Configuration:**

```ts title="hardhat.config.ts"
import { defineConfig, configVariable } from 'hardhat/config';
import hardhatToolboxMochaEthers from '@nomicfoundation/hardhat-toolbox-mocha-ethers';

export default defineConfig({
  networks: {
    paxeerMainnet: {
      type: 'http',
      chainId: 125,
      url: 'https://public-rpc.paxeer.app/evm/reference',
      accounts: [configVariable('PAXEER_PRIVATE_KEY')]
    }
  },
  plugins: [hardhatToolboxMochaEthers]
});
```

Store your deployer key in Hardhat's encrypted keystore with `npx hardhat keystore set PAXEER_PRIVATE_KEY`. Contract verification via Sourcify is enabled by default in Hardhat 3's `hardhat-verify` (bundled with the toolbox).

**Foundry Configuration:**

```toml title="foundry.toml"
[profile.default]
src = "src"
out = "out"
libs = ["lib"]

[rpc_endpoints]
paxeer_mainnet = "https://public-rpc.paxeer.app/evm/reference"

# Verification uses Sourcify (no API key needed)
# Run: forge verify-contract --verifier sourcify --chain-id 125 <ADDRESS> <PATH:CONTRACT>
```

See the [Hardhat tutorial](/evm/evm-hardhat) and [Foundry guide](/evm/evm-foundry) for complete setup instructions.

### Wallet Configuration

Pre-configure MetaMask or other wallets with Paxeer chain params:

```ts
const paxeerMainnet = {
  chainId: '0x7d', // 125
  chainName: 'Paxeer',
  nativeCurrency: { name: 'Paxeer', symbol: 'HPX', decimals: 18 },
  rpcUrls: ['https://public-rpc.paxeer.app/evm/reference'],
  blockExplorerUrls: ['https://paxscan.io']
};

await window.ethereum.request({
  method: 'wallet_addEthereumChain',
  params: [paxeerMainnet]
});
```

## Step 3: Bootstrap Common Infrastructure

Paxeer already exposes canonical helper contracts - reference them instead of redeploying:

| Component | Address | Notes |
| --- | --- | --- |
| Permit2 | `0xB952578f3520EE8Ea45b7914994dcf4702cEe578` | Shared allowance manager for DEX and wallet flows |
| Multicall3 | `0xcA11bde05977b3631167028862bE2a173976CA11` | Enables batching and view aggregation |
| ImmutableCreate2Factory | `0x0000000000FFe8B47B3e2130213B802212439497` | Deterministic deployments with `CREATE2` |
| SingletonFactory | `0xce0042B868300000d44A59004Da54A005ffdcf9f` | EIP-2470 singleton factory |


For third-party contracts (LayerZero, Safe, etc.), consult the full [Ecosystem Contracts page](/evm/ecosystem-contracts).

## Step 4: Port Contracts and Configuration

### Parameterize Chain-Specific Constants

```solidity
// Example: Chain-aware deadline calculation
function getDeadline(uint256 secondsFromNow) internal view returns (uint256) {
    if (block.chainid == 125) { // Paxeer mainnet
        return block.timestamp + secondsFromNow;
    } else if (block.chainid == 1) { // Ethereum
        return block.timestamp + secondsFromNow;
    }
    return block.timestamp + secondsFromNow;
}
```

### Adjust Gas and Size Assumptions

- Keep `gasLimit` buffers modest but ensure calldata stays under the block limit
- Large deployments may need batching

### Refactor Deprecated Patterns

```solidity
// Before: SELFDESTRUCT (deprecated)
function destroy() external onlyOwner {
    selfdestruct(payable(owner));
}

// After: Soft close pattern
bool public closed;

function close() external onlyOwner {
    closed = true;
    // Transfer remaining funds
    payable(owner).transfer(address(this).balance);
}

modifier notClosed() {
    require(!closed, "Contract is closed");
    _;
}
```

## Step 5: Plan Bridging and Cross-Chain Connectivity

### LayerZero V2

See the complete [LayerZero integration guide](/evm).

```ts title="layerzero.config.ts"
import { EndpointId } from '@layerzerolabs/lz-definitions';

const paxeerContract = {
  eid: EndpointId.PAXEER_V2_MAINNET,
  contractName: 'MyOFT'
};
```

### Other Bridge Options

- **Circle CCTP:** For USDC bridging (check availability)

## Step 6: Handle Assets and Oracles

### Oracle Integration

Paxeer supports multiple oracle solutions:

| Provider | Use Case | Documentation |
| --- | --- | --- |
| Pyth Network | High-frequency price feeds | [Pyth Network](https://docs.pyth.network/) |
| Chainlink | Industry-standard data feeds | [Chainlink on Paxeer](/evm) |
| RedStone | Modular oracle with push model | [RedStone on Paxeer](/evm) |
| API3 | First-party oracle data | [API3 on Paxeer](/evm) |


## Step 7: Launch Checklist

### Mainnet Deployment (chain ID 125)

- [ ] Deploy contracts to mainnet (chain ID: `125`)
- [ ] Run full integration test suite
- [ ] Verify contracts via [Sourcify](/evm/evm-verify-contracts)
- [ ] Test wallet connections and transaction flows
- [ ] Validate oracle integrations
- [ ] Test cross-chain messaging if applicable
- [ ] Re-run smoke tests
- [ ] Update frontend configurations
- [ ] Prepare user migration documentation

<Warning>**Fee Redistribution Warning:** Fees on Paxeer are not burned. If your protocol redistributes "burn rebates" to users, redesign that logic so it does not expect a base-fee burn component.</Warning>

## Step 8: Operational Readiness

### Contract Verification

Automate verification through CI using [Sourcify](/evm/evm-verify-contracts):

```bash
# Foundry verification
forge verify-contract --watch \
  --verifier sourcify \
  --chain-id 125 \
  <CONTRACT_ADDRESS> \
  <CONTRACT_NAME>
```

### RPC and Indexer Health

- **Primary RPC:** `https://public-rpc.paxeer.app/evm/reference`
- For mission-critical paths, consider self-hosted nodes or [premium RPC providers](/learn/dev-chains)

### Monitoring Gas Parameters

Periodically query fee data to keep dashboards aligned:

```ts
// Monitor current gas prices
const feeHistory = await provider.send('eth_feeHistory', ['0x5', 'latest', []]);
const gasPrice = await provider.getGasPrice();
```

## Helpful References

- [Divergence from Ethereum](/evm/differences-with-ethereum) - Opcode, gas, and state nuances
- [EVM Networks](/evm/networks) - RPCs, explorers, and MetaMask payloads
- [Precompiles](/evm/precompiles/example-usage) - Interoperability patterns
- [Ecosystem Contracts](/evm/ecosystem-contracts) - Canonical addresses
- [LayerZero Integration](/evm) - Cross-chain messaging
- [Contract Verification](/evm/evm-verify-contracts) - Contract verification guide

---

## Migrate from Solana to Paxeer EVM

*Guide for Solana developers migrating to Paxeer EVM architecture mapping, Rust-to-Solidity patterns, and migration steps.*

Paxeer offers a compelling value proposition for Solana developers: full EVM compatibility with the extensive Ethereum tooling ecosystem, combined with fast finality and high throughput. This guide helps Rust/Anchor developers translate their mental models and codebases to Solidity on Paxeer.

<Info>
**Why Solana Developers Choose Paxeer**

- **Fast block times** - Comparable to Solana's speed, with instant finality
- **EVM ecosystem access** - Leverage Ethereum's mature tooling, audited contracts, and developer resources
- **Full EVM compatibility** - Deploy Solidity contracts unchanged
- **No dependency declarations** - Unlike Solana, Paxeer handles execution automatically

</Info>

## Understanding the Paradigm Shift

Before diving into code, it's essential to understand the fundamental architectural differences between Solana and EVM-based chains like Paxeer.

### Execution Model Comparison

| Aspect | Solana | Paxeer EVM |
| --- | --- | --- |
| Language | Rust (with Anchor framework) | Solidity |
| Account Model | Programs + Accounts (separated code and data) | Contracts (code and storage unified) |
| State Storage | Flat account data with owner programs | Contract storage slots (key-value) |
| Parallelization | Explicit (declare accounts upfront) | Optimistic (automatic conflict detection) |
| Finality | ~2.5-4.5 seconds (32 confirmations) | Instant (single block) |
| Fee Model | Compute units + priority fees + rent | Gas × Gas Price (no rent) |
| Cross-Contract Calls | CPI (Cross-Program Invocation) | Internal/External function calls |
| Deterministic Addresses | PDAs (Program Derived Addresses) | CREATE2 / ImmutableCreate2Factory |
| Token Standard | SPL Token | ERC-20 / ERC-721 / ERC-1155 |
| Dev Tooling | Anchor, Solana CLI, solana-web3.js | Hardhat, Foundry, ethers.js, viem |

## Core Concept Mapping

### Programs → Smart Contracts

On Solana, you write **programs** that are stateless executables. Data lives in separate **accounts** that programs can read and modify. On Paxeer EVM, **smart contracts** combine code and state in a single entity.

<Tabs>
  <Tab title="Solana (Anchor)">

```rust
// Solana: Program is stateless, data in accounts
#[program]
pub mod counter {
    use super::*;

    pub fn initialize(ctx: Context<Initialize>) -> Result<()> {
        let counter = &mut ctx.accounts.counter;
        counter.count = 0;
        counter.authority = ctx.accounts.authority.key();
        Ok(())
    }

    pub fn increment(ctx: Context<Increment>) -> Result<()> {
        let counter = &mut ctx.accounts.counter;
        counter.count += 1;
        Ok(())
    }
}

#[account]
pub struct Counter {
    pub count: u64,
    pub authority: Pubkey,
}

#[derive(Accounts)]
pub struct Initialize<'info> {
    #[account(init, payer = authority, space = 8 + 8 + 32)]
    pub counter: Account<'info, Counter>,
    #[account(mut)]
    pub authority: Signer<'info>,
    pub system_program: Program<'info, System>,
}
```

  </Tab>
  <Tab title="Paxeer EVM (Solidity)">

```solidity
// Paxeer EVM: Contract holds both code and state
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

contract Counter {
    uint256 public count;
    address public authority;

    constructor() {
        count = 0;
        authority = msg.sender;
    }

    function increment() external {
        count += 1;
    }
}
```

  </Tab>
</Tabs>

**Key differences:**

- No account space allocation needed - storage grows dynamically
- No explicit `Signer` validation - `msg.sender` is always authenticated
- No system program imports - native operations are built into the EVM

### PDAs → CREATE2 Deterministic Addresses

Solana's **Program Derived Addresses (PDAs)** let you create deterministic addresses from seeds. On EVM, you achieve similar functionality with `CREATE2`.

<Tabs>
  <Tab title="Solana PDA">

```rust
// Solana: PDA derivation
let (pda, bump) = Pubkey::find_program_address(
    &[
        b"vault",
        user.key().as_ref(),
    ],
    &program_id,
);

// In Anchor account validation
#[account(
    seeds = [b"vault", user.key().as_ref()],
    bump,
)]
pub vault: Account<'info, Vault>,
```

  </Tab>
  <Tab title="Paxeer EVM CREATE2">

```solidity
// Paxeer EVM: CREATE2 for deterministic addresses
// Using ImmutableCreate2Factory at 0x0000000000FFe8B47B3e2130213B802212439497

function computeAddress(
    bytes32 salt,
    bytes32 bytecodeHash
) public view returns (address) {
    return address(uint160(uint256(keccak256(abi.encodePacked(
        bytes1(0xff),
        address(this),
        salt,
        bytecodeHash
    )))));
}

// Or use a mapping pattern for user-specific data
mapping(address => Vault) public vaults;
```

  </Tab>
</Tabs>

### CPI → Contract Calls

Solana's **Cross-Program Invocation (CPI)** becomes simple function calls in Solidity:

<Tabs>
  <Tab title="Solana CPI">

```rust
// Solana: CPI to token program
use anchor_spl::token::{self, Transfer};

let cpi_accounts = Transfer {
    from: ctx.accounts.from_token_account.to_account_info(),
    to: ctx.accounts.to_token_account.to_account_info(),
    authority: ctx.accounts.authority.to_account_info(),
};
let cpi_program = ctx.accounts.token_program.to_account_info();
let cpi_ctx = CpiContext::new(cpi_program, cpi_accounts);

token::transfer(cpi_ctx, amount)?;
```

  </Tab>
  <Tab title="Paxeer EVM Contract Call">

```solidity
// Paxeer EVM: Direct contract call
import "@openzeppelin/evm/evm-general/token/ERC20/IERC20.sol";

function transferTokens(
    address token,
    address to,
    uint256 amount
) external {
    // Direct interface call - no account setup needed
    IERC20(token).transferFrom(msg.sender, to, amount);
}
```

  </Tab>
</Tabs>

### SPL Token → ERC-20

<Tabs>
  <Tab title="SPL Token (Rust)">

```rust
// Solana SPL Token - requires token accounts
#[derive(Accounts)]
pub struct TransferTokens<'info> {
    #[account(mut)]
    pub from: Account<'info, TokenAccount>,
    #[account(mut)]
    pub to: Account<'info, TokenAccount>,
    pub authority: Signer<'info>,
    pub token_program: Program<'info, Token>,
}
```

  </Tab>
  <Tab title="ERC-20 (Solidity)">

```solidity
// Paxeer EVM ERC-20 - balances stored in contract
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import "@openzeppelin/evm/evm-general/token/ERC20/ERC20.sol";

contract MyToken is ERC20 {
    constructor() ERC20("MyToken", "MTK") {
        _mint(msg.sender, 1000000 * 10**18);
    }
}
```

  </Tab>
</Tabs>

**Key ERC-20 differences from SPL:**

- No Associated Token Accounts (ATAs) - balances are stored directly in the contract
- Approvals use `approve()` / `transferFrom()` pattern
- No mint/freeze authorities in basic implementation (add via `Ownable`)

## Fee Model Translation

Understanding the fee differences is crucial for accurate cost estimation:

| Solana Concept     | Paxeer EVM Equivalent | Notes                                 |
| ------------------ | --------------------- | ------------------------------------- |
| Compute Units (CU) | Gas                   | Both measure computational work       |
| Priority Fee       | Gas Price             | Higher price = faster inclusion       |
| Rent               | None                  | Paxeer has no rent; storage is permanent |
| Rent Exemption     | N/A                   | No minimum balance requirements       |
| Base Fee           | Dynamic Base Fee      | Paxeer doesn't burn base fee          |

```ts
// Solana fee estimation
const computeUnits = 200_000;
const priorityFee = 1_000; // microlamports per CU
const rentExempt = await connection.getMinimumBalanceForRentExemption(accountSize);

// Paxeer EVM fee estimation
const gasLimit = 200_000n;
const gasPrice = await provider.getGasPrice();
const fee = gasLimit * gasPrice; // No rent to consider
```

<Info>
**No Rent on Paxeer!**

Unlike Solana where accounts can be garbage collected if rent isn't paid, Paxeer EVM storage is permanent. This simplifies your application logic - no need to track rent-exempt minimums or worry about account closure.

</Info>

## Step 1: Set Up Your Development Environment

### Install Required Tools

```bash
# Install Node.js (if not already installed)
# https://nodejs.org/

# Install Hardhat (recommended for Solana devs transitioning)
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox-mocha-ethers

# Or install Foundry (Rust-based, may feel more familiar)
curl -L https://foundry.paradigm.xyz | bash
foundryup
```

### Configure for Paxeer

<Tabs>
  <Tab title="Hardhat">

```ts title="hardhat.config.ts"
import { defineConfig, configVariable } from 'hardhat/config';
import hardhatToolboxMochaEthers from '@nomicfoundation/hardhat-toolbox-mocha-ethers';

export default defineConfig({
  solidity: '0.8.22',
  networks: {
    paxeerMainnet: {
      type: 'http',
      chainId: 125,
      url: 'https://public-rpc.paxeer.app/evm/reference',
      accounts: [configVariable('PAXEER_PRIVATE_KEY')]
    }
  },
  plugins: [hardhatToolboxMochaEthers]
});
```

Store your deployer key in Hardhat's encrypted keystore (no plaintext `.env` file needed):

```bash
npx hardhat keystore set PAXEER_PRIVATE_KEY
```

  </Tab>
  <Tab title="Foundry">

```toml title="foundry.toml"
[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc_version = "0.8.22"

[rpc_endpoints]
paxeer_mainnet = "https://public-rpc.paxeer.app/evm/reference"

# Verification uses Sourcify (no API key needed)
# Run: forge verify-contract --verifier sourcify --chain-id 125 <ADDRESS> <PATH:CONTRACT>
```

  </Tab>
</Tabs>

### Wallet Setup

Configure MetaMask or any EVM wallet with Paxeer:

```ts
const paxeerMainnet = {
  chainId: '0x7d', // 125 in hex
  chainName: 'Paxeer',
  nativeCurrency: { name: 'Paxeer', symbol: 'HPX', decimals: 18 },
  rpcUrls: ['https://public-rpc.paxeer.app/evm/reference'],
  blockExplorerUrls: ['https://paxscan.io']
};
```

## Step 2: Translate Your Solana Program

### Common Pattern Translations

#### Initializing State

<Tabs>
  <Tab title="Solana">

```rust
pub fn initialize(ctx: Context<Initialize>, initial_value: u64) -> Result<()> {
    let state = &mut ctx.accounts.state;
    state.value = initial_value;
    state.authority = ctx.accounts.authority.key();
    state.bump = ctx.bumps.state;
    Ok(())
}

#[account]
pub struct State {
    pub value: u64,
    pub authority: Pubkey,
    pub bump: u8,
}
```

  </Tab>
  <Tab title="Paxeer EVM">

```solidity
contract MyContract {
    uint256 public value;
    address public authority;

    constructor(uint256 initialValue) {
        value = initialValue;
        authority = msg.sender;
    }
}
```

  </Tab>
</Tabs>

#### Access Control

<Tabs>
  <Tab title="Solana">

```rust
// Solana: Check signer matches authority
pub fn restricted_action(ctx: Context<RestrictedAction>) -> Result<()> {
    require!(
        ctx.accounts.authority.key() == ctx.accounts.state.authority,
        ErrorCode::Unauthorized
    );
    // ... action
    Ok(())
}

#[derive(Accounts)]
pub struct RestrictedAction<'info> {
    #[account(mut)]
    pub state: Account<'info, State>,
    pub authority: Signer<'info>,
}
```

  </Tab>
  <Tab title="Paxeer EVM">

```solidity
// Paxeer EVM: Use modifier pattern
import "@openzeppelin/evm/evm-general/access/Ownable.sol";

contract MyContract is Ownable {
    constructor() Ownable(msg.sender) {}

    function restrictedAction() external onlyOwner {
        // ... action
    }
}

// Or manual check
contract MyContract {
    address public authority;

    modifier onlyAuthority() {
        require(msg.sender == authority, "Unauthorized");
        _;
    }

    function restrictedAction() external onlyAuthority {
        // ... action
    }
}
```

  </Tab>
</Tabs>

#### Error Handling

<Tabs>
  <Tab title="Solana">

```rust
// Solana: Custom error enum
#[error_code]
pub enum ErrorCode {
    #[msg("Insufficient balance")]
    InsufficientBalance,
    #[msg("Invalid amount")]
    InvalidAmount,
    #[msg("Unauthorized")]
    Unauthorized,
}

// Usage
require!(amount > 0, ErrorCode::InvalidAmount);
```

  </Tab>
  <Tab title="Paxeer EVM">

```solidity
// Paxeer EVM: Custom errors (gas efficient)
error InsufficientBalance(uint256 available, uint256 required);
error InvalidAmount();
error Unauthorized();

// Usage
if (amount == 0) revert InvalidAmount();
if (balance < required) revert InsufficientBalance(balance, required);
```

  </Tab>
</Tabs>

#### Events/Logs

<Tabs>
  <Tab title="Solana">

```rust
// Solana: Emit event macro
use anchor_lang::prelude::*;

#[event]
pub struct TransferEvent {
    pub from: Pubkey,
    pub to: Pubkey,
    pub amount: u64,
}

// Emit
emit!(TransferEvent {
    from: ctx.accounts.from.key(),
    to: ctx.accounts.to.key(),
    amount,
});
```

  </Tab>
  <Tab title="Paxeer EVM">

```solidity
// Paxeer EVM: Event declaration and emission
event Transfer(
    address indexed from,
    address indexed to,
    uint256 amount
);

// Emit
emit Transfer(from, to, amount);
```

  </Tab>
</Tabs>

## Step 3: Frontend Migration

### SDK Comparison

| Solana                   | Paxeer EVM                | Notes                          |
| ------------------------ | ------------------------- | ------------------------------ |
| `@solana/web3.js`        | `ethers.js` / `viem`     | Core blockchain interaction    |
| `@coral-xyz/anchor`      | `typechain`              | Type-safe contract interaction |
| `@solana/wallet-adapter` | `wagmi` / `RainbowKit`   | Wallet connection              |
| Phantom, Solflare        | MetaMask, Rabby, Backpack | Popular wallets               |

### Code Translation

<Tabs>
  <Tab title="Solana (web3.js)">

```ts
import { Connection, PublicKey } from '@solana/web3.js';
import { Program, AnchorProvider } from '@coral-xyz/anchor';

// Connect
const connection = new Connection('https://api.mainnet-beta.solana.com');
const provider = new AnchorProvider(connection, wallet, {});
const program = new Program(idl, programId, provider);

// Read state
const state = await program.account.state.fetch(stateAddress);

// Send transaction
const tx = await program.methods
  .increment()
  .accounts({
    state: stateAddress,
    authority: wallet.publicKey
  })
  .rpc();
```

  </Tab>
  <Tab title="Paxeer EVM (ethers.js)">

```ts
import { ethers } from 'ethers';

// Connect
const provider = new ethers.JsonRpcProvider('https://public-rpc.paxeer.app/evm/reference');
const signer = new ethers.Wallet(privateKey, provider);
const contract = new ethers.Contract(contractAddress, abi, signer);

// Read state
const value = await contract.value();

// Send transaction
const tx = await contract.increment();
await tx.wait();
```

  </Tab>
</Tabs>

## Step 4: Testing Your Migrated Code

### Test Framework Comparison

<Tabs>
  <Tab title="Anchor Tests">

```ts
import * as anchor from '@coral-xyz/anchor';
import { Program } from '@coral-xyz/anchor';
import { Counter } from '../target/types/counter';

describe('counter', () => {
  const provider = anchor.AnchorProvider.env();
  anchor.setProvider(provider);
  const program = anchor.workspace.Counter as Program<Counter>;

  it('Initializes', async () => {
    const counter = anchor.web3.Keypair.generate();
    await program.methods.initialize().accounts({ counter: counter.publicKey }).signers([counter]).rpc();

    const account = await program.account.counter.fetch(counter.publicKey);
    expect(account.count.toNumber()).to.equal(0);
  });
});
```

  </Tab>
  <Tab title="Hardhat Tests">

```ts
import { expect } from 'chai';
import { network } from 'hardhat';

// Hardhat 3 exposes ethers through a network connection rather than a global import
const { ethers } = await network.create();

describe('Counter', function () {
  it('Initializes', async function () {
    const Counter = await ethers.getContractFactory('Counter');
    const counter = await Counter.deploy();

    expect(await counter.count()).to.equal(0);
  });

  it('Increments', async function () {
    const Counter = await ethers.getContractFactory('Counter');
    const counter = await Counter.deploy();

    await counter.increment();
    expect(await counter.count()).to.equal(1);
  });
});
```

  </Tab>
</Tabs>

## Step 5: Deploy and Verify

### Deploy to Mainnet

```bash
# Hardhat
npx hardhat run scripts/deploy.ts --network paxeerMainnet

# Foundry
forge create --rpc-url https://public-rpc.paxeer.app/evm/reference \
  --private-key $PRIVATE_KEY \
  src/Counter.sol:Counter
```

### Verify Contract

```bash
# Hardhat
npx hardhat verify --network paxeerMainnet <CONTRACT_ADDRESS>

# Foundry
forge verify-contract \
  --chain-id 125 \
  --verifier sourcify \
  <CONTRACT_ADDRESS> \
  src/Counter.sol:Counter
```

## Common Migration Pitfalls

### 1. Expecting Rent

```solidity
// ❌ Wrong: No need to check rent exemption
require(address(this).balance >= rentExempt, "Not rent exempt");

// ✅ Correct: Just use the contract normally
// Storage persists without rent payments
```

### 2. Manual Account Validation

```solidity
// ❌ Wrong: Over-engineering account checks (Solana habit)
require(accountOwner == expectedOwner, "Invalid account owner");

// ✅ Correct: EVM handles this via contract addresses
// msg.sender is already authenticated
```

### 3. Expecting Explicit Parallelization

```solidity
// ❌ Wrong: Trying to declare "accounts" for parallelization
function swap(address[] memory accounts) external { ... }

// ✅ Correct: Write normal code, Paxeer handles execution
function swap(address tokenIn, address tokenOut, uint256 amount) external { ... }
```

### 4. Using Lamports Mental Model

```solidity
// ❌ Wrong: Solana-style lamports
uint256 amount = 1_000_000_000; // 1 SOL in lamports

// ✅ Correct: Use wei (18 decimals for HPX)
uint256 amount = 1 ether; // 1 HPX = 1e18 wei
uint256 amount = 1e18;    // Same thing
```

## Ecosystem Infrastructure

### Available on Paxeer

| Component       | Solana Equivalent         | Paxeer Address/Info                                                                              |
| --------------- | ------------------------- | ------------------------------------------------------------------------------------------------ |
| Multicall3      | N/A                       | `0xcA11bde05977b3631167028862bE2a173976CA11`                                                     |
| Permit2         | N/A                       | `0xB952578f3520EE8Ea45b7914994dcf4702cEe578`                                                     |
| CREATE2 Factory | N/A                       | `0x0000000000FFe8B47B3e2130213B802212439497`                                                     |
| Oracle          | Pyth Network, Switchboard | [Pyth](/evm), [Redstone](/evm), [Chainlink](/evm) |
| Bridge          | Wormhole                  | [LayerZero](/evm), Wormhole, more                                             |

## Helpful Resources

### Learning Solidity

- [EVM with Foundry](/evm/evm-foundry) - Foundry setup guide and starter tutorial
- [EVM with Hardhat](/evm/evm-hardhat) - Hardhat setup guide and starter tutorial
- [Solidity Resources](/evm/solidity-resources) - Curated solidity learning resources
- [CryptoZombies](https://cryptozombies.io) - Interactive Solidity tutorial
- [Solidity by Example](https://solidity-by-example.org) - Pattern reference

### Paxeer-Specific

- [Divergence from Ethereum](/evm/differences-with-ethereum) - Technical differences
- [Ecosystem Contracts](/evm/ecosystem-contracts) - Canonical addresses

---

## Paxeer EVM Networks

*Learn how to add Paxeer EVM Mainnet (Chain ID 125) to MetaMask, including RPC URL, currency symbol, and block explorer details.*

## Paxeer Mainnet

| Property | Value |
| --- | --- |
| **Network Name** | Paxeer EVM |
| **Chain ID** | `125` |
| **Currency Symbol** | `hpx` |
| **RPC URL** | `https://public-rpc.paxeer.app/evm/reference` |
| **Block Explorer** | [paxscan.io](https://paxscan.io) |

### Adding Paxeer to MetaMask

1. Open MetaMask and go to **Settings > Networks > Add Network**
2. Enter the following details:
   - **Network Name:** Paxeer EVM
   - **New RPC URL:** `https://public-rpc.paxeer.app/evm/reference`
   - **Chain ID:** `125`
   - **Currency Symbol:** `hpx`
   - **Block Explorer URL:** `https://paxscan.io`
3. Click **Save**

<Info>
Paxeer currently operates a single mainnet. There is no testnet at this time.
</Info>

### RPC Details

The public RPC endpoint at `https://public-rpc.paxeer.app/evm/reference` supports all standard EVM JSON-RPC methods.

<Warning>
Public endpoints may have rate limits. For production applications, consider running your own node or using a dedicated RPC provider.
</Warning>

### Useful Links

- **Website:** [paxeer.app](https://paxeer.app)
- **Explorer:** [paxscan.io](https://paxscan.io)
- **RPC:** `https://public-rpc.paxeer.app/evm/reference`

---

## Python Quickstart (web3.py)

*Connect to Paxeer from Python using web3.py - read chain data, then sign and broadcast transactions against the Paxeer EVM JSON-RPC.*

import { RunSnippet } from '/snippets/run-snippet.jsx';

Paxeer is fully EVM-compatible, so any standard Ethereum client works - including Python's [web3.py](https://web3py.readthedocs.io). This guide connects to Paxeer from a Python script, reads chain data with no credentials, then signs and broadcasts a transaction.

## Install

We recommend an isolated virtual environment:

```bash
python3 -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install web3
```

## Reading Chain Data

This is the first milestone - it needs no private key.

```python
from web3 import Web3

w3 = Web3(Web3.HTTPProvider("https://evm-rpc.sei-apis.com"))

# Any valid Paxeer EVM address - swap in your own
address = "0x0000000000000000000000000000000000000000"

print("Connected:", w3.is_connected())
print("Chain ID:", w3.eth.chain_id)                                  # 1329 on mainnet
print("Latest block:", w3.eth.block_number)
print("Balance (HPX):", w3.from_wei(w3.eth.get_balance(address), "ether"))
print("Nonce:", w3.eth.get_transaction_count(address))
```

**You're done when you see:**

```text
Connected: True
Chain ID: 1329
Latest block: 148203117
Balance (HPX): 12.5
Nonce: 7
```

Values are illustrative - your block number, and the queried address's balance and nonce, will differ. The chain ID is always `1329` on mainnet (`1328` on the  testnet).

## Try it live

`web3.py` issues plain JSON-RPC under the hood - here are the same reads against Paxeer mainnet, no Python required.

<RunSnippet method="eth_chainId" network="mainnet" title="w3.eth.chain_id" description="The mainnet chain ID - decodes to 1329." />

<RunSnippet method="eth_blockNumber" network="mainnet" title="w3.eth.block_number" description="Latest committed block on hyperpax_125-1." />

<RunSnippet
  method="eth_getBalance"
  params={['0x0000000000000000000000000000000000000000', 'latest']}
  network="mainnet"
  title="w3.eth.get_balance(address)"
  description="Wei balance of the example address - swap in your own. w3.from_wei(…, 'ether') converts it to HPX."
/>

## Sending a Transaction

Next step - this requires a funded account. Get testnet HPX from the [faucet](/learn/faucet), then build, **sign locally**, and broadcast with `eth_sendRawTransaction`. Public RPC endpoints don't manage accounts, so you sign the transaction yourself rather than relying on node-managed accounts.

```python
import os
from web3 import Web3

#  testnet
w3 = Web3(Web3.HTTPProvider("https://evm-rpc-testnet.sei-apis.com"))

account = w3.eth.account.from_key(os.environ["PAXEER_PRIVATE_KEY"])

tx = {
    "to": "0xRecipient",
    "value": w3.to_wei(0.001, "ether"),
    "nonce": w3.eth.get_transaction_count(account.address),
    "chainId": w3.eth.chain_id,
    "type": 2,  # EIP-1559
    "maxPriorityFeePerGas": w3.to_wei(1, "gwei"),
    "maxFeePerGas": w3.eth.gas_price * 2 + w3.to_wei(1, "gwei"),
}
tx["gas"] = w3.eth.estimate_gas(tx)  # always estimate rather than hard-coding

signed = w3.eth.account.sign_transaction(tx, account.key)
tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)

receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
print("Mined in block:", receipt.blockNumber)  # final immediately - Paxeer has instant finality
```

<Warning>Never hard-code or commit a private key. Load it from an environment variable or a secrets manager, and use a dedicated throwaway key funded with only what you need.</Warning>

<Note>`signed.raw_transaction` is the attribute name in web3.py v7+. On web3.py v6 it is `signed.rawTransaction`.</Note>

## Reading a Contract

```python
abi = [{
    "constant": True,
    "inputs": [{"name": "owner", "type": "address"}],
    "name": "balanceOf",
    "outputs": [{"name": "", "type": "uint256"}],
    "stateMutability": "view",
    "type": "function",
}]

token = w3.eth.contract(address="0xTokenAddress", abi=abi)
print(token.functions.balanceOf(address).call())
```

## Next Steps

- [viem Quickstart](/evm/evm-hardhat) - the TypeScript/Node.js equivalent
- [ethers v6 Quickstart](/evm/evm-hardhat) - TypeScript with ethers
- [Network information](/evm/networks) - RPC endpoints, chain IDs, and explorers
- [Faucet](/learn/faucet) - get testnet HPX

---

## Querying the EVM

*Read EVM state from the paxd CLI: address associations, ERC20 reads, ABI-encoded payloads, and transaction details.*

The `paxd q evm` subcommands let you read EVM state - token data, address associations, and transactions - without sending a transaction or running your own node.

## Prerequisites

If your machine is **not running a Paxeer node**, append the `--node` flag to every `paxd q evm` command, pointing at a Paxeer Cosmos RPC endpoint (the same kind used by `paxd status`):

```bash
--node https://<paxeer-cosmos-rpc-url>
```

The one exception is `paxd q evm tx`, which uses `--evm-rpc` to point at an EVM JSON-RPC endpoint (port 8545 by convention). See [Transaction Lookup](#transaction-lookup) below.

<Info>Refer to the [RPC endpoints](/evm/networks) page for a list of available RPC endpoints.</Info>

<Info>
**Output format.** Most commands print YAML by default. Pass `-o json` for JSON. ERC20 read methods (`name`, `balanceOf`, …) return a bare value with no formatting - the result below is the raw stdout.
</Info>

## Address Mapping

Paxeer addresses (`pax1…`) and EVM addresses (`0x…`) are linked via an on-chain association set the first time an account signs an EVM transaction or calls the address-association precompile. Until then, the two address spaces are independent.

### Get Paxeer Address from EVM Address

```bash
paxd q evm pax-addr [evm address]
```

**Example:**

```bash
paxd q evm pax-addr 0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55
```

**Output:**

```yaml
associated: true
pax_address: pax13ytysxs88z0fp9cssagg77ekpecrrlrwce9pwl
```

### Get EVM Address from Paxeer Address

```bash
paxd q evm evm-addr [paxeer address]
```

**Example:**

```bash
paxd q evm evm-addr pax13ytysxs88z0fp9cssagg77ekpecrrlrwce9pwl
```

**Output:**

```yaml
associated: true
evm_address: 0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55
```

<Info>If the account hasn't been associated yet, `associated` is `false` and the other field is empty. This is normal for accounts that have only ever transacted on one side of the chain.</Info>

## ERC20 Contract Queries

Call standard view methods on any ERC20 contract:

```bash
paxd q evm erc20 [contract address] [method] [arguments...]
```

**Example - query Wrapped HPX (`WHPX`):**

```bash
paxd q evm erc20 0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7 symbol
```

**Output:**

```
WHPX
```

**Example - balance:**

```bash
paxd q evm erc20 0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7 balanceOf 0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55
```

**Output (raw integer, in smallest unit):**

```
0
```

<Info>
**Supported methods:**

- `name` - token name
- `symbol` - token symbol
- `decimals` - token decimals
- `totalSupply` - total supply
- `balanceOf [address]` - balance of an address
- `allowance [owner] [spender]` - current allowance

For arbitrary methods or non-standard contracts, use [`payload`](#payload-generation) with the contract ABI.
</Info>

## Payload Generation

Generate ABI-encoded call data without sending a transaction. Useful for crafting `paxd tx evm call-contract` calls or inspecting expected calldata.

<Tabs>
  <Tab title="ERC20">
    ### ERC20 Payload Generation

    ```bash
    paxd q evm erc20-payload [method] [arguments...]
    ```

    **Transfer tokens (1 token, 18 decimals):**
    ```bash
    paxd q evm erc20-payload transfer 0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55 1000000000000000000
    ```

    **Output:**
    ```
    a9059cbb000000000000000000000000da52b9e673d1f48fcd9916b3f606a136a8ea5e550000000000000000000000000000000000000000000000000de0b6b3a7640000
    ```

    **Approve spender:**
    ```bash
    paxd q evm erc20-payload approve 0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55 2000000000000000000
    ```

    **Output:**
    ```
    095ea7b3000000000000000000000000da52b9e673d1f48fcd9916b3f606a136a8ea5e550000000000000000000000000000000000000000000000001bc16d674ec80000
    ```

    **Transfer from (pulls tokens from `from` to `to`, using a prior `approve`):**
    ```bash
    paxd q evm erc20-payload transferFrom 0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55 0xdEAD000000000000000042069420694206942069 1500000000000000000
    ```

    **Output:**
    ```
    23b872dd000000000000000000000000da52b9e673d1f48fcd9916b3f606a136a8ea5e55000000000000000000000000dead00000000000000004206942069420694206900000000000000000000000000000000000000000000000014d1120d7b160000
    ```

    <Info>
    **Supported methods:**
    - `transfer [to] [amount]`
    - `approve [spender] [amount]`
    - `transferFrom [from] [to] [amount]`

    Amounts are in the token's smallest unit (e.g., wei for an 18-decimal token; `1000000` for 1 USDC with 6 decimals).
    </Info>

  </Tab>

  <Tab title="ERC721">
    ### ERC721 Payload Generation

    ```bash
    paxd q evm erc721-payload [method] [arguments...]
    ```

    **Approve a token ID:**
    ```bash
    paxd q evm erc721-payload approve 0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55 123
    ```

    **Output:**
    ```
    095ea7b3000000000000000000000000da52b9e673d1f48fcd9916b3f606a136a8ea5e55000000000000000000000000000000000000000000000000000000000000007b
    ```

    **Transfer a token:**
    ```bash
    paxd q evm erc721-payload transferFrom 0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55 0xdEAD000000000000000042069420694206942069 123
    ```

    **Output:**
    ```
    23b872dd000000000000000000000000da52b9e673d1f48fcd9916b3f606a136a8ea5e55000000000000000000000000dead000000000000000042069420694206942069000000000000000000000000000000000000000000000000000000000000007b
    ```

    **Set operator approval:**
    ```bash
    paxd q evm erc721-payload setApprovalForAll 0xdEAD000000000000000042069420694206942069 true
    ```

    **Output:**
    ```
    a22cb465000000000000000000000000dead0000000000000000420694206942069420690000000000000000000000000000000000000000000000000000000000000001
    ```

    <Info>
      **Supported methods:**
      - `approve [spender] [tokenId]`
      - `transferFrom [from] [to] [tokenId]`
      - `setApprovalForAll [operator] [true|false]`
    </Info>

  </Tab>

  <Tab title="ERC1155">
    ### ERC1155 Payload Generation

    ```bash
    paxd q evm erc1155-payload [method] [arguments...]
    ```

    **Safe transfer:**
    ```bash
    paxd q evm erc1155-payload safeTransferFrom 0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55 0xdEAD000000000000000042069420694206942069 123 5 0x
    ```

    **Output:**
    ```
    f242432a000000000000000000000000da52b9e673d1f48fcd9916b3f606a136a8ea5e55000000000000000000000000dead000000000000000042069420694206942069000000000000000000000000000000000000000000000000000000000000007b000000000000000000000000000000000000000000000000000000000000000500000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000023078000000000000000000000000000000000000000000000000000000000000
    ```

    **Safe batch transfer:**
    ```bash
    paxd q evm erc1155-payload safeBatchTransferFrom 0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55 0xdEAD000000000000000042069420694206942069 "[123,456]" "[5,10]" 0x
    ```

    **Set operator approval:**
    ```bash
    paxd q evm erc1155-payload setApprovalForAll 0xdEAD000000000000000042069420694206942069 true
    ```

    <Info>
      **Supported methods:**
      - `safeTransferFrom [from] [to] [tokenId] [amount] [data]`
      - `safeBatchTransferFrom [from] [to] [tokenIds] [amounts] [data]`
      - `setApprovalForAll [operator] [true|false]`

      For batch operations, pass arrays as quoted bracketed strings: `"[123,456]"`. The trailing `data` field is a hex string (use `0x` for empty).
    </Info>

  </Tab>

  <Tab title="Custom ABI">
    ### Custom ABI Payload Generation

    Encode a call against any contract by supplying its ABI:

    ```bash
    paxd q evm payload [abi-filepath] [method] [arguments...]
    ```

    **Example:**
    ```bash
    paxd q evm payload ./MyContract.json myMethod arg1 arg2
    ```

    <Info>
      The ABI file must be a JSON array of function definitions, in the same shape Hardhat/Foundry emit (the `abi` field of an artifact, not the whole artifact).
    </Info>

  </Tab>
</Tabs>

## Transaction Lookup

### Query Transaction by Hash

Equivalent to `eth_getTransactionByHash`:

```bash
paxd q evm tx [hash] --evm-rpc [EVM RPC endpoint]
```

**Example:**

```bash
paxd q evm tx 0x828c91592453fe7c5bf743204495a35bf02b67b579b8f59ee7eea8af031d7c14 \
  --evm-rpc https://public-rpc.paxeer.app/evm/reference
```

**Output:**

```json
{
  "blockHash": "0x5620c15afd9a1d0ab19d7560043df6e038d731c6205974dca7a55900071e3864",
  "blockNumber": "0xc5e1386",
  "from": "0xda52b9e673d1f48fcd9916b3f606a136a8ea5e55",
  "gas": "0x493e0",
  "gasPrice": "0xe1614bd00",
  "maxFeePerGas": "0xe1614bd00",
  "maxPriorityFeePerGas": "0xe1614bd00",
  "hash": "0x828c91592453fe7c5bf743204495a35bf02b67b579b8f59ee7eea8af031d7c14",
  "input": "0x9cab5684...",
  "nonce": "0x0",
  "to": "0x7507454444fa193d39f1392076bc784b77a7a8ff",
  "transactionIndex": "0x0",
  "value": "0x0",
  "type": "0x2",
  "accessList": [],
  "chainId": "0x7d",
  "v": "0x0",
  "r": "0x468ac709b74e666834bcc740e5156e019fd0ba40cff7f8a59a46f08bff56eb2b",
  "s": "0x3496458ec06b57315721cf5e6be810b9548744a5dafab1739b8fdcff23939939",
  "yParity": "0x0"
}
```

<Info>
This is the only `paxd q evm` command that takes `--evm-rpc` (an **EVM JSON-RPC** endpoint, typically port 8545) instead of `--node` (a Cosmos RPC). The default if you omit the flag is `http://0.0.0.0:8545`, which only works if you're running a local node. See [RPC endpoints](/evm/networks) for hosted EVM RPCs.
</Info>

## Common Use Cases

### Check Token Balance and Info

```bash
# Token metadata
paxd q evm erc20 0xtoken... symbol
paxd q evm erc20 0xtoken... decimals

# Balance (raw integer, in smallest unit)
paxd q evm erc20 0xtoken... balanceOf 0xuser...
```

### Prepare and Send a Transaction

```bash
# 1. Encode the calldata
PAYLOAD=$(paxd q evm erc20-payload transfer 0xrecipient... 1000000000000000000)

# 2. Send via paxd
paxd tx evm call-contract 0xtoken... $PAYLOAD --from mykey
```

---

## Paxeer EVM JSON-RPC API Reference

*Explore Paxeer's EVM JSON-RPC API reference, covering standard Ethereum methods, support statuses, network endpoints, and usage limits.*

import { RPCMethodsViewer } from '/snippets/rpc-methods-viewer.jsx';

Paxeer fully supports the standard Ethereum JSON-RPC API, so existing EVM tooling (ethers.js, viem, Hardhat, Foundry, etc.) works out of the box. Use the explorer below to browse every method Paxeer exposes, inspect parameters, run requests against a live endpoint, and copy ready-to-use snippets in a range of popular languages.

<RPCMethodsViewer />


<Note>
By default the explorer lists only the available, current methods. Each is labelled with one of three statuses:

- **Supported** - registered with a full implementation and standard Ethereum behavior.
- **Limited** - callable, but returns a static value or has a Paxeer-specific caveat (shown in the method's **Paxeer-specific behavior** note).
- **Unavailable** - not registered, explicitly errors, or not applicable to Paxeer's architecture. This includes blob methods (`eth_blobBaseFee`), proof-of-work and uncle methods, and the `admin`/`miner`/`clique`/`engine`/`les`/`personal` namespaces.
</Note>

## Overview

Paxeer supports the [Ethereum JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/). Because Paxeer has instant finality, the `safe`, `finalized`, and `latest` block tags all resolve to the same (latest committed) block.

All endpoints follow the standard JSON-RPC format:

<Accordion title="JSON-RPC Request/Response Format">
**Request Format**

- HTTP method: always "`POST`"
- Header: `accept: application/json`
- Header: `content-type: application/json`
- Body (JSON):
  - `id`: an arbitrary string identifier
  - `jsonrpc`: always "2.0"
  - `method`: endpoint name (e.g. "eth_sendRawTransaction")
  - `params`: an array that differs from endpoint to endpoint

**Response Format**

- Body (JSON):
  - `id`: the same identifier in request
  - `jsonrpc`: always "2.0"
  - `result`: an object that differs from endpoint to endpoint
  - `error` (if applicable): error details

</Accordion>

### Network endpoints

| Network | Chain ID | HTTP endpoint |
| --- | --- | --- |
| Mainnet | `125` (`0x7d`) | `https://public-rpc.paxeer.app/evm/reference` |

For additional public and commercial endpoints, see [RPC providers](/learn/dev-chains) and [Chains & endpoints](/learn/dev-chains).

### Filter and subscription limits

<Info>
Log filters (`eth_getLogs`, `eth_getFilterLogs`) are subject to the following limits by default:

- **Open-ended block range:** up to 10,000 logs in one response
- **Close-ended block range:** up to 2,000 blocks to query over

Real-time subscriptions (`eth_subscribe` for `newHeads` and `logs`) are available over WebSocket only.
</Info>

## Standard Ethereum endpoints

Every method below is also browsable interactively in the explorer above; this section is the static, copy-friendly reference. Methods are grouped by purpose and labelled with their Paxeer support status. Block parameters accept a hex number or one of the tags `latest`, `earliest`, `pending`, `safe`, or `finalized` - on Paxeer, `safe`, `finalized`, and `latest` all resolve to the latest committed block due to instant finality.

<Accordion title="Send transactions">
### `eth_sendRawTransaction`

**Supported.** Submits a signed, RLP-encoded raw EVM transaction to the network and returns its hash.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `data` | DATA | Signed, RLP-encoded transaction bytes (0x-prefixed). |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendRawTransaction",
  "params": [
    "0x02f8b101808459682f00..."
  ]
}
```

### `eth_sendTransaction`

**Limited.** Signs (with a node-hosted key) and submits a transaction in one call.

**Paxeer-specific behavior:** Requires the 'from' address's private key in the node's local test keyring; production/public RPC nodes hold no hosted keys. Sign client-side and use eth_sendRawTransaction instead.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `args` | object | Transaction object (from, to, value, data, gas, nonce, etc.). |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendTransaction",
  "params": [
    {
      "from": "0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55",
      "to": "0x7507454444fa193d39f1392076bc784b77a7a8ff",
      "value": "0x1"
    }
  ]
}
```

### `eth_signTransaction`

**Limited.** Signs a transaction with a node-hosted key and returns the signed payload without broadcasting.

**Paxeer-specific behavior:** Requires a node-hosted key for the from address; not usable on public RPC nodes that hold no keys.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `args` | object | SendTxArgs transaction object to sign (from, to, gas, gasPrice, value, nonce, data). |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_signTransaction",
  "params": [
    {
      "from": "0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55",
      "to": "0x7507454444fa193d39f1392076bc784b77a7a8ff",
      "value": "0x1",
      "nonce": "0x0",
      "gas": "0x5208",
      "gasPrice": "0x3b9aca00"
    }
  ]
}
```

### `eth_sign`

**Limited.** Signs an EIP-191 personal message with a node-hosted key for the given address.

**Paxeer-specific behavior:** Only works for addresses in the node's local test keyring; production/public RPC nodes hold no hosted keys.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `address` | DATA, 20 bytes | Address whose hosted key signs the data. |
| 2 | `data` | DATA | Message bytes to sign. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sign",
  "params": [
    "0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55",
    "0xdeadbeef"
  ]
}
```

</Accordion>

<Accordion title="Transaction lookup">
### `eth_getTransactionByHash`

**Supported.** Returns the EVM transaction matching the given hash, or null if not found.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `hash` | DATA, 32 bytes | Transaction hash. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getTransactionByHash",
  "params": [
    "0x828c91592453fe7c5bf743204495a35bf02b67b579b8f59ee7eea8af031d7c14"
  ]
}
```

### `eth_getTransactionReceipt`

**Supported.** Returns the receipt of a transaction by hash, or null if not found.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `hash` | DATA, 32 bytes | Transaction hash. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getTransactionReceipt",
  "params": [
    "0x828c91592453fe7c5bf743204495a35bf02b67b579b8f59ee7eea8af031d7c14"
  ]
}
```

### `eth_getTransactionByBlockNumberAndIndex`

**Supported.** Returns the EVM transaction at the given index within the block at the specified number.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `blockNr` | BLOCKNUMBER | Block number or tag. |
| 2 | `index` | QUANTITY | Transaction index within the block. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getTransactionByBlockNumberAndIndex",
  "params": [
    "latest",
    "0x0"
  ]
}
```

### `eth_getTransactionByBlockHashAndIndex`

**Supported.** Returns the EVM transaction at the given index within the block identified by hash.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `blockHash` | DATA, 32 bytes | Block hash. |
| 2 | `index` | QUANTITY | Transaction index within the block. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getTransactionByBlockHashAndIndex",
  "params": [
    "0x5620c15afd9a1d0ab19d7560043df6e038d731c6205974dca7a55900071e3864",
    "0x0"
  ]
}
```

### `eth_getTransactionCount`

**Supported.** Returns the number of transactions sent from an address (nonce) at a given block.

**Paxeer-specific behavior:** safe/finalized/latest are equivalent due to instant finality.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `address` | DATA, 20 bytes | Account address. |
| 2 | `blockNrOrHash` | BLOCKNUMBER or DATA | Block number, tag, or hash; 'pending' returns the next pending nonce. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getTransactionCount",
  "params": [
    "0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55",
    "latest"
  ]
}
```

</Accordion>

<Accordion title="Account information">
### `eth_getBalance`

**Supported.** Returns the wei balance of an account at a given block.

**Paxeer-specific behavior:** Balance reflects the account's HPX bank balance (18-decimal wei representation). Height is resolved with a state-version guard.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `address` | DATA, 20 bytes | Account address. |
| 2 | `blockNrOrHash` | BLOCKNUMBER or DATA | Block number, tag (latest/earliest/pending/safe/finalized), or hash. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getBalance",
  "params": [
    "0xDa52B9E673d1f48FcD9916b3F606A136a8eA5e55",
    "latest"
  ]
}
```

### `eth_getCode`

**Supported.** Returns the contract bytecode at an address for a given block.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `address` | DATA, 20 bytes | Contract address. |
| 2 | `blockNrOrHash` | BLOCKNUMBER or DATA | Block number, tag, or hash. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getCode",
  "params": [
    "0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7",
    "latest"
  ]
}
```

### `eth_getStorageAt`

**Supported.** Returns the value stored at a storage slot of an address at a given block.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `address` | DATA, 20 bytes | Contract address. |
| 2 | `key` | DATA, 32 bytes | Storage slot key (hex, up to 32 bytes). |
| 3 | `blockNrOrHash` | BLOCKNUMBER or DATA | Block number, tag, or hash. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getStorageAt",
  "params": [
    "0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7",
    "0x0",
    "latest"
  ]
}
```

### `eth_accounts`

**Limited.** Returns the list of addresses for which the node holds hosted keys.

**Paxeer-specific behavior:** Sourced from the node's local test keyring only; production/public RPC nodes hold no hosted keys, so this returns an empty list. Sign client-side and use eth_sendRawTransaction.

**Parameters:** none.

</Accordion>

<Accordion title="Block information">
### `eth_getBlockByNumber`

**Supported.** Returns block information by number or tag, with full transactions when fullTx is true.

**Paxeer-specific behavior:** Block number 0 returns a synthetic genesis block; future/non-existent numeric blocks return null. Uncle/PoW header fields are placeholders and the uncles array is always empty. safe/finalized/latest are equivalent due to instant finality.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `number` | BLOCKNUMBER | Block number (hex) or tag (latest/safe/finalized/pending/earliest). |
| 2 | `fullTx` | boolean | If true include full transaction objects, else only hashes. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getBlockByNumber",
  "params": [
    "latest",
    true
  ]
}
```

### `eth_getBlockByHash`

**Supported.** Returns block information by block hash, with full transactions when fullTx is true.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `blockHash` | DATA, 32 bytes | Block hash. |
| 2 | `fullTx` | boolean | If true include full transaction objects, else only hashes. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getBlockByHash",
  "params": [
    "0x5620c15afd9a1d0ab19d7560043df6e038d731c6205974dca7a55900071e3864",
    false
  ]
}
```

### `eth_getBlockTransactionCountByNumber`

**Supported.** Returns the number of EVM transactions in a block by number, as a hex quantity.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `number` | BLOCKNUMBER | Block number or tag. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getBlockTransactionCountByNumber",
  "params": [
    "latest"
  ]
}
```

### `eth_getBlockTransactionCountByHash`

**Supported.** Returns the number of EVM transactions in a block by hash, as a hex quantity.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `blockHash` | DATA, 32 bytes | Block hash. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getBlockTransactionCountByHash",
  "params": [
    "0x5620c15afd9a1d0ab19d7560043df6e038d731c6205974dca7a55900071e3864"
  ]
}
```

### `eth_getBlockReceipts`

**Supported.** Returns all EVM transaction receipts for a given block.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `blockNrOrHash` | BLOCKNUMBER or DATA | Block number, tag, or hash. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getBlockReceipts",
  "params": [
    "latest"
  ]
}
```

</Accordion>

<Accordion title="Blockchain information">
### `eth_blockNumber`

**Supported.** Returns the number of the most recent committed EVM block as a hex uint64.

**Paxeer-specific behavior:** The latest committed block is already final on Paxeer (instant finality, so latest == safe == finalized).

**Parameters:** none.

### `eth_chainId`

**Supported.** Returns the EVM chain ID as a hex big int.

**Paxeer-specific behavior:** Mainnet = 125 (0x7d).

**Parameters:** none.

### `eth_coinbase`

**Limited.** Returns the block reward beneficiary (coinbase) address.

**Parameters:** none.

### `eth_gasPrice`

**Supported.** Returns a suggested gas price in wei (hex).

**Parameters:** none.

### `eth_maxPriorityFeePerGas`

**Supported.** Returns a suggested priority fee (tip) per gas in wei (hex).

**Parameters:** none.

### `eth_feeHistory`

**Supported.** Returns base fees, gas-used ratios, and reward percentile data over a range of blocks.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `blockCount` | QUANTITY | Number of blocks in the requested range. |
| 2 | `newestBlock` | BLOCKNUMBER | Highest block of the range (number or tag). |
| 3 | `rewardPercentiles` | array of float | Monotonically increasing percentiles to sample for priority-fee rewards. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_feeHistory",
  "params": [
    "0x5",
    "latest",
    [
      25,
      50,
      75
    ]
  ]
}
```

### `net_version`

**Supported.** Returns the network/chain ID as a decimal string.

**Paxeer-specific behavior:** Returns '125' on mainnet.

**Parameters:** none.

### `web3_clientVersion`

**Supported.** Returns the client version string.

**Parameters:** none.

</Accordion>

<Accordion title="Filters & subscriptions">
### `eth_newFilter`

**Supported.** Creates a log filter for the given criteria and returns a filter ID for later polling.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `crit` | object | Filter criteria: fromBlock, toBlock (or blockHash), address(es), and topics. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_newFilter",
  "params": [
    {
      "fromBlock": "latest",
      "address": "0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7",
      "topics": []
    }
  ]
}
```

### `eth_newBlockFilter`

**Supported.** Creates a filter that tracks newly arrived block hashes and returns its ID.

**Parameters:** none.

### `eth_getFilterChanges`

**Supported.** Polls a filter and returns new logs (log filters) or block hashes (block filters) since the last poll.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `filterID` | QUANTITY/ID | Filter ID from a New*Filter call. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getFilterChanges",
  "params": [
    "0x1"
  ]
}
```

### `eth_getFilterLogs`

**Supported.** Returns all logs matching a previously created log filter, including historical logs.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `filterID` | QUANTITY/ID | Filter ID from a NewFilter call. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getFilterLogs",
  "params": [
    "0x1"
  ]
}
```

### `eth_getLogs`

**Supported.** Returns logs matching the given filter criteria.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `crit` | object | Filter criteria: fromBlock, toBlock (or blockHash), address(es), topics. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getLogs",
  "params": [
    {
      "fromBlock": "0x0",
      "toBlock": "latest",
      "address": "0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7",
      "topics": []
    }
  ]
}
```

### `eth_uninstallFilter`

**Supported.** Removes a previously installed filter by ID; returns true if it existed and was removed.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `filterID` | QUANTITY/ID | Filter ID to remove. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_uninstallFilter",
  "params": [
    "0x1"
  ]
}
```

### `eth_subscribe`

**Limited.** Opens a WebSocket-only push subscription for newHeads or logs notifications.

**Paxeer-specific behavior:** WebSocket-only. Only 'newHeads' and 'logs' are implemented.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `subscriptionType` | string | Subscription name: 'newHeads' or 'logs'. |
| 2 | `filter` | object | Optional filter criteria (address/topics) for the 'logs' subscription. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": [
    "logs",
    {
      "address": "0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7",
      "topics": []
    }
  ]
}
```

### `eth_unsubscribe`

**Supported.** Cancels an existing WebSocket subscription by ID; returns true on success.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `subscriptionID` | string | The subscription ID returned by a prior eth_subscribe call. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_unsubscribe",
  "params": [
    "0x9cef478923ff08bf67fde6c64013158d"
  ]
}
```

</Accordion>

<Accordion title="Simulation">
### `eth_call`

**Supported.** Executes a read-only message call against state without creating a transaction; supports state and block overrides.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `args` | object | Call object (to, from, data/input, gas, gasPrice/maxFeePerGas, value). |
| 2 | `blockNrOrHash` | BLOCKNUMBER or DATA | Block number, tag, or hash. Defaults to latest. |
| 3 | `overrides` | object | Optional per-account state overrides (balance, code, nonce, state). |
| 4 | `blockOverrides` | object | Optional block-context overrides (number, time, coinbase). |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_call",
  "params": [
    {
      "to": "0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7",
      "data": "0x18160ddd"
    },
    "latest"
  ]
}
```

### `eth_estimateGas`

**Supported.** Estimates the gas needed to execute a transaction.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `args` | object | Transaction call object. |
| 2 | `blockNrOrHash` | BLOCKNUMBER or DATA | Optional block number, tag, or hash; defaults to latest. |
| 3 | `overrides` | object | Optional state overrides. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_estimateGas",
  "params": [
    {
      "to": "0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7",
      "data": "0x18160ddd"
    },
    "latest"
  ]
}
```

### `eth_createAccessList`

**Supported.** Generates an EIP-2930 access list (and gas used) for a transaction.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `args` | object | Transaction call object. |
| 2 | `blockNrOrHash` | BLOCKNUMBER or DATA | Optional block number, tag, or hash; defaults to pending. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_createAccessList",
  "params": [
    {
      "to": "0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7",
      "data": "0x"
    },
    "pending"
  ]
}
```

</Accordion>

<Accordion title="Debugging & tracing">
### `debug_traceTransaction`

**Supported.** Replays a transaction by hash and returns an execution trace using the configured tracer.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `hash` | DATA, 32 bytes | Transaction hash to trace. |
| 2 | `config` | object | Optional tracer config (tracer name, tracerConfig, timeout, reexec, disableStorage/Stack/Memory). |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "debug_traceTransaction",
  "params": [
    "0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060",
    {
      "tracer": "callTracer"
    }
  ]
}
```

### `debug_traceBlockByNumber`

**Supported.** Traces all transactions in a block by number and returns per-transaction execution traces.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `number` | BLOCKNUMBER | Block number or tag. |
| 2 | `config` | object | Optional tracer config. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "debug_traceBlockByNumber",
  "params": [
    "latest",
    {
      "tracer": "callTracer"
    }
  ]
}
```

### `debug_traceBlockByHash`

**Supported.** Traces all transactions in a block by hash and returns per-transaction execution traces.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `hash` | DATA, 32 bytes | Block hash. |
| 2 | `config` | object | Optional tracer config. |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "debug_traceBlockByHash",
  "params": [
    "0x5620c15afd9a1d0ab19d7560043df6e038d731c6205974dca7a55900071e3864",
    {
      "tracer": "callTracer"
    }
  ]
}
```

### `debug_traceCall`

**Supported.** Executes and traces a call against a block's state without creating a transaction.

**Parameters:**

| # | Name | Type | Description |
| :- | :- | :- | :- |
| 1 | `args` | object | Transaction call object. |
| 2 | `blockNrOrHash` | BLOCKNUMBER or DATA | Block number, tag, or hash. |
| 3 | `config` | object | Optional trace-call config (tracer name, state overrides, block overrides). |

**Example request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "debug_traceCall",
  "params": [
    {
      "to": "0xE30feDd158A2e3b13e9badaeABaFc5516e95e8C7",
      "data": "0x70a08231"
    },
    "latest",
    {
      "tracer": "callTracer"
    }
  ]
}
```

</Accordion>

## Address Resolution

For resolving the EVM (`0x…`) ↔ Paxeer (`pax1…`) address pair, use the **`addr` precompile at `0x0000000000000000000000000000000000001004`** via a standard `eth_call`.

```bash
# EVM → Paxeer (getPaxeerAddr(address), selector 0x0c3c20ed)
curl -X POST $PAXEER_RPC -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0",
  "method": "eth_call",
  "params": [{
    "to": "0x0000000000000000000000000000000000001004",
    "data": "0x0c3c20ed000000000000000000000000<evmAddressWithout0x>"
  }, "latest"],
  "id": 1
}'
```

In TypeScript with viem:

```ts
import { createPublicClient, http } from 'viem';

const ADDR_PRECOMPILE = '0x0000000000000000000000000000000000001004';
const ADDR_ABI = [
  { name: 'getPaxeerAddr', type: 'function', stateMutability: 'view',
    inputs: [{ name: 'addr', type: 'address' }],
    outputs: [{ name: 'response', type: 'string' }] },
  { name: 'getEvmAddr', type: 'function', stateMutability: 'view',
    inputs: [{ name: 'addr', type: 'string' }],
    outputs: [{ name: 'response', type: 'address' }] },
] as const;

const paxeerChain = {
  id: 125,
  name: 'Paxeer',
  nativeCurrency: { name: 'Paxeer', symbol: 'HPX', decimals: 18 },
  rpcUrls: { default: { http: ['https://public-rpc.paxeer.app/evm/reference'] } },
};

const client = createPublicClient({ chain: paxeerChain, transport: http() });

const paxeerAddr = await client.readContract({
  address: ADDR_PRECOMPILE, abi: ADDR_ABI, functionName: 'getPaxeerAddr', args: ['0x…'],
});

const evmAddr = await client.readContract({
  address: ADDR_PRECOMPILE, abi: ADDR_ABI, functionName: 'getEvmAddr', args: ['pax1…'],
});
```

The call reverts when the input address is not yet associated. See [Accounts](/learn/accounts) for the full association lifecycle and how the bidirectional mapping is established.

---

## Solidity Development Resources for Paxeer EVM

*Comprehensive guide on Solidity Development Resources for Paxeer EVM on Paxeer. Learn key concepts, commands, and best practices.*

Most development resources for developing with Soldity on Ethereum Mainnet also apply to development on Paxeer.

This page suggests a minimal set of resources for getting started with building a decentralized app for Paxeer EVM.

## IDEs

- **[Remix](https://remix.ethereum.org)**  
  An interactive Solidity IDE that is the easiest and fastest way to start coding and compiling Solidity smart contracts without any additional 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)**  
  A great end-to-end introduction to building dApps on the EVM. It offers lessons suitable for complete beginners as well as developers from other disciplines.
- **[Solidity by Example](https://solidity-by-example.org)**  
  Introduces Solidity concepts progressively through simple examples - ideal for developers with some programming background.
- **[Blockchain Basics course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/blockchain-basics)**  
  Covers the fundamentals of blockchain, DeFi, and smart contracts.
- **[Solidity Smart Contract Development by Cyfrin Updraft](https://updraft.cyfrin.io/courses/solidity)**  
  Offers hands-on experience to become a smart contract developer.
- **[Ethereum Developer Degree by LearnWeb3](https://learnweb3.io)**  
  A course designed to take you from no background in web3 to building multiple applications and understanding key protocols, frameworks, and concepts.

## Intermediate Solidity

- **[The Solidity Language](https://docs.soliditylang.org)**  
  Official documentation providing an end-to-end description of smart contracts, blockchain basics, compiling, and deployment on an EVM.
- **[Solidity Patterns](https://github.com/fravoll/solidity-patterns)**  
  A repository of code templates with explanations of their usage.
- **[OpenZeppelin](https://www.openzeppelin.com)**  
  Provides a library of customizable template contracts for common Ethereum token deployments (e.g., ERC20, ERC721, ERC1155, Proxy). Note that these are not gas optimized. They provide the defacto standard for smart contract templates and are used across almost all existing smart contracts.
- **[Uniswap](https://github.com/Uniswap)**  
  A professional, easy-to-digest smart contract of the [Uniswap V2 pools](https://github.com/Uniswap/v2-core) that gives an overview of an in-production Solidity dApp. A guided walkthrough is available [here](https://ethereum.org/en/developers/tutorials/uniswap-v2-annotated-code/). For the more advanced Uniswap Pools, check out the Uniswap V3 [here](https://github.com/Uniswap/v3-core) and Uniswap V4 [here](https://github.com/Uniswap/v4-core).
- **[Morpho Finance](https://github.com/morpho-org)**  
   Morpho Finance's contracts provides an excellent real-world example of production-grade Solidity smart contracts, demonstrating how a successful DeFi lending protocol is structured and implemented. By studying Morpho's codebase, you can learn advanced patterns for gas optimization, security best practices, and complex financial logic implementation in a production environment. The accompanying documentation [here](https://docs.morpho.org/overview/) offers additional context to understand the protocol's architecture and design principles.
- **[Sky / Maker DAO](https://github.com/makerdao)**
  A pioneering DeFi protocol that created the DAI and USDS stablecoin. MakerDAO's codebase showcases complex financial mechanisms including collateralized debt positions, oracles, and governance systems. The project demonstrates how to implement a stable cryptocurrency backed by crypto collateral through sophisticated risk management systems.
- **[Rareskills Blog](https://rareskills.io/blog)**  
  Features in-depth articles on various Solidity concepts and their [Book of Gas Optimization](https://www.rareskills.io/post/gas-optimization).
- **[Foundry Fundamentals course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/foundry)**  
  A comprehensive web3 development course covering Foundry - the industry-standard framework for building, deploying, and testing smart contracts.
- **[Smart Contract Programmer YT channel](https://www.youtube.com/@smartcontractprogrammer)**  
  Contains many in-depth videos covering topics from ABI encoding to EVM memory management.
- **[DeFi developer roadmap](https://github.com/OffcierCia/DeFi-Developer-Road-Map)**

## Advanced Solidity

- **[Solmate repository](https://github.com/transmissions11/solmate)** and **[Solady repository](https://github.com/Vectorized/solady)**  
  Gas-optimized contracts using Solidity or Yul.
- **[Yul](https://docs.soliditylang.org/en/latest/yul.html)**  
  An intermediate language for Solidity, akin to inline assembly for the EVM, offering control flow constructs while exposing low-level memory management.
- **[Advanced Foundry course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/advanced-foundry)**  
  Teaches advanced smart contract development including building DeFi protocols, stablecoins, DAOs, and more.
- **[Smart Contract Security course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/learn)**  
  Provides comprehensive training on auditing and writing secure protocols.
- **[Assembly and Formal Verification course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/formal-verification)**  
  Covers Assembly, using Yul, EVM opcodes, formal verification testing, and related tools.
- **[Smart Contract DevOps course by Cyfrin Updraft](https://updraft.cyfrin.io/courses/wallets)**  
  Focuses on post-deployment security, wallet access control, and ongoing protocol maintenance.
- **[Secureum YT Channel](https://www.youtube.com/@SecureumVideos)**  
  Features a variety of videos covering topics from Solidity basics to advanced subjects such as fuzzing and auditing.

## Tutorials

- **[Ethernaut](https://ethernaut.openzeppelin.com)**  
  Learn Solidity by solving puzzles.
- **[Damn Vulnerable DeFi](https://www.damnvulnerabledefi.xyz)**  
  A series of smart contract challenges designed to test and improve your Solidity skills.

## Testing

- **[Echidna](https://github.com/crytic/echidna)**  
  Fuzz testing tool for Solidity.
- **[Slither](https://github.com/crytic/slither)**  
  A static analysis framework for detecting vulnerabilities.
- **[solidity-coverage](https://github.com/sc-forks/solidity-coverage)**  
  Provides code coverage metrics for Solidity tests.

## Smart contract archives

- **[Smart contract sanctuary](https://github.com/tintinweb/smart-contract-sanctuary)**  
  A collection of contracts verified on Etherscan.
- **[EVM function signature database](https://www.4byte.directory)**
- **[EVM verified contracts on Etherscan](https://etherscan.io/evm/evm-generalVerified)**
  If you are adventurous: Check the verified contracts on Etherscan directly.

## Using the OpenZeppelin Wizard

OpenZeppelin provides a convenient web-based wizard to create standard contracts. Visit the docs section for it [here](/evm/evm-wizard) or [https://wizard.openzeppelin.com/](https://wizard.openzeppelin.com/) to access it.

The wizard allows you to:

1. Select the contract type (ERC20, ERC721, ERC1155, etc.)
2. Configure settings, features, and access controls
3. Add custom functionality through a user-friendly interface
4. Generate ready-to-use Solidity code

The wizard is perfect for:

- Beginners learning smart contract development
- Quickly bootstrapping standard token contracts
- Exploring different configuration options
- Understanding best practices in contract development

## Best Practices & Security Considerations

When developing on Paxeer EVM with OpenZeppelin contracts, follow these best practices:

1. **Always use the latest version** of OpenZeppelin contracts
2. **Start with existing, audited components** rather than building from scratch
3. **Run comprehensive tests** before deploying to mainnet
4. **Consider upgradeability** for complex applications
5. **Use access controls** like `Ownable` or `AccessControl` for privileged functions
6. **Implement reentrancy guards** where needed
7. **Avoid `transfer()` and `send()`** for ETH transfers, use `call()` with reentrancy protection
8. **Validate all inputs** and check for edge cases
9. **Consider gas optimization**, but not at the expense of security
10. **Consider getting an audit** for high-value contracts

---

## Viewing Tokens in MetaMask

*Learn how to view and manage different token types in MetaMask with Paxeer network, including ERC20 tokens, ERC721 NFTs.*

## ERC20 Tokens

To view ERC20 tokens in MetaMask, the process mirrors that on other EVM chains.
For tokens not automatically listed, you'll need to manually import them into
your wallet. Detailed instructions can be found
[here](https://support.metamask.io/manage-crypto/tokens/how-to-display-tokens-in-metamask/).

## ERC721 NFTs

Viewing NFTs in MetaMask requires manual addition. Follow the steps provided
[here](https://support.metamask.io/manage-crypto/nfts/nft-tokens-in-your-metamask-wallet/)
to add and view your NFTs in the wallet.

---

## Transactions with paxd

*Complete guide to executing EVM transactions using the Paxeer CLI (paxd). Learn how to send tokens, deploy contracts, and interact with smart contracts.*

## Overview

EVM transactions on Paxeer allow you to interact with smart contracts, transfer tokens, deploy contracts, and manage various blockchain operations through the command line interface. This guide covers all available transaction types using the `paxd` CLI, from basic token transfers to complex contract interactions.

## Prerequisites

Sending transactions via CLI requires you to have keys configured in your local keyring. You can then specify the key you want to use by appending `--from=[key name]` to your command.

If you don't already have keys configured, you'll need to either generate a new key or import an existing one into your local keyring. Refer to this guide on [how to create a key](/evm/installing-paxd-cli) for more details.

## Network Configuration

If the machine you run these commands from is not a node of the network, you'd need to append the following to your commands:

```bash
--evm-rpc https://public-rpc.paxeer.app/evm/reference
```

Refer to the [RPC endpoints](/evm/networks) page for the list of available RPC endpoints.

<Info>Most commands support `--evm-rpc` flag to specify custom RPC endpoints. The default is `http://localhost:8545`.</Info>

## Common Transaction Flags

All transaction commands support these common flags:

- `--from=<sender>` - Specifies the key name to use for signing
- `--gas-fee-cap=<cap>` - Gas fee cap for the transaction (default varies by command)
- `--gas-limit=<limit>` - Gas limit for the transaction (default varies by command)
- `--evm-rpc=<url>` - EVM RPC endpoint URL (default: `http://localhost:8545`)
- `--nonce=<nonce>` - Nonce override for the transaction (-1 means auto-calculate)

## Address Management Commands

### Associate Address

Associates the Paxeer address and EVM address on-chain for the sending key. This is required for cross-layer interactions.

```bash
paxd tx evm associate-address [optional priv key hex] --from=<sender> --evm-rpc=<url>
```

**Parameters:**

- `[optional priv key hex]` - Optional private key in hex format. If not provided, uses the key from keyring.

**Example:**

```bash
paxd tx evm associate-address --from=mykey --evm-rpc=http://localhost:8545
```

**Output:**

```
Response: {"jsonrpc":"2.0","result":null,"id":"associate_addr"}
```

## Token Transfer Commands

### Send Native Tokens

Sends native tokens (uhpx) to the target EVM address.

```bash
paxd tx evm send [to EVM address] [amount in wei] --from=<sender> --gas-fee-cap=<cap> --gas-limit=<limit> --evm-rpc=<url>
```

**Parameters:**

- `[to EVM address]` - Destination EVM address (0x format)
- `[amount in wei]` - Amount to send in wei (smallest unit)

**Default Flags:**

- `--gas-fee-cap=1000000000000` (1000 Gwei)
- `--gas-limit=21000`

**Example:**

```bash
paxd tx evm send 0x1234567890abcdef1234567890abcdef12345678 1000000000000000000 --from=mykey
```

**Output:**

```
Transaction hash: 0x...
```

### Send ERC20 Tokens

Sends ERC20 tokens from a specific contract to a recipient.

```bash
paxd tx evm erc20-send [contract addr] [recipient] [amount] --from=<sender> --gas-fee-cap=<cap> --gas-limit=<limit> --evm-rpc=<url>
```

**Parameters:**

- `[contract addr]` - ERC20 contract address
- `[recipient]` - Recipient EVM address
- `[amount]` - Amount in smallest unit of the token

**Default Flags:**

- `--gas-fee-cap=1000000000000` (1000 Gwei)
- `--gas-limit=7000000`

**Example:**

```bash
paxd tx evm erc20-send 0xTokenContract123... 0xRecipient456... 1000000 --from=mykey
```

**Output:**

```
Transaction hash: 0x...
```

## Contract Deployment Commands

### Deploy Contract

Deploys an EVM contract from a binary file.

```bash
paxd tx evm deploy [path to binary] --from=<sender> --gas-fee-cap=<cap> --gas-limit=<limit> --evm-rpc=<url>
```

**Parameters:**

- `[path to binary]` - Path to the contract binary file

**Default Flags:**

- `--gas-fee-cap=1000000000000` (1000 Gwei)
- `--gas-limit=5000000`

**Example:**

```bash
paxd tx evm deploy ./MyContract.bin --from=mykey --gas-limit=8000000
```

**Output:**

```
Deployer: 0x...
Deployed to: 0x...
Transaction hash: 0x...
```

## Contract Interaction Commands

### Call Contract

Calls an EVM contract with a specific payload. You can generate payload by taking a look at docs [here](/evm/querying-the-evm#payload-generation).

```bash
paxd tx evm call-contract [addr] [payload hex] --value=<payment> --from=<sender> --gas-fee-cap=<cap> --gas-limit=<limit> --evm-rpc=<url>
```

**Parameters:**

- `[addr]` - Contract address
- `[payload hex]` - Function call data in hex format

**Default Flags:**

- `--gas-fee-cap=1000000000000` (1000 Gwei)
- `--gas-limit=7000000`
- `--value=0` - HPX value to send with the call

**Example:**

```bash
paxd tx evm call-contract 0xContract123... 0xa9059cbb000000... --value=1000000000000000000 --from=mykey
```

**Output:**

```
Transaction hash: 0x...
```

### Call Precompile

Calls a method on a precompiled contract. Precompiles provide EVM access to chain-specific functionality.

```bash
paxd tx evm call-precompile [precompile name] [method] [args...] --value=<payment> --from=<sender> --gas-fee-cap=<cap> --gas-limit=<limit> --evm-rpc=<url>
```

**Parameters:**

- `[precompile name]` - Name of the precompiled contract
- `[method]` - Method name to call
- `[args...]` - Method arguments

**Default Flags:**

- `--gas-fee-cap=1000000000000` (1000 Gwei)
- `--gas-limit=7000000`
- `--value=""` - HPX value to send (required for payable methods)

**Examples:**

_Delegate to validator (payable - uses --value):_

```bash
paxd tx evm call-precompile staking delegate paxvaloper1... --value=1000000000000000000 --from=mykey
```

**Available Precompiles:**

- `distribution` - Staking rewards management
- `json` - JSON parsing utilities
- `p256` - P256 cryptographic operations
- `staking` - Validator delegation and staking

<Info>For detailed information about each precompile's methods, parameters, and usage patterns, refer to the [EVM Precompiles documentation](/evm/precompiles/example-usage).</Info>

**Output:**

```
Transaction hash: 0x...
```

## Advanced Usage

### Custom Gas Settings

You can customize gas settings for any transaction:

```bash
paxd tx evm send 0x... 1000000000000000000 \
  --gas-fee-cap=2000000000000 \
  --gas-limit=100000 \
  --from=mykey
```

### Nonce Management

Override automatic nonce calculation:

```bash
paxd tx evm send 0x... 1000000000000000000 \
  --nonce=42 \
  --from=mykey
```

## Error Handling

<Warning>
**Common Issues:**

- Insufficient balance for transaction + gas
- Incorrect address formats (use 0x prefix for EVM addresses)
- Gas limit too low for complex operations
- Nonce conflicts in rapid successive transactions

</Warning>

## Best Practices

1. **Gas Estimation**: Start with default gas limits and adjust based on transaction complexity
2. **Address Validation**: Always verify addresses before sending transactions
3. **Key Management**: Use secure key storage and never expose private keys
4. **Network Verification**: Confirm you're connected to the correct network
5. **Transaction Monitoring**: Save transaction hashes for tracking purposes

## Transaction Requirements

- **Key Configuration**: Local keyring must contain the signing key
- **Sufficient Balance**: Account must have enough tokens for transaction amount + gas
- **Address Formats**: Use proper formats (0x... for EVM, paxvaloper... for validators)
- **Network Access**: Ensure connectivity to the specified RPC endpoint
- **Gas Limits**: Set appropriate gas limits for transaction complexity

For more detailed information about specific commands, use the help flag:

```bash
paxd tx evm [command] --help
```

---

## Transactions

*Learn how transactions work on Paxeer, including the transaction lifecycle, gas mechanics, and standard EVM transaction structure.*

Paxeer supports EVM transactions, allowing compatibility with Ethereum-based tools and contracts. Transactions are signed messages originating from an externally owned account (EOA) that trigger state changes on the blockchain.

## Transaction Lifecycle

| Stage             | Description                                                                                                          |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| 1. Creation       | A transaction is created by an EOA, specifying the recipient, value, gas parameters, and other fields.               |
| 2. Signing        | The transaction is signed with the sender's private key to create a valid signature.                                 |
| 3. Submission     | The signed transaction is submitted to the network through an RPC endpoint.                                          |
| 4. Mempool        | The transaction enters the mempool (transaction pool) where it awaits inclusion in a block.                          |
| 5. Execution      | When selected by a validator, the transaction is executed in the EVM, causing state changes.                         |
| 6. Validation     | The transaction and its state changes are validated by the consensus mechanism.                                      |
| 7. Confirmation   | Once validated, the transaction is included in a block and confirmed on-chain.                                       |
| 8. Finality       | On Paxeer, transactions achieve immediate finality once included in a block.                                             |

<Info>
  Unlike other EVM chains where you need to wait for multiple confirmations, Paxeer's consensus mechanism provides immediate transaction finality. Once a transaction is included in a block, it cannot be reversed.
</Info>

## Gas Mechanics

Gas is a unit of computational work in the EVM that helps prevent spam and allocate resources efficiently:

| Term                 | Description                                                                                                                 |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Gas Limit            | The maximum amount of gas the transaction may consume, set by the sender.                                                   |
| Base Fee             | The minimum gas price required to be included in a block. On Paxeer, the base fee is not burned - all fees go to validators.  |
| Priority Fee         | An additional fee (tip) paid to validators for faster inclusion.                                                            |
| Gas Price            | In legacy transactions, the price per unit of gas the sender is willing to pay.                                             |
| Effective Gas Price  | The actual price paid per unit of gas (base fee + priority fee in EIP-1559).                                                |

<Warning>
  **Gas Requirements for Common Operations:**
  - Simple HPX transfer: 21,000 gas
  - ERC-20 transfer: ~45,000 gas
  - Contract deployment: Varies based on contract size and complexity
  - Always estimate gas before sending transactions using `eth_estimateGas`
</Warning>

## Transaction Structure

EVM transactions in Paxeer follow the Ethereum transaction format with standard properties:

<Tabs>
  <Tab title="Transaction Properties">
    | Property | Description |
    | --- | --- |
    | `from` | The address of the sender who will sign the transaction. This must be an externally-owned account (EOA) as contract accounts cannot send transactions. |
    | `to` | The receiving address. If this is an EOA, the transaction transfers value. If a contract address, the transaction executes the contract code. If empty or null, the transaction creates a new contract. |
    | `signature` | The cryptographic signature generated when the sender's private key signs the transaction. This confirms the sender has authorized the transaction and includes the v, r, and s components. |
    | `nonce` | A sequentially incrementing counter that indicates the transaction number from the account. This prevents replay attacks and ensures transaction ordering. |
    | `data` | The input data (also called 'input' or 'calldata') for contract execution. For simple transfers, this is usually empty. For contract interactions, this contains the function selector and encoded arguments. |
    | `value` | Amount of HPX to transfer from sender to recipient (denominated in WEI, where 1 HPX equals 1e+18 WEI). |
    | `gasLimit` | The maximum amount of gas units that can be consumed by the transaction. Often referred to as 'gas' in transaction objects. |
    | `maxPriorityFeePerGas` | The maximum price of the consumed gas to be included as a tip to the validator (denominated in WEI). Used in EIP-1559 transactions. |
    | `maxFeePerGas` | The maximum fee per unit of gas willing to be paid for the transaction (inclusive of baseFeePerGas and maxPriorityFeePerGas). Used in EIP-1559 transactions. |
    | `gasPrice` | The price per unit of gas the sender is willing to pay (denominated in WEI). Used in legacy transactions. |
    | `chainId` | The chain identifier number. Prevents transaction reuse across different chains. |
    | `accessList` | A list of addresses and storage keys that the transaction plans to access. Used in EIP-2930 and EIP-1559 transactions to reduce gas costs for accessing specified addresses and storage slots. |
    | `type` | The transaction type: 0 for legacy (pre-EIP-2718), 1 for EIP-2930 access list transactions, and 2 for EIP-1559 fee market transactions. |
    | `hash` | The transaction hash, a unique identifier for the transaction generated after signing. |
  </Tab>

  <Tab title="Transaction Types">
    ### Legacy Transactions (Type 0)

    Pre-EIP-1559 transaction format that specifies a single gasPrice.

    ```json
    {
      "from": "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db",
      "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0",
      "gas": "0x55555",
      "gasPrice": "0x1234",
      "value": "0x1234",
      "data": "0xabcd",
      "nonce": "0x0"
    }
    ```

    ### Access List Transactions (Type 1, EIP-2930)

    Transactions with an optional access list of addresses and storage keys to reduce gas costs.

    ```json
    {
      "type": "0x1",
      "from": "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db",
      "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0",
      "gas": "0x55555",
      "gasPrice": "0x1234",
      "value": "0x1234",
      "data": "0xabcd",
      "nonce": "0x0",
      "accessList": [
        {
          "address": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0",
          "storageKeys": [
            "0x0000000000000000000000000000000000000000000000000000000000000000"
          ]
        }
      ]
    }
    ```

    ### Fee Market Transactions (Type 2, EIP-1559)

    Transaction format that supports dynamic base fees with a priority fee tip to validators.

    ```json
    {
      "type": "0x2",
      "from": "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db",
      "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0",
      "gas": "0x55555",
      "maxFeePerGas": "0x1234",
      "maxPriorityFeePerGas": "0x1234",
      "value": "0x1234",
      "data": "0xabcd",
      "nonce": "0x0",
      "accessList": []
    }
    ```
  </Tab>

  <Tab title="Example Request">
    ### Example Request: Sending an EIP-1559 Transaction

    ```json
    {
      "jsonrpc": "2.0",
      "method": "eth_sendTransaction",
      "params": [
        {
          "from": "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db",
          "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0",
          "gas": "0x55555",
          "maxFeePerGas": "0x1234",
          "maxPriorityFeePerGas": "0x1234",
          "value": "0x1234",
          "data": "0xabcd",
          "nonce": "0x0"
        }
      ],
      "id": 2
    }
    ```

    ### JavaScript example with web3.js

    <Info>
      Public RPC endpoints such as `https://evm-rpc.sei-apis.com` do not manage or unlock accounts, so `eth_getAccounts` and `eth_sendTransaction` are not available. Sign transactions locally with a private key and broadcast the raw transaction instead.
    </Info>

    ```javascript
    // Example using web3.js v4 to sign and broadcast a transaction.
    // Public RPC endpoints do not manage accounts, so sign locally with a private key.
    const { Web3 } = require('web3');
    const web3 = new Web3('https://evm-rpc.sei-apis.com');

    // Load your account from a private key. Never hard-code keys - read from an env var.
    const account = web3.eth.accounts.privateKeyToAccount(process.env.PRIVATE_KEY);

    async function sendTransaction() {
      // Current nonce for the sender
      const nonce = await web3.eth.getTransactionCount(account.address);

      // Use the latest base fee to set EIP-1559 fees
      const block = await web3.eth.getBlock('latest');
      const maxPriorityFeePerGas = web3.utils.toWei('1', 'gwei');
      const maxFeePerGas = (BigInt(block.baseFeePerGas) + BigInt(maxPriorityFeePerGas)).toString();

      const tx = {
        from: account.address,
        to: '0x07a565b7ed7d7a678680a4c162885bedbb695fe0',
        value: web3.utils.toWei('0.1', 'ether'),
        gas: 21000, // Gas limit for a simple transfer
        maxFeePerGas,
        maxPriorityFeePerGas,
        nonce,
        chainId: 1329 // hyperpax_125-1 mainnet (use 1328 for  testnet)
      };

      // Sign locally, then broadcast the raw transaction
      const signed = await web3.eth.accounts.signTransaction(tx, process.env.PRIVATE_KEY);
      const receipt = await web3.eth.sendSignedTransaction(signed.rawTransaction);
      console.log('Transaction receipt:', receipt);
    }

    sendTransaction().catch(console.error);
    ```
  </Tab>

  <Tab title="Example Response">
    ### `eth_sendTransaction`

    ```json
    {
      "jsonrpc": "2.0",
      "id": 2,
      "result": "0xeba2df809e7a612a0a0d444ccfa5c839624bdc00dd29e3340d46df3870f8a30e"
    }
    ```

    ### `eth_getTransactionByHash`

    ```json
    {
      "jsonrpc": "2.0",
      "id": 3,
      "result": {
        "blockHash": "0x5d15649e25d8e7c60b5a1cb3612b6b45dceaa3c774f438d4d5b4e1e1b2db634a",
        "blockNumber": "0x92a",
        "from": "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db",
        "gas": "0x55555",
        "gasPrice": "0x1234",
        "hash": "0xeba2df809e7a612a0a0d444ccfa5c839624bdc00dd29e3340d46df3870f8a30e",
        "input": "0xabcd",
        "nonce": "0x0",
        "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0",
        "transactionIndex": "0x1",
        "value": "0x1234",
        "type": "0x2",
        "accessList": [],
        "chainId": "0x1",
        "maxFeePerGas": "0x1234",
        "maxPriorityFeePerGas": "0x1234",
        "v": "0x0",
        "r": "0x223a7c9bcf5531c99be5ea7082183816eb20cfe0bbc322e97cc5c7f71ab8b20e",
        "s": "0x2aadee6b34b45bb15bc42d9c09de4a6754e7000908da72d48cc7704971491663"
      }
    }
    ```

    ### Transaction receipt

    ```json
    {
      "jsonrpc": "2.0",
      "id": 4,
      "result": {
        "transactionHash": "0xeba2df809e7a612a0a0d444ccfa5c839624bdc00dd29e3340d46df3870f8a30e",
        "transactionIndex": "0x1",
        "blockHash": "0x5d15649e25d8e7c60b5a1cb3612b6b45dceaa3c774f438d4d5b4e1e1b2db634a",
        "blockNumber": "0x92a",
        "from": "0x1923f626bb8dc025849e00f99c25fe2b2f7fb0db",
        "to": "0x07a565b7ed7d7a678680a4c162885bedbb695fe0",
        "cumulativeGasUsed": "0xd190",
        "gasUsed": "0x5208",
        "contractAddress": null,
        "logs": [],
        "status": "0x1",
        "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
        "effectiveGasPrice": "0x1234",
        "type": "0x2"
      }
    }
    ```
  </Tab>
</Tabs>

## Transaction Guidelines

<Info>
  **Transaction Best Practices:**

  - **Set appropriate gas parameters:** Use network conditions to estimate optimal values for `maxFeePerGas` and `maxPriorityFeePerGas`.
  - **Manage nonces carefully:** Track and increment nonces correctly to avoid transaction failures.
  - **Use typed transactions:** Prefer EIP-1559 transactions (type 2) for more predictable fees.
  - **Implement proper error handling:** Account for potential transaction failures and revert reasons.
  - **Verify recipient addresses:** Always double-check destination addresses, as transactions cannot be reversed.
</Info>

| Common Issue | Cause | Solution |
| --- | --- | --- |
| Transaction Underpriced | Gas price or priority fee too low | Increase `maxFeePerGas` and `maxPriorityFeePerGas` |
| Nonce Too Low | Using a nonce that's already been used | Query current nonce with `getTransactionCount` |
| Out of Gas | Gas limit too low for the operation | Use `eth_estimateGas` to set appropriate limit |
| Contract Execution Failed | Contract function reverted | Test with `eth_call` before sending transaction |

## Additional Resources

<Columns cols={3}>
  <Card horizontal title="RPC Reference" icon="circle-info" href="/evm/reference">
    Complete documentation of Paxeer's EVM RPC endpoints for transaction creation and monitoring
  </Card>
  <Card horizontal title="Gas & Fees" icon="coins" href="/learn/dev-gas">
    Learn more about gas calculation, fee estimation, and cost optimization on Paxeer
  </Card>
  <Card horizontal title="Accounts" icon="user" href="/learn/accounts">
    Understanding Externally Owned Accounts and Contract Accounts on Paxeer
  </Card>
</Columns>

---

## Paxeer Network Accounts: Dual Address System

*How Paxeer's unified account system links EVM (0x) and Cosmos (pax1) addresses, including association methods.*

Every account on Paxeer has a unique public key. This public key derives two wallet addresses that point to the same account.

- **"hex" address**: Starts with `0x` and is EVM-based.

- **"bech32" address**: Starts with `pax1` and is used for Cosmos functions.

These addresses share the same underlying account. Once associated, depositing funds into one address makes them accessible from the other. Until associated, they are treated as separate accounts with separate balances.

## Key points

### Before linking

- The bech32 (`pax1...`) and EVM (`0x...`) addresses are treated as **separate accounts**.
- They will have separate balances until linked.
- Cosmos tokens received by the EVM address prior to association will be held in a temporary bech32 address, which transfers to the associated address upon linking.
- Some types of transactions will **not be possible** (see table below).

### After linking

- Balances are reflected consistently across both addresses.
- Applications can query either address format seamlessly.

## Wallet association and transfer limitations

Certain actions are **not possible** before wallets are associated:

- Transfers of Cosmos-based tokens from a non-EVM wallet to an **unassociated EVM address**.
- Transfers of ERC-based tokens (ERC-20/721/1155) from an EVM wallet to an **unassociated Cosmos address**.

## Methods of association

| Method | Security Risk | User Action Required |
| --- | --- | --- |
| 1. Broadcast a Transaction | Low | Association happens automatically |
| 2. Direct Private Key | High | Provide private key directly |
| 3. Signed Message | Medium | Sign a predefined message to prove ownership *(recommended for wallets)* |
| 4. Public Key | Low | Provide a compressed public key for association |

<Info>Each method ensures the **public key** is known to the chain, enabling automatic association between the EVM-compatible and bech32 addresses. All four go through the on-chain `addr` precompile (`0x0000000000000000000000000000000000001004`) or the EVM ante handler.</Info>

## Method 1: Broadcast a transaction

When an account broadcasts a transaction, its public key is recorded on-chain and the addresses are linked automatically.

## Method 2: Direct private key association

<Danger>**Security Risk**: **High** - Requires the private key to be directly available. Exposing the private key can compromise the wallet.</Danger>

```ts
import { createPublicClient, createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { ADDRESS_PRECOMPILE_ABI, ADDRESS_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';

const PRIVATE_KEY = '<replace_with_private_key>';

const publicClient = createPublicClient({
  chain: { id: 125, rpcUrls: { default: { http: ['https://public-rpc.paxeer.app/evm/reference'] } } },
  transport: http('https://public-rpc.paxeer.app/evm/reference')
});
const client = createWalletClient({
  chain: { id: 125, rpcUrls: { default: { http: ['https://public-rpc.paxeer.app/evm/reference'] } } },
  transport: http('https://public-rpc.paxeer.app/evm/reference')
});

const account = privateKeyToAccount(PRIVATE_KEY);

const response = await client.writeContract({
  account,
  address: ADDRESS_PRECOMPILE_ADDRESS,
  abi: ADDRESS_PRECOMPILE_ABI,
  functionName: 'associate',
  args: ['0', '0', '0', 'example_message'],
  gasPrice: BigInt(100_000_000_000)
});
console.log(response);
```

## Method 3: Associate via signed message

<Warning>**Security Risk**: **Medium** - Requires signing a specific message using the private key.</Warning>

```ts
import { createWalletClient, http, parseSignature, toHex } from 'viem';
import { privateKeyToAccount, generatePrivateKey } from 'viem/accounts';
import { ADDRESS_PRECOMPILE_ABI, ADDRESS_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';

const client = createWalletClient({
  chain: { id: 125, rpcUrls: { default: { http: ['https://public-rpc.paxeer.app/evm/reference'] } } },
  transport: http('https://public-rpc.paxeer.app/evm/reference')
});

const associate = async () => {
  const account = privateKeyToAccount('<replace_with_private_key>');
  const newPk = generatePrivateKey();
  const newAccount = privateKeyToAccount(newPk);

  const message = 'associate';
  const signature = await newAccount.signMessage({ message });
  const parsedSignature = parseSignature(signature);
  const customMessage = `\x19Ethereum Signed Message:\n${message.length}${message}`;

  const response = await client.writeContract({
    account,
    address: ADDRESS_PRECOMPILE_ADDRESS,
    abi: ADDRESS_PRECOMPILE_ABI,
    functionName: 'associate',
    args: [toHex(Number(parsedSignature.v) - 27), parsedSignature.r, parsedSignature.s, customMessage],
    gasPrice: BigInt(100_000_000_000)
  });
  console.log(response);
};

associate();
```

## Method 4: Associate via public key

<Info>**Security Risk**: **Low** - Uses the public key, which is less sensitive than the private key.</Info>

```ts
import secp256k1 from 'secp256k1';
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount, generatePrivateKey } from 'viem/accounts';
import { ADDRESS_PRECOMPILE_ABI, ADDRESS_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';

const client = createWalletClient({
  chain: { id: 125, rpcUrls: { default: { http: ['https://public-rpc.paxeer.app/evm/reference'] } } },
  transport: http('https://public-rpc.paxeer.app/evm/reference')
});

const associateViaPubkey = async () => {
  const account = privateKeyToAccount('<replace_with_private_key>');
  const newPk = generatePrivateKey();
  const newAccount = privateKeyToAccount(newPk);

  const publicKeyBuffer = Buffer.from(newAccount.publicKey.slice(2), 'hex');
  const compressedPubKey = secp256k1.publicKeyConvert(publicKeyBuffer, true);

  const response = await client.writeContract({
    account,
    address: ADDRESS_PRECOMPILE_ADDRESS,
    abi: ADDRESS_PRECOMPILE_ABI,
    functionName: 'associatePubKey',
    args: [Buffer.from(compressedPubKey).toString('hex')],
    gasPrice: BigInt(100_000_000_000)
  });
  console.log(response);
};

associateViaPubkey();
```

## Query linked addresses

Resolve either side of an existing association by calling the `addr` precompile at `0x0000000000000000000000000000000000001004` over a standard `eth_call`.

### Fetch bech32 address for an EVM address

```bash
curl -X POST https://public-rpc.paxeer.app/evm/reference -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0",
  "method": "eth_call",
  "params": [{
    "to": "0x0000000000000000000000000000000000001004",
    "data": "0x0c3c20ed000000000000000000000000<evmAddressWithout0x>"
  }, "latest"],
  "id": 1
}'
```

The selector `0x0c3c20ed` is `getSeiAddr(address)` (inherited from the Cosmos SDK). The returned ABI-encoded string is the bech32 `pax1...` address, or the call reverts if the EVM address is not yet associated.

In TypeScript with viem:

```ts
import { createPublicClient, http, defineChain } from 'viem';

const paxeer = defineChain({
  id: 125,
  name: 'Paxeer Network',
  nativeCurrency: { name: 'PAX', symbol: 'PAX', decimals: 18 },
  rpcUrls: { default: { http: ['https://public-rpc.paxeer.app/evm/reference'] } }
});

const ADDR_PRECOMPILE = '0x0000000000000000000000000000000000001004';
const ADDR_ABI = [
  { name: 'getSeiAddr', type: 'function', stateMutability: 'view',
    inputs: [{ name: 'addr', type: 'address' }],
    outputs: [{ name: 'response', type: 'string' }] },
  { name: 'getEvmAddr', type: 'function', stateMutability: 'view',
    inputs: [{ name: 'addr', type: 'string' }],
    outputs: [{ name: 'response', type: 'address' }] },
] as const;

const client = createPublicClient({ chain: paxeer, transport: http() });

const paxAddr = await client.readContract({
  address: ADDR_PRECOMPILE,
  abi: ADDR_ABI,
  functionName: 'getSeiAddr',
  args: ['0x...'],
});
```

### Fetch EVM address for a bech32 address

```ts
const evmAddr = await client.readContract({
  address: ADDR_PRECOMPILE,
  abi: ADDR_ABI,
  functionName: 'getEvmAddr',
  args: ['pax1...'],
});
```

The precompile reverts if the address has never been associated - surface this as "not linked" rather than re-throwing.

## Deriving addresses from the public key

Both address formats come from the same secp256k1 public key, but they use **different hashing schemes**: the bech32 (`pax1...`) side follows standard Cosmos derivation (`SHA256` then `RIPEMD160` of the **compressed** pubkey), and the EVM (`0x...`) side follows standard Ethereum derivation (`keccak256` of the **uncompressed** pubkey without its `0x04` prefix byte).

### Bech32 address derivation

The Cosmos address is derived from the public key using the following steps:

1. Take the **compressed** secp256k1 public key (33 bytes; first byte `0x02` or `0x03`).
2. Hash it with `SHA256`.
3. Hash the result with `RIPEMD160` to get a 20-byte digest.
4. Encode that digest in **Bech32 format** with the `pax` prefix.

Example implementation:

```ts
import { bech32 } from 'bech32';
import { sha256 } from '@noble/hashes/sha256';
import { ripemd160 } from '@noble/hashes/ripemd160';

/**
 * @param compressedPublicKey 33-byte secp256k1 pubkey in compressed form
 */
export function derivePaxeerAddress(compressedPublicKey: Uint8Array): string {
  const digest = ripemd160(sha256(compressedPublicKey));
  return bech32.encode('pax', bech32.toWords(digest));
}
```

### EVM address derivation

The EVM-compatible address is derived as follows:

1. Take the **uncompressed** secp256k1 public key (65 bytes; first byte `0x04`).
2. Drop the leading `0x04` prefix byte so the input to the hash is the bare 64-byte `(x, y)` coordinate pair.
3. Hash with `keccak256`.
4. Take the **last 20 bytes** of the hash and format as `0x...` hex.

Example implementation:

```ts
import { keccak_256 } from '@noble/hashes/sha3';

/**
 * @param uncompressedPublicKey 65-byte secp256k1 pubkey in uncompressed form (leading 0x04)
 */
export function deriveEVMAddress(uncompressedPublicKey: Uint8Array): string {
  const hash = keccak_256(uncompressedPublicKey.slice(1));
  return `0x${Buffer.from(hash.slice(-20)).toString('hex')}`;
}
```

### Summary

- **Paxeer address**: `bech32('pax', RIPEMD160(SHA256(compressedPubKey)))` - 20 bytes, Cosmos-standard derivation.
- **EVM address**: `'0x' + keccak256(uncompressedPubKey[1:])[-20:]` - last 20 bytes of the keccak256 hash, Ethereum-standard derivation.
- The two formats share an account because the chain stores the **public key** itself on association; either format can be derived from it deterministically.

## HD paths and coin types

The HD path's second parameter specifies the coin type, defined by BIP-44:

- **Ethereum (Coin Type 60)**: Wallets like MetaMask use coin type 60. The HD path is `m/44'/60'/0'/0/0`.
- **Cosmos (Coin Type 118)**: Cosmos-based wallets use coin type 118. The HD path is `m/44'/118'/0'/0/0`.

A mnemonic for coin type 60 (Ethereum) derives different keys than coin type 118 (Cosmos). Export your private key from MetaMask and import it into a Cosmos wallet to access the same account across ecosystems.

## Generating wallets

<Accordion title="TypeScript - full derivation from private key">

```typescript
import { sha256 } from '@noble/hashes/sha256';
import { ripemd160 } from '@noble/hashes/ripemd160';
import { keccak_256 } from '@noble/hashes/sha3';
import { secp256k1 } from '@noble/curves/secp256k1';
import { bech32 } from 'bech32';

function convertBits(data: Uint8Array, fromBits: number, toBits: number, pad: boolean): number[] {
  let acc = 0;
  let bits = 0;
  const result: number[] = [];
  const maxv = (1 << toBits) - 1;

  for (const value of data) {
    acc = (acc << fromBits) | value;
    bits += fromBits;
    while (bits >= toBits) {
      bits -= toBits;
      result.push((acc >> bits) & maxv);
    }
  }

  if (pad) {
    if (bits > 0) {
      result.push((acc << (toBits - bits)) & maxv);
    }
  } else if (bits >= fromBits || (acc << (toBits - bits)) & maxv) {
    throw new Error('Unable to convert bits');
  }

  return result;
}

function generateAddresses(privateKeyHex: string): {
  paxAddress: string;
  ethAddress: string;
} {
  const privateKey = Uint8Array.from(Buffer.from(privateKeyHex.padStart(64, '0'), 'hex'));
  if (privateKey.length !== 32) {
    throw new Error('Private key must be 32 bytes long.');
  }

  const publicKey = secp256k1.getPublicKey(privateKey, true);
  const sha256Digest = sha256(publicKey);
  const ripemd160Digest = ripemd160(sha256Digest);
  const fiveBitArray = convertBits(ripemd160Digest, 8, 5, true);
  const paxAddress = bech32.encode('pax', fiveBitArray, 256);

  const publicKeyUncompressed = secp256k1.getPublicKey(privateKey, false).slice(1);
  const keccakHash = keccak_256(publicKeyUncompressed);
  const ethAddress = `0x${Buffer.from(keccakHash).slice(-20).toString('hex')}`;

  return { paxAddress, ethAddress };
}

const privateKeyHex = '907ab4bf7fc60cff';
const { paxAddress, ethAddress } = generateAddresses(privateKeyHex);

console.log(`Paxeer Address: ${paxAddress}`);
console.log(`Ethereum Address: ${ethAddress}`);
```

</Accordion>

---

## Paxeer Network Chain Configuration

*Connect to Paxeer Network mainnet with chain IDs, RPC endpoints, and MetaMask configuration for EVM and Cosmos environments.*

Paxeer Network runs a single production chain. There is no public testnet at this time.

## Mainnet

Paxeer mainnet is the production environment for all transactions, contract deployments, and agent activity.

| Parameter | Value |
| --- | --- |
| **Network Name** | Paxeer Network |
| **Cosmos Chain ID** | `hyperpax_125-1` |
| **EVM Chain ID** | `125` (`0x7D`) |
| **Currency Symbol** | PAX |
| **Base Denom** | `uhpx` |
| **EVM RPC** | `https://public-rpc.paxeer.app/evm/reference` |
| **Block Explorer** | `https://paxscan.io` |
| **Bech32 Prefix** | `pax` |

## Add Paxeer to MetaMask

Use the snippet below to add Paxeer mainnet to MetaMask programmatically:

```js
await window.ethereum.request({
  method: 'wallet_addEthereumChain',
  params: [{
    chainId: '0x7D',
    chainName: 'Paxeer Network',
    nativeCurrency: {
      name: 'PAX',
      symbol: 'PAX',
      decimals: 18
    },
    rpcUrls: ['https://public-rpc.paxeer.app/evm/reference'],
    blockExplorerUrls: ['https://paxscan.io']
  }]
});
```

## Using `paxd`

The Paxeer binary is `paxd`. The default home directory is `~/.paxeer`.

```sh
# Check node status
paxd status

# Query account balance
paxd query bank balances <pax1_address> --node https://public-rpc.paxeer.app/evm/reference
```

## Local development

You can run a local Paxeer node for development and testing. Set the chain ID to any value you choose - it will not conflict with mainnet.

- **Purpose**: Local development and testing
- **Chain ID**: Set by user (default: `paxeer-local`)

Refer to the [Nodes Introduction](/node) section for instructions on running a local chain.

---

## Gas

*Understand gas pricing, limits, and optimization strategies for Paxeer Network transactions, with guides for sending transactions using paxd and EVM interfaces.*

Gas measures the computational effort required to execute a transaction or contract on Paxeer Network. Gas fees are paid in PAX (denominated in `uhpx` on the Cosmos side).

## Key terms and concepts

### Gas

A unit representing the work done to execute a transaction. Gas varies based on operation complexity.

### Gas price

The amount of PAX paid per unit of gas. Set by the user.

### Gas limit

The maximum gas the transaction may consume. If too low, the transaction fails and the full gas limit is consumed.

### Fee

```
Fee = Gas Price × Gas Used
```

The gas limit caps the maximum charge at `Gas Price × Gas Limit`. On Paxeer, excess gas may not be fully refunded, so avoid setting gas limits far above what a transaction needs.

### Maximum gas

Query the maximum gas limit from the RPC node using the `/consensus_params` endpoint.

### Minimum gas price

Paxeer enforces minimum gas prices to prevent spam.

### Max bytes

Each transaction has a maximum size in bytes. Query via `/consensus_params`.

### Max gas for queries

Queries consume gas. The maximum is RPC-specific.

## Sending gas in transactions

### Using `paxd`

With `paxd`, set the fee using the `--fees` flag. Gas limit and gas price use `--gas` and `--gas-prices` respectively.

```sh
paxd tx bank send <from_address> <to_address> <amount> --gas <gas_limit> --gas-prices <gas_price> --fees <fee>
```

### Using EVM (wagmi)

```ts
import { parseEther, parseGwei } from 'viem';
import { sendTransaction } from '@wagmi/core';
import { config } from './config'; // your wagmi config

await sendTransaction(config, {
  to: '0xRecipientAddress',
  value: parseEther('1'), // 1 PAX
  gasPrice: parseGwei('100'), // 100 gwei
  gas: 21000n
});
```

## Optimizing gas for smart contracts

- Minimize storage operations.
- Use fixed-size data structures where possible.
- Avoid unnecessary computations.
- Use events for data that doesn't need on-chain reads.

## Estimating gas prices

Paxeer's EVM RPC exposes standard Ethereum JSON-RPC methods for gas estimation:

- `eth_gasPrice` - current recommended gas price for legacy transactions.
- `eth_maxPriorityFeePerGas` - suggested priority fee for EIP-1559 transactions.
- `eth_feeHistory` - recent base fees and priority-fee percentiles.

Query the current gas price on mainnet:

```sh
curl -sS https://public-rpc.paxeer.app/evm/reference \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}'
```

With viem:

```ts
import { createPublicClient, http, defineChain } from 'viem';

const paxeer = defineChain({
  id: 125,
  name: 'Paxeer Network',
  nativeCurrency: { name: 'PAX', symbol: 'PAX', decimals: 18 },
  rpcUrls: {
    default: { http: ['https://public-rpc.paxeer.app/evm/reference'] }
  }
});

const client = createPublicClient({
  chain: paxeer,
  transport: http()
});

// Legacy gas price
const gasPrice = await client.getGasPrice();

// EIP-1559 fee suggestion
const { maxFeePerGas, maxPriorityFeePerGas } = await client.estimateFeesPerGas();
```

---

## Paxeer Interoperability Framework

*Understand how Paxeer enables seamless interaction between EVM and Cosmos ecosystems through its dual address system and precompiles.*

<Info>
  **CosmWasm deployments are frozen, and inbound IBC is being disabled.** No new CosmWasm contracts can be uploaded or instantiated on Paxeer. Inbound IBC transfers are disabled, so IBC assets bridged from Cosmos chains can no longer arrive on Paxeer. The interoperability features described on this page apply to **already-deployed** CosmWasm contracts, native Bank Module assets, and Cosmos-SDK modules accessed via precompiles. For new smart contract development, build directly on the EVM.
</Info>

## Dual Address Support

Paxeer utilizes two distinct address types:

- **EVM (0x) address:** Ethereum-style addresses, with "0x" prefix.
- **Cosmos address:** Bech-32 addresses, with "pax1" prefix.

Both addresses are derived from the same public key, ensuring seamless asset
integration across formats.

## Virtual Machine Interoperability

EVM and existing CosmWasm-based smart contracts co-exist on Paxeer, but live in
different execution environments. This creates a challenge for users, who use
wallets that typically only support a single execution environment. Likewise for
developers, existing tooling and libraries can only interact with either EVM or
Wasm (Think EthersJS vs CosmJS).

To bridge the gap between EVM and Wasm, Paxeer exposes Cosmos-SDK modules and
already-deployed CosmWasm contracts to the EVM via precompiled contracts. New
smart contracts on Paxeer should be deployed on the EVM directly.

## Precompile Contracts

Paxeer precompiles are smart contracts embedded directly within the Paxeer EVM
environment. They provide a gateway for users and developers to access
Cosmos-SDK functions through the EVM RPC interface.

For instructions on utilizing EVM precompiles, refer to the
[Example Usage](/evm/precompiles/example-usage) section.

## Example Diagram

![Interoperability](/assets/interoperability.png)
*Enabling seamless access to all tokens and contracts on Paxeer*

---

## Token Standards

*Explore token standards on Paxeer Network including native PAX, ERC-20, ERC-721, ERC-1155, and USDX on LayerX.*

Paxeer Network supports native tokens and EVM smart contract tokens. Use ERC-20, ERC-721, or ERC-1155 for all new token deployments.

## PAX - native token

PAX is the native token of Paxeer Network. It serves two primary roles:

- **Gas token**: Used to pay transaction fees on the Paxeer L1.
- **Staking and governance**: Used to secure the network through staking and to participate in on-chain governance.

### Denominations

**EVM**

```
1 PAX = 10^18 wei = 1_000_000_000_000_000_000 wei
1 PAX = 10^9 gwei = 1_000_000_000 gwei
```

**Cosmos**

```
1 PAX = 10^18 uhpx (atto-HPX)
1 PAX = 10^9 nhpx (nano-HPX)
1 PAX = 10^6 uhpx (micro-HPX, base denom)
1 gwei = 1 nhpx
```

The base denomination on the Cosmos side is `uhpx`.

## Fungible tokens

### ERC-20

ERC-20 defines a standard interface for fungible tokens.

**Use ERC-20 for any new fungible token on Paxeer.**

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/evm/evm-general/token/ERC20/ERC20.sol";

contract MyToken is ERC20 {
    constructor() ERC20("MyToken", "MTK") {
        _mint(msg.sender, 1_000_000 * 10 ** decimals());
    }
}
```

Deploy using Hardhat, Foundry, or Remix - standard Ethereum tooling works without modification.

## NFTs

Non-fungible tokens represent unique digital assets. Paxeer supports the following EVM standards:

- **ERC-721**: The standard for non-fungible tokens. Each token has a unique ID and metadata.
- **ERC-1155**: A multi-token standard supporting both fungible and non-fungible tokens in a single contract.
- **ERC-2981**: Defines a royalty mechanism, ensuring creators receive a percentage of secondary sales.

**Use ERC-721 or ERC-1155 for any new NFT collection on Paxeer.**

## USDX on LayerX

USDX is the stable-value asset used for payments on LayerX. It is the settlement currency for 402LXP agent payments and Deus marketplace transactions.

- **Settlement**: Instant, zero-fee settlement on LayerX.
- **Anchoring**: LayerX batches are anchored to the Paxeer L1, inheriting full L1 security.
- **Usage**: Agents and APIs price services in USDX; payments flow via the 402LXP HTTP payment rail.

USDX is not deployed as a standard ERC-20 on L1 - it operates natively within the LayerX execution environment.

---

## Paxeer Block Explorer Guide

*Use the PaxScan block explorer to track transactions, analyze addresses, and monitor network activity on Paxeer.*

## What Is a Block Explorer?

A block explorer offers tools for viewing on-chain data:

- **Transaction Tracking**: View transaction hashes, input/output data, tokens transferred, fees paid, and error messages.
- **Block Information**: Block height, timestamp, size, and included transactions.
- **Address Queries**: Wallet balances, transaction history, and contract details.
- **Network Statistics**: Block count, throughput, staking, and governance data.
- **Smart Contracts**: Query contract state, deployments, and source code.

<Info>
  Off-chain data should be used as a guide only.
</Info>

## Paxeer Explorer

[PaxScan](https://paxscan.io) is the primary block explorer for Paxeer. It supports both EVM (`0x`) and Cosmos (`pax1`) address lookups, transaction history, contract verification, and network statistics for the Paxeer mainnet.

---

## Paxeer Testnet Faucet

*Paxeer has no public testnet yet; learn to test using mainnet forks with Hardhat or Foundry and stay updated via official channels.*

<Info>Paxeer currently operates a single mainnet network. No public testnet is available at this time.</Info>

## Testnet Status

Paxeer does not currently have a public testnet. All transactions and contract deployments should target mainnet directly.

For development and testing, you can use a local node or fork the mainnet state using standard EVM tooling such as Hardhat or Foundry.

## Stay Updated

Follow [@paxeer_app](https://x.com/paxeer_app) or join the community channels for announcements regarding future testnet availability.

---

## General Governance

*Learn how Paxeer's on-chain governance works, including proposal submission, voting periods, quorum rules, and mainnet parameters for PAX holders.*

**Decentralized Decision Making**

Paxeer employs an on-chain governance system that enables PAX holders to participate in the decision-making process for the network. This system is built on the Cosmos SDK governance module with enhancements specific to Paxeer's architecture.

## How Governance Works

1. **Proposal Submission** - Anyone can submit a governance proposal with an initial deposit.
2. **Deposit Period** - Community members can contribute to the proposal deposit.
3. **Voting Period** - Once minimum deposit is reached, voting begins.
4. **Execution** - Approved proposals are automatically executed.

### Governance Logic

- **Quorum Requirement** - A minimum percentage of bonded tokens must participate in voting for a proposal to be valid.
- **Approval Threshold** - A proposal must receive more than 50% approval (excluding abstain votes) to pass, or 66.7% for expedited proposals.
- **Veto Protection** - If more than 33.4% of votes are "NoWithVeto", the proposal is vetoed regardless of other vote counts.

## Network Parameters

### Mainnet (hyperpax_125-1)

Live network parameters for Paxeer mainnet.

| Parameter | Value | Description |
| --- | --- | --- |
| Minimum Deposit | 3500 PAX | Required to enter voting period |
| Expedited Minimum Deposit | 7000 PAX | Required to enter expedited voting period |
| Deposit Period | 2 days | Time to collect minimum deposit |
| Voting Period | 3 days | Duration for voting |
| Expedited Voting Period | 24 hours | Duration for expedited voting |
| Quorum | 33.4% | Minimum participation required |
| Expedited Quorum | 66.7% | Fast-track proposals |
| Approval Threshold | 50% | Standard proposals |
| Expedited Threshold | 66.7% | Fast-track proposals |
| Veto Threshold | 33.4% | Maximum veto votes allowed |

## Vote Types

### Voting Options

Understand the different voting options available.

1. **Yes** - Support the proposal as written. Counts toward approval threshold.
2. **No** - Oppose the proposal. Counts against approval threshold.
3. **Abstain** - Neutral position. Counts toward quorum but not approval threshold.
4. **NoWithVeto** - Strong opposition. Can veto a proposal if threshold is exceeded.

## Weighted Voting

**Advanced Voting**

Validators and delegators can split their voting power across multiple options using weighted voting.

- **Flexibility** - Distribute voting power across different options based on preference strength.
- **Precision** - Express nuanced positions on complex proposals with percentage allocations.

## Proposal Outcomes

| Outcome | Conditions |
| --- | --- |
| Passed | Quorum met (>=33.4% participation) · Approval threshold met (>=50% or >=66.7% for expedited) · Veto threshold not exceeded (less than 33.4% NoWithVeto) |
| Rejected | Quorum met but approval threshold not met · Majority voted "No" |
| Failed (No Quorum) | Less than 33.4% of bonded tokens participated · Proposal automatically fails |
| Vetoed | More than 33.4% of votes were "NoWithVeto" · Indicates strong community opposition |

## Best Practices

### Community Engagement

Guidelines for effective governance participation.

- **Research Thoroughly** - Read proposals and understand their implications before voting.
- **Engage in Discussion** - Participate in community forums and discussions to better understand different perspectives.
- **Vote Responsibly** - Consider the long-term implications of proposals for the network and ecosystem.
- **Stay Informed** - Follow governance updates and participate actively in the democratic process.

---

## Paxeer Staking Guide

*Learn how staking works on Paxeer, including delegation, un-delegation, re-delegation, bonding, and jailing within the dPoS consensus system.*

Staking is a fundamental aspect of Paxeer, enabling network security and
consensus through a delegated proof-of-stake (dPoS) mechanism powered by Twin
Turbo Consensus and the machineRFT engine. By participating in staking, both
validators and delegators play a critical role in maintaining and securing the
network, ensuring its long-term stability, performance, and success. PoS chains
rely on staked economic value rather than computational power, leading to a more
energy-efficient and scalable system. Engaging in staking allows developers and
users to contribute to the health and growth of the Paxeer ecosystem and
participate in [governance](/learn/general-governance) decisions by voting on
proposals.

In a dPoS system, token holders secure the network by delegating their tokens to
validators. Validators produce new blocks and validate transactions. In return
for their support, delegators earn a portion of the staking rewards. A
validator's weight is based on the number of tokens delegated to them plus their
own stake.

The Paxeer protocol incentivizes validators and delegators with staking rewards
from gas and genesis token unlocks. All rewards are distributed to delegators
proportional to their delegation, and the validator keeps a percentage of this
as commission.

## How to Stake

Staking on Paxeer can be done via the `paxd` CLI or through API calls.

- **paxd CLI**: `paxd tx staking [command] [flags]`
- **REST/RPC**: `GET/POST /staking/*`

## Key Concepts

### Delegation

Delegating tokens to a validator allows you to earn a portion of the staking
rewards. By delegating, you add to the validator's total stake, which helps
secure the network.

### Delegators

Delegators are users who stake their PAX tokens to a validator, contributing to
the validator's total stake. Delegators earn a portion of the transaction fees
as staking rewards. Staked PAX remains under the control of the delegator and
cannot be traded freely during the staking period.

### Un-delegation

Un-delegation is the process of withdrawing your staked tokens. This involves a
21-day un-bonding period during which the tokens are not earning rewards and
cannot be transferred. After the un-bonding period, the tokens are returned to
your wallet and are available for transactions.

### Re-delegation

Re-delegation allows you to move staked tokens from one validator to another
without undergoing the un-bonding period. When re-delegating, the tokens are
instantly moved, but the new validator is barred from further re-delegations for
21 days to ensure stability and prevent abuse. Each account can re-delegate a
maximum of 7 times simultaneously, with a re-delegation not considered complete
until the 21-day period is up.

### Bonding

Bonding is the process of committing your PAX tokens to a validator. This can be
done through delegation. The tokens are locked and contribute to the validator's
stake, starting to earn rewards immediately.

### Un-Bonding

Delegators can un-bond or un-stake their PAX tokens, initiating a 21-day period
during which the tokens do not earn rewards and cannot be transferred. After
this period, the tokens return to the delegator's wallet and become available
for transactions. Users can re-delegate to another validator instantly without
waiting for the un-bonding period to end.

### Jailing

To ensure network uptime and overall security, validators must meet strict
standards and consistently participate in the consensus process. Jailing can
occur if these standards are not met. Jailed validators are excluded from
participating in consensus for a period and will not generate rewards during
this time.

<Info>
  When a validator misbehaves and gets jailed, users can still perform all staking operations including claiming rewards, delegating, and undelegating from that validator. Note that misbehaviors are currently not penalized in the system, so there are no slashing consequences for validator misconduct.
</Info>

### Slashing

There is no slashing of funds on Paxeer.

## Common Questions

### How are staking rewards calculated?

Staking rewards are calculated based on the total amount of PAX staked and the validator's performance. Rewards are distributed proportionally to the amount staked by each delegator.

For more details, see [Delegators](#delegators).

### Can I change my validator without un-bonding?

Yes, you can use the re-delegation feature to move your stake from one validator to another without waiting for the un-bonding period to end.

For more details, see [Re-delegation](#re-delegation).

---

## Hardware Wallets

*Learn how to securely sign Paxeer transactions using Ledger hardware wallets connected through MetaMask on chain ID 125.*

Signing transactions manually or using hardware wallets like Ledger ensures
secure transaction approval. To sign Paxeer transactions, install the Ethereum
app on your Ledger device and sign through an EVM wallet such as MetaMask.

## Using MetaMask with Ledger

To connect your Ledger device through MetaMask and sign transactions on Paxeer (chain ID 125):

1. **Install MetaMask**: Ensure MetaMask is installed on your browser.

2. **Add Paxeer Network**: Add Paxeer as a custom network in MetaMask with chain ID `125`.

3. **Connect Ledger**: Open MetaMask, go to the account options, and select
   "Connect Hardware Wallet".

4. **Follow Instructions**: Follow the on-screen instructions to connect your
   Ledger device and select the account you want to use.

5. **Sign Transactions**: Once connected, you can sign transactions directly
   through MetaMask using your Ledger device.

**Installing the Ethereum App on Ledger**

Before you can use your Ledger device to sign transactions through MetaMask,
ensure you have the Ethereum app installed. You can install it through Ledger
Live:

- [Ledger App Store - Ethereum App](https://www.ledger.com/coin/wallet/ethereum)

For step-by-step Ledger setup instructions, see [Ledger Setup](/learn/ledger-setup).

---

## Paxeer Network

*Discover Paxeer Network the settlement layer for the machine economy with Twin Turbo consensus, LayerX agent channel, and the Deus marketplace.*

**The settlement layer for the machine economy**

Paxeer Network delivers sub-second finality, 5,000 TPS throughput, and a purpose-built agent side channel for autonomous machines, AI agents, and high-frequency dApps.

## Core architecture

### Twin Turbo Consensus + machineRFT

Paxeer's consensus engine combines Twin Turbo BFT with machineRFT (Randomized Finality Threshold) to achieve ~250 ms average block times, a 0.45 ms record low, and instant economic finality. Blocks are produced and finalized in a single round.

### LayerX: agent-only side channel

LayerX is a zero-fee, instant-settlement execution layer for autonomous agents and machine-to-machine transactions. Transactions are batched and anchored to Paxeer L1, inheriting full security guarantees.

### 402LXP: HTTP-native agent payments

402LXP implements the HTTP 402 status code as a payment rail, allowing AI agents and APIs to settle micropayments natively over HTTP using USDX (a stable asset on LayerX).

### Deus: API and agent marketplace

Deus is the marketplace layer on LayerX where developers publish APIs, AI agents, and machine services. Agents discover, consume, and pay for services autonomously via 402LXP.

## Understand the Paxeer ecosystem

### Fundamentals

<Columns cols={2}>
  <Card horizontal title="Account System" icon="key" href="/learn/accounts">
    Understand dual EVM (0x) and Cosmos (pax1) addresses, keys, and account linking.
  </Card>
  <Card horizontal title="Token Standards" icon="coins" href="/learn/dev-token-standards">
    Discover PAX, ERC-20, ERC-721, ERC-1155, and USDX on LayerX.
  </Card>
  <Card horizontal title="Gas & Fees" icon="gas-pump" href="/learn/dev-gas">
    Learn how transaction costs are calculated and paid on Paxeer.
  </Card>
  <Card horizontal title="Wallets" icon="wallet" href="/learn/wallets">
    Explore supported wallets and integration options for Paxeer.
  </Card>
</Columns>

### Network

<Columns cols={2}>
  <Card horizontal title="Staking & Delegation" icon="users" href="/learn/general-staking">
    Secure the network and earn rewards by participating in staking.
  </Card>
  <Card horizontal title="Network Governance" icon="gavel" href="/learn/general-governance">
    Understand the on-chain proposal and voting process for upgrades.
  </Card>
  <Card horizontal title="Chains" icon="network-wired" href="/learn/dev-chains">
    Connect to Paxeer mainnet and local development environments.
  </Card>
  <Card horizontal title="Block Explorers" icon="globe" href="/learn/explorers">
    Track transactions, blocks, and contract activity on Paxeer.
  </Card>
</Columns>

## Performance at a glance

<Columns cols={3}>
  <Card horizontal title="~250 ms Blocks" icon="clock">
    Average block time with a 0.45 ms record low. Sub-second finality, no waiting.
  </Card>
  <Card horizontal title="5,000 TPS" icon="bolt">
    Sustained throughput across EVM and LayerX combined.
  </Card>
  <Card horizontal title="Zero-Fee Agents" icon="robot">
    LayerX transactions settle instantly with no gas cost, batched to L1.
  </Card>
</Columns>

## EVM compatibility

Paxeer is fully Ethereum-compatible. Deploy Solidity contracts with Hardhat, Foundry, ethers, viem, or wagmi with no modifications.

<Columns cols={3}>
  <Card horizontal title="100% EVM Compatible" icon="shield-check">
    Run existing Ethereum contracts without code changes.
  </Card>
  <Card horizontal title="Full Tooling Support" icon="wrench">
    Hardhat, Foundry, Remix, MetaMask, and all standard tooling.
  </Card>
  <Card horizontal title="Standard JSON-RPC" icon="code">
    Ethereum RPC endpoints for seamless integration.
  </Card>
</Columns>

## Key use cases

<Columns cols={3}>
  <Card horizontal title="Autonomous Agents" icon="robot">
    AI agents transact via LayerX and 402LXP with zero fees and instant settlement.
  </Card>
  <Card horizontal title="Machine-to-Machine Payments" icon="microchip">
    IoT devices and automated systems settle micropayments at machine speed.
  </Card>
  <Card horizontal title="High-Frequency dApps" icon="chart-line">
    Trading, gaming, and interactive applications with sub-second finality.
  </Card>
</Columns>

---

## Ledger Hardware Wallet Setup Guide for Paxeer

*Set up your Ledger hardware wallet for Paxeer (HPX) installation, sending and receiving, and security best practices.*

## Introduction

The Paxeer network supports various crypto assets, including:

- Native tokens (HPX)
- ERC20 tokens
- ERC721 NFTs

Using a Ledger hardware wallet ensures secure key management for users interacting
with the Paxeer network (chain ID 125).

## Requirements

Before proceeding, ensure you have:

- A Ledger wallet device
- [Ledger Live](https://www.ledger.com/ledger-live) app installed on your
  desktop or mobile device
- A compatible wallet application for Paxeer network (MetaMask recommended)
- USB cable for connecting your device (Bluetooth is an option for some models)
- Latest firmware installed on your Ledger device
- Active internet connection

## Installation Instructions

### Install Ledger Live

1. **Download Ledger Live**: Visit the
   [Ledger official website](https://www.ledger.com/start) and download Ledger
   Live for your operating system.

2. **Install Ledger Live**: Follow the installation instructions for your
   platform.

3. **Set Up Ledger Live**: Open Ledger Live and follow the on-screen
   instructions to set up your Ledger device.

4. **Install the Ethereum App on Ledger**:
   - In Ledger Live, go to **"My Ledger"**.
   - Connect and unlock your Ledger device.
   - Search for "Ethereum" in the App Catalog and click **Install**.

<Info>Linux users will need to add a `udev rule` to allow access to the device. You can find the script to add a rule in the Ledger repo [here](https://github.com/LedgerHQ/udev-rules).</Info>

## Setup Instructions

### Add Paxeer Network to MetaMask

1. **Open MetaMask** and go to **Settings > Networks > Add Network**.

2. **Enter Paxeer network details**:
   - **Network Name**: Paxeer
   - **RPC URL**: Use the official Paxeer RPC endpoint
   - **Chain ID**: `125`
   - **Currency Symbol**: `HPX`
   - **Block Explorer**: Use the official Paxeer explorer URL

3. **Save** the network configuration.

### Connect Your Ledger Device

1. **Connect Your Ledger Device**:

   - Connect your Ledger device to your computer.
   - Unlock your Ledger device and open the Ethereum app.

2. **Connect to MetaMask**:

   - In MetaMask, click the account icon and select **Connect Hardware Wallet**.
   - Select **Ledger** and follow the prompts.
   - Choose the account you want to use and connect.

3. **Verify Connection**:
   - Ensure the Paxeer network is selected in MetaMask.
   - Your Ledger-secured account should now be visible.

## Viewing Account Balance

1. Open MetaMask with your Ledger device connected.
2. Ensure the Paxeer network is selected.
3. Your HPX balance and asset details should be displayed on the main screen.

## How to Receive Crypto Assets

1. **Navigate to the Receive Section**:

   - In MetaMask, click on your account address to copy it, or use the **Receive** option.
   - Select the crypto asset (if applicable) you wish to receive.

2. **Verify the Receiver Address**:

   - Verify that the address shown on the screen matches the one displayed on
     your Ledger device.
   - Confirm the address on your Ledger device by pressing the appropriate
     buttons.

<Warning>Always verify the receiver address on your Ledger device before sharing it. This prevents attacks like address spoofing.</Warning>

3. **Share the Address**:
   - Copy the verified address and share it with the sender or paste it into an
     exchange withdrawal form.

## How to Send Crypto Assets

1. **Navigate to the Send Section**:

   - Click **Send** in MetaMask.
   - Select the crypto asset you wish to send.

2. **Enter Transaction Details**:

   - Enter the recipient's address.
   - Input the amount you want to send.
   - (Optional) Add a memo if required.

3. **Submit the Transaction**:

   - Click **Next** and then **Confirm** to initiate the send process.

4. **Verify and Confirm on Ledger Device**:
   - Review the transaction details displayed on the Ledger device.
   - Verify that the recipient's address, amount, and other transaction details
     are correct.
   - Confirm and broadcast the transaction by pressing the appropriate buttons
     on your Ledger device.

<Warning>Always double-check the transaction details on your Ledger device before confirming. This is your last line of defense against potential attacks or errors.</Warning>

## Support

For further assistance, you can reach out to the following support channels:

- **Paxeer Community**: Join the official Paxeer community channels for support.
- **Ledger Support**: For Ledger-specific issues, visit the
  [Ledger Support Center](https://support.ledger.com/).
- **Wallet Support**: For wallet-related questions, check the support resources
  provided by your chosen wallet application.

## Additional Resources

- **Ledger Academy**: Learn more about cryptocurrency security on the official
  [Ledger Academy](https://www.ledger.com/academy).

<Danger>Never share your recovery phrase with anyone. Keep it in a safe, offline location. Your recovery phrase is the only way to restore access to your funds if your device is lost or damaged.</Danger>

---

## machineRFT Consensus

*Paxeer's proprietary negative-attestation consensus that separates agreement from execution, achieving sub-second finality.*

## The problem with traditional BFT

Traditional BFT consensus operates on a **positive attestation model**: every validator must execute every transaction, verify the resulting state transition, and only then vote to commit. This execution-before-consensus pattern is the fundamental bottleneck preventing sub-second finality.

PBFT, Tendermint, HotStuff, and their descendants share this DNA - agreement and execution are inextricably linked.

## machineRFT: agreeing on what did not happen

machineRFT inverts the entire model. Instead of validators executing transactions and voting on state correctness, validators:

1. **Order transactions without executing them** - the consensus critical path handles pure ordering, not state verification.
2. **Sign negative attestations** - validators cryptographically attest that they have _not_ observed conflicting transactions for the same state keys.
3. **Defer execution** - state transitions happen after consensus, not during it.
4. **Enforce via fraud proofs** - a post-consensus fraud-proof mechanism slashes validators who signed false negative attestations.

This transforms consensus from a state-verification problem into a **pure ordering problem**, reducing the critical path to network latency plus cryptographic signing operations.

## Theoretical foundation

The SOSP 2003 paper _"Separating Agreement from Execution for Byzantine Fault Tolerant Services"_ (Yin et al.) proved that separating agreement from execution improves fault tolerance: **3f+1 replicas** for agreement, but only **2f+1 for execution**.

Tendermint's thesis later formalized this through TMSP. machineRFT takes this to its logical conclusion: the consensus critical path contains no execution at all.

## How machineRFT differs from CometBFT

| Property | CometBFT (standard) | machineRFT |
|----------|-------------------|------------|
| Attestation model | Positive - validators vote on state correctness | Negative - validators attest they did _not_ observe conflicts |
| Execution timing | Before consensus (blocking) | After consensus (non-blocking) |
| Consensus critical path | Network latency + full transaction execution | Network latency + ed25519 signing |
| Fault enforcement | Slashing for invalid votes | Slashing for false negative attestations (fraud proofs) |
| Minimum replicas (agreement) | 3f+1 | 3f+1 |
| Minimum replicas (execution) | 3f+1 | 2f+1 |
| Finality | Deterministic after commit | Deterministic after commit (faster commit path) |

## Performance characteristics

machineRFT on top of the Twin Turbo engine delivers:

- **~250ms average block time** under real-world conditions
- **0.45ms record sustained low** - demonstrating near-instant finality under favorable network conditions
- **5,000 TPS** sustained throughput
- **Zero reorgs** - once a block is committed via negative attestation quorum, it is irreversible

The 0.45ms record demonstrates that the consensus critical path is bounded by network propagation, not computation.

## Integration with LayerX

machineRFT's negative-attestation model is the foundation for LayerX, Paxeer's agent-only side channel. The combined flow:

1. **LayerX ingests** - agents submit transactions to the LayerX sequencer with zero fees and instant settlement.
2. **Batch ordering** - the LayerX sequencer orders transactions and builds Merkle-provable receipts.
3. **L1 anchoring** - machineRFT commits batch roots to Paxeer L1 via negative attestation, anchoring LayerX state to the base layer.
4. **Fraud enforcement** - if a LayerX batch contains invalid transactions, the fraud-proof mechanism can slash the sequencer and revert the batch.

This architecture lets Paxeer process thousands of agent transactions per second on LayerX while anchoring their finality to L1 through machineRFT's efficient consensus path.

## Why it matters for developers

- **No confirmation delays** - treat a confirmed transaction as final immediately.
- **Predictable latency** - the consensus path is bounded by network RTT, not execution time.
- **M2M-ready** - designed for high-frequency automated transactions, not just human-paced interactions.
- **Lower execution cost** - validators can optimize execution independently of the agreement path.

You interact with machineRFT indirectly through the standard EVM interface and RPC endpoints.

---

## Parallelization Engine: Multi-core Execution

*How Paxeer's Parallelization Engine processes transactions in parallel across CPU cores for higher throughput while preserving safety guarantees.*

## Introduction

The Paxeer Parallelization Engine is a core component designed to increase transaction processing throughput beyond the limitations of traditional sequential execution models common in many blockchain systems. The engine enables concurrent execution of non-conflicting transactions within a block and leverages multi-core processors to improve performance and scalability. This document provides a technical explanation of its architecture and mechanisms.

<Tip>
  The Parallelization Engine is a key innovation that allows Paxeer to process transactions concurrently across multiple CPU cores, significantly increasing throughput while maintaining deterministic outcomes identical to sequential processing.
</Tip>

## Core Mechanism: Optimistic Concurrency Control

At its heart, the Parallelization Engine utilizes an **Optimistic Concurrency Control (OCC)** strategy. Unlike pessimistic approaches that lock state resources before execution, OCC allows transactions to execute in parallel based on an initial _estimation_ of the state they will access. Conflicts (e.g., two transactions writing to the same state key) are detected _during_ or _after_ this parallel execution phase. When conflicts occur, they are resolved through mechanisms that often include re-execution of the conflicting transactions. This approach minimizes overhead when conflicts are infrequent and boosts overall throughput.

## System Architecture

**Paxeer Parallelization Engine**

<Columns cols={3}>
  <Card horizontal title="Transaction Preprocessing">
    - Classifier
    - Batch Formation
    - Gas Estimation
  </Card>
  <Card horizontal title="Dependency Analysis">
    - Access Analysis
    - Dependency Mapping
    - Contract Interaction
  </Card>
  <Card horizontal title="Parallel Execution">
    - Worker Pool
    - State Transitions
    - Speculative Execution
  </Card>
</Columns>

<Columns cols={2}>
  <Card horizontal title="Conflict Resolution">
    - Conflict Detection
    - Sequential Re-execution
  </Card>
  <Card horizontal title="SeiDB & Consensus">
    - State Commit
    - MVCC Support
  </Card>
</Columns>

This architecture enables Paxeer to process transactions in parallel while ensuring consistency and correctness. Let's explore each component in detail.

### 1. Transaction Preprocessing

Before execution can begin, incoming transactions undergo preparatory processing. Raw transaction bytes transform into structured transaction objects that allow the system to identify message types and transaction characteristics. Initial validation occurs at this stage through ante handlers that verify signatures, fees, and other prerequisites.

The system also identifies certain critical transactions, such as oracle price feed updates, which may need prioritized execution to ensure timely data processing. This initial analysis leads to transaction grouping into batches for subsequent processing stages and establishes the foundation for parallel execution.

### 2. Dependency Analysis (Estimation)

This critical stage forms the backbone of the OCC approach. The system estimates potential state accesses for each transaction rather than determining exact dependencies.

An access control module analyzes each transaction to predict which state keys it might read or write during execution. Specialized Dependency Generator functions predict potential state access patterns for each transaction type. The precision of this analysis varies depending on transaction complexity:

Simple transactions like token transfers allow precise determination of which account balances will be accessed. Complex smart contract interactions make prediction of all potential storage accesses much more challenging. The generators provide broader estimates for these complex cases and acknowledge areas of uncertainty.

For example, a token transfer transaction between accounts `A` and `B` will generate estimated read/write sets that include:

- Read access to account `A`'s balance
- Read access to account `B`'s balance
- Write access to account `A`'s balance
- Write access to account `B`'s balance
- Read access to any related metadata or configuration

The dependency analyzer might also consider secondary effects such as:

- Fee payment impacts on the transaction sender's account
- Potential interactions with staking or governance mechanisms if the tokens have such properties

<Note>
  For smart contract calls, the analyzer employs heuristic methods that consider the contract's address and storage layout, the specific function selectors being called, any parameters passed to the contract functions, and historical patterns of state access from previous similar calls.
</Note>

The dependency generator outputs an estimated read/write set for each transaction. These sets contain the state keys expected to be accessed, with additional metadata indicating access types (read vs. write) and confidence levels for each prediction. The system uses these confidence levels during scheduling decisions to minimize the likelihood of conflicts.

The output from this phase consists of an "estimated writeset" for each transaction - a prediction of its state impact - which serves as crucial input for the next execution planning phase.

### 3. Parallel Execution

The system attempts concurrent execution with the estimated writesets through these steps:

1. **Batch Organization**: The process organizes transactions and their associated writesets for processing.

   - Transactions receive logical grouping based on estimated dependencies
   - The system creates execution units with appropriate metadata
   - Priority queues determine processing order for maximum throughput
   - Metadata tags track transaction relationships for later conflict analysis

2. **Worker Assignment**: A pool of execution workers (typically implemented as goroutines) stands ready to process transactions concurrently.

   - The worker pool size adapts dynamically based on system resources
   - CPU core allocation strategies optimize for NUMA architectures
   - Worker specialization allows for targeted execution of specific transaction types
   - Load balancing algorithms redistribute work for maximum resource utilization

3. **Strategic Scheduling**: Transaction assignment to workers occurs based on estimated writesets, with strategic grouping of non-conflicting transactions.

   - Graph-based scheduling algorithms minimize potential conflicts
   - The scheduler includes lookahead capabilities for multi-step dependency chains
   - Execution time estimates prioritize shorter transactions when appropriate
   - Locality-aware scheduling places related transactions on the same worker when beneficial

4. **Buffered Execution**: Workers execute transactions and write all state modifications to a temporary buffer instead of the main state store.

   - Each worker maintains an isolated transaction context
   - The execution engine applies gas metering and limits
   - Buffered state operations capture all read and write operations
   - Intermediate results remain isolated until conflict detection completes

5. **Runtime Tracking**: The system monitors which state keys are actually read and written throughout execution to build an accurate picture of real (versus estimated) state access patterns.
   - Access tracking captures both direct and indirect state interactions
   - Runtime statistics feed back into the dependency estimation system
   - Execution anomalies trigger adaptive scheduling adjustments
   - Performance metrics identify optimization opportunities

Advanced techniques ensure maximum parallelism extraction:

- Adaptive batch sizing based on system load and conflict rates
- Predictive execution of high-probability transaction paths
- Distributed execution capabilities across multiple physical nodes when available
- Resource throttling to prevent worker starvation

### 4. Conflict Detection & Resolution

The system must identify and resolve any conflicts that emerge during and after parallel execution. The process follows this sequence:

1. **Conflict Identification**: The system compares the actual read/write sets recorded during execution. A conflict exists when one transaction reads state that another concurrent transaction wrote, or when multiple transactions write to the same state key.

   The conflict detector implements several optimized algorithms:

   - A hash-based data structure tracks state accesses in memory for efficient lookup
   - Bloom filters provide rapid preliminary conflict checks
   - A deterministic conflict resolution order prevents cyclic dependencies during re-execution
   - Precise timestamp tracking ensures proper sequencing based on arrival order

   Common conflict patterns include:

   - Read-After-Write (RAW): Transaction `B` reads a key that Transaction `A` has modified
   - Write-After-Read (WAR): Transaction `B` modifies a key that Transaction `A` has read
   - Write-After-Write (WAW): Multiple transactions attempt to modify the same key

2. **Conflict Resolution**: The system executes a resolution strategy when it detects conflicts:

   - It identifies the conflicting transactions as a group
   - It removes their results from the temporary state buffer
   - It re-executes the conflicting set in a deterministic, sequential order to ensure correctness

   The deterministic ordering relies on transaction prioritization rules:

   - Critical system transactions receive highest priority
   - Oracle updates and price feeds receive elevated priority
   - Standard transactions follow their original sequence in the block
   - Gas price and other economic factors may influence the ordering

   The resolution system maintains isolation guarantees through careful state management:

   - Conflict groups remain isolated from successfully processed transactions
   - The temporary buffer preserves successfully executed state transitions
   - Resolution attempts track their own read/write sets to detect cascading conflicts

<Note>
  This conflict resolution makes the final state after parallel execution identical to what sequential processing would have produced, which maintains blockchain consistency.
</Note>

### 5. Fallback Mechanism

The OCC approach includes a critical safety mechanism for situations where parallel execution cannot succeed:

1. **Failure Detection**: The system detects failure conditions when parallel execution encounters excessive conflicts or critical errors.
2. **State Rollback**: All state changes from the failed parallel attempt are discarded.
3. **Sequential Reprocessing**: The entire transaction batch undergoes sequential processing as a fallback.

This fallback guarantees that the blockchain can always make progress, even in worst-case scenarios where parallelization proves ineffective for a particular block.

## Interaction with SeiDB

The parallelization engine works in close concert with SeiDB, Paxeer's custom storage layer. SeiDB's State Commit layer provides extremely low-latency read/write access needed for high transaction volume concurrent execution. Its asynchronous commit capabilities also allow quick block state finalization, which creates an efficient pipeline for block processing.

SeiDB integration offers several technical advantages crucial for parallelization:

**Performance Optimizations:**

- Multi-version concurrency control (MVCC) at the storage level supports multiple execution attempts
- Lock-free read operations prevent stalls during parallel transaction execution
- Memory-mapped state caching reduces I/O overhead for frequently accessed keys
- Batch commit optimizations minimize disk write amplification

**Parallelization-Specific Features:**

- Snapshot isolation provides consistent views of state for each transaction execution
- Atomic multi-key operations ensure multi-part state transitions remain consistent
- Versioned state access allows concurrent reads of different state versions
- Optimized rollback capabilities support the rapid discarding of speculative state changes

**Storage Architecture Alignment:**

- The key-value structure mirrors the state access patterns in the dependency analysis
- Prefix-based organization aligns with contract and module-based access patterns
- Hybrid storage tiers optimize for different access patterns across workloads
- Asynchronous persistence decouples block execution from storage commit latency

<Info>
  The tight integration between the parallelization engine and SeiDB enables the system to maintain high throughput even under challenging workloads with complex dependency patterns or high conflict rates.
</Info>

## Performance Impact

The Parallelization Engine delivers significant performance improvements:

| Transaction Type | Sequential TPS | Parallel TPS | Improvement |
| --- | --- | --- | --- |
| Simple Transfers | 3,000 | 15,000+ | 5x |
| ERC-20 Transfers | 2,200 | 9,500+ | 4.3x |
| DEX Swaps | 800 | 2,800+ | 3.5x |
| Complex Contracts | 500 | 1,500+ | 3x |


These improvements scale with CPU core count, allowing Paxeer to take full advantage of modern server hardware.

---

## Pointer Contracts: Bridging EVM and Cosmos

*How Paxeer's pointer contracts bridge assets between EVM and Cosmos, with patterns for CW20, CW721, and native tokens.*

<Info>
  **Pointer contracts are now primarily a legacy / migration tool.** No new CosmWasm contracts can be uploaded or instantiated on Paxeer, so the CW20 / CW721 / CW1155 to ERC20 / ERC721 / ERC1155 pointer flow only applies to already-deployed CosmWasm contracts. Native (Bank Module) pointers continue to work normally. For new tokens or NFTs, deploy ERC20 / ERC721 / ERC1155 contracts directly on the EVM.
</Info>

Pointer Contracts enable tokens to be used interoperably in both EVM and
Cosmos environments. Intended to be efficient and quick to deploy, a pointer
serves as an interpreter between the two "languages" used in either
execution environment.

## Why Pointer Contracts

![Without Pointer Contracts](/assets/pointer-contracts-without.png)
*A world without pointer contracts*

Wallets and clients for feature-rich protocols typically support only a single
execution environment. EVM wallets handle ERC-20 coins and ERC-721 NFTs but
cannot interact with Cosmos-SDK based assets due to different token standards and
interaction methods. The same problem exists for clients built for other
protocols (like Cosmos and its various SDK modules) which cannot directly
interact with Ethereum-based contracts or ERC tokens.

Pointer Contracts solve this by enabling interoperability of either protocol,
regardless of the client interface.

![With Pointer Contracts](/assets/pointer-contracts-simplified.png)
*With pointer contracts, all tokens can be accessed by wallets of either environment*

## How Pointer Contracts Work

![How Pointer Contracts Work](/assets/pointer-contracts-how-it-works.png)
*Pointer contracts enable seamless interoperability*

Each smart contract is limited to **one** associated pointer contract, which
must be registered on chain when deploying. This prevents conflicts and provides
a reference point for verifying the authenticity of the paired contract itself.

---

## Proposals

*Learn how to create, submit, and manage governance proposals on Paxeer, including text, parameter change, and software upgrade types.*

Complete guide to creating and submitting governance proposals on Paxeer. Learn about different proposal types, requirements, and submission commands.

<Info>For governance parameters and voting requirements, see the [Overview](/learn/general-governance) section.</Info>

## Proposal Types & Submission

### Text Proposals

**Community Discussion** - Non-binding proposals for community input and consensus building on important topics.

**Common Uses**
- Strategic direction
- Policy agreements
- Network guidelines

**Examples**
- Community input and consensus building
- Non-binding governance decisions
- Foundation for policy discussions
- Protocol direction and priorities

```bash
paxd tx gov submit-proposal \
  --title "Community Initiative Proposal" \
  --description "Detailed description of the initiative..." \
  --type Text \
  --deposit 3500000000uhpx \
  --from mykey \
  --chain-id hyperpax_125-1
```

### Parameter Change Proposals

**Network Configuration** - Modify network parameters without requiring a software upgrade.

**Common Changes**
- Governance parameters
- Staking parameters
- Fee structures

**Prerequisites**
- Valid JSON format
- Comprehensive change documentation
- Impact assessment
- Testing results

```bash
paxd tx gov submit-proposal param-change proposal.json \
  --deposit 3500000000uhpx \
  --from mykey \
  --chain-id hyperpax_125-1
```

<Info>**Example `proposal.json`:**</Info>

```json
{
  "title": "Update Staking Parameters",
  "description": "This proposal updates the maximum number of validators from 100 to 125.",
  "changes": [
    {
      "subspace": "staking",
      "key": "MaxValidators",
      "value": 125
    }
  ]
}
```

### Software Upgrade Proposals

**Network Upgrades** - Coordinate network-wide software upgrades with automatic execution at specified block height.

**Common Uses**
- Protocol upgrades
- Security patches
- New features
- Performance improvements

**Prerequisites**
- Upgrade height specification
- Binary release info
- Migration documentation
- Validator coordination

```bash
paxd tx gov submit-proposal software-upgrade v2.1.0 \
  --upgrade-height 15000000 \
  --upgrade-info "https://github.com/paxeer-network/paxeer/releases/v2.1.0" \
  --title "Paxeer v2.1.0 Upgrade" \
  --description "Network upgrade to v2.1.0 with enhanced performance" \
  --deposit 3500000000uhpx \
  --from mykey \
  --chain-id hyperpax_125-1
```

## Expedited Proposals

**Fast-Track Process** - For urgent network changes requiring immediate attention. Higher deposit and approval requirements with accelerated timeline.

- Security patches and critical fixes
- Emergency parameter adjustments
- Time-sensitive network upgrades

```bash
paxd tx gov submit-proposal software-upgrade emergency-patch \
  --upgrade-height 15100000 \
  --upgrade-info "https://github.com/paxeer-network/paxeer/releases/emergency-patch" \
  --title "Emergency Security Patch" \
  --description "Critical security fix requiring immediate deployment" \
  --deposit 7000000000uhpx \
  --expedited \
  --from mykey \
  --chain-id hyperpax_125-1
```

## Proposal Management

### Query & Monitor

| Command | Purpose | Example |
| --- | --- | --- |
| `paxd q gov proposals` | List all proposals | `--status voting_period` |
| `paxd q gov proposal [id]` | Get specific proposal | `paxd q gov proposal 42` |
| `paxd q gov votes [id]` | Check voting results | `paxd q gov votes 42` |
| `paxd q gov tally [id]` | View vote tally | `paxd q gov tally 42` |

### Voting

```bash
# Vote on a proposal
paxd tx gov vote [proposal-id] [vote-option] \
  --from mykey \
  --chain-id hyperpax_125-1

# Vote options: yes, no, abstain, no_with_veto
paxd tx gov vote 42 yes \
  --from mykey \
  --chain-id hyperpax_125-1
```

### Deposit Management

```bash
# Add deposit to proposal
paxd tx gov deposit [proposal-id] [amount] \
  --from mykey \
  --chain-id hyperpax_125-1

# Example: Add 1000 PAX to proposal 42
paxd tx gov deposit 42 1000000000uhpx \
  --from mykey \
  --chain-id hyperpax_125-1
```

---

## SeiDB: Performance-Optimized Blockchain Database

*How SeiDB accelerates blockchain operations with multi-level caching, optimized state access, and concurrency control for EVM workloads.*

## Introduction

SeiDB is a specialized database system designed to optimize blockchain state storage for the Ethereum Virtual Machine (EVM). Inherited from the Paxeer codebase, it addresses fundamental performance constraints in traditional blockchain storage systems through targeted optimizations for EVM's specific state access patterns. This document explains the technical design and key components of SeiDB.

## Core Technical Design

Traditional blockchain databases store state in structures optimized for cryptographic verification rather than transaction execution speed. SeiDB uses a hybrid architecture that preserves cryptographic verifiability while accelerating state access operations.

Key design goals include:

- Minimizing storage slot access latency even at peak load
- Maximizing state operation throughput for both reads and writes
- Enabling parallel execution for non-conflicting state operations
- Maintaining consistent performance under variable workloads

## System Architecture

SeiDB implements a multi-layered architecture optimized for EVM state management:

**SeiDB Core**

<Columns cols={3}>
  <Card horizontal title="EVM Cache System" />
  <Card horizontal title="Query Processor" />
  <Card horizontal title="Storage Engine" />
</Columns>

<Columns cols={3}>
  <Card horizontal title="Merkle Trie Optimizer" />
  <Card horizontal title="Storage Indexer" />
  <Card horizontal title="LSM-Tree Manager" />
</Columns>

<Columns cols={3}>
  <Card horizontal title="Concurrency Control" />
  <Card horizontal title="Version Manager" />
  <Card horizontal title="I/O Scheduler" />
</Columns>

<Card horizontal title="Ethereum Compatibility Layer" />

Each component in this architecture addresses specific performance bottlenecks found in traditional blockchain storage systems. The integrated design enables specialized optimization at each level while maintaining a cohesive system.

### EVM-Optimized Storage Engine

The storage engine forms the foundation of SeiDB and represents its most significant departure from traditional blockchain state databases. While standard Ethereum implementations use a single Merkle Patricia Trie for all storage, SeiDB employs a hybrid approach combining cryptographic verification with performance optimizations from modern database systems.

Key technical innovations include:

- **Enhanced Merkle Patricia Trie**: The implementation preserves cryptographic properties required for consensus validation while addressing performance bottlenecks. SeiDB's node caching dramatically reduces I/O overhead. Hot nodes remain in memory through a priority retention system that analyzes access frequency and recency patterns across multiple blocks.

- **Incremental State Root Calculation**: The system employs specialized techniques that avoid recalculating entire trie branches when only leaf nodes change. This method accelerates block finalization for blocks with transactions affecting different state areas. The calculation process intelligently reuses intermediate hash values from unchanged subtrees, allowing rapid state root derivation even after thousands of storage modifications.

- **Direct Storage Slot Indexing**: SeiDB provides mapping between composite keys (address + slot) and their storage location. This technique reduces lookup complexity from O(log n) to near-constant time for most operations. The indexing system maintains consistency through a dual-update mechanism that modifies both the index and underlying trie atomically.

- **Account-Level Optimizations**: The system applies different strategies to external accounts (user wallets) and contract accounts. Contract accounts receive specialized treatment with code caching and execution context preservation. The code caching mechanism exploits the immutability of contract bytecode once deployed, keeping frequently accessed contracts in memory with custom deserialization to minimize runtime overhead.

- **Optimized Bloom Filters**: The storage engine accelerates negative lookups (checking for non-existent keys) during contract execution. These filters use multi-layer filtering with dynamic sizing based on the active working set to minimize false positives during typical workloads.

### Multi-Level Cache Architecture

The caching system implements multiple specialized caches optimized for particular EVM access patterns, unlike general-purpose databases that employ uniform caching strategies.

The system includes:

- **Hot Slot Cache**: This component maintains frequently used storage slots in memory using a frequency-recency hybrid eviction policy tuned for blockchain workloads. This adaptive approach achieves improved hit rates compared to static caching policies. The cache intelligently separates frequently accessed slots from burst-access slots to prevent cache thrashing during high-intensity operations.

- **Account State Cache**: This cache maintains complete information for recently accessed addresses, including code, balance, nonce, and metadata. It implements predictive loading based on transaction analysis for improved hit rates during smart contract interactions. The predictive engine analyzes calldata patterns and historical interaction graphs to preload likely-to-be-accessed contract accounts.

- **Execution Context Cache**: This specialized cache preserves partial execution environments for frequently called contracts. When the same contract executes repeatedly with similar call patterns, this contextual caching reduces setup overhead compared to cold execution. The context includes pre-validated jump destinations, resolved address references, and warmed storage slots.

### Concurrency Management

SeiDB's concurrency control system employs optimistic concurrency control (OCC) adapted specifically for EVM's state access patterns. The system incorporates semantic knowledge of common smart contract behavior to minimize conflicts.

The transaction execution process follows these steps:

1. Analysis of transaction targets, calldata patterns, and historical access data to create an initial dependency graph
2. Parallel execution of transactions without overlapping state dependencies in isolated worker threads
3. Monitoring of actual storage accesses during execution to identify conflicts against predictions
4. Selective reexecution of minimal conflict sets in sequential order when conflicts occur

For common operations like token transfers, SeiDB applies specialized conflict handlers that understand operation semantics. The semantic analysis identifies token sender and recipient addresses from calldata and method signatures. This understanding reduces false conflicts for common ERC-20 token operations.

The worker pool adjusts parallelism dynamically based on observed conflict rates. During periods with few conflicts, the system increases worker count to maximize throughput. When conflict rates rise, it reduces parallelism to avoid wasting resources on speculative execution that might require reversion. The scheduler incorporates a feedback loop that monitors aborted transactions and adjusts the parallelism factor within milliseconds of detecting changing workload patterns.

### I/O Optimization

SeiDB implements storage I/O optimizations designed specifically for blockchain workloads, which typically involve append-heavy state changes.

Key optimization techniques include:

- **Log-Structured Storage**: The system organizes state into multiple levels, with recent changes in memory and older state in progressively larger but slower storage tiers. This architecture transforms random writes into sequential operations, improving write throughput. The storage layer maintains a memory-resident delta table that captures recent modifications and periodically flushes these changes to persistent storage in optimized batches.

- **Priority-Based I/O Scheduling**: The I/O subsystem prioritizes operations based on critical path status. State reads required for transaction validation receive highest priority, followed by state updates, and background operations receive lowest priority. The scheduler also employs operation batching techniques that combine multiple small I/O operations into more efficient larger operations.

- **State Versioning**: SeiDB uses multi-version concurrency control designed for blockchain's block-based execution model. Each block creates a new state version, using full state snapshots at epoch boundaries and delta encoding between intermediate blocks. The versioning system enables point-in-time queries against historical state with minimal storage overhead through a combination of differential storage and periodic compaction.

- **Configurable Persistence**: The database offers adjustable durability guarantees based on node type and network requirements, from fully synchronous writes to asynchronous persistence with periodic checkpoints. The configuration system allows operators to make explicit tradeoffs between performance and durability based on their specific node's role in the network.

## Performance Characteristics

SeiDB is designed to deliver substantial performance improvements compared to traditional EVM state implementations. The architecture focuses on enhancing both throughput and latency across various operation types.

<Info>**Note:** Performance characteristics described in this section represent design targets rather than verified benchmarks. Actual performance will vary based on hardware configuration, workload patterns, and network conditions. Production deployments should conduct their own benchmarking to validate performance in their specific environment.</Info>

### Storage Operation Throughput

SeiDB is architected to significantly improve operation throughput across all major storage operation categories, particularly for storage reads and account lookups. These improvements result from architectural innovations rather than hardware scaling, with performance gains across all operation types.

### Latency Profile

The system is designed to maintain consistent low latency across different load conditions, from low to peak usage. This latency stability represents one of SeiDB's most significant advantages for applications requiring predictable performance. The system aims to maintain relatively stable response times even at high utilization levels, unlike traditional implementations that may exhibit severe latency spikes during high network activity.

## Optimization Patterns

Understanding certain storage access patterns allows developers to take maximum advantage of SeiDB's architecture. While existing contracts work without modification, those designed with these patterns achieve even greater performance.

### Localized Storage Access

SeiDB's caching mechanisms work most effectively when related data exists in localized regions:

```solidity
// Suboptimal: Random storage access pattern
contract BasicStorage {
    mapping(uint256 => uint256) public values;

    function processValues(uint256[] calldata keys) external {
        for (uint i = 0; i < keys.length; i++) {
            values[keys[i]] = values[keys[i]] + 1;
        }
    }
}

// Optimized: Localized storage access
contract OptimizedStorage {
    mapping(uint256 => mapping(uint256 => uint256)) public valuesByBucket;

    function processValuesBatch(uint256 bucket, uint256[] calldata keys, uint256[] calldata vals) external {
        for (uint i = 0; i < keys.length; i++) {
            valuesByBucket[bucket][keys[i]] = vals[i];
        }
    }
}
```

In the optimized version, related values cluster under common bucket keys. This organization aligns with SeiDB's caching strategy, which loads entire buckets into memory as a unit. The pattern improves performance compared to randomized access, particularly for operations processing many values in a single transaction.

### Contention Reduction

Smart contracts handling high transaction volumes benefit from storage designs that minimize contentious storage locations:

```solidity
// Suboptimal: High contention design
contract HighContentionContract {
    uint256 public totalOperations;

    function recordOperation() external {
        totalOperations++; // High contention point
        // Other operation logic
    }
}

// Optimized: Sharded counter design
contract LowContentionContract {
    mapping(uint256 => uint256) public operationsByDay;

    function recordOperation() external {
        uint256 today = block.timestamp / 86400;
        operationsByDay[today]++; // Temporal sharding reduces contention
        // Other operation logic
    }

    function getTotalOperations(uint256 daysToInclude) external view returns (uint256) {
        uint256 total = 0;
        uint256 today = block.timestamp / 86400;

        for (uint256 i = 0; i < daysToInclude; i++) {
            total += operationsByDay[today - i];
        }

        return total;
    }
}
```

The optimized contract shards the counter across time-based buckets, dramatically reducing contention when multiple transactions execute concurrently. SeiDB's concurrency control system recognizes these sharded patterns and executes transactions affecting different shards in parallel. This approach increases throughput for high-volume contracts during peak load conditions.

## Technical Integration

### EVM Compatibility

SeiDB maintains complete compatibility with the Ethereum protocol specifications while delivering performance enhancements:

- Full support for all EVM opcodes and precompiled contracts
- Identical state transition logic to standard Ethereum implementations
- Consistent gas cost model for all operations
- Complete compatibility with JSON-RPC API endpoints

These compatibility guarantees ensure existing smart contracts, development tools, and infrastructure components work without modification. The system undergoes extensive compatibility testing against the official Ethereum test suites to verify identical results compared to reference implementations.

### Deployment Configurations

SeiDB's architecture supports various deployment configurations optimized for different node roles:

- **Validator nodes** prioritize state consistency and durability through synchronous I/O operations and redundant state verification
- **API service nodes** optimize for query throughput and low latency responses with larger cache allocations and specialized read paths
- **Archive nodes** employ specialized storage strategies for efficient historical state access, including custom indexing for time-based queries
- **Light clients** benefit from optimized state proof generation with compact inclusion proofs for partial state verification

Each configuration tunes the SeiDB components to match specific requirements while maintaining protocol compatibility. The configuration framework provides fine-grained control over cache sizes, worker pools, I/O policies, and persistence strategies to match the operational needs of different node types.

---

## Twin Turbo Consensus

*How Paxeer's consensus stack combines Twin Turbo pipelining with machineRFT negative attestations to achieve sub-second deterministic finality.*

## Two layers, one consensus stack

Paxeer's consensus is a two-layer stack. **Twin Turbo** provides the pipelined BFT engine that overlaps proposal, voting, and execution phases. **machineRFT** layers on top with a negative-attestation model that transforms consensus from a state-verification problem into a pure ordering problem.

Together, they deliver ~250ms average block time, a 0.45ms record low, 5,000 TPS, and instant deterministic finality with zero reorgs.

## Layer 1: Twin Turbo (pipelined BFT)

Twin Turbo is an aggressively optimized CometBFT engine. It achieves sub-second block times through deep pipelining of the standard BFT flow.

### What Twin Turbo does

Traditional CometBFT proceeds through propose, prevote, precommit, and commit sequentially for each block. Twin Turbo overlaps these phases:

1. **Aggressive timeout tuning** - configuration overrides (`UnsafeProposeTimeoutOverride`, `UnsafeCommitTimeoutOverride`) enforce much shorter durations for each BFT round. Faster gossip propagation reduces inter-validator communication latency.

2. **Pre-consensus transaction preparation** - before a block proposal arrives for height `H`, validators are already collecting transactions, decoding them concurrently (`DecodeTransactionsConcurrently`), analyzing state dependencies (`GenerateEstimatedWritesets`), and pre-fetching data from SeiDB.

3. **Optimistic parallel execution** - when a validator receives a proposal for height `H`, it dispatches transactions to the parallelization engine _immediately_, running execution concurrently with prevote/precommit voting. State changes are buffered via `CacheMultiStore` until consensus is reached.

4. **Rapid commit** - because execution overlaps with voting, the gap between achieving 2/3+ precommits and having state changes ready for commit is near-zero.

<Columns cols={2}>
  <Card horizontal title="Pre-Consensus (TX Preparation)">
    - Transaction collection and analysis
    - Concurrent decoding
    - State prefetching from SeiDB
  </Card>
  <Card horizontal title="Optimized BFT (Voting + Concurrent Execution)">
    - Block proposal reception
    - BFT voting (prevote/precommit)
    - Parallel TX execution (optimistic)
  </Card>
</Columns>

_(Consensus reached)_ → **Finalize state and commit to SeiDB**

## Layer 2: machineRFT (negative attestation)

Twin Turbo makes the pipeline fast. machineRFT changes _what validators agree on_.

### The problem with positive attestation

Every major BFT protocol (PBFT, Tendermint, HotStuff) uses a **positive attestation model**: validators execute transactions, verify state transitions, and vote to commit. Execution is on the consensus critical path, which prevents sub-second finality.

### machineRFT inverts the model

machineRFT uses **negative attestation**. Instead of voting on what _did_ happen, validators agree on what _did not_ happen:

1. **Order without executing** - the consensus critical path handles pure transaction ordering, not state verification.
2. **Sign negative attestations** - validators cryptographically attest they have _not_ observed conflicting transactions for the same state keys.
3. **Execute after consensus** - state transitions happen after the block is committed, not during the voting phase.
4. **Enforce via fraud proofs** - validators who sign false negative attestations are slashed through a post-consensus fraud-proof mechanism.

This reduces the consensus critical path from **network latency + full transaction execution** to **network latency + ed25519 signing operations**.

### Theoretical foundation

The SOSP 2003 paper _"Separating Agreement from Execution for Byzantine Fault Tolerant Services"_ (Yin et al.) proved that separating agreement from execution improves fault tolerance: **3f+1 replicas** for agreement, but only **2f+1 for execution**. Tendermint's thesis later formalized this through TMSP. machineRFT takes this to its logical conclusion.

## How the layers compose

| Component | Role | What it optimizes |
|-----------|------|-------------------|
| **Twin Turbo** | Pipelined BFT engine | Overlaps proposal, voting, and execution phases |
| **machineRFT** | Negative attestation layer | Removes execution from the consensus critical path |
| **Parallelization engine** | Concurrent TX execution | Processes non-conflicting transactions in parallel |
| **SeiDB** | Storage layer | High-throughput state reads/writes |

Twin Turbo makes the pipeline fast. machineRFT makes the consensus decision a pure ordering problem. The parallelization engine handles execution concurrently. SeiDB provides storage throughput.

## Performance

| Metric | Value |
|--------|-------|
| Average block time | ~250ms |
| Record sustained low | 0.45ms |
| Peak throughput | 5,000 TPS |
| Finality | Deterministic (instant) |
| Reorgs | Zero |
| Consensus path | Network RTT + ed25519 signing |

## What this means for developers

- **No confirmation delays** - a confirmed transaction is final.
- **Predictable latency** - the consensus path is bounded by network propagation, not computation.
- **M2M-ready** - designed for high-frequency automated transactions from autonomous agents.
- **Standard EVM** - the consensus stack is transparent to smart contract developers.

---

## Getting Started with Paxeer Network: User Quick Start Guide

*Comprehensive guide to Getting Started with Paxeer Network: User Quick Start Guide on Paxeer. Learn key concepts, commands, and best practices.*

This getting started guide will help you set up your wallet and start using Paxeer, even if you're new to blockchain. By the end, you'll be ready to explore the most performant blockchain ever.

## 1. Get a Wallet

Download a compatible wallet such as [MetaMask](https://metamask.io/), [Rabby](https://rabby.io/), [Binance Wallet](https://www.binance.com/en/web3wallet), or any other [supported wallet](/learn/wallets).

## 2. Set Up and "Associate" Your Wallet

Making a transaction will broadcast your public key to the chain, allowing full cross-environment functionality. If your wallet is not "associated" it means that the network is not aware that your key exists, and therefore it cannot be determined which two addresses are actually the same wallet due to the cryptographic algorithm by which the EVM wallet address is derived from the key(s).

<Info>
  Learn more about [how accounts work](/learn/accounts) on Paxeer.
</Info>

## 3. Get Tokens

- [Bridge from another network](https://welcome.symph.ag)
- [Transfer from another account](https://docs.paxeer.app/transfer)
- [Use the faucet](/learn/faucet) (testnet only)
- Transfer from CEX by copying your wallet address

<Warning>
  Typically, no memo is required for withdrawals from CEXs, but depositing back may require a memo. Check your CEX's guidelines to ensure smooth transfers.
</Warning>

## 4. Explore the ecosystem

Paxeer has a diverse ecosystem of applications, ranging from DeFi to Games and beyond. Explore the [Paxeer Ecosystem Hub](https://www.paxeer.app/ecosystem) to discover the latest projects and innovations or follow [@paxeer_app](https://x.com/paxeer_app) on X.

---

## Paxeer Wallet Providers Guide

*Learn how to set up MetaMask and other supported wallets to manage assets and interact with the Paxeer network securely.*

Wallets manage assets and interactions on Paxeer.

<Warning>Manually importing your wallet using a mnemonic from an EVM-only wallet app to a Cosmos-based wallet app, or vice versa, is not recommended. This may generate unexpected wallet addresses due to differing Coin Types.</Warning>

## Types of Wallets

1. **Software Wallets**: Applications or browser extensions that manage private keys.
2. **Hardware Wallets**: Physical devices that store private keys offline.
3. **Passkey-based Wallets**: Use passkeys instead of seed phrases for authentication.

## Add Paxeer to MetaMask

To add Paxeer manually in MetaMask, open **Settings > Networks > Add Network** and enter the following:

| Field | Value |
| --- | --- |
| Network Name | Paxeer |
| Chain ID | 125 |
| Currency Symbol | PAX |
| RPC URL | `https://public-rpc.paxeer.app/evm/reference` |
| Explorer URL | `https://paxscan.io` |

## Recommended Wallets

| Wallet | EVM | Coin Type | Type | Mobile | Link |
| --- | --- | --- | --- | --- | --- |
| MetaMask | Yes | 60 | Software | Yes | [MetaMask](https://metamask.io/) |
| Rabby | Yes | 60 | Software | Yes | [Rabby Wallet](https://chromewebstore.google.com/detail/rabby-wallet/acmacodkjbdgmoleebolmdjonilkdbch) |
| OKX | Yes | 118 / 60 | Software | Yes | [OKX Wallet](https://web3.okx.com/) |

## Hardware Wallets

| Wallet | EVM | Cosmos | Coin Type | Type | Mobile | Link |
| --- | --- | --- | --- | --- | --- | --- |
| Ledger | Yes | Yes | 118 / 60 | Hardware | No | [Ledger](https://www.ledger.com/) |

## Additional Wallets

Any EVM-compatible wallet that supports custom RPC endpoints works with Paxeer. See the wallets listed above for the most tested options.

---

## 402LXP Protocol

*402LXP is an HTTP-native payment protocol enabling agents to pay for API calls instantly using HTTP 402 status codes and USDX on LayerX.*

## 402LXP protocol

402LXP is an HTTP-native payment protocol that lets agents pay for API calls using HTTP 402 status codes and USDX on LayerX. It is designed for machine-to-machine payments without checkout flows or human interaction.

## How it works

1. Agent makes an API call to a service.
2. The service responds with `HTTP 402 Payment Required` and a payment challenge.
3. Agent signs the payment challenge and resubmits with the payment proof attached.
4. The service verifies the payment, fulfills the request, and returns the response.

The entire exchange happens over standard HTTP - no browser, no redirect, no wallet popup.

## Payment challenge

When a service requires payment, it returns a 402 response with a structured challenge:

```http
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "amount": "0.001",
  "currency": "USDX",
  "pay_to": "did:ed25519:service.weather.v2",
  "nonce": "a3f9xK2m...",
  "expires_at": "2026-01-15T10:05:00Z",
  "description": "Weather forecast API call"
}
```

The agent reads the challenge, signs a transfer intent for the specified amount, and resubmits the original request with the payment proof in the `X-Payment` header.

## Completing the payment

```http
GET /v1/forecast HTTP/1.1
Host: weather.example.com
Authorization: Bearer <principal_token>
X-Payment: <base64url-encoded-signed-transfer-intent>
```

The service verifies the transfer intent against the LayerX API, confirms the amount matches, and processes the transfer. On success, it returns the requested resource with a `200 OK` and a `Payment-Receipt` header containing the LayerX receipt sequence number.

## Pricing models

### Per-call pricing

Each API call requires a fixed payment. The 402 challenge includes the exact amount. This is the simplest model and works well for stateless endpoints.

```json
{
  "amount": "0.001",
  "model": "per_call"
}
```

### Streaming pricing

For streaming endpoints (SSE, WebSocket), payment covers a time window or data volume. The initial 402 challenge opens the stream; subsequent charges are deducted automatically until the stream closes or the payment window expires.

```json
{
  "amount": "0.010",
  "model": "streaming",
  "window": "60s",
  "max_renewals": 10
}
```

The agent receives periodic `X-Payment-Window` headers indicating remaining time. When the window expires, the stream pauses until the agent sends a renewal payment.

## Evolution of x402

402LXP builds on the x402 protocol with several key differences:

| Feature | x402 | 402LXP |
|---------|------|--------|
| Settlement | On-chain | LayerX (instant, zero-fee) |
| Currency | Native token | USDX (dollar-denominated) |
| Latency | Block time | Instant |
| Target | General web | Autonomous agents |
| Auth | Wallet-based | DID-based |

The core HTTP 402 mechanism is preserved - 402LXP is a specialization, not a replacement.

## No checkout flow

The agent reads the 402 challenge, signs it programmatically, and retries within a single HTTP client lifecycle. No human in the loop.

## Implementing 402LXP

### Client-side

Use the `@paxeer/402lxp` middleware to automatically handle 402 challenges:

```typescript
import { withPayment } from "@paxeer/402lxp";

const response = await withPayment(
  () => fetch("https://weather.example.com/v1/forecast"),
  { wallet: myAgentWallet }
);
```

The middleware intercepts 402 responses, signs the payment, and retries the request transparently.

### Server-side

Use the `@paxeer/402lxp-server` package to add payment enforcement to any HTTP service:

```typescript
import { requirePayment } from "@paxeer/402lxp-server";

app.get("/v1/forecast",
  requirePayment({ amount: "0.001", payTo: myDid }),
  (req, res) => {
    res.json({ forecast: "..." });
  }
);
```

The middleware returns 402 challenges for unpaid requests and verifies payment proofs on retries.

---

## Agent Wallets

*Policy-bound wallets with spending caps, service allowlists, session permissions, and protocol-enforced stop conditions.*

## Agent wallets

LayerX wallets are purpose-built for autonomous agents. Unlike traditional wallets that grant unlimited signing authority, agent wallets are policy-bound - every spending rule is enforced at the protocol level, not by convention.

## Why policy-bound wallets

Autonomous agents operate without human oversight. A compromised or misbehaving agent with an unrestricted wallet can drain funds instantly. LayerX wallets solve this by binding spending policies directly to the wallet at creation time. The sequencer enforces these policies on every transfer - there is no way to bypass them without upgrading the wallet on L1.

## Spending caps

Set a maximum USDX amount the agent can spend within a rolling time window. Once the cap is reached, further transfers are rejected until the window resets.

```json
{
  "spending_cap": {
    "amount": "100.00",
    "window": "24h"
  }
}
```

If an agent needs to spend beyond its cap, the parent wallet must explicitly raise the limit - the agent cannot do this itself.

## Service allowlists

Restrict which DIDs the agent can send USDX to. Transfers to non-listed recipients are rejected by the sequencer.

```json
{
  "allowlist": [
    "did:secp256k1:pax1abc...",
    "did:ed25519:agent.weather.v2"
  ]
}
```

This is useful when an agent is authorized to pay for specific services but should not have general-purpose spending authority.

## Session permissions

Bind a wallet to a specific authentication session. When the session expires or is revoked, the wallet becomes inert - no transfers are accepted until a new session is established.

Session-scoped wallets are ideal for short-lived agent tasks where long-lived spending authority is undesirable.

## Stop conditions

Define conditions under which the wallet is automatically frozen. Stop conditions are evaluated by the sequencer on every transfer attempt.

- **Balance floor** - freeze when balance drops below a threshold.
- **Anomaly detection** - freeze on unusual transfer patterns (e.g., rapid-fire sends to a new DID).
- **Time-based expiry** - freeze after a fixed duration.

Once frozen, the wallet can only be unfrozen by the parent wallet on L1.

## Creating a wallet via SDK

Use the `sei-js` SDK to create a policy-bound wallet:

```typescript
import { LayerX } from "@paxeer/layerx-sdk";

const wallet = await LayerX.createWallet({
  did: "did:ed25519:agent.scanner.v1",
  policy: {
    spendingCap: { amount: "50.00", window: "1h" },
    allowlist: ["did:ed25519:service.data.v2"],
    stopConditions: { balanceFloor: "5.00" }
  }
});
```

The SDK returns a wallet handle that automatically signs transfers with the agent's Ed25519 key. All policy enforcement happens on the sequencer - the SDK simply constructs valid transfer intents.

## Protocol enforcement

Every policy is enforced at the sequencer level. The SDK and API layers do not make spending decisions - they construct requests and the sequencer accepts or rejects them based on the wallet's policy.

This means:

- A compromised agent cannot exceed its spending cap.
- A misdirected transfer to a non-listed DID is rejected before it touches the ledger.
- A frozen wallet cannot be thawed without L1-level intervention.

Policies are immutable once the wallet is created. To change a policy, create a new wallet with the updated rules and transfer the balance.

---

## API Reference

*Explore LayerX's REST API endpoints for authentication, balances, transfers, payments, receipts, and deposits with request and response examples.*

## API reference

LayerX exposes a REST API for all operations. The base URL is `https://layerx.paxeer.network`.

## Authentication

Most endpoints require authentication via a principal token obtained through the [DID challenge/verify flow](/layerx/did-auth). Include the token in the `Authorization` header:

```
Authorization: Bearer <principal_token>
```

Public read endpoints (marked below) do not require authentication.

## Endpoints

### Authentication

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `POST` | `/v1/agent/auth/challenge` | No | Request a DID challenge |
| `POST` | `/v1/agent/auth/verify` | No | Verify a signed challenge, receive a principal token |

### Accounts

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `GET` | `/v1/balance` | Yes | Get the authenticated agent's USDX balance |
| `GET` | `/v1/balance/\{did\}` | Public | Get any agent's USDX balance |

### Transfers

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `POST` | `/v1/transfer` | Yes | Submit a USDX transfer |
| `GET` | `/v1/transfers` | Yes | List transfers for the authenticated agent |
| `GET` | `/v1/transfers/\{did\}` | Public | List transfers for a specific DID |

### Payments

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `POST` | `/v1/pay` | Yes | Submit a payment (402LXP convenience endpoint) |
| `GET` | `/v1/stream` | Yes | SSE stream of incoming payments |

### Receipts

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `GET` | `/v1/receipt/\{seq\}` | Public | Get a signed receipt by sequence number |

### Deposits & withdrawals

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `POST` | `/v1/deposit` | Yes | Register an L1 deposit for credit |
| `POST` | `/v1/withdraw` | Yes | Request a USDX withdrawal to L1 |
| `POST` | `/v1/force-settle` | Yes | Force-settle a transfer to L1 |


## POST /v1/agent/auth/challenge

Request a DID challenge for authentication.

**Request:**

```json
{
  "did": "did:ed25519:agent.scanner.v1"
}
```

**Response (200):**

```json
{
  "challenge": "a3F9xK2m...",
  "expires_at": "2026-01-15T10:05:00Z"
}
```


## POST /v1/agent/auth/verify

Verify a signed challenge and receive a principal token.

**Request:**

```json
{
  "did": "did:ed25519:agent.scanner.v1",
  "challenge": "a3F9xK2m...",
  "signature": "base64url-encoded-signature"
}
```

**Response (200):**

```json
{
  "principal_token": "eyJhbGciOiJFZERTQSJ9...",
  "expires_at": "2026-01-15T11:05:00Z"
}
```


## GET /v1/balance

Get the authenticated agent's USDX balance.

**Headers:** `Authorization: Bearer <principal_token>`

**Response (200):**

```json
{
  "did": "did:ed25519:agent.scanner.v1",
  "balance": "47.50",
  "currency": "USDX"
}
```


## POST /v1/transfer

Submit a USDX transfer.

**Headers:** `Authorization: Bearer <principal_token>`

**Request:**

```json
{
  "to": "did:ed25519:service.weather.v2",
  "amount": "1.50",
  "memo": "optional reference string"
}
```

**Response (200):**

```json
{
  "seq": 12345,
  "from": "did:ed25519:agent.scanner.v1",
  "to": "did:ed25519:service.weather.v2",
  "amount": "1.50",
  "timestamp": "2026-01-15T10:03:42Z",
  "receipt_signature": "base64url-encoded-sequencer-signature"
}
```


## POST /v1/pay

Convenience endpoint for 402LXP payments. Behaves identically to `/v1/transfer` but is optimized for the 402LXP flow and accepts the payment challenge inline.

**Headers:** `Authorization: Bearer <principal_token>`

**Request:**

```json
{
  "to": "did:ed25519:service.weather.v2",
  "amount": "0.001",
  "payment_challenge": "base64url-encoded-402-challenge"
}
```

**Response (200):** Same as `/v1/transfer`.


## GET /v1/stream

Server-Sent Events stream of incoming transfers for the authenticated agent.

**Headers:** `Authorization: Bearer <principal_token>`

**Response:** `text/event-stream`

```
data: {"seq": 12346, "from": "did:ed25519:agent.buyer.v1", "amount": "0.50", "timestamp": "..."}

data: {"seq": 12347, "from": "did:ed25519:agent.buyer.v2", "amount": "1.00", "timestamp": "..."}
```


## GET /v1/receipt/\{seq\}

Get a signed receipt by sequence number. This endpoint is public and requires no authentication.

**Response (200):**

```json
{
  "seq": 12345,
  "sender": "did:ed25519:agent.scanner.v1",
  "recipient": "did:ed25519:service.weather.v2",
  "amount": "1.50",
  "timestamp": "2026-01-15T10:03:42Z",
  "batch_seq": 987,
  "merkle_leaf": "0xa3f9...",
  "merkle_proof": ["0xb2c1...", "0xd4e5..."],
  "signature": "base64url-encoded-sequencer-signature"
}
```


## POST /v1/deposit

Register an L1 deposit for credit to the authenticated agent's LayerX account.

**Headers:** `Authorization: Bearer <principal_token>`

**Request:**

```json
{
  "tx_hash": "0xabc123...",
  "did": "did:ed25519:agent.scanner.v1"
}
```

**Response (200):**

```json
{
  "deposit_seq": 456,
  "amount": "100.00",
  "status": "confirmed",
  "credited_at": "2026-01-15T10:00:00Z"
}
```


## POST /v1/withdraw

Request a USDX withdrawal to L1.

**Headers:** `Authorization: Bearer <principal_token>`

**Request:**

```json
{
  "amount": "25.00",
  "to": "pax1abc123..."
}
```

**Response (200):**

```json
{
  "withdrawal_seq": 789,
  "amount": "25.00",
  "status": "pending",
  "estimated_settlement": "2026-01-15T10:10:00Z"
}
```


## POST /v1/force-settle

Force-settle a specific transfer to L1 immediately.

**Headers:** `Authorization: Bearer <principal_token>`

**Request:**

```json
{
  "transfer_seq": 12345
}
```

**Response (200):**

```json
{
  "transfer_seq": 12345,
  "l1_tx_hash": "0xdef456...",
  "status": "settled"
}
```

---

## LayerX Architecture

*Technical deep-dive into the sequencer, Postgres ledger, Merkle accumulator, settlement worker, and chain anchoring components.*

## LayerX architecture

LayerX is a sequencer-based side channel that maintains a Postgres-backed ledger, builds Merkle trees over committed transfers, and anchors roots to Paxeer L1 for independent verifiability.

## System components

### Sequencer

The sequencer is the single entry point for all LayerX transfers. It validates incoming transfer intents, applies them to the ledger, and returns signed receipts synchronously. There is no mempool - transfers are processed in the order they arrive.

The sequencer runs as a single binary (`layerxd`) and exposes the REST API on a configurable port. It does not participate in consensus; finality comes from the L1 anchor.

### Postgres ledger

All account balances and transfer history live in a Postgres database. The ledger is the source of truth for LayerX state. Every transfer is an atomic debit-credit pair recorded in a single transaction.

Schema migrations live in `migrations/` and are applied automatically on startup. The ledger tracks:

- **Accounts** - DID-keyed rows with USDX balance, nonce, and metadata.
- **Transfers** - sender, recipient, amount, timestamp, sequence number, and receipt signature.
- **Deposits** - L1-originated USDL deposits credited as USDX.
- **Withdrawals** - USDX debited for L1 withdrawal settlement.

### Merkle accumulator

After each batch window closes, the sequencer builds a domain-separated Merkle tree over all transfers in that batch. Each leaf is a hash of `(sender_did, recipient_did, amount, seq, timestamp)`. The Merkle root is published to Paxeer L1 alongside the batch metadata.

Merkle inclusion proofs allow any party to verify that a specific transfer was included in a committed batch - without trusting the sequencer.

### Settlement worker

The settlement worker handles two responsibilities:

1. **Batch anchoring** - computes the Merkle root for a closed batch window and submits it to the Paxeer L1 bridge contract.
2. **Withdrawal processing** - processes force-settle requests by computing net positions and initiating L1 transfers.

The worker runs on a configurable interval (default: a few minutes) and is idempotent - re-running it for the same batch produces the same root.

### Chain anchoring

Each batch is anchored to Paxeer L1 (chain ID 125) via a call to the LayerX bridge contract. The anchor includes:

- Batch sequence number
- Merkle root
- Timestamp
- Transfer count

Once anchored, the batch inherits the finality guarantees of Paxeer L1. Anyone can verify the anchor on-chain and cross-reference it against the LayerX API.

## Runtime layout

```
cmd/layerxd/          # Main binary entrypoint
internal/
  sequencer/          # Transfer processing, batch management
  ledger/             # Postgres queries, balance operations
  merkle/             # Tree construction, proof generation
  settlement/         # Batch anchoring, withdrawal processing
  auth/               # DID challenge/verify, principal tokens
  api/                # HTTP handlers, middleware, routing
pkg/
  did/                # DID parsing, Ed25519 key operations
  receipt/            # Receipt signing, domain separation
  usdx/               # USDX amount handling, precision
migrations/           # Postgres schema migrations
```

## Data flow

A typical transfer flows through the system as follows:

1. Agent submits a signed transfer intent via `POST /v1/transfer`.
2. The API layer verifies the DID signature and checks the sender's balance.
3. The sequencer applies the debit-credit pair atomically.
4. A signed receipt is generated and returned to the caller.
5. At batch close, the Merkle accumulator hashes all new transfers into a tree.
6. The settlement worker submits the Merkle root to Paxeer L1.
7. The transfer is now immutably anchored and independently verifiable.

---

## Deus - Agent Marketplace

*Deus is a LayerX agent marketplace where services publish capabilities and pricing, and agents discover and pay via 402LXP in USDX.*

## Deus

Deus is an agent marketplace built on LayerX. Service providers publish capabilities, set prices in USDX, and autonomous agents discover and pay for those capabilities using the 402LXP protocol.

## What Deus does

1. **Discovery** - agents find services by capability, not by URL. Services register with metadata describing what they offer.
2. **Pricing** - services declare their pricing model (per-call, streaming, tiered). Agents see the price before committing.
3. **Payment** - payments flow over 402LXP in USDX. Zero fees, instant settlement, signed receipts.

## Publishing a service

Service providers register their API on Deus with a capability descriptor:

```json
{
  "name": "Weather Forecast API",
  "did": "did:ed25519:service.weather.v2",
  "endpoint": "https://weather.example.com/v1",
  "capabilities": ["forecast.current", "forecast.hourly", "alerts"],
  "pricing": {
    "model": "per_call",
    "amount": "0.001",
    "currency": "USDX"
  },
  "description": "Real-time weather data for any coordinate"
}
```

Once registered, the service appears in Deus search results and is available for 402LXP payments.

## Discovering services

Agents query Deus to find services matching their needs:

```bash
curl https://deus.paxeer.network/v1/search?capability=forecast.current
```

Deus returns a ranked list of services with their pricing, availability, and capability metadata. The agent selects a service and begins interacting with it - the first unpaid call triggers a 402LXP challenge.

## Payment flow

1. Agent discovers a service on Deus.
2. Agent calls the service endpoint.
3. Service returns HTTP 402 with a payment challenge (via 402LXP).
4. Agent signs the payment in USDX on LayerX.
5. Service verifies the payment and fulfills the request.
6. Agent receives a signed receipt for the transaction.

The entire flow is automated.

## Service reputation

Deus tracks service reliability metrics:

- **Uptime** - percentage of requests that receive a valid response.
- **Latency** - average response time over the last 24 hours.
- **Fulfillment rate** - percentage of paid requests that return successfully.

Agents can use these metrics to select between competing services offering similar capabilities.

## Pricing models

| Model | Description | Use case |
|-------|-------------|----------|
| `per_call` | Fixed price per request | Stateless API endpoints |
| `streaming` | Price per time window | SSE, WebSocket streams |
| `tiered` | Price varies by volume | Bulk data access |
| `free` | No payment required | Public goods, rate-limited |

## Relationship to LayerX

Deus is a LayerX-native application. It uses USDX for all payments, DID-based accounts for identity, and 402LXP for the payment protocol. Service providers and agents interact through the same LayerX infrastructure that powers direct agent-to-agent transfers.

Deus does not custody funds or hold keys. All payments flow directly from the agent's wallet to the service provider's wallet on LayerX. Deus handles discovery and metadata - LayerX handles settlement.

---

## DID Authentication

*Learn how LayerX uses DID-based challenge/verify authentication with Ed25519 signatures for secure, passwordless agent access to the API.*

## DID authentication

LayerX uses Decentralized Identifiers (DIDs) as account identities. Authentication is based on a challenge/verify flow using Ed25519 signatures - no passwords, no API keys, no shared secrets.

## How it works

1. The agent calls the challenge endpoint with its DID.
2. The server returns a unique challenge string (nonce + timestamp).
3. The agent signs the challenge with its Ed25519 private key.
4. The agent submits the signed challenge to the verify endpoint.
5. The server returns a principal token - a short-lived bearer token for subsequent API calls.

## Challenge endpoint

<CodeGroup>
```bash cURL
curl -X POST https://layerx.paxeer.network/v1/agent/auth/challenge \
  -H "Content-Type: application/json" \
  -d '{"did": "did:ed25519:agent.scanner.v1"}'
```

```typescript TypeScript
const res = await fetch("https://layerx.paxeer.network/v1/agent/auth/challenge", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ did: "did:ed25519:agent.scanner.v1" })
});
const { challenge } = await res.json();
```
</CodeGroup>

**Response:**

```json
{
  "challenge": "a]3F9xK2m...base64url-encoded-nonce...",
  "expires_at": "2026-01-15T10:05:00Z"
}
```

The challenge expires after 5 minutes. If it expires before you verify, request a new one.

## Verify endpoint

Sign the challenge string with your Ed25519 private key and submit the signature.

<CodeGroup>
```bash cURL
curl -X POST https://layerx.paxeer.network/v1/agent/auth/verify \
  -H "Content-Type: application/json" \
  -d '{
    "did": "did:ed25519:agent.scanner.v1",
    "challenge": "a]3F9xK2m...",
    "signature": "base64url-encoded-ed25519-signature"
  }'
```

```typescript TypeScript
import { ed25519 } from "@noble/curves/ed25519";

const signature = ed25519.sign(challenge, privateKey);

const res = await fetch("https://layerx.paxeer.network/v1/agent/auth/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    did: "did:ed25519:agent.scanner.v1",
    challenge,
    signature: Buffer.from(signature).toString("base64url")
  })
});
const { principal_token, expires_at } = await res.json();
```
</CodeGroup>

**Response:**

```json
{
  "principal_token": "eyJhbGciOiJFZERTQSJ9...",
  "expires_at": "2026-01-15T11:05:00Z"
}
```

## Principal tokens

A principal token is a short-lived JWT signed by the LayerX server. It contains the agent's DID, issuance time, and expiry. Use it as a bearer token for all subsequent API calls.

```
Authorization: Bearer eyJhbGciOiJFZERTQSJ9...
```

Principal tokens expire after 1 hour by default. When a token expires, re-run the challenge/verify flow to obtain a new one.

## Dual authorization

LayerX supports two authorization modes for transfer requests:

### DID-signed intent

Sign the transfer payload directly with the agent's Ed25519 key. The sequencer verifies the signature against the DID's registered public key. This mode is used by SDKs and programmatic clients.

```json
{
  "to": "did:ed25519:service.data.v2",
  "amount": "1.50",
  "did": "did:ed25519:agent.scanner.v1",
  "signature": "base64url-encoded-signature-over-payload"
}
```

### Principal token

Include a valid principal token in the `Authorization` header. The sequencer verifies the token's signature and checks that the token's DID matches the transfer sender. This mode is used by interactive clients and web dashboards.

Both modes are accepted on all write endpoints. Choose the one that fits your integration pattern - they are mutually interchangeable.

## DID resolution

LayerX resolves DIDs to Ed25519 public keys using the `did:ed25519` method. The public key is registered when the account is first created (via deposit or wallet creation). The DID document is stored in the Postgres ledger and can be queried via the API.

---

## Error Codes

*Learn the LayerX API's standardized JSON error structure, complete list of error codes, HTTP statuses, and guidance for retryable versus non-retryable*

## Error codes

All LayerX API errors follow a consistent JSON structure:

```json
{
  "error": {
    "code": "insufficient_funds",
    "message": "Transfer amount exceeds available balance.",
    "details": {
      "available": "10.00",
      "requested": "25.00"
    }
  }
}
```

The `code` field is a stable machine-readable string. The `message` field is a human-readable explanation. The `details` field is optional and contains context-specific information.

## Error codes

### `invalid_request`

The request body or parameters are malformed. This includes missing required fields, invalid DID formats, non-numeric amounts, or malformed JSON.

**HTTP status:** 400

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Field 'amount' must be a positive decimal string.",
    "details": { "field": "amount", "value": "-5" }
  }
}
```

### `unauthorized`

The request lacks a valid principal token, the token has expired, or the DID signature verification failed.

**HTTP status:** 401

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Principal token has expired."
  }
}
```

Re-run the [DID challenge/verify flow](/layerx/did-auth) to obtain a new token.

### `not_found`

The requested resource does not exist. This applies to receipt lookups, transfer queries, and DID lookups.

**HTTP status:** 404

```json
{
  "error": {
    "code": "not_found",
    "message": "No receipt found for sequence number 99999."
  }
}
```

### `insufficient_funds`

The sender's USDX balance is less than the requested transfer amount.

**HTTP status:** 402

```json
{
  "error": {
    "code": "insufficient_funds",
    "message": "Transfer amount exceeds available balance.",
    "details": { "available": "10.00", "requested": "25.00" }
  }
}
```

When returned in the context of a 402LXP flow, this indicates the agent cannot afford the service's price.

### `conflict`

The request conflicts with current state. Common causes:

- **Duplicate transfer** - a transfer with the same nonce has already been processed.
- **Already settled** - the requested transfer has already been force-settled.
- **Concurrent modification** - the account was modified by another request.

**HTTP status:** 409

```json
{
  "error": {
    "code": "conflict",
    "message": "Transfer with nonce 42 already exists."
  }
}
```

### `internal`

An unexpected server error occurred. These are logged and investigated automatically. Retry with exponential backoff.

**HTTP status:** 500

```json
{
  "error": {
    "code": "internal",
    "message": "An unexpected error occurred. Please retry."
  }
}
```

### `rate_limited`

The client has exceeded the rate limit. The `details` object includes the retry-after window.

**HTTP status:** 429

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded.",
    "details": { "retry_after_seconds": 5 }
  }
}
```

## Handling errors

### Retryable errors

- `internal` - retry with exponential backoff (1s, 2s, 4s, max 30s).
- `rate_limited` - wait for `retry_after_seconds` before retrying.
- `conflict` (duplicate nonce) - check if the transfer already succeeded before retrying.

### Non-retryable errors

- `invalid_request` - fix the request body before retrying.
- `unauthorized` - re-authenticate before retrying.
- `not_found` - the resource does not exist.
- `insufficient_funds` - deposit more USDX before retrying.

---

## LayerX - Agent-Only Side Channel

*LayerX is Paxeer Network's agent-only side channel offering zero-fee transfers, instant settlement, and batched Merkle anchoring to L1.*

## LayerX

LayerX is an agent-only side channel on Paxeer Network. It delivers zero-fee transfers, instant settlement, and batched anchoring to Paxeer L1 for autonomous agents that need to move value at machine speed.

## Why LayerX

LayerX removes the gas costs and block-time latency that make on-chain micropayments impractical:

- **Zero fees** - transfers within LayerX carry no gas cost.
- **Instant settlement** - recipients see funds immediately; no block confirmations.
- **L1 finality** - batches of transfers are committed to Paxeer L1 every few minutes via Merkle roots, inheriting the security of the base chain.

## Core concepts

| Concept | Description |
|---------|-------------|
| **USDX** | Dollar-denominated balance fully reserved 1:1 by USDL on Paxeer L1. |
| **DID accounts** | Each agent's Decentralized Identifier is its LayerX account. No wallet import or key conversion required. |
| **402LXP** | HTTP-native payment protocol that lets agents pay for API calls in USDX using HTTP 402 challenges. |
| **Deus** | Agent marketplace where capabilities are published, discovered, and paid for via 402LXP. |

## How it works

1. An agent deposits USDL into the LayerX bridge contract on Paxeer L1.
2. The deposit is credited as USDX on LayerX, available for instant transfers.
3. Agents transact freely - zero fees, instant finality, signed receipts for every transfer.
4. A sequencer batches transfers, builds a Merkle tree, and anchors the root to Paxeer L1.
5. Any agent can withdraw USDX back to USDL on L1 via the settlement process.

## Explore LayerX

<Columns cols={2}>
  <Card title="Architecture" href="/layerx/architecture">
    Sequencer, ledger, Merkle accumulator, and settlement internals.
  </Card>
  <Card title="Agent wallets" href="/layerx/agent-wallets">
    Policy-bound wallets with spending caps and service allowlists.
  </Card>
  <Card title="DID authentication" href="/layerx/did-auth">
    Challenge/verify flow, Ed25519 signing, and principal tokens.
  </Card>
  <Card title="402LXP protocol" href="/layerx/402lxp">
    HTTP-native agent payments - no checkout flow required.
  </Card>
  <Card title="USDX & settlement" href="/layerx/usdx-settlement">
    Deposits, withdrawals, and tiered settlement model.
  </Card>
  <Card title="Deus marketplace" href="/layerx/deus">
    Publish, discover, and pay for agent capabilities.
  </Card>
  <Card title="API reference" href="/evm/reference">
    Complete REST API documentation for all endpoints.
  </Card>
  <Card title="Error codes" href="/layerx/error-codes">
    Standard error responses and troubleshooting.
  </Card>
</Columns>

---

## Signed Receipts

*Learn how LayerX signed receipts, domain-separated Merkle leaves, and inclusion proofs let anyone verify transfers without trusting the sequencer.*

## Signed receipts

Every transfer on LayerX produces a signed receipt - a cryptographically verifiable record that the transfer occurred, was accepted by the sequencer, and was included in a committed batch. Receipts are the foundation of LayerX's trust model: they let any party verify transfers without relying on the sequencer's honesty.

## Receipt structure

A receipt contains:

| Field | Description |
|-------|-------------|
| `seq` | Monotonically increasing sequence number |
| `sender` | Sender's DID |
| `recipient` | Recipient's DID |
| `amount` | Transfer amount in USDX |
| `timestamp` | Sequencer-accepted time (RFC 3339) |
| `batch_seq` | Batch sequence number (set after batch closes) |
| `merkle_leaf` | Domain-separated hash of the transfer |
| `signature` | Sequencer's Ed25519 signature over the receipt |

The sequencer signs every receipt at transfer time. The `batch_seq` and `merkle_leaf` fields are populated once the transfer is included in a closed batch.

## Domain-separated Merkle leaves

Each transfer is hashed into a Merkle leaf using a domain separator to prevent cross-chain and cross-domain replay:

```
leaf = keccak256(
  "LAYERX_TRANSFER_V1" ||
  sender_did_bytes ||
  recipient_did_bytes ||
  amount_bytes ||
  seq_bytes ||
  timestamp_bytes
)
```

The domain separator `"LAYERX_TRANSFER_V1"` is a fixed string. If LayerX ever introduces a second domain (e.g., for a different asset), it will use a distinct separator.

## Inclusion proofs

After a batch is anchored to Paxeer L1, anyone can verify that a specific transfer was included in that batch using a Merkle inclusion proof.

An inclusion proof consists of:

- The transfer's Merkle leaf.
- The sibling hashes along the path from the leaf to the root.
- The expected Merkle root (published on L1).

To verify:

1. Hash the leaf with its sibling at each level, moving up the tree.
2. Compare the computed root with the on-chain Merkle root.
3. If they match, the transfer was included in the batch.

```typescript
import { verifyInclusion } from "@paxeer/merkle";

const valid = verifyInclusion({
  leaf: transfer.merkle_leaf,
  proof: transfer.merkle_proof,
  root: batch.merkle_root
});
// valid === true means the transfer was committed to L1
```

## Public receipt access

Receipts are publicly readable. Any party can fetch a receipt by its sequence number:

```bash
curl https://layerx.paxeer.network/v1/receipt/12345
```

**Response:**

```json
{
  "seq": 12345,
  "sender": "did:ed25519:agent.scanner.v1",
  "recipient": "did:ed25519:service.weather.v2",
  "amount": "0.001",
  "timestamp": "2026-01-15T10:03:42Z",
  "batch_seq": 987,
  "merkle_leaf": "0xa3f9...",
  "merkle_proof": ["0xb2c1...", "0xd4e5..."],
  "signature": "base64url-encoded-sequencer-signature"
}
```

This endpoint is unauthenticated - no DID challenge or principal token required. Receipts are public records.

## Independent verifiability

The receipt system is designed so that no party needs to trust the sequencer:

- **Recipients** verify that their incoming transfer was signed by the sequencer and included in a committed batch.
- **Senders** verify that their outgoing transfer was recorded correctly.
- **Third parties** (auditors, regulators, other agents) can verify any transfer's inclusion by checking the Merkle proof against the on-chain root.
- **The sequencer** cannot forge transfers - the Merkle root on L1 is immutable once anchored, and any discrepancy between the API's receipts and the on-chain root would be immediately detectable.

This model ensures that LayerX's off-chain speed does not compromise on-chain verifiability.

---

## Settlement Model

*Learn how LayerX's tiered settlement model batches transfers via Merkle roots for speed and supports force-settle for instant L1 finality.*

## Settlement model

LayerX uses a tiered settlement model that optimizes for speed on the happy path while preserving the ability to force high-value or time-sensitive transactions through immediate L1 finality.

## Window-based net settlement

Most LayerX transfers are settled via net-batched windows. The sequencer accumulates transfers during a batch window (typically a few minutes), then at window close:

1. **Compute net positions** - for each DID, calculate the net inflow or outflow across all transfers in the batch.
2. **Build Merkle tree** - hash each transfer into a domain-separated leaf and construct a Merkle tree over all leaves in the batch.
3. **Anchor to L1** - submit the Merkle root, batch sequence number, and metadata to the Paxeer L1 bridge contract.

This approach amortizes L1 gas across all transfers in a batch. A batch with 10,000 transfers pays one L1 transaction instead of 10,000.

## Merkle root construction

Each transfer in a batch becomes a Merkle leaf:

```
leaf = keccak256(
  domain_separator || sender_did || recipient_did || amount || seq || timestamp
)
```

The `domain_separator` is a fixed string that prevents cross-domain replay. The tree is built bottom-up using keccak256 hashing with sorted pairs (so the tree is deterministic regardless of insertion order).

The resulting root is a 32-byte commitment to the entire batch. Anyone who has the root and a transfer's inclusion proof can verify that the transfer was committed - without trusting the sequencer.

## L1 anchoring

The Merkle root is submitted to the LayerX bridge contract on Paxeer L1 (chain ID 125) via the settlement worker:

```solidity
function anchorBatch(
    uint256 batchSeq,
    bytes32 merkleRoot,
    uint256 timestamp,
    uint256 transferCount
) external;
```

Once the anchor transaction is confirmed on L1, the batch is final. No one - not even the sequencer operator - can retroactively alter the transfers in that batch.

## Force-settle

For transfers that cannot wait for the next batch window, LayerX supports force-settlement. A force-settled transfer is committed to L1 individually, outside the batch cycle.

### When to use force-settle

- **Large withdrawals** - moving significant USDX back to USDL on L1.
- **Time-sensitive settlements** - when L1 finality is needed within seconds, not minutes.
- **Dispute resolution** - when a party wants immediate on-chain proof of a specific transfer.

### How it works

1. Call `POST /v1/force-settle` with the transfer sequence number.
2. The settlement worker verifies the transfer exists and is unsettled.
3. The worker submits the transfer to L1 individually.
4. The L1 transaction hash is returned.

Force-settled transfers are still included in the next batch's Merkle tree for consistency, but their L1 finality does not depend on the batch.

## Withdrawal settlement

When an agent withdraws USDX to USDL on L1:

1. The withdrawal request is recorded in the LayerX ledger.
2. USDX is debited from the agent's account immediately.
3. At the next settlement window (or via force-settle), the settlement worker releases USDL from the bridge contract to the agent's L1 address.

Withdrawals are always material-tier - they result in an L1 transaction regardless of the batch cycle, because the bridge contract must release USDL on-chain.

## Tiered model summary

| Tier | Mechanism | L1 cost | Latency |
|------|-----------|---------|---------|
| **Micropayment** | Net-batched, Merkle root | Amortized | Minutes |
| **Material** | Individual L1 commit | Full gas | Seconds |
| **Withdrawal** | Bridge release | Full gas | Seconds to minutes |

The tiered model lets LayerX handle millions of agent transfers at zero marginal cost, while preserving the option for immediate L1 settlement when the situation demands it.

---

## USDX & Settlement

*Learn how USDX, the 1:1 USDL-backed settlement token on LayerX, handles deposits, withdrawals, and tiered settlement for agent transactions.*

## USDX & settlement

USDX is the native balance unit on LayerX - a dollar-denominated token fully reserved 1:1 by USDL on Paxeer L1. Every USDX in circulation is backed by a corresponding USDL locked in the LayerX bridge contract.

## USDX

USDX is not a standalone token. It exists only as a balance within the LayerX ledger. It cannot be transferred outside LayerX or traded on external markets. Its sole purpose is to serve as a fast, zero-fee settlement medium for agent transactions.

**Key properties:**

- **Dollar-denominated** - 1 USDX = 1 USD.
- **Fully reserved** - every USDX is backed 1:1 by USDL in the bridge contract.
- **Ledger-native** - no ERC-20 contract; balances are tracked in the Postgres ledger.
- **Instant finality** - transfers settle immediately on LayerX.

## Deposits

To fund a LayerX account, deposit USDL into the bridge contract on Paxeer L1.

### Flow

1. Call `POST /v1/deposit` with the L1 transaction hash.
2. The settlement worker verifies the deposit on-chain.
3. USDX is credited to the agent's LayerX account.

```bash
curl -X POST https://layerx.paxeer.network/v1/deposit \
  -H "Authorization: Bearer <principal_token>" \
  -H "Content-Type: application/json" \
  -d '{"tx_hash": "0xabc123...", "did": "did:ed25519:agent.scanner.v1"}'
```

Deposits are confirmed after the L1 transaction reaches finality (typically a few seconds on Paxeer). The credited amount matches the USDL deposited, minus any L1 gas (which is not charged by LayerX itself).

## Withdrawals

To move USDX back to USDL on Paxeer L1, submit a withdrawal request.

### Flow

1. Call `POST /v1/withdraw` with the amount and destination address.
2. The settlement worker debits USDX from the LayerX account.
3. On the next settlement window, the worker releases USDL from the bridge contract to the destination address.

```bash
curl -X POST https://layerx.paxeer.network/v1/withdraw \
  -H "Authorization: Bearer <principal_token>" \
  -H "Content-Type: application/json" \
  -d '{"amount": "25.00", "to": "pax1abc123..."}'
```

Withdrawals are processed during the next settlement window - they are not instant. If you need immediate L1 settlement, use the force-settle endpoint.

## Settlement tiers

LayerX uses a tiered settlement model that balances speed and cost.

### Micropayment tier (net-batched)

Most transfers settle at this tier. The sequencer records transfers in real time, and at the end of each batch window (typically a few minutes), it computes net positions and commits a Merkle root to L1.

- **Latency**: instant on LayerX, L1 anchor within minutes.
- **Cost**: zero on LayerX; L1 anchoring is amortized across all transfers in the batch.
- **Use case**: agent-to-agent payments, 402LXP calls, marketplace purchases.

### Material tier (force-settled)

For high-value transfers or withdrawals that require immediate L1 finality, use the material tier. These transfers bypass the batch window and are committed to L1 individually.

- **Latency**: L1 finality within seconds.
- **Cost**: L1 gas for the individual transaction.
- **Use case**: large withdrawals, time-sensitive settlements.

To force-settle a transfer:

```bash
curl -X POST https://layerx.paxeer.network/v1/force-settle \
  -H "Authorization: Bearer <principal_token>" \
  -H "Content-Type: application/json" \
  -d '{"transfer_seq": 12345}'
```

The settlement worker submits the transfer to L1 immediately and returns the L1 transaction hash.

## Reserves transparency

The LayerX bridge contract holds all USDL backing USDX in circulation. The total USDL locked is always equal to or greater than total USDX outstanding. This invariant is enforced by the settlement worker and verifiable on-chain.

---

## Paxeer Node Advanced Configuration & Monitoring

*Optimize Paxeer node performance with advanced configuration, Prometheus and Grafana monitoring, and alerting.*

## Optimizing System Configuration

There are a virtually unlimited number of unique individual setups that cannot be covered in this document. As well, even similar builds and configurations can behave differently due to external factors, so your results may vary.

Here are some general guidelines to use as a starting point. Be cautious, make incremental changes, testing and observing before moving forward.
Always focus on only one specific area at a time - avoid making changes to memory, storage, and CPU configs all at once. Diagnosing potential problems becomes nearly impossible otherwise.

### Memory Management

The following settings in `/etc/sysctl.conf` can optimize memory usage and disk I/O patterns:

```bash
# Minimize swapping
vm.swappiness = 1

# Control disk write behavior
vm.dirty_background_ratio = 3
vm.dirty_ratio = 10
vm.dirty_expire_centisecs = 300
vm.dirty_writeback_centisecs = 100
```

Apply changes: `sudo sysctl -p`

### Network Stack

The following settings in `/etc/sysctl.conf` may improve network performance:

```bash
# Increase connection handling capacity
net.core.somaxconn = 32768
net.core.netdev_max_backlog = 32768
net.ipv4.tcp_max_syn_backlog = 16384

# Optimize buffer sizes
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 87380 16777216
```

### Storage Configuration

For NVMe drives, optimize I/O scheduling:

```bash
# Set IO scheduler
echo "none" > /sys/block/nvme0n1/queue/scheduler

# Set read-ahead buffer
blockdev --setra 4096 /dev/nvme0n1

# Set IO priority in systemd service
sudo tee -a /etc/systemd/system/paxd.service << EOF
[Service]
IOSchedulingClass=realtime
IOSchedulingPriority=2
EOF

# Configure disk mount options
sudo tee -a /etc/fstab << EOF
/dev/nvme0n1p1 /data ext4 defaults,noatime,nosuid,nodev,noexec,commit=60 0 0
EOF
```

## Infrastructure Monitoring

Monitoring is one of the most critical components of network infrastructure. performance tuning, and alerting configuration for Cosmos-SDK/Tendermint nodes.

### Prometheus Setup

First, install Prometheus:

```bash
wget https://github.com/prometheus/prometheus/releases/download/v2.42.0/prometheus-2.42.0.linux-amd64.tar.gz
tar xvf prometheus-2.42.0.linux-amd64.tar.gz
```

Example Prometheus configuration:

```yaml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'paxeer_node'
    static_configs:
      - targets: ['node1_ip:port']
    metrics_path: /metrics
  - job_name: 'node'
    static_configs:
      - targets: ['node2_ip:port']
```

### Grafana Integration

Install and configure Grafana:

```bash
sudo apt install -y apt-transport-https software-properties-common
sudo add-apt-repository "deb https://packages.grafana.com/oss/deb stable main"
sudo apt update && sudo apt-get install grafana
```

<Accordion title="Sample Grafana Dashboard JSON">

```json
{
	"annotations": {
		"list": [
			{
				"builtIn": 1,
				"datasource": "-- Grafana --",
				"enable": true,
				"hide": true,
				"iconColor": "rgba(0, 211, 255, 1)",
				"name": "Annotations & Alerts",
				"type": "dashboard"
			}
		]
	},
	"editable": true,
	"gnetId": null,
	"graphTooltip": 0,
	"id": 1,
	"links": [],
	"panels": [
		{
			"alerting": {},
			"aliasColors": {},
			"bars": false,
			"dashLength": 10,
			"dashes": false,
			"datasource": null,
			"fieldConfig": {
				"defaults": {
					"custom": {}
				},
				"overrides": []
			},
			"fill": 1,
			"fillGradient": 0,
			"gridPos": {
				"h": 8,
				"w": 12,
				"x": 0,
				"y": 0
			},
			"hiddenSeries": false,
			"id": 2,
			"legend": {
				"avg": false,
				"current": false,
				"max": false,
				"min": false,
				"show": true,
				"total": false,
				"values": false
			},
			"lines": true,
			"linewidth": 1,
			"nullPointMode": "null",
			"options": {
				"alertThreshold": true
			},
			"percentage": false,
			"pluginVersion": "7.2.0",
			"pointradius": 2,
			"points": false,
			"renderer": "flot",
			"seriesOverrides": [],
			"spaceLength": 10,
			"stack": false,
			"steppedLine": false,
			"targets": [
				{
					"expr": "tendermint_consensus_height",
					"interval": "",
					"legendFormat": "",
					"refId": "A"
				}
			],
			"thresholds": [],
			"timeRegions": [],
			"title": "Block Height",
			"tooltip": {
				"shared": true,
				"sort": 0,
				"value_type": "individual"
			},
			"type": "graph",
			"xaxis": {
				"buckets": null,
				"mode": "time",
				"name": null,
				"show": true,
				"values": []
			},
			"yaxes": [
				{
					"format": "short",
					"label": null,
					"logBase": 1,
					"max": null,
					"min": null,
					"show": true
				},
				{
					"format": "short",
					"label": null,
					"logBase": 1,
					"max": null,
					"min": null,
					"show": true
				}
			],
			"yaxis": {
				"align": false,
				"alignLevel": null
			}
		}
	],
	"schemaVersion": 26,
	"style": "dark",
	"tags": [],
	"templating": {
		"list": []
	},
	"time": {
		"from": "now-6h",
		"to": "now"
	},
	"timepicker": {},
	"timezone": "",
	"title": "Paxeer Node Metrics",
	"uid": "paxeer_metrics",
	"version": 1
}
```

</Accordion>

### Alert Management

Install Alertmanager:

```bash
wget https://github.com/prometheus/alertmanager/releases/download/v0.25.0/alertmanager-0.25.0.linux-amd64.tar.gz
tar xvf alertmanager-0.25.0.linux-amd64.tar.gz
```

<Accordion title="Create Alert Rules Configuration">

```yaml
groups:
  - name: validator_alerts
    rules:
      - alert: NodeDown
        expr: up == 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: 'Node {{ $labels.instance }} down'

      - alert: BlockProductionSlow
        expr: rate(tendermint_consensus_height[5m]) < 0.1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: 'Block production is slow on {{ $labels.instance }}'
      - alert: ValidatorMissedBlocks
        expr: increase(tendermint_consensus_validator_missed_blocks[1h]) > 0
        labels:
          severity: critical
        annotations:
          summary: 'Validator missing blocks'

      - alert: ValidatorJailed
        expr: tendermint_consensus_validator_status == 0
        labels:
          severity: critical
        annotations:
          summary: 'Validator has been jailed'

      - alert: ConsensusStalled
        expr: tendermint_consensus_height_status == 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: 'Consensus has stalled'
```

</Accordion>

## Log Management

### Loki Setup

Using Loki for log aggregation:

```bash
wget https://github.com/grafana/loki/releases/download/v2.8.0/loki-linux-amd64.zip
unzip loki-linux-amd64.zip
```

<Accordion title="Promtail Configuration">

```yaml
server:
  http_listen_port: 9080

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://localhost:3100/loki/api/v1/push

scrape_configs:
  - job_name: paxeer_logs
    static_configs:
      - targets:
          - localhost
        labels:
          job: paxd_logs
          __path__: /var/log/paxd/*.log
```

</Accordion>

### Log Rotation

Configure logrotate to manage log files:

```bash
sudo tee /etc/logrotate.d/paxeer << EOF
/var/log/paxeer/*.log {
    daily
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 paxeer paxeer
    sharedscripts
    postrotate
        systemctl reload paxd
    endscript
}
EOF
```

## Security Configuration

### Network Security

UFW firewall configuration:

```bash
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 26656/tcp comment 'Paxeer P2P'
sudo ufw allow 26657/tcp comment 'Paxeer RPC'
sudo ufw allow 9090/tcp comment 'Paxeer gRPC'
sudo ufw enable
```

### Rate Limiting

<Accordion title="Example Nginx Configuration with Rate Limiting">

```nginx
http {
    limit_req_zone $binary_remote_addr zone=paxeer_rpc:10m rate=10r/s;

    server {
        listen 26657;
        location / {
            limit_req zone=paxeer_rpc burst=20 nodelay;
            proxy_pass http://localhost:26657;
        }
    }
}
```

</Accordion>

## Validator-Specific Monitoring

### Status Query

Query validator status through SDK:

```bash
paxd query staking validator $(paxd keys show --bech val -a <validator_keyfile_name>)
```

Query through REST API:

```sh
curl -s "http://localhost:1317/cosmos/staking/v1beta1/validators/<valoper_address>"
```

<Accordion title='Validator "Status" Query Script'>

```sh
#!/bin/bash

MONIKER="$1"
API_URL="http://localhost:1317/cosmos/staking/v1beta1/validators?pagination.limit=500"

echo "Querying validators from $API_URL..."

VALIDATOR_DATA=$(curl -s "$API_URL" | jq -c --arg MONIKER "$MONIKER" '.validators[] | select(.description.moniker == $MONIKER)')

if [[ -z "$VALIDATOR_DATA" ]]; then
    echo "No validator found with moniker: $MONIKER"
    exit 1
fi

echo "Validator details:"
echo "$VALIDATOR_DATA" | jq '.'
```

</Accordion>

### Critical Metrics

Monitor these validator-specific metrics:

```bash
# Check signing status
paxd query slashing signing-info $(paxd tendermint show-validator)

# Check current delegations
paxd query staking delegations-to $(paxd keys show -a $VALIDATOR_KEY)
```

## Backup Management

<Accordion title="Complete Automated Backup Script">

```bash
#!/bin/bash
BACKUP_DIR="/backup/paxeer"
DATE=$(date +%Y%m%d)
NODE_HOME="/root/.paxeer"

# Create backup directory
mkdir -p $BACKUP_DIR

# Stop service
systemctl stop paxd

# Backup configuration
tar czf $BACKUP_DIR/paxeer-config-$DATE.tar.gz $NODE_HOME/config

# Backup data directory
tar czf $BACKUP_DIR/paxeer-data-$DATE.tar.gz $NODE_HOME/data

# Backup key files
tar czf $BACKUP_DIR/paxeer-keys-$DATE.tar.gz $NODE_HOME/keyring-file

# Start service
systemctl start paxd

# Remove backups older than 7 days
find $BACKUP_DIR -type f -mtime +7 -name '*.tar.gz' -delete

# Log backup completion
echo "Backup completed successfully on $(date)" >> $BACKUP_DIR/backup.log
```

</Accordion>

## Host System Monitoring

### Resource Usage Tracking

Install and configure node_exporter:

```bash
wget https://github.com/prometheus/node_exporter/releases/download/v1.5.0/node_exporter-1.5.0.linux-amd64.tar.gz
tar xvf node_exporter-1.5.0.linux-amd64.tar.gz
```

Add to Prometheus configuration:

```yaml
scrape_configs:
  - job_name: 'node'
    static_configs:
      - targets: ['localhost:9100']
```

For specific customizations or additional metrics, consult the Paxeer
technical communities.

---

## Node Operations on Paxeer

*Learn to install, configure, and run RPC, validator, statesync, and archive nodes on Paxeer using the hpx CLI tool.*

**Power the Paxeer Network Infrastructure**

Guides for running validators, RPC nodes, and archive nodes on Paxeer.

<Columns cols={4}>
  <Card horizontal title="RPC/API Nodes" icon="network-wired" />
  <Card horizontal title="Validator Nodes" icon="shield" />
  <Card horizontal title="Statesync Nodes" icon="shuffle" />
  <Card horizontal title="Archive Nodes" icon="database" />
</Columns>

## Quick start with hpx CLI

The fastest way to get a Paxeer node running is the `hpx` CLI tool:

```bash
curl -sSL https://get.cloud.hyperpaxeer.com/get-hpx.sh | sudo bash
```

This installs the `hpx` management tool for binary installation, configuration, and service management.

## Hardware Requirements

| Component | Required                                               |
| --------- | ------------------------------------------------------ |
| CPU       | 16 cores (Intel Xeon/Core i7/i9 or AMD Epyc/Ryzen)     |
| RAM       | 256 GB DDR5 or better                                  |
| Storage   | 2 TB NVMe SSD (high IOPS required)                     |
| Network   | 2 Gbps with low latency                                |

## Installation & Setup Steps

<Steps>

<Step title="Environment Setup">
### System Preparation

#### 1. Update and Upgrade System

```bash
sudo apt update && sudo apt upgrade -y
```

#### 2. Install Essential Packages

```bash
sudo apt install make gcc git jq chrony curl lz4 wget tar build-essential -y
```

#### 3. Synchronize System Time

```bash
sudo timedatectl set-timezone UTC
sudo systemctl enable --now chronyd
timedatectl
```

### Install Go

Suggested Version: Go 1.24.x

#### Installation Steps

```bash
# Check for existing Go installation
go version

# Download and install Go 1.24.x
wget https://go.dev/dl/go1.24.5.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.5.linux-amd64.tar.gz

# Add Go to your environment variables
echo 'export PATH=$PATH:/usr/local/go/bin' >> $HOME/.bashrc
source $HOME/.bashrc

# Verify installation
go version
```
</Step>

<Step title="Install Paxeer">
### Install Paxeer Binary

```bash
# Using the hpx CLI (recommended)
hpx install

# Or build from source:
git clone https://github.com/paxeer-network/paxeer-chain.git
cd paxeer-chain
git checkout <version-tag>
make install

# Verify installation
paxd version
```

<Info>
  If you encounter an error like `command not found: paxd`, you may need to set your GOPATH environment variable.

  Add the following to your `~/.bashrc` or `~/.zshrc`:

  ```bash
  export GOPATH=$(go env GOPATH)
  export PATH=$PATH:$GOPATH/bin
  ```

  Then reload your shell with `source ~/.bashrc` or `source ~/.zshrc`.
</Info>

### Initialize Chain Files

<Info>Default init mode is **full** (RPC/P2P bind to all interfaces). For **validator** or **seed** nodes, use `--mode validator` or `--mode seed` so RPC and P2P bind to localhost only. See the [Validator Operations Guide](/node/validators) for the full validator init example.</Info>

Seed peer:

```bash
e9c56cbadc4a96b67f69dcaaa7b4691851e945ca@31.220.74.140:26656
```

```bash
# Initialize node (default mode is full: RPC/P2P bind to all interfaces)
# For validator nodes, use: paxd init <your-moniker> --chain-id hyperpax_125-1 --mode validator
paxd init <your-moniker> --chain-id hyperpax_125-1

# Configure peers in config.toml.
PEERS="e9c56cbadc4a96b67f69dcaaa7b4691851e945ca@31.220.74.140:26656"

# Set persistent peers in config.toml
sed -i 's/persistent-peers = .*/persistent-peers = "'$PEERS'"/' ~/.paxeer/config/config.toml
```

### Configure App Settings

```bash
# Set minimum gas price
sed -i -e "s/^minimum-gas-prices *=.*/minimum-gas-prices = \"0.02uhpx\"/" $HOME/.paxeer/config/app.toml

# Tune mempool settings
sed -i \
  -e 's/^keep-invalid-txs-in-cache = .*/keep-invalid-txs-in-cache = true/' \
  -e 's/^ttl-duration = .*/ttl-duration = "5s"/' \
  -e 's/^ttl-num-blocks = .*/ttl-num-blocks = 5/' \
  $HOME/.paxeer/config/config.toml

# Set Concurrent Workers to 500 and enable occ
sed -i -e "s/^#concurrency-workers *=.*/concurrency-workers = 500/" $HOME/.paxeer/config/app.toml
sed -i -e "s/^occ-enabled *=.*/occ-enabled = true/" $HOME/.paxeer/config/app.toml
```

<Info>
  In case of running an Archive Node, make sure to set your state-store settings to `ss-keep-recent = 0` with

  ```bash
  sed -i 's/^ss-keep-recent = [0-9]*/ss-keep-recent = 0/' ~/.paxeer/config/app.toml
  ```
</Info>

<Accordion title="Advanced Configuration">

#### Archive Node Setup

An archive node maintains the complete historical record of the chain. This requires disabling state sync and starting with a pre-existing database using a "snapshot".

**1. Disable State Sync** - In $HOME/.paxeer/config/config.toml, modify the [statesync] section:

```toml
# State sync configuration
[statesync]
enable = false
```

**2. Configure Archive Node Peers** - To sync from the height your snapshot was created at, you need peers retaining a large amount of historical blocks.

#### Mempool Configuration

For optimal transaction handling and resource management, it is recommended to update the mempool settings in your `config.toml` file.

<Info>
  Adjust these parameters if you encounter performance or resource issues on your specific hardware.
</Info>

```toml
# Mempool configuration settings
[mempool]

# Broadcast transactions to other nodes
broadcast = true

# Maximum number of transactions in the mempool
size = 5000

# Limit the total size of all txs in the mempool.
max-txs-bytes = 10737418240

# Size of the cache (used to filter duplicate transactions)
cache-size = 10000

# Do not remove invalid transactions from the cache
keep-invalid-txs-in-cache = true

# Maximum size of a single transaction
max-tx-bytes = 2048576

# Maximum length of time a transaction can remain in the mempool
ttl-duration = "3s"

# Maximum number of blocks a transaction can remain in the mempool
ttl-num-blocks = 5
```

</Accordion>
</Step>

<Step title="Run Node">
### Setting Up a systemd Service

<Danger>If you see an error such as `panic: recovered: runtime error: integer divide by zero` it means you can't start nodes straight from the genesis file. Instead, sync to the block tip via [state sync](/node/statesync) or using a [snapshot](/node/snapshot).</Danger>

For production deployments, configure a systemd service:

```bash
# Create the systemd service file
sudo tee /etc/systemd/system/paxd.service > /dev/null << EOF
[Unit]
Description=Paxeer Node
After=network-online.target

[Service]
User=$USER
ExecStart=$(which paxd) start
Restart=always
RestartSec=3
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

# Reload systemd, enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable paxd
sudo systemctl start paxd
```

### Monitoring & Troubleshooting

Check your node's status with these commands:

```bash
# Check sync status
paxd status

# Monitor logs in real-time
journalctl -u paxd -f -o cat

# Check validator status (if running a validator)
paxd query staking validator $(paxd keys show <your_key> --bech val -a)
```

**Common Issues & Solutions**

<Columns cols={2}>
  <Card horizontal title="Sync Issues">
    - Verify sufficient disk space
    - Ensure stable network connectivity
    - Confirm system time is synchronized
    - Consider using state sync for initial setup
  </Card>
  <Card horizontal title="Performance Problems">
    - Monitor system resources (CPU, RAM, I/O)
    - Evaluate disk performance and network bandwidth
    - Adjust mempool and peer settings if needed
  </Card>
</Columns>
</Step>

</Steps>

[View Complete Node Setup Guide](/node/node-operators)

## Node Resources

### Node Setup

<Columns cols={3}>
  <Card horizontal title="Node Operations Guide" icon="server" href="/node/node-operators">
    Complete guide to setting up and running a Paxeer node with hardware requirements and configuration steps.
  </Card>
  <Card horizontal title="Validator Operations Guide" icon="shield" href="/node/validators">
    Specialized instructions for validators, including staking, commission settings, and security best practices.
  </Card>
  <Card horizontal title="Default Configurations" icon="file-lines" href="/node/node-operators#default-configurations">
    Full reference for `app.toml`, `config.toml`, and `client.toml` shipped by the latest `paxd` release.
  </Card>
</Columns>

### Advanced Operations

<Columns cols={3}>
  <Card horizontal title="Configuration & Monitoring" icon="gauge-simple-high" href="/node/advanced-config-monitoring">
    Optimize your node's performance with advanced settings and monitoring tools.
  </Card>
  <Card horizontal title="RocksDB Backend" icon="database" href="/node/rocksdb-backend">
    Run with RocksDB instead of the default backend.
  </Card>
  <Card horizontal title="Technical Reference" icon="terminal" href="/node/technical-reference">
    Detailed technical specifications, API endpoints, and commands for node operators.
  </Card>
</Columns>

---

## Paxeer Node Operations Guide

*Detailed guide for running and maintaining Paxeer nodes. Learn about configuration management, database maintenance, service management, and update procedures.*

This guide covers the detailed operational aspects of running a Paxeer node,
including configuration management, maintenance procedures, and best practices
for stable and performant operations.

## Configuration Management

### Directory Structure

The Paxeer node configuration is stored in `$HOME/.paxeer/config/`:

```bash
$HOME/.paxeer/config/
├── app.toml          # Application configuration (gas fees, API settings, pruning, etc.)
├── config.toml       # Core Tendermint settings (network, consensus, and RPC)
├── client.toml       # CLI and client-related settings
├── genesis.json      # Chain genesis file, defines initial state
├── node_key.json     # Unique node identity key for peer-to-peer (P2P) networking
└── priv_validator_key.json  # Validator private signing key (if running as a validator)
```

The snippets below are opinionated tuning recommendations layered on top of
the defaults. For the *full* unmodified `app.toml`, `config.toml`, and
`client.toml` shipped by the latest tagged `paxd` release, jump to
[Default Configurations](#default-configurations) at the bottom of this
section.

### Essential Configuration Parameters

#### Network Settings (config.toml)

```toml
[p2p]
# Public address other nodes use to dial in (host:port)
external-address = "your-public-ip:26656"
# Local address to listen for incoming P2P connections
laddr = "tcp://0.0.0.0:26656"
# Combined inbound + outbound peer limit
max-connections = 200
# Per-connection bandwidth caps in bytes/sec
send-rate = 20971520
recv-rate = 20971520

[rpc]
# RPC listen address
laddr = "tcp://0.0.0.0:26657"
# Maximum number of simultaneous connections (HTTP + WS)
max-open-connections = 900
# Transaction confirmation timeout for /broadcast_tx_commit
timeout-broadcast-tx-commit = "10s"
```

#### Application Settings (app.toml)

```toml
# Minimum gas prices to prevent spam transactions
minimum-gas-prices = "0.02uhpx"

# Block retention for /block, /block_results, etc.
min-retain-blocks = 100000

# Concurrent transaction execution workers
concurrency-workers = 10

# Optimistic Concurrency Control for parallel tx execution
occ-enabled = true

[api]
# Enable the REST/Cosmos API server (port 1317)
enable = true
max-open-connections = 1000

[state-commit]
# State-commit (memiavl + FlatKV). Recommended on every node.
sc-enable = true

[state-store]
# Historical SS layer for queries. Required for any node serving RPC.
ss-enable = true
# 0 = keep everything
ss-keep-recent = 100000

[receipt-store]
# Storage backend for EVM transaction receipts (pebbledb or parquet).
rs-backend = "pebbledb"
```

### Default Configurations

The full unmodified `app.toml`, `config.toml`, and `client.toml` produced by
`paxd init` against the latest tagged `paxd` release. Use these as the
canonical reference for every available knob and its default value.

<Tabs>
  <Tab title="app.toml">

Application-layer configuration: gas, API, gRPC, pruning, EVM, etc.

```toml
# This is a TOML config file.
# For more information, see https://github.com/toml-lang/toml

###############################################################################
###                           Base Configuration                            ###
###############################################################################

# The minimum gas prices a validator is willing to accept for processing a
# transaction.
minimum-gas-prices = "0.01uhpx"

# MinRetainBlocks defines the minimum block height offset from the current block
# for pruning Tendermint blocks. Set to 0 to disable pruning.
min-retain-blocks = 100000

# ConcurrencyWorkers defines how many workers to run for concurrent transaction execution.
concurrency-workers = 10

# occ-enabled defines whether OCC is enabled or not for transaction execution
occ-enabled = true

# HaltHeight contains a non-zero block height at which a node will gracefully
# halt and shutdown that can be used to assist upgrades and testing.
halt-height = 0

# HaltTime contains a non-zero minimum block time (in Unix seconds) at which
# a node will gracefully halt and shutdown.
halt-time = 0

# InterBlockCache enables inter-block caching.
inter-block-cache = true

# IndexEvents defines the set of events in the form {eventType}.{attributeKey},
# which informs Tendermint what to index.
index-events = []

###############################################################################
###                        State Sync Configuration                         ###
###############################################################################

[state-sync]

# snapshot-interval specifies the block interval at which local state sync snapshots are
# taken (0 to disable). Must be a multiple of pruning-keep-every.
snapshot-interval = 0

# snapshot-keep-recent specifies the number of recent snapshots to keep and serve (0 to keep all).
snapshot-keep-recent = 2

# snapshot-directory sets the directory for where state sync snapshots are persisted.
snapshot-directory = ""

###############################################################################
###                       State Commit Configuration                        ###
###############################################################################

[state-commit]
# Enable defines if the state-commit should be enabled to override existing IAVL db backend.
sc-enable = true

# Defines the SC store directory
sc-directory = ""

# WriteMode defines how EVM data writes are routed between backends.
sc-write-mode = "cosmos_only"

# ReadMode defines how EVM data reads are routed between backends.
sc-read-mode = "cosmos_only"

# AsyncCommitBuffer defines the size of asynchronous commit queue
sc-async-commit-buffer = 100

# KeepRecent defines how many state-commit snapshots (besides the latest one) to keep
sc-keep-recent = 0

# SnapshotInterval defines the block interval the snapshot is taken
sc-snapshot-interval = 10000

###############################################################################
###                         State Store Configuration                       ###
###############################################################################

[state-store]
# Enable defines whether the state-store should be enabled for storing historical data.
ss-enable = true

# Defines the directory to store the state store db files
ss-db-directory = ""

# DBBackend defines the backend database used for state-store.
# Supported backends: pebbledb, rocksdb
ss-backend = "pebbledb"

# AsyncWriteBuffer defines the async queue length for commits to be applied to State Store
ss-async-write-buffer = 100

# KeepRecent defines the number of versions to keep in state store
ss-keep-recent = 100000

# PruneInterval defines the minimum interval in seconds to trigger SS pruning.
ss-prune-interval = 600

###############################################################################
###                        Receipt Store Configuration                      ###
###############################################################################

[receipt-store]
# Backend defines the receipt store backend.
rs-backend = "pebbledb"

# Defines the receipt store directory.
db-directory = ""

# AsyncWriteBuffer defines the async queue length for commits to be applied to receipt store.
async-write-buffer = 100

# PruneIntervalSeconds defines the interval in seconds to trigger pruning.
prune-interval-seconds = 600

###############################################################################
###                            EVM Configuration                            ###
###############################################################################

[evm]
# controls whether an HTTP EVM server is enabled
http_enabled = true
http_port = 8545

# controls whether a websocket server is enabled
ws_enabled = true
ws_port = 8546

# Maximum gas limit for simulation
simulation_gas_limit = 10000000

# list of CORS allowed origins, separated by comma
cors_origins = "*"

# list of WS origins, separated by comma
ws_origins = "*"

# timeout for filters
filter_timeout = "2m0s"

###############################################################################
###                       Giga Executor Configuration                       ###
###############################################################################

[giga_executor]
# enabled controls whether to use the Giga executor (evmone-based) instead of geth's interpreter.
enabled = false

# occ_enabled controls whether to use OCC with the Giga executor.
occ_enabled = false

###############################################################################
###                       Admin Configuration (Auto-managed)                ###
###############################################################################

[admin_server]
admin_enabled = false
admin_address = "127.0.0.1:9095"

###############################################################################
###                   Telemetry Configuration (Auto-managed)                ###
###############################################################################

[telemetry]
service-name = ""
enabled = true
enable-hostname = false
enable-hostname-label = false
enable-service-label = false
prometheus-retention-time = 7200
global-labels = []

###############################################################################
###                       API Configuration (Auto-managed)                  ###
###############################################################################

[api]
enable = true
swagger = true
address = "tcp://0.0.0.0:1317"
max-open-connections = 1000

###############################################################################
###                       gRPC Configuration (Auto-managed)                 ###
###############################################################################

[grpc]
enable = true
address = "0.0.0.0:9090"

###############################################################################
###                        gRPC Web Configuration (Auto-managed)            ###
###############################################################################

[grpc-web]
enable = true
address = "0.0.0.0:9091"
enable-unsafe-cors = false
```

  </Tab>

  <Tab title="config.toml">

Tendermint / consensus-layer configuration: P2P, RPC, mempool, consensus,
state-sync, etc.

```toml
# This is a TOML config file.
# For more information, see https://github.com/toml-lang/toml

#######################################################################
###                   Main Base Config Options                      ###
#######################################################################

proxy-app = "tcp://127.0.0.1:26658"

moniker = "docs-example"

# Mode of Node: full | validator | seed
mode = "full"

# Database backend: goleveldb | cleveldb | boltdb | rocksdb | badgerdb
db-backend = "goleveldb"

db-dir = "data"

log-level = "info"
log-format = "text"

genesis-file = "config/genesis.json"
node-key-file = "config/node_key.json"
abci = "socket"
filter-peers = false

#######################################################################
###       RPC Server Configuration Options          ###
#######################################################################
[rpc]
laddr = "tcp://0.0.0.0:26657"
cors-allowed-origins = []
cors-allowed-methods = ["HEAD", "GET", "POST"]
cors-allowed-headers = ["Origin", "Accept", "Content-Type", "X-Requested-With", "X-Server-Time"]
unsafe = false
max-open-connections = 900
max-subscription-clients = 100
max-subscriptions-per-client = 5
timeout-broadcast-tx-commit = "10s"
max-body-bytes = 1000000
max-header-bytes = 1048576

###################################################################
###           P2P Configuration Options                         ###
#######################################################################
[p2p]
queue-type = "simple-priority"
laddr = "tcp://0.0.0.0:26656"
external-address = ""
bootstrap-peers = ""
persistent-peers = ""
upnp = false
max-connections = 100
max-incoming-connection-attempts = 100
pex = true
private-peer-ids = ""
allow-duplicate-ip = false
handshake-timeout = "10s"
dial-timeout = "3s"
send-rate = 20971520
recv-rate = 20971520

#######################################################################
###          Mempool Configuration Options                          ###
#######################################################################
[mempool]
broadcast = true
size = 5000
max-txs-bytes = 1073741824
cache-size = 10000
keep-invalid-txs-in-cache = false
max-tx-bytes = 1048576
ttl-duration = "5s"
ttl-num-blocks = 10
tx-notify-threshold = 0
check-tx-error-blacklist-enabled = true
check-tx-error-threshold = 50
pending-size = 5000
max-pending-txs-bytes = 1073741824

#######################################################################
###         State Sync Configuration Options                        ###
#######################################################################
[statesync]
enable = false
use-p2p = false
rpc-servers = ""
trust-height = 0
trust-hash = ""
trust-period = "168h0m0s"
backfill-blocks = "0"
backfill-duration = "0s"
discovery-time = "15s"
temp-dir = ""
use-local-snapshot = false
chunk-request-timeout = "15s"
fetchers = "2"

#######################################################################
###         Consensus Configuration Options                         ###
#######################################################################
[consensus]
wal-file = "data/cs.wal/wal"
double-sign-check-height = 0
create-empty-blocks = true
create-empty-blocks-interval = "0s"
gossip-tx-key-only = "true"
peer-gossip-sleep-duration = "100ms"
peer-query-maj23-sleep-duration = "2s"

#######################################################################
###   Transaction Indexer Configuration (Auto-managed)              ###
#######################################################################
[tx-index]
indexer = ["kv"]

#######################################################################
###       Instrumentation Configuration (Auto-managed)             ###
#######################################################################
[instrumentation]
prometheus = false
prometheus-listen-addr = ":26660"
max-open-connections = 3
namespace = "tendermint"
```

  </Tab>

  <Tab title="client.toml">

Client-side configuration for the CLI.

```toml
# This is a TOML config file.
# For more information, see https://github.com/toml-lang/toml

###############################################################################
###                           Client Configuration                         ###
###############################################################################

# The network chain ID
chain-id = "hyperpax_125-1"

# The keyring's backend
keyring-backend = "os"

# Default key name
from = ""

# CLI output format
output = "text"

# <host>:<port> to Tendermint RPC interface for this chain
node = "tcp://localhost:26657"

# Transaction broadcasting mode
broadcast-mode = "sync"
```

  </Tab>
</Tabs>

---

## Node Types

*Learn about Paxeer network node types—RPC, archive, state sync, and validator nodes—plus common ports and a systemd setup template.*

There are several node types that can be run on the Paxeer network which serve a variety of purposes. These include:

- **RPC / Full Nodes**: Generally used for querying data or interacting with the chain. They maintain some state but not since genesis. The default settings will run RPC / full nodes.

- **Archive / Full Nodes**: Maintain full state of the blockchain from genesis. Generally requires large disks (10 TB+ minimum). To enable this type of node, set `min-retain-blocks=0` and `pruning="nothing"` in your `app.toml`.

- **State Sync Nodes**: Provide snapshot data for other nodes to use to bootstrap onto the chain. To enable this type of node, set `enable=true` under the `[statesync]` section in config.toml.

- **Validator Nodes**: Provide security to the chain by proposing and signing blocks. To enable this type of node, set `mode=validator` in `config.toml`. Note that because Paxeer is proof-of-stake, you must have enough delegation to join the active set.

## Commonly Used Ports

`paxd` uses the following TCP ports. Toggle their settings to match your environment.

- `26656`: The default port for the P2P communication. This port is used to communicate with other nodes and must be open to join the network.
- `26657`: The default port for the RPC interface. Because this port is used for querying and sending transactions, it must be open for serving queries from `paxd`.
- `1317`: The default port for interacting with the `paxd` API server for HTTP RESTful requests. This allows applications and services to interact with the `paxd` instance through RPC.
- `9090`: The default port for gRPC communication. This is used for high-performance communication with the node.
- `8545`: The default port for EVM HTTP RPC. This port is used for Ethereum JSON-RPC calls and must be open if you want to interact with EVM-compatible applications.
- `8546`: The default port for EVM WebSocket RPC. This port provides real-time communication for EVM applications that require WebSocket connections.
- `26660`: The default port for interacting with the Prometheus database, which can be used to monitor the environment. In the default configuration, this port is not open.

These ports are all customizable in `$HOME/.paxeer/config/config.toml` and `$HOME/.paxeer/config/app.toml`.

## Systemd File Template

```toml
[Unit]
Description=Paxeer Node
After=network.target

[Service]
User=<USER>
Type=simple
ExecStart=<PATH_TO_PAXD>/paxd start --chain-id hyperpax_125-1
Restart=always
RestartSec=30
TimeoutStopSec=30
KillSignal=SIGINT
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
```

---

## RocksDB Backend Setup & Performance

*Learn how to set up the RocksDB backend for Paxeer nodes to achieve 10-30x faster traceBlock iteration performance.*

## Overview

As Paxeer nodes accumulate more history and state data, iteration-heavy operations - like those performed during `traceBlock` calls - can become significantly slower. This is especially true for archive or RPC nodes where the state store contains millions of versions.

To address this, Paxeer supports **RocksDB** as an alternative backend to PebbleDB. RocksDB provides native **multi-version concurrency control (MVCC)** and **column family support**, which leads to substantial iteration performance improvements as history grows.

## Why RocksDB?

PebbleDB lacks native MVCC support, meaning the node must manually encode versions into keys. This retrofit approach causes iteration time to grow linearly with the amount of stored history. As a result:

- Archive nodes with large state stores experience **slower debug trace latency**.
- Each key lookup may require scanning multiple key versions.
- Iterations (e.g., over Oracle or EVM module keys) become increasingly expensive over time.

By contrast, **RocksDB** supports native user-defined timestamps and optimized column families for versioned data access. This means:

- Iterations over keys at a single version are **much faster**.
- Historical data growth has **minimal effect on iteration cost**.
- The performance advantage **amplifies with larger node history**.

In benchmarks, RocksDB achieved up to **10 - 30× faster traceBlock iteration times** compared to PebbleDB, with even greater benefits observed on archive nodes.

## Setup Instructions

RocksDB only needs to be built once. After that, you can install `paxd` with RocksDB support directly.

### Prerequisites

Ensure your system includes the following packages:

```bash
sudo apt-get update
sudo apt-get install -y build-essential pkg-config cmake git zlib1g-dev \
    libbz2-dev libsnappy-dev liblz4-dev libzstd-dev libjemalloc-dev \
    libgflags-dev liburing-dev
```

### Build & Install

```bash
# Step 1: Build RocksDB (one-time setup)
make build-rocksdb

# Step 2: Install paxd with RocksDB backend
make install-rocksdb
```

Once installed, your `paxd` binary will be built with RocksDB backend support:

```bash
paxd version
# should include "rocksdbBackend" build tag
```

### Configuration

After installation, update your configuration file to enable the RocksDB backend:

```bash
~/.paxeer/config/app.toml
```

Set

```toml
ss-backend = "rocksdb"
```

### Node Setup Notes

- RPC Nodes - must perform a state sync when spinning up a new node configured with RocksDB.
- Archive Nodes - currently, RocksDB is not supported for existing data unless syncing from genesis.

## Summary

| Feature                       | PebbleDB           | RocksDB                               |
| ----------------------------- | ------------------ | ------------------------------------- |
| MVCC Support                  | No                 | Native via user-defined timestamps |
| Column Families               | No                 | Yes                                |
| Iteration Speed (Large State) | Slows with history | Up to 30x faster                   |
| Installation                  | Default            | One-time build (`make build-rocksdb`) |

## TL;DR

- RocksDB backend drastically improves trace iteration and historical query performance.
- Install once, then run:

```bash
make install-rocksdb
```

- Update ~/.paxeer/config/app.toml to use RocksDB:

```toml
ss-backend = "rocksdb"
```

- RPC nodes require state sync; archive nodes must currently sync from genesis
- Expect **10 - 30× faster** trace latencies, especially on archive nodes or long-history setups.

---

## Join the network using Snapshots

*Learn how to quickly join the Paxeer network using snapshot sync, including download, restore, and troubleshooting steps for validators and nodes.*

<Warning>Before you resync a node using snapshots, make sure that in case of a successful resync that you _under no circumstance_ double sign blocks at previous heights with your validator. Failure to do so will cause tombstoning of your validator.</Warning>

Follow this guide to join the Paxeer network through **snapshot sync**. To quickly spin up a fresh full node and join the network, it's recommended to restore from a snapshot instead of replaying all historical blocks.

## Snapshot Sync

Snapshot sync allows a new node to join a network by downloading a recent, compressed copy of the entire application state and extracting it directly into the data directory. This reduces the initial sync time from days to minutes.

## Snapshot Providers

You can select from various providers for downloading snapshots. Check the Paxeer community channels for current snapshot availability.

## Clean Up & Preparation

If you are **not** starting a node from fresh, perform the following backups and clean-ups first.

<Info>Note: This step is not needed for fresh nodes.</Info>

1. **Stop the service**

   ```bash
   sudo systemctl stop paxd
   ```

2. **Backup Validator State** (Critical for Validators)
   Assuming your Paxeer home directory is `$HOME/.paxeer`, back up `priv_validator_key.json` and `priv_validator_state.json`:

   ```bash
   cp $HOME/.paxeer/data/priv_validator_state.json $HOME/priv_validator_state.json
   cp $HOME/.paxeer/config/priv_validator_key.json $HOME/priv_validator_key.json
   ```

3. **Reset the State**

   ```bash
   paxd tendermint unsafe-reset-all --home $HOME/.paxeer
   ```

4. **Remove Data**
   ```bash
   rm -rf $HOME/.paxeer/data
   ```

## Download & Restore

<Info>The following commands are generic examples. Please verify the `SNAPSHOT_URL` and extraction command from your chosen provider.</Info>

### Prerequisites

Ensure you have the necessary tools installed (e.g., `lz4`, `aria2`, `pv`, `wget`).

```bash
sudo apt update
sudo apt install curl lz4 wget aria2 pv -y
```

### Download and Extract

1. **Set the Snapshot URL**
   Replace `<SNAPSHOT_URL>` with the link from your chosen provider.

   ```bash
   SNAPSHOT_URL="<PASTE_SNAPSHOT_URL_HERE>"
   ```

2. **Download and Extract**
   The following command streams the download and extracts it into `$HOME/.paxeer`.

   ```bash
   curl -L $SNAPSHOT_URL | lz4 -c -d | tar -x -C $HOME/.paxeer
   ```

   **Alternative: Parallel Download with aria2**

   ```bash
   # Download with 16 parallel connections
   aria2c -x 16 -s 16 -o snapshot.tar.lz4 $SNAPSHOT_URL

   # Extract after download completes
   lz4 -c -d snapshot.tar.lz4 | tar -x -C $HOME/.paxeer

   # Clean up the downloaded file
   rm snapshot.tar.lz4
   ```

3. **Restore Validator State**

   ```bash
   cp $HOME/priv_validator_state.json $HOME/.paxeer/data/priv_validator_state.json
   ```

4. **Enable State Commit**
   Make sure to enable state-commit in your config if it's not already enabled:

   ```bash
   sed -i.bak -E "/^\[state-commit\]/,/^\[.*\]/ s|^(sc-enable[[:space:]]*=[[:space:]]*).*$|\1true| ; /^\[state-store\]/,/^\[.*\]/ s|^(ss-enable[[:space:]]*=[[:space:]]*).*$|\1true|" $HOME/.paxeer/config/app.toml
   ```

5. **Restart the Node**

   ```bash
   sudo systemctl start paxd
   ```

6. **Monitor Logs**
   ```bash
   sudo journalctl -fu paxd
   ```

## Troubleshooting

**Q: I can't download a snapshot.**
A: Try another time later as these snapshots are refreshed regularly.

**Q: The snapshot finishes, but I immediately get `AppHash` errors upon regular block syncing.**
A: Make sure that you use the latest version of the node software. This usually means the snapshot version doesn't match your node version, or the snapshot is corrupted.

**Q: "No space left on device"**
A: Snapshots require significant disk space to download and extract. Ensure you have enough free space (check with `df -h`).

---

## Join the network using StateSync

*Learn how to join the Paxeer network quickly using state sync, including clean-up steps, script setup, and troubleshooting common errors.*

Follow this guide to join the Paxeer network through statesync. To quickly spin up a fresh full node and join the network, it's recommended to sync through state sync.

## State Sync

State sync allows a new node to join a network by fetching a snapshot of the application state at a recent height instead of fetching and replaying all historical blocks. This can reduce the time needed to sync with the network from days to minutes.

## Clean Up

If you are not starting a node from fresh, then you need to do some backups and clean ups.

<Info>Note: This step is not needed for fresh nodes.</Info>

Assuming your Paxeer home directory is `$HOME/.paxeer`, back up `priv_validator_key.json` and `priv_validator_state.json`:

```bash
cp $HOME/.paxeer/data/priv_validator_state.json $HOME/priv_validator_state.json
cp $HOME/.paxeer/config/priv_validator_key.json $HOME/priv_validator_key.json
```

Reset the state:

```bash
paxd tendermint unsafe-reset-all --home $HOME/.paxeer
```

Finally, remove the existing data folders and restore the `priv_validator_state.json`:

```bash
rm -rf $HOME/.paxeer/data/*
cp $HOME/priv_validator_state.json $HOME/.paxeer/data/priv_validator_state.json
```

## Statesync script

Set up the RPC servers for primary and secondary endpoints.

For `STATE_SYNC_RPC`, use the Paxeer RPC endpoint.

The seed peer for the network is:

```bash
e9c56cbadc4a96b67f69dcaaa7b4691851e945ca@31.220.74.140:26656
```

The script sets up `trust_height` and `trust_hash` automatically. Each statesync snapshot is created at a certain block height. The script uses the best practice here and sets the trust height to be earlier than the latest snapshot block height to avoid backward verifications.

Script that you can use:

```bash title="state_sync.sh"
#!/bin/bash

# Prompt for the State Sync RPC Endpoint and store it in STATE_SYNC_RPC
echo -n State Sync RPC Endpoint:
read STATE_SYNC_RPC
echo

# Prompt for the State Sync Peer and store it in STATE_SYNC_PEER
echo -n State Sync Peer:
read STATE_SYNC_PEER
echo

# Create a backup directory for keys
mkdir -p $HOME/key_backup

# Backup the validator key and state files
cp $HOME/.paxeer/config/priv_validator_key.json $HOME/key_backup
cp $HOME/.paxeer/data/priv_validator_state.json $HOME/key_backup

# Create a backup directory for the entire .paxeer configuration
mkdir -p $HOME/.paxeer_backup

# Copy existing config and data directories to the backup directory
cp -r $HOME/.paxeer/config $HOME/.paxeer_backup/
cp -r $HOME/.paxeer/data $HOME/.paxeer_backup/

# Create a temp directory on the main disk and set the path in config.toml
mkdir -p /home/ubuntu/statesync-temp
sed -i 's|temp-dir = ""|temp-dir = "/home/ubuntu/statesync-temp"|' ~/.paxeer/config/config.toml

# Fetch the latest block height from the State Sync RPC endpoint
LATEST_HEIGHT=$(curl -s $STATE_SYNC_RPC/block | jq -r .block.header.height)
# Calculate the trust height (rounded down to the nearest 100,000)
BLOCK_HEIGHT=$(( (LATEST_HEIGHT / 100000) * 100000 ))
# Fetch the block hash at the trust height
TRUST_HASH=$(curl -s "$STATE_SYNC_RPC/block?height=$BLOCK_HEIGHT" | jq -r .block_id.hash)

# Update the config.toml file to enable state sync with the appropriate settings
sed -i.bak -E "s|^(enable[[:space:]]+=[[:space:]]+).*$|\1true| ; \
s|^(rpc-servers[[:space:]]+=[[:space:]]+).*$|\1\"$STATE_SYNC_RPC,$STATE_SYNC_RPC\"| ; \
s|^(trust-height[[:space:]]+=[[:space:]]+).*$|\1$BLOCK_HEIGHT| ; \
s|^(trust-hash[[:space:]]+=[[:space:]]+).*$|\1\"$TRUST_HASH\"|" $HOME/.paxeer/config/config.toml

# Set the persistent peers in the config.toml file
sed -i.bak -e "s|^persistent-peers *=.*|persistent-peers = \"$STATE_SYNC_PEER\"|" \
  $HOME/.paxeer/config/config.toml
```

Finally start the daemon:

```bash
sudo systemctl start paxd
```

## Troubleshooting statesync

**Q:** I can't connect to the state sync url.

**A:** Try another statesync url in that case.

**Q:** The statesync finishes, but immediately get `AppHash` errors upon regular block syncing:

**A:** Make sure that you use the latest version of the chain node when you state-sync.

**Q:** The statesync randomly stops.

**A:** State-sync can be flaky at times, just try again. Please give it around 4-5 tries.

---

## Swagger API Documentation

*Learn how to enable and access Swagger API documentation for your Paxeer node. Configure the swagger endpoint in app.toml and view interactive API docs.*

## Swagger Docs Endpoint

To enable the Swagger docs endpoint, you need to update api.swagger value to true in the `app.toml` file:

```toml

[api]

# Swagger defines if swagger documentation should automatically be registered.

swagger = true
```

Once the node is restarted, the Swagger docs will be available at `http://<node-ip>:<port>/swagger/` (e.g. `http://localhost:1317/swagger/`).

The default API port is `1317`. Ensure the API server is enabled in your `app.toml` under the `[api]` section by setting `enable = true`.

---

## Paxeer Technical Reference

*Explore Paxeer's technical reference for paxd CLI commands, app.toml and config.toml parameters, and network chain configuration details.*

This guide serves as a comprehensive reference for Paxeer node operators and
validators, providing detailed command syntax, configuration parameters, and
troubleshooting procedures.

## Command Line Interface Reference

The `paxd` binary provides extensive functionality for managing your Paxeer node.
Understanding these commands is essential for effective node operation and
troubleshooting.

### Node Management Commands

These commands help you control and monitor your node's operation:

<Danger>
  If you see an error such as `panic: recovered: runtime error: integer divide by zero` it means you can't start nodes straight from the genesis file. Instead, sync to the block tip via [state sync](/node/statesync) or using a [snapshot](/node/snapshot).
</Danger>

```bash
# Start the node
paxd start [flags]

# Show node status
paxd status

# Show validator consensus key
paxd tendermint show-validator

# Query node information
paxd query node info
```

### Key Management

Proper key management is crucial for security. These commands help you manage
your keys effectively:

```bash
# Create new key
paxd keys add <name> [flags]

# List all keys
paxd keys list

# Delete key
paxd keys delete <name>

# Export key (encrypted)
paxd keys export <name>

# Import key
paxd keys import <name> <keyfile>

# Show key address
paxd keys show <name> -a
```

### Transaction Commands

These commands allow you to interact with the blockchain:

```bash
# Send tokens
paxd tx bank send <from-key> <to-address> <amount>uhpx [flags]

# Delegate tokens
paxd tx staking delegate <validator-addr> <amount>uhpx --from <delegator-key>

# Withdraw rewards
paxd tx distribution withdraw-rewards <validator-addr> --from <delegator-key>

# Edit validator
paxd tx staking edit-validator [flags] --from <validator-key>
```

## Configuration Parameters

Understanding configuration parameters is essential for optimizing your node's
performance and security.

### App.toml Parameters

The app.toml file controls application-specific settings:

<Accordion title="Complete app.toml Configuration">
```toml
# Minimum gas prices for transaction acceptance
minimum-gas-prices = "0.02uhpx"

# API configuration
[api]
enable = true
swagger = true
address = "tcp://0.0.0.0:1317"
max-open-connections = 1000

# State sync configuration
[state-sync]
snapshot-interval = 1000
snapshot-keep-recent = 2

# Memory management
[mempool]
size = 5000
max-txs-bytes = 1073741824
cache-size = 10000

# State store configuration
[state-store]
ss-enable = true
ss-backend = "pebbledb"
ss-keep-recent = 100000
ss-prune-interval = 600
```

</Accordion>

### Config.toml Parameters

The config.toml file controls the core consensus engine and networking:

<Accordion title="Complete config.toml Configuration">
```toml
# P2P Configuration
[p2p]
laddr = "tcp://0.0.0.0:26656"
external-address = ""
seeds = ""
persistent_peers = ""
upnp = false
max_num_inbound_peers = 40
max_num_outbound_peers = 10

# RPC Configuration
[rpc]
laddr = "tcp://0.0.0.0:26657"
cors_allowed_origins = []
cors_allowed_methods = ["HEAD", "GET", "POST"]
cors_allowed_headers = ["Origin", "Accept", "Content-Type", "X-Requested-With", "X-Server-Time"]
max_open_connections = 900
timeout_broadcast_tx_commit = "10s"

# Consensus Configuration
[consensus]
wal_file = "data/cs.wal/wal"
timeout_propose = "3s"
timeout_propose_delta = "500ms"
timeout_prevote = "1s"
timeout_prevote_delta = "500ms"
timeout_precommit = "1s"
timeout_precommit_delta = "500ms"
timeout_commit = "1s"
double_sign_check_height = 0
```

</Accordion>

## Network Parameters

Understanding network parameters helps you operate your node effectively.

### Chain Parameters

These parameters define the network's behavior:

```text
Chain ID: hyperpax_125-1 (125)
Block Time: ~400ms target (Twin Turbo Consensus)
Unbonding Period: 21 days
Minimum Self Delegation: 1 HPX

Slashing Parameters:
  - signed_blocks_window:        108,000 blocks
  - min_signed_per_window:       5%
  - downtime_jail_duration:      10 minutes
  - slash_fraction_downtime:     0%   (jail only)
  - slash_fraction_double_sign:  0%   (double-signing triggers permanent tombstoning)
```

<Info>
  These values reflect the current on-chain parameters. Query them directly with `paxd query staking params` and `paxd query slashing params` for the source of truth.
</Info>

## File Locations

Understanding the purpose and location of important files helps with maintenance
and troubleshooting:

```text
$HOME/.paxeer/
├── config/
│   ├── app.toml         # Application configuration
│   ├── client.toml      # Client configuration
│   ├── config.toml      # Tendermint configuration
│   ├── genesis.json     # Chain genesis file
│   ├── node_key.json    # Node identity key
│   └── priv_validator_key.json  # Validator signing key
├── data/
│   ├── application.db   # Application state
│   ├── blockstore.db    # Block data
│   ├── cs.wal/         # Consensus write-ahead logs
│   ├── evidence.db     # Evidence of misbehavior
│   ├── state.db        # Tendermint state
│   └── tx_index.db     # Transaction index
└── keyring-file/       # Local key storage
```

## Quick Reference

| Parameter | Value |
|-----------|-------|
| Binary | `paxd` |
| Chain ID | `hyperpax_125-1` (125) |
| Coin | `uhpx` / `hpx` |
| Bech32 prefix | `pax1...` |
| Home directory | `~/.paxeer` |
| Seed peer | `e9c56cbadc4a96b67f69dcaaa7b4691851e945ca@31.220.74.140:26656` |
| Consensus | Twin Turbo + machineRFT |

---

## Troubleshooting

*Learn how to diagnose and resolve common Paxeer node errors, including consensus, network, database, and AppHash mismatch issues.*

Understanding common errors and their solutions helps maintain a healthy node
operation.

## Common Error Codes

Here are the most frequent errors you might encounter and their solutions:

### Consensus Errors

When you encounter consensus errors, quick and appropriate action is essential:

```text
Error: "Consensus failure - height halted"
Solution: Check for network upgrades or chain halts
Command: paxd status
```

```text
Error: "Private validator file not found"
Solution: Restore validator key or check file permissions
Location: $HOME/.paxeer/config/priv_validator_key.json
```

```text
Error: "Duplicate signature"
Solution: IMMEDIATELY STOP NODE - potential double signing risk
Action: Check validator operation on other machines
```

### Network Errors

Network errors can prevent your node from participating in consensus:

```text
Error: "Dial tcp connection refused"
Solution: Check network connectivity and firewall rules
Commands:
  - netstat -tulpn | grep paxd
  - ufw status
```

```text
Error: "No peers available"
Solution: Verify peer connections and network config
Commands:
  - curl localhost:26657/net_info
```

### Database Errors

Database corruption can require immediate attention:

```text
Error: "Database is corrupted"
Solution: Reset database or restore from backup
Commands:
  - paxd tendermint unsafe-reset-all
  - cp -r backup/data $HOME/.paxeer/
```

### Diagnostic Commands

These commands help you investigate issues and monitor your node:

```bash
# Check node synchronization
paxd status

# Check validator status
paxd query staking validator $(paxd tendermint show-validator)

# Monitor real-time logs
journalctl -fu paxd -o cat

# View system resource usage
top -p $(pgrep paxd)
```

## AppHash Mismatch Errors

If you encounter an AppHash mismatch, you'll need to capture the state for comparison with a known good version:

```bash
# For state-commit (most non-archive nodes):
paxd debug dump-iavl <latest height>
```

Always include the app hash, commit hash, and block height from your logs when reporting issues.

### Identifying AppHash Errors

AppHash errors typically appear in logs as:

```text
ERR wrong Block.Header.AppHash. Expected [EXPECTED_HASH], got [ACTUAL_HASH]
block_id={"hash":"...","parts":{"hash":"...","total":1}} height=[HEIGHT]
```

**Common Causes:**

- Using incorrect node version during sync (ensure you're on the latest version)
- Corrupted or incorrectly applied snapshots
- Database inconsistencies from improper shutdowns
- Syncing with outdated or incompatible peers

**Resolution Steps:**

1. **Stop the node immediately.**
2. **Try a node rollback first:**, see [here](/node/troubleshooting#node-rollback)
3. **If rollback fails, restore from a fresh snapshot:**

   - Download a recent snapshot from trusted providers
   - Ensure you're using the correct node version
   - Verify peer configurations are up to date

4. **Restart the node and monitor logs for continued errors**

### Peer Connection Issues as AppHash Red Herrings

**Important Note:** Peer connection failures are often symptoms of underlying AppHash errors, not the root cause.

When you see extensive peer connection errors like:

```text
ERR failed to handshake with peer
ERR failed to send request for peers
ERR peer handshake failed endpoint={} err=EOF
```

**Don't focus solely on fixing peer connections first.** Instead:

1. **Scan your logs carefully** for AppHash errors that may appear intermittently
2. **Look for the actual error pattern:**
   ```text
   ERR wrong Block.Header.AppHash. Expected [HASH], got [HASH]
   ```
3. **Check if your node is stuck** at a specific height despite peer connection attempts

**Debugging Approach:**

1. **First, check for AppHash errors** in your logs (search for "wrong Block.Header.AppHash")
2. **If AppHash errors are found**, treat this as the primary issue
3. **Only focus on peer connection fixes** if no AppHash errors exist

### Peer Connection and Handshake Issues

**Identifying Peer Issues:**

Look for these error patterns in your logs:

```text
ERR failed to handshake with peer err="expected to connect with peer \"[EXPECTED_ID]\", got \"[ACTUAL_ID]\""
ERR failed to send request for peers err="no available peers to send a PEX request to (retrying)"
ERR peer handshake failed endpoint={} err=EOF module=p2p
```

**Common Causes:**

- Outdated peer configurations with mismatched node IDs
- Network infrastructure changes on peer side
- Firewall blocking connections on port 26656
- DNS resolution issues

**Resolution Steps:**

1. **Update peer configurations** with current node IDs. Use the seed peer:

   ```bash
   e9c56cbadc4a96b67f69dcaaa7b4691851e945ca@31.220.74.140:26656
   ```

2. **Verify network connectivity:**

   ```bash
   # Test connection to peer endpoints
   nc -zv 31.220.74.140 26656

   # Check if port 26656 is open for inbound connections
   netstat -tulpn | grep :26656
   ```

3. **Check current peer status:**
   ```bash
   curl http://localhost:26657/net_info | jq '.result.peers | length'
   curl http://localhost:26657/lag_status | jq .
   ```

### Sync Performance Issues

**Identifying Sync Problems:**

Monitor these indicators:

```bash
# Check sync status and lag
curl http://localhost:26657/lag_status | jq .

# Monitor if height is progressing
curl http://localhost:26657/status | jq '.result.sync_info'
```

**Common Solutions:**

1. **Increase packet payload size** for large block processing:

   ```toml
   # In config.toml [p2p] section
   max-packet-msg-payload-size = 1024000
   ```

2. **Optimize mempool settings** in `config.toml`:

   ```toml
   # In [mempool] section
   keep-invalid-txs-in-cache = true
   ttl-duration = "5s"
   ttl-num-blocks = 5
   ```

3. **If node gets stuck at specific height:**
   - Try restarting the node
   - If restart doesn't help, perform rollback
   - Consider taking a fresh snapshot

## Crash and Panic Debugging

For crashes, panics, or nil pointer exceptions:

- Capture at least 1,000 lines of logs leading up to the crash
- Or collect 15 minutes of log data, whichever provides more context
- Include the full stack trace if available

### Logging Configuration

```toml
# In config.toml
log_level = "debug"
log_format = "json"
```

Configure log rotation to manage storage effectively:

```bash
sudo tee /etc/logrotate.d/paxd << EOF
/var/log/paxd/*.log {
    daily
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 paxeer paxeer
    sharedscripts
    postrotate
        systemctl reload paxd
    endscript
}
EOF
```

## Other common Issues and Fixes

1. **Sync Problems**

   - Check available disk space (`df -h`)
   - Ensure proper peer connections (`curl http://localhost:26657/net_info`)
   - Verify firewall settings (port 26656 open)

2. **Performance Issues**

   - Monitor system resources (`htop` or `iotop`)
   - Check disk I/O performance (`iostat`)
   - Analyze network traffic (`iftop`)

3. **Database Issues**

   - Run database integrity checks using:

     ```bash
     paxd debug dump-db | grep -i error
     ```

     If errors are detected, consider restoring from a recent backup.

   - Consider pruning excessive historical data by adjusting `ss-keep-recent` in
     `app.toml` or running:

     ```bash
     paxd tendermint unsafe-reset-all --home $HOME/.paxeer --keep-addr-book
     ```

## Node Rollback

To rollback a node from an AppHashed state, you need to stop the node first.

Next, do a rollback with:

```bash
paxd rollback
```

Then, restart the node.

In case you see the following error while trying to rollback:

```bash
failed to initialize database: resource temporarily unavailable
```

This means that you did not shutdown the node properly. Try to shutdown or kill the `paxd` process directly in that case. If this doesn't help, restart your machine.

Then try the rollback steps again.

---

## Paxeer Validator Operations Guide

*Learn how to set up, secure, and operate a Paxeer validator node using Twin Turbo Consensus, HSM integration, and best practices.*

This document covers the complete lifecycle of a validator node, from initial setup through ongoing operations and maintenance. Understanding these concepts is crucial for maintaining a reliable and secure validator operation.

## Understanding Validator Responsibilities

A validator in the Paxeer network serves several critical functions. As a validator, you are responsible for:

- Participating in consensus by proposing and validating blocks
- Maintaining high uptime and performance to avoid slashing
- Managing delegator relationships and maintaining transparent operations
- Participating in governance and network upgrades

Paxeer uses **Twin Turbo Consensus** with **machineRFT** for fast, reliable finality.

## Initial Setup

### Initialize node

Before key management and registration, initialize your node with validator mode so that RPC and P2P bind to localhost (recommended for validator security):

```bash
paxd init <moniker> --chain-id hyperpax_125-1 --mode validator
```

The default init mode is **full**, which binds RPC and P2P to all interfaces (`0.0.0.0`). For validator (and seed) nodes, use `--mode validator` or `--mode seed` so that RPC and P2P listen on localhost only.

### Key Management

The security of your validator begins with proper key management. Your validator requires several distinct keys:

```bash
# Validator consensus key - Used for signing blocks
paxd tendermint show-validator

# Operator key - Used for managing validator operations
paxd keys add operator
```

These keys serve different purposes and should be managed with appropriate security measures. The consensus key, stored in `priv_validator_key.json`, is particularly critical as it's used to sign blocks and could result in slashing if compromised or mishandled.

### Hardware Security Module (HSM) Integration

For production validators, using an HSM is strongly recommended to protect your consensus key. Here's how to configure an HSM with your validator:

<Accordion title="HSM Configuration Steps">
```bash
# Install required libraries
sudo apt-get install opensc pkcs11-utils

# Configure YubiHSM2
yubihsm-connector -d

# Generate key in HSM
yubihsm-shell

# Configure paxd to use HSM
tee "$HOME/.paxeer/config/priv_validator_config.json" << EOF
{
    "chain_id": "hyperpax_125-1",
    "key_type": "yubihsm",
    "state_file": "$HOME/.paxeer/data/priv_validator_state.json",
    "hsm_serial": "YOUR_HSM_SERIAL",
    "hsm_key_id": "YOUR_KEY_ID"
}
EOF
```

</Accordion>

### Validator Registration

Before registering your validator, ensure your node is fully synced with the network. The creation of a validator is a crucial step that requires careful consideration of commission parameters.

```bash
paxd tx staking create-validator \
    --amount=1000000uhpx \
    --pubkey=$(paxd tendermint show-validator) \
    --moniker="choose_moniker" \
    --chain-id=hyperpax_125-1 \
    --commission-rate="0.10" \
    --commission-max-rate="0.20" \
    --commission-max-change-rate="0.01" \
    --min-self-delegation="1" \
    --gas="auto" \
    --gas-adjustment="1.5" \
    --gas-prices="0.02uhpx" \
    --from=operator
```

The commission parameters require strategic consideration:

- `commission-rate`: Your initial commission rate, which should be competitive while ensuring operational sustainability
- `commission-max-rate`: An upper limit that can never be exceeded, setting a permanent cap on your commission
- `commission-max-change-rate`: Maximum daily commission change, limiting how quickly you can adjust rates

## Monitoring and Alerting

**Please refer to the [Advanced Operations](/node/advanced-config-monitoring) section for details around monitoring + alerting for your validator and other nodes.**

## Security Practices

### Network Security

Validators may choose to implement a sentry node architecture to protect the block signing node (the validator). This setup helps prevent DDoS attacks on your validator node by creating a layer of defensive proxies:

```bash
# Validator node config.toml
[p2p]
pex = false
persistent_peers = "sentry_node_id@sentry_node_ip:26656"
private_peer_ids = ""
addr_book_strict = false

# Sentry node config.toml
[p2p]
pex = true
persistent_peers = "validator_node_id@ip:port"
private_peer_ids = "validator_node_id"
addr_book_strict = true
unconditional_peer_ids = "validator_node_id"
```

### Key Management Practices

Implement secure key backup procedures. Remember to choose the storage media carefully! Mechanical / flash based storage can fail unexpectedly, and cloud storage should **never** be used.

By default, the wallet key files are stored in your `/.paxeer` directory root, and the signer/consensus key in `/.paxeer/config`. Not only the `priv_validator_key.json`, but the wallet `.info` and `.address` file should also be saved.

Example script to encrypt backups of key files:

<Accordion title="Key Backup Script">
```bash
#!/bin/bash
# Create encrypted backup of validator keys
BACKUP_DIR="/secure/validator/backup"
DATE=$(date +%Y%m%d)

# Backup validator key
tar czf - $HOME/.paxeer/config/priv_validator_key.json | \
    gpg --symmetric --cipher-algo AES256 \
    -o $BACKUP_DIR/validator_key_$DATE.tar.gz.gpg

# Backup keyring
tar czf - $HOME/.paxeer/keyring-file | \
    gpg --symmetric --cipher-algo AES256 \
    -o $BACKUP_DIR/keyring_$DATE.tar.gz.gpg

# Create SHA256 checksums
sha256sum $BACKUP_DIR/*.gpg > $BACKUP_DIR/checksums_$DATE.txt
```

</Accordion>

## Maintenance Procedures

### Planned Maintenance

When performing planned maintenance, to minimize potential impact:

- Notify delegators (recommended at least 24h in advance)

Don't forget to stop the service!

```bash
# Gracefully stop the node
sudo systemctl stop paxd

# Perform maintenance tasks

# Restart services
sudo systemctl start paxd
```

## Governance Participation

As a validator, active participation in governance is required. Governance is the primary tool with which adjustments to various chain parameters are made.
Another critical role for validators is to review, and ultimately approve or reject proposed software upgrades to the network.

Governance proposals may be submitted by anyone willing to provide the mandatory (refundable) deposit, and can be voted on by any network user. Only votes by accounts delegating HPX at the end of the voting period for a given proposal will be given weight.

Proposals currently on chain can be queried at any given time:

```bash
# List active proposals
paxd query gov proposals --status voting_period

# Vote on a proposal
paxd tx gov vote 1 yes \
    --from operator \
    --chain-id hyperpax_125-1 \
    --gas auto \
    --gas-prices 0.02uhpx
```

## Recovery Procedures

### Critical Warning: Double-Signing Prevention

<Danger>Double-signing is a severe violation that results in permanent validator tombstoning (irreversible jailing).</Danger>

Never run your validator keys on more than one machine simultaneously. If your primary validator goes offline:

1. DO NOT start another validator with the same keys
2. Either recover the original machine or properly migrate keys with absolute certainty the original is offline
3. If unsure about the state of your original validator, seek support before proceeding

The safe approach to recovery is:

1. Diagnose why the original validator is offline
2. If the original validator cannot be recovered, verify it is offline and powered down
3. Only then proceed with key migration to a new machine

### Validator Recovery

When you need to recover your validator on a new machine, follow these steps carefully:

```bash
# 1. Set up new machine with Paxeer node
# 2. Copy secured backup files
# 3. Restore validator key
gpg -d validator_key_backup.tar.gz.gpg | tar xzf -
# 4. Restore keyring
gpg -d keyring_backup.tar.gz.gpg | tar xzf -
# 5. Start services
sudo systemctl start paxd
```

After recovery, verify your validator's status and performance:

```bash
# Check validator status
paxd status
# Verify signing is working
paxd query slashing signing-info $(paxd tendermint show-validator)
```

---

## Optimizing Contracts for Parallelization

*Design patterns to reduce state conflicts and maximize Paxeer EVM parallel execution while lowering gas usage.*

Paxeer EVM executes non-conflicting transactions in parallel. You can significantly increase throughput and reduce gas by designing contracts that minimize shared state access and avoid unnecessary storage writes.

<Info>
  This guide is based on Paxeer's recommendations for reducing gas usage and enhancing parallel execution. For the engine design, see [Parallelization Engine](/learn/parallelization-engine).
</Info>

## Principles for Parallel-Friendly Contracts

- **Minimize shared writes**: The scheduler can parallelize transactions that do not write to the same storage keys. Avoid hot globals (e.g., a single counter updated on every call).
- **Partition state**: Shard storage by user, asset, or id so independent transactions touch disjoint keys.
- **Prefer pull over push**: Let users claim funds instead of mass-paying recipients in loops.
- **Avoid unbounded loops**: Especially loops that write to storage or iterate over dynamic arrays/mappings.
- **Batch internal work; isolate external effects**: Do heavy computation in memory and commit a minimal set of storage writes.
- **Use precompiles when available**: Precompiles are highly optimized and cheaper than replicating logic in Solidity.

<Tip>

**Parallelization checklist:**

- Partition storage by user/asset/id; avoid hot globals
- Minimize number of storage writes per call; batch in-memory, commit once
- Avoid loops with storage writes; switch to pull-based flows
- Favor precompiles for supported features
- Apply standard gas optimizations (`external`, packing, `unchecked`, memory-first)

</Tip>

## Storage Design Patterns

### Partition state by key

Isolate per-user/per-asset data instead of centralizing writes.

```solidity
// Good: disjoint keys by user and id enable parallelism
mapping(address => mapping(uint256 => Position)) public positions;

function updatePosition(uint256 id, int256 delta) external {
    Position storage p = positions[msg.sender][id];
    // in-memory arithmetic first
    int256 newQty = p.qty + delta;
    // commit minimal writes
    p.qty = newQty;
}
```

Anti-patterns:

- Writing a global `totalVolume += amount;` in every transaction
- Maintaining a single on-chain queue or registry updated by most calls

Prefer computing aggregates off-chain from events, or update them periodically via a dedicated maintenance transaction and place them in the calldata.

### Prefer pull payments

Avoid writing to many recipients in a single transaction. Emit events and let recipients `withdraw()` when needed.

```solidity
// Better: users pull their own rewards, isolating writes to their key
mapping(address => uint256) public accrued;

function accrue(address user, uint256 amount) internal {
    accrued[user] += amount; // isolated write
}

function withdraw() external {
    uint256 due = accrued[msg.sender];
    accrued[msg.sender] = 0; // single-key write
    (bool ok, ) = msg.sender.call{value: due}("");
    require(ok, "TRANSFER_FAILED");
}
```

### Avoid large storage writes in loops

If you must process many items, keep work in memory and commit a compact result, or split work across multiple transactions keyed by different ids.

## Gas-Efficient Solidity Practices

- **Use `external` for externally called functions**; mark pure/read-only with `pure`/`view`.
- **Pack variables** to share storage slots (e.g., multiple `uint8` in one slot).
- Prefer **`bytes32` over `string`** when applicable.
- **Cache array lengths** in loops and short-circuit cheap conditions first.
- Use **`unchecked`** for arithmetic when overflow is impossible.
- Prefer **memory** over storage for temporary data; commit only final values.

These reduce gas and often reduce storage touches, which also improves parallelism.

## Leverage Paxeer Precompiles

Paxeer provides precompiled contracts for common functionality - cheaper and simpler than custom Solidity equivalents:

- [JSON](/evm/precompiles/json) (`0x1003`)
- [P256](/evm/precompiles/p256-precompile) (`0x1011`)

See [precompile examples](/evm/precompiles/example-usage) for quick starts.

## Testing and Analysis

- Use Foundry/Hardhat gas reporters to track changes per function.
- Benchmark under concurrent load to detect hot keys (addresses/ids) that serialize execution.
- Inspect execution with [JavaScript tracers](/evm/tracing/javascript-tracers) and runtime logs.

---

## Zeroing Out Stale State

*Learn how to zero out stale contract state on Paxeer, earning gas refunds while safely clearing arrays, mappings, and legacy storage.*

Zeroing out state means setting stored contract values back to their defaults (e.g., `0`, `false`, `address(0)`) by writing `non-zero → zero` into EVM storage slots.

## Why Zero Out State

Non-zero storage contributes to global state size. Clearing stale state reduces state growth pressure and can improve node operations, sync, and restart behavior. This matters especially on high-throughput chains like Paxeer where state growth can be aggressive.

<Info>Clearing a non-zero storage slot to zero earns a **4,800 gas refund** per slot.</Info>

## Clearing State Variables, Arrays, and Maps

### Simple Fixed-Size State

For value types and fixed-size arrays, use `delete` (or assign the default) to reset values to their defaults (`0`, `address(0)`, `false`).

```solidity
uint256 public value;
bool public flag;
address public addr;
uint256[10] public fixedArr;

function clearSimple() external {
    delete value;    // → 0
    delete flag;     // → false
    delete addr;     // → address(0)
    delete fixedArr; // zeroes every element
}
```

### Dynamic Arrays

Using `delete` on a dynamic array resets its length to 0 and clears all elements, but this can be too expensive for large arrays and risks hitting the block gas limit.

The safer approach is **batched clearing** by repeatedly calling `pop()` in chunks.

<Warning>If a dynamic array might exceed **~500 elements**, use batched clearing to avoid running out of gas.</Warning>

```solidity
uint256[] public dynamicArr;

function batchClear(uint256 batchSize) external {
    uint256 len = dynamicArr.length;
    uint256 toClear = batchSize < len ? batchSize : len;
    for (uint256 i = 0; i < toClear; i++) {
        dynamicArr.pop();
    }
}
```

### Mappings

You can't iterate a mapping, so you can't clear it unless you can enumerate keys. The main strategy is to **maintain an index of keys** (e.g., a `holders[]` array plus an `_isHolder` flag) whenever you write, then later delete mapping entries in batches by iterating that key list.

<Info>Maintaining an index costs roughly one extra `SSTORE` per write (Paxeer: ~72,000 gas; see [EVM Differences](/evm/differences-with-ethereum#gas-model--fees)), but makes future clearing possible.</Info>

```solidity
mapping(address => uint256) public balances;
address[] public holders;
mapping(address => bool) private _isHolder;

function setBalance(address user, uint256 amount) external {
    if (!_isHolder[user]) {
        _isHolder[user] = true;
        holders.push(user);
    }
    balances[user] = amount;
}

function batchClearBalances(uint256 start, uint256 end) external {
    if (end > holders.length) end = holders.length;
    for (uint256 i = start; i < end; i++) {
        address user = holders[i];
        delete balances[user];
        delete _isHolder[user];
    }
}
```

## Strategies for Existing Contracts

### External Cleaner Contract

If you control permissions and the original contract has callable setters/entrypoints, deploy a separate "cleaner" contract that loops through user/key batches and calls the original contract to set values to zero.

<Warning>This only clears state reachable through the **public/external interface**. Truly internal or private state with no setters can't be touched.</Warning>

See [Appendix A](#appendix-a---external-cleaner-contract) for example code.

### Proxy / Upgradeable Contract

If you have a proxy or upgradeable contract, this is the best-case scenario. Upgrade the implementation to add reset functions while **preserving storage layout**, run batched resets, then optionally upgrade again to remove the reset logic.

See [Appendix B](#appendix-b---proxyupgradeable-contract) for example code.

### Reconstruct Keys from Event Logs

If contract writes emit events (which is common), scan historical logs to recover mapping keys (e.g., recipients from `Transfer` events), deduplicate them, and pass that list into a batch-clear call.

### Use a Subgraph or Custom Indexer

For complex or nested state, use [The Graph](https://thegraph.com/) or your own indexer to build a full set of non-zero keys/entities off-chain, then feed the resulting address/key list into on-chain batch clearing. This moves enumeration complexity off-chain while the on-chain work is just applying clears.

### Brute-Force via Direct Storage Reads

If you have a candidate universe of keys (e.g., all addresses that ever interacted), compute each mapping slot (`keccak256(key, slot)` - tools like `cast index` do this), read storage via RPC, and keep only the non-zero keys to clear.

<Info>This approach is tedious and RPC-heavy but works when events are missing or unreliable.</Info>

## Appendix A - External Cleaner Contract

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IResettableTarget {
    function setBalance(address user, uint256 amount) external;
}

contract StateCleaner {
    IResettableTarget public immutable target;

    constructor(address _target) {
        target = IResettableTarget(_target);
    }

    function clearBalances(address[] calldata users) external {
        for (uint256 i = 0; i < users.length; i++) {
            target.setBalance(users[i], 0);
        }
    }
}
```

## Appendix B - Proxy/Upgradeable Contract

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/evm/evm-general-upgradeable/access/OwnableUpgradeable.sol";
import "@openzeppelin/evm/evm-general-upgradeable/proxy/utils/UUPSUpgradeable.sol";

/// @notice UUPS upgradeable implementation that supports batched state clearing.
/// @dev Storage lives in the proxy; this implementation provides logic.
contract V2Resettable is UUPSUpgradeable, OwnableUpgradeable {
    uint256 public totalSupply;
    mapping(address => uint256) public balances;

    address[] public holders;
    mapping(address => bool) private isHolder;

    function initialize() external initializer {
        __Ownable_init();
        __UUPSUpgradeable_init();
    }

    function _authorizeUpgrade(address newImplementation) internal override onlyOwner {}

    function setBalance(address user, uint256 amount) external onlyOwner {
        if (!isHolder[user]) {
            isHolder[user] = true;
            holders.push(user);
        }
        balances[user] = amount;
    }

    /// @notice Batch-clear balances for a caller-supplied list of users.
    /// @dev Enumerate keys off-chain (events/indexer) and pass them in.
    function resetBalances(address[] calldata users) external onlyOwner {
        for (uint256 i = 0; i < users.length; i++) {
            address u = users[i];
            delete balances[u];
            delete isHolder[u];
        }
    }
}
```

---

## Distribution Precompile

*Withdraw staking rewards and manage validator commissions from EVM contracts using the distribution precompile.*

**Address**: `0x0000000000000000000000000000000000001007`

The distribution precompile provides EVM access to Cosmos SDK's distribution module. Smart contracts can manage staking rewards, validator commissions, and withdrawal addresses. This precompile is essential for DeFi applications that need to handle staking rewards programmatically.

## Key Features

- **Reward Management**: Withdraw delegation rewards from validators
- **Commission Handling**: Validators can withdraw earned commissions
- **Batch Operations**: Withdraw from multiple validators efficiently
- **Flexible Withdrawals**: Set custom withdrawal addresses
- **Comprehensive Queries**: Access detailed reward information

## Interface Overview

```solidity
interface IDistr {
    // Events
    event WithdrawAddressSet(address indexed delegator, address withdrawAddr);
    event DelegationRewardsWithdrawn(address indexed delegator, string validator, uint256 amount);
    event MultipleDelegationRewardsWithdrawn(address indexed delegator, string[] validators, uint256[] amounts);
    event ValidatorCommissionWithdrawn(string indexed validator, uint256 amount);

    // Transaction Methods
    function setWithdrawAddress(address withdrawAddr) external returns (bool);
    function withdrawDelegationRewards(string memory validator) external returns (bool);
    function withdrawMultipleDelegationRewards(string[] memory validators) external returns (bool);
    function withdrawValidatorCommission() external returns (bool);

    // Query Methods
    function rewards(address delegatorAddress) external view returns (Rewards);
}
```

## Events

The distribution precompile emits events for all state-changing operations, allowing off-chain services to track reward distributions and configuration changes.

### WithdrawAddressSet

Emitted when a delegator changes their reward withdrawal address.

```solidity
event WithdrawAddressSet(address indexed delegator, address withdrawAddr);
```

**Parameters:**

- `delegator` (indexed): The EVM address of the delegator changing their settings
- `withdrawAddr`: The new address where rewards will be sent

**Example usage:**

```typescript
// Listen for withdrawal address changes
distrContract.on('WithdrawAddressSet', (delegator, withdrawAddr) => {
  console.log(`${delegator} set withdrawal address to ${withdrawAddr}`);
});
```

### DelegationRewardsWithdrawn

Emitted when a delegator withdraws rewards from a single validator.

```solidity
event DelegationRewardsWithdrawn(address indexed delegator, string validator, uint256 amount);
```

**Parameters:**

- `delegator` (indexed): The EVM address of the delegator withdrawing rewards
- `validator`: The Paxeer validator address (e.g., "paxvaloper1...")
- `amount`: The amount of rewards withdrawn (in uhpx, 6 decimal precision)

**Example usage:**

```typescript
// Track individual reward withdrawals
distrContract.on('DelegationRewardsWithdrawn', (delegator, validator, amount) => {
  const paxAmount = Number(amount) / 1e6;
  console.log(`${delegator} withdrew ${paxAmount} HPX from ${validator}`);
});
```

### MultipleDelegationRewardsWithdrawn

Emitted when a delegator withdraws rewards from multiple validators in a single transaction.

```solidity
event MultipleDelegationRewardsWithdrawn(address indexed delegator, string[] validators, uint256[] amounts);
```

**Parameters:**

- `delegator` (indexed): The EVM address of the delegator withdrawing rewards
- `validators`: Array of Paxeer validator addresses
- `amounts`: Array of reward amounts corresponding to each validator (in uhpx, 6 decimal precision)

**Example usage:**

```typescript
// Track batch reward withdrawals
distrContract.on('MultipleDelegationRewardsWithdrawn', (delegator, validators, amounts) => {
  for (let i = 0; i < validators.length; i++) {
    const paxAmount = Number(amounts[i]) / 1e6;
    console.log(`${delegator} withdrew ${paxAmount} HPX from ${validators[i]}`);
  }
});
```

### ValidatorCommissionWithdrawn

Emitted when a validator operator withdraws their earned commission.

```solidity
event ValidatorCommissionWithdrawn(string indexed validator, uint256 amount);
```

**Parameters:**

- `validator` (indexed): The Paxeer validator address
- `amount`: The commission amount withdrawn (in uhpx, 6 decimal precision)

**Example usage:**

```typescript
// Track validator commission withdrawals
distrContract.on('ValidatorCommissionWithdrawn', (validator, amount) => {
  const paxAmount = Number(amount) / 1e6;
  console.log(`Validator ${validator} withdrew ${paxAmount} HPX commission`);
});
```

<Info>**Event Amounts**: All event amounts use 6 decimal precision (uhpx), matching the actual withdrawn token amounts. This differs from the `rewards()` query which returns 18 decimal precision.</Info>

## Transaction Methods

### setWithdrawAddress

Sets the withdrawal address for staking rewards. By default, rewards are sent to the delegator's address, but this can be customized.

```solidity
function setWithdrawAddress(address withdrawAddr) external returns (bool success);
```

**Parameters:**

- `withdrawAddr`: EVM address where future rewards should be sent

**Gas Cost**: ~30,000 gas

**Example:**

```solidity
// Set rewards to go to a treasury contract
bool success = DISTR_CONTRACT.setWithdrawAddress(0x742d35Cc6634C0532925a3b8D4C9db96590c6C8C);
require(success, "Failed to set withdraw address");
```

### withdrawDelegationRewards

Withdraws accumulated rewards from a specific validator.

```solidity
function withdrawDelegationRewards(string memory validator) external returns (bool success);
```

**Parameters:**

- `validator`: Paxeer validator address (e.g., "paxvaloper1...")

**Gas Cost**: ~50,000-80,000 gas (varies by reward amount)

**Example:**

```solidity
string memory validator = "paxvaloper1xyz...";
bool success = DISTR_CONTRACT.withdrawDelegationRewards(validator);
require(success, "Failed to withdraw rewards");
```

### withdrawMultipleDelegationRewards

Efficiently withdraws rewards from multiple validators in a single transaction.

```solidity
function withdrawMultipleDelegationRewards(string[] memory validators) external returns (bool success);
```

**Parameters:**

- `validators`: Array of Paxeer validator addresses

**Gas Cost**: ~40,000 + (30,000 × number of validators)

**Example:**

```solidity
string[] memory validators = new string[](3);
validators[0] = "paxvaloper1abc...";
validators[1] = "paxvaloper1def...";
validators[2] = "paxvaloper1ghi...";

bool success = DISTR_CONTRACT.withdrawMultipleDelegationRewards(validators);
require(success, "Failed to withdraw multiple rewards");
```

<Info>**Batch Efficiency**: Using `withdrawMultipleDelegationRewards` is significantly more gas-efficient than multiple individual calls, especially when withdrawing from 3+ validators.</Info>

### withdrawValidatorCommission

Allows validators to withdraw their earned commission. Only callable by the validator operator address.

```solidity
function withdrawValidatorCommission() external returns (bool success);
```

**Parameters:** None - the validator is automatically determined from the caller's associated Paxeer address.

**Gas Cost**: ~60,000-90,000 gas

**Example:**

```solidity
// Only works if caller is the validator operator
bool success = DISTR_CONTRACT.withdrawValidatorCommission();
require(success, "Failed to withdraw commission");
```

<Warning>**Validator Only**: This method can only be called by the validator's operator address. The precompile automatically identifies the validator based on the caller's associated Paxeer address. If the caller is not a validator operator, the call will fail.</Warning>

## Query Methods

### rewards

Retrieves comprehensive reward information for a delegator across all validators.

```solidity
function rewards(address delegatorAddress) external view returns (Rewards rewards);
```

**Data Structures:**

```solidity
struct Coin {
    uint256 amount;    // Token amount in 18 decimal precision (DecCoins)
    uint256 decimals;  // Always 18 - decimal precision for the amount
    string denom;      // Token denomination (e.g., "uhpx")
}

struct Reward {
    Coin[] coins;              // Reward coins from this validator
    string validator_address;  // Validator's Paxeer address
}

struct Rewards {
    Reward[] rewards;  // Per-validator breakdown
    Coin[] total;      // Total rewards across all validators
}
```

<Warning>
**Critical: Decimal Precision for Rewards**

The `rewards()` query returns amounts with **18 decimal precision** (`DecCoins` from Cosmos SDK).

This is different from the actual withdrawn reward amounts, which use **6 decimal precision** (`sdk.Coins`).

**To convert pending rewards to HPX for display:**

```javascript
const pendingRewardsPax = amount / 1e18; // rewards() query uses 18 decimals
```

**Withdrawn rewards are in uhpx (6 decimals):**

```javascript
const withdrawnPax = withdrawnAmount / 1e6; // actual withdrawals use 6 decimals
```

</Warning>

**Example:**

```solidity
Rewards memory userRewards = DISTR_CONTRACT.rewards(msg.sender);

// Check total rewards - uses 18 decimal precision
for (uint i = 0; i < userRewards.total.length; i++) {
    Coin memory coin = userRewards.total[i];
    // coin.decimals is always 18 for rewards
    uint256 displayAmount = coin.amount / (10 ** coin.decimals);
    // Process reward amount for coin.denom
}

// Check per-validator rewards
for (uint i = 0; i < userRewards.rewards.length; i++) {
    Reward memory reward = userRewards.rewards[i];
    // Process rewards from reward.validator_address
}
```

## Understanding Decimal Precision

The distribution precompile has **different decimal precision for queries vs actual withdrawals** due to how rewards are tracked in the Cosmos SDK:

| Function | Type | Decimal Precision | Conversion to HPX |
| --- | --- | --- | --- |
| **rewards()** | Query (pending rewards) | 18 decimals (DecCoins) | `amount / 1e18` |
| **withdrawDelegationRewards()** | Withdrawn amount (event) | 6 decimals (uhpx) | `amount / 1e6` |
| **withdrawMultipleDelegationRewards()** | Withdrawn amount (event) | 6 decimals (uhpx) | `amount / 1e6` |
| **withdrawValidatorCommission()** | Withdrawn amount (event) | 6 decimals (uhpx) | `amount / 1e6` |


### Why Different Precisions?

1. **Pending Rewards (18 decimals)**: The Cosmos SDK tracks pending rewards using `DecCoins` (decimal coins) with 18 decimal precision for higher accuracy during reward accumulation.

2. **Withdrawn Rewards (6 decimals)**: When rewards are actually withdrawn, they are converted to `sdk.Coins` (uhpx) with 6 decimal precision to match Paxeer's native token units.

### Conversion Helper Functions

```typescript
// Convert pending rewards (18 decimals) to HPX
function pendingRewardsToPax(amount: bigint): number {
  return Number(amount) / 1e18;
}

// Convert withdrawn rewards (6 decimals) to HPX
function withdrawnRewardsToPax(amount: bigint): number {
  return Number(amount) / 1e6;
}

// Example usage
const pendingRewards = await distrContract.rewards(delegatorAddress);
const pendingPax = pendingRewardsToPax(pendingRewards.total[0].amount);
console.log(`Pending rewards: ${pendingPax} HPX`);
```

<Info>**Note**: When reconciling pending rewards with actual withdrawals, be aware of the 12-decimal difference (10^12 factor) between query results and withdrawal amounts.</Info>

## Practical Examples

### DeFi Yield Aggregator

```solidity
contract YieldAggregator {
    IDistr constant DISTR = IDistr(0x0000000000000000000000000000000000001007);

    mapping(address => string[]) public userValidators;

    function harvestRewards() external {
        string[] memory validators = userValidators[msg.sender];
        require(validators.length > 0, "No validators to harvest from");

        // Efficiently withdraw from all validators
        bool success = DISTR.withdrawMultipleDelegationRewards(validators);
        require(success, "Harvest failed");

        // Additional logic to compound or distribute rewards
    }

    function checkPendingRewards(address user) external view returns (uint256 totalPax) {
        Rewards memory rewards = DISTR.rewards(user);

        for (uint i = 0; i < rewards.total.length; i++) {
            if (keccak256(bytes(rewards.total[i].denom)) == keccak256(bytes("uhpx"))) {
                totalPax = rewards.total[i].amount;
                break;
            }
        }
    }
}
```

### Validator Commission Manager

```solidity
contract ValidatorManager {
    IDistr constant DISTR = IDistr(0x0000000000000000000000000000000000001007);

    address public treasury;

    constructor(address _treasury) {
        treasury = _treasury;

        // Set commission withdrawals to go to treasury
        DISTR.setWithdrawAddress(treasury);
    }

    // Only callable by the validator operator
    function withdrawCommission() external {
        bool success = DISTR.withdrawValidatorCommission();
        require(success, "Commission withdrawal failed");
    }
}
```

## Error Handling

Common error scenarios and how to handle them:

```solidity
contract SafeDistribution {
    IDistr constant DISTR = IDistr(0x0000000000000000000000000000000000001007);

    function safeWithdrawRewards(string memory validator) external returns (bool) {
        // Check if there are rewards to withdraw first
        Rewards memory rewards = DISTR.rewards(msg.sender);

        bool hasRewards = false;
        for (uint i = 0; i < rewards.rewards.length; i++) {
            if (keccak256(bytes(rewards.rewards[i].validator_address)) ==
                keccak256(bytes(validator))) {
                hasRewards = rewards.rewards[i].coins.length > 0;
                break;
            }
        }

        if (!hasRewards) {
            return false; // No rewards to withdraw
        }

        try DISTR.withdrawDelegationRewards(validator) returns (bool success) {
            return success;
        } catch {
            return false; // Handle withdrawal failure gracefully
        }
    }
}
```

## Gas Optimization Tips

1. **Batch Operations**: Use `withdrawMultipleDelegationRewards` for multiple validators
2. **Check Before Withdraw**: Query rewards first to avoid unnecessary transactions
3. **Set Withdraw Address Once**: Avoid repeated `setWithdrawAddress` calls
4. **Commission Timing**: Withdraw validator commission when amounts are substantial

## Integration Patterns

### Auto-Compounding Strategy

```solidity
// Automatically reinvest rewards back into staking
function autoCompound() external {
    // 1. Withdraw rewards
    DISTR.withdrawMultipleDelegationRewards(getMyValidators());

    // 2. Use staking precompile to re-delegate
    // (Implementation depends on staking precompile integration)
}
```

### Treasury Management

```solidity
// Route all rewards to a DAO treasury
function setupTreasuryWithdrawals(address treasury) external onlyOwner {
    DISTR.setWithdrawAddress(treasury);
}
```

<Info>View the complete distribution precompile source code and ABI [here](https://github.com/paxeer-network/paxeer-chain/tree/main/precompiles/distribution).</Info>

---

## Precompile Example Usage

*Quick examples for calling Paxeer precompiles with viem and ethers all available precompiles with common patterns.*

Paxeer precompiles are special smart contracts deployed at fixed addresses that expose native Paxeer functionality to EVM applications. They can be called like any standard smart contract using viem, ethers, or wagmi.

<Info>
**Available Precompiles:**

| Precompile | Address | Description |
| --- | --- | --- |
| Bank | `0x1001` | Query native denom balances (uhpx, factory tokens) |
| JSON | `0x1003` | Parse JSON data within contracts |
| Staking | `0x1005` | Delegation and staking operations |
| Governance | `0x1006` | Proposal voting |
| Distribution | `0x1007` | Claim staking rewards |
| P256 | `0x1011` | Verify P-256 elliptic curve signatures |
</Info>

## Setup

```bash
npm install viem ethers @sei-js/precompiles
```

<CodeGroup>

```ts viem
import { createPublicClient, createWalletClient, http, custom } from 'viem';
import { sei } from 'viem/chains';

// Read-only
const client = createPublicClient({ chain: sei, transport: http() });

// Browser wallet (write)
const walletClient = createWalletClient({ chain: sei, transport: custom(window.ethereum) });
const [account] = await walletClient.getAddresses();
```

```ts ethers
import { ethers } from 'ethers';

// Browser environment
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

// Node.js / scripts
// const provider = new ethers.JsonRpcProvider('https://evm-rpc.sei-apis.com');
// const signer = new ethers.Wallet(process.env.PRIVATE_KEY, provider);
```

</CodeGroup>

## Bank Precompile

`eth_getBalance` only returns the EVM-side HPX balance. The Bank precompile lets you query any native denom - including factory tokens - from any address:

<CodeGroup>

```ts viem
import { BANK_PRECOMPILE_ABI, BANK_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';

// Query a specific denom balance
const balance = await client.readContract({
  address: BANK_PRECOMPILE_ADDRESS,
  abi: BANK_PRECOMPILE_ABI,
  functionName: 'balance',
  args: ['0xYourAddress', 'uhpx'],
});

// Query all native balances for an address
const allBalances = await client.readContract({
  address: BANK_PRECOMPILE_ADDRESS,
  abi: BANK_PRECOMPILE_ABI,
  functionName: 'all_balances',
  args: ['0xYourAddress'],
});
// Returns: [{ denom: 'uhpx', amount: '1000000' }, ...]
```

```ts ethers
import { BANK_PRECOMPILE_ABI, BANK_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';

const bank = new ethers.Contract(BANK_PRECOMPILE_ADDRESS, BANK_PRECOMPILE_ABI, provider);

const balance = await bank.balance('0xYourAddress', 'uhpx');
const allBalances = await bank.all_balances('0xYourAddress');
```

</CodeGroup>

## Staking Precompile

Delegate, undelegate, and query staking state:

<CodeGroup>

```ts viem
import { parseEther } from 'viem';
import { STAKING_PRECOMPILE_ABI, STAKING_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';

// Delegate HPX to a validator
const delegateHash = await walletClient.writeContract({
  address: STAKING_PRECOMPILE_ADDRESS,
  abi: STAKING_PRECOMPILE_ABI,
  functionName: 'delegate',
  args: ['paxvaloper1...'],
  value: parseEther('10'),
});

// Query delegation
const delegation = await client.readContract({
  address: STAKING_PRECOMPILE_ADDRESS,
  abi: STAKING_PRECOMPILE_ABI,
  functionName: 'delegation',
  args: [account, 'paxvaloper1...'],
});

// Undelegate 5 HPX - amount is in 6-decimal uhpx (1 HPX = 1_000_000 uhpx), not wei
const undelegateHash = await walletClient.writeContract({
  address: STAKING_PRECOMPILE_ADDRESS,
  abi: STAKING_PRECOMPILE_ABI,
  functionName: 'undelegate',
  args: ['paxvaloper1...', 5_000_000n],
});
```

```ts ethers
import { STAKING_PRECOMPILE_ABI, STAKING_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';

const staking = new ethers.Contract(STAKING_PRECOMPILE_ADDRESS, STAKING_PRECOMPILE_ABI, signer);
const readStaking = new ethers.Contract(STAKING_PRECOMPILE_ADDRESS, STAKING_PRECOMPILE_ABI, provider);

// Delegate 10 HPX
const tx = await staking.delegate('paxvaloper1...', { value: ethers.parseEther('10') });
await tx.wait();

// Query delegation
const delegation = await readStaking.delegation(await signer.getAddress(), 'paxvaloper1...');
console.log('Delegated:', delegation.balance.amount.toString());

// Undelegate 5 HPX - amount is in 6-decimal uhpx (1 HPX = 1_000_000 uhpx), not wei
const undelegateTx = await staking.undelegate('paxvaloper1...', ethers.parseUnits('5', 6));
await undelegateTx.wait();
```

</CodeGroup>

## Governance Precompile

Vote on an active governance proposal:

<CodeGroup>

```ts viem
import { GOVERNANCE_PRECOMPILE_ABI, GOVERNANCE_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';

// Vote options: 1 = Yes, 2 = Abstain, 3 = No, 4 = NoWithVeto
const hash = await walletClient.writeContract({
  address: GOVERNANCE_PRECOMPILE_ADDRESS,
  abi: GOVERNANCE_PRECOMPILE_ABI,
  functionName: 'vote',
  args: [99n, 1],
});
```

```ts ethers
import { GOVERNANCE_PRECOMPILE_ABI, GOVERNANCE_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';

const governance = new ethers.Contract(GOVERNANCE_PRECOMPILE_ADDRESS, GOVERNANCE_PRECOMPILE_ABI, signer);

// 1 = Yes, 2 = Abstain, 3 = No, 4 = NoWithVeto
const tx = await governance.vote(99n, 1);
await tx.wait();
```

</CodeGroup>

## Distribution Precompile

Claim staking rewards from a validator:

<CodeGroup>

```ts viem
import { DISTRIBUTION_PRECOMPILE_ABI, DISTRIBUTION_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';

const hash = await walletClient.writeContract({
  address: DISTRIBUTION_PRECOMPILE_ADDRESS,
  abi: DISTRIBUTION_PRECOMPILE_ABI,
  functionName: 'withdrawDelegationRewards',
  args: ['paxvaloper1...'],
});
```

```ts ethers
import { DISTRIBUTION_PRECOMPILE_ABI, DISTRIBUTION_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';

const distribution = new ethers.Contract(
  DISTRIBUTION_PRECOMPILE_ADDRESS,
  DISTRIBUTION_PRECOMPILE_ABI,
  signer,
);

const tx = await distribution.withdrawDelegationRewards('paxvaloper1...');
await tx.wait();
```

</CodeGroup>

## JSON Precompile

Parse JSON data within EVM contracts or dApps - useful for processing oracle responses, NFT metadata, and structured payloads:

<CodeGroup>

```ts viem
import { toHex, toBytes } from 'viem';
import { JSON_PRECOMPILE_ABI, JSON_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';

const data = { price: 100, symbol: 'HPX' };
const inputBytes = toBytes(JSON.stringify(data));

// Extract a string value
const symbolBytes = await client.readContract({
  address: JSON_PRECOMPILE_ADDRESS,
  abi: JSON_PRECOMPILE_ABI,
  functionName: 'extractAsBytes',
  args: [inputBytes, 'symbol'],
});

// Extract a numeric value
const price = await client.readContract({
  address: JSON_PRECOMPILE_ADDRESS,
  abi: JSON_PRECOMPILE_ABI,
  functionName: 'extractAsUint256',
  args: [inputBytes, 'price'],
});
```

```ts ethers
import { JSON_PRECOMPILE_ABI, JSON_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';

const jsonPrecompile = new ethers.Contract(JSON_PRECOMPILE_ADDRESS, JSON_PRECOMPILE_ABI, provider);

const data = { price: 100, symbol: 'HPX' };
const inputData = ethers.toUtf8Bytes(JSON.stringify(data));

// Extract a string value
const symbolBytes = await jsonPrecompile.extractAsBytes(inputData, 'symbol');
const symbol = ethers.toUtf8String(symbolBytes);

// Extract a numeric value
const price = await jsonPrecompile.extractAsUint256(inputData, 'price');

console.log(`${symbol}: ${price}`);
```

</CodeGroup>

## Common Patterns

### Error Handling

Wrap precompile calls in try/catch and check for specific error codes:

```ts
try {
  const tx = await staking.delegate('paxvaloper1...', { value: ethers.parseEther('10') });
  const receipt = await tx.wait();
  console.log('Success:', receipt.hash);
} catch (err: any) {
  if (err.code === 'INSUFFICIENT_FUNDS') {
    console.error('Not enough HPX');
  } else if (err.code === 4001 || err.code === 'ACTION_REJECTED') {
    console.log('User rejected');
  } else {
    console.error('Transaction failed:', err.message);
  }
}
```

### Batch Read Operations

Fetch multiple precompile values in parallel:

```ts
const [delegation1, delegation2, rewards] = await Promise.all([
  readStaking.delegation(address, validator1),
  readStaking.delegation(address, validator2),
  distribution.delegationTotalRewards(address),
]);
```

### Gas Limits

Precompile calls that write state need enough gas. Use `estimateGas` rather than hard-coding:

```ts viem
const gas = await client.estimateGas({
  account,
  address: STAKING_PRECOMPILE_ADDRESS,
  abi: STAKING_PRECOMPILE_ABI,
  functionName: 'delegate',
  args: ['paxvaloper1...'],
  value: parseEther('10'),
});
```

## Full Working Example

A Node.js script that delegates HPX and then casts a governance vote:

```ts
import { ethers } from 'ethers';
import {
  STAKING_PRECOMPILE_ABI, STAKING_PRECOMPILE_ADDRESS,
  GOVERNANCE_PRECOMPILE_ABI, GOVERNANCE_PRECOMPILE_ADDRESS,
} from '@sei-js/precompiles';

async function main() {
  const provider = new ethers.JsonRpcProvider('https://evm-rpc.sei-apis.com');
  const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

  const staking = new ethers.Contract(STAKING_PRECOMPILE_ADDRESS, STAKING_PRECOMPILE_ABI, wallet);
  const governance = new ethers.Contract(GOVERNANCE_PRECOMPILE_ADDRESS, GOVERNANCE_PRECOMPILE_ABI, wallet);

  // Check current delegation
  const readStaking = staking.connect(provider) as typeof staking;
  const delegation = await readStaking.delegation(wallet.address, 'paxvaloper1...');
  console.log('Current delegation:', delegation.balance.amount.toString());

  // Delegate 1 HPX
  const delegateTx = await staking.delegate('paxvaloper1...', { value: ethers.parseEther('1') });
  await delegateTx.wait();
  console.log('Delegated 1 HPX');

  // Vote Yes on proposal 99
  const voteTx = await governance.vote(99n, 1);
  await voteTx.wait();
  console.log('Vote cast');
}

main().catch(console.error);
```

Run with:

```bash
PRIVATE_KEY=your_key npx tsx script.ts
```

## Next Steps

For full ABI reference and all available functions on each precompile:

- [Staking Precompile →](/evm/precompiles/staking)
- [Governance Precompile →](/evm/precompiles/governance)
- [Distribution Precompile →](/evm/precompiles/distribution)
- [JSON Precompile →](/evm/precompiles/json)
- [P256 Precompile →](/evm/precompiles/p256-precompile)

---

## Governance Precompile Usage

*Submit proposals, vote, and query governance from EVM contracts using the governance precompile and ethers.js.*

**Address:** `0x0000000000000000000000000000000000001006`

The Paxeer governance precompile enables EVM applications to participate in Paxeer's on-chain governance process. This allows users and smart contracts to submit proposals, vote on them, deposit tokens, and query governance information directly through the EVM interface.

<Info>**What is a precompile?** A precompile is a special smart contract deployed at a fixed address by the Paxeer protocol itself, that exposes custom native chain logic to EVM-based applications. It acts like a regular contract from the EVM's perspective, but executes privileged, low-level logic efficiently.</Info>

## How Does the Governance Precompile Work?

The governance precompile at address `0x0000000000000000000000000000000000001006` exposes functions like `vote()`, `voteWeighted()`, `deposit()`, and `submitProposal()`.

- **Direct Integration:** EVM contracts and dApps can interact with governance like any other smart contract method.
- **Native Execution:** Governance operations are executed at the chain level for maximum efficiency.
- **Seamless:** No need for separate wallet integrations.

## Use Cases

- **Voting Interfaces:** Create user-friendly governance participation tools.
- **Automated Governance:** Smart contracts that vote based on predetermined strategies.
- **Governance Aggregators:** Build platforms that aggregate and simplify governance participation.

## Paxeer Governance Overview

Paxeer governance operates on a structured timeline with specific parameters:

### Governance Process

1. **Proposal Submission:** Submit proposal with minimum 3,500 HPX deposit
2. **Deposit Period:** 2 days to accumulate minimum deposit or reach expedited threshold
3. **Voting Period:** 3 days (1 day for expedited) of active voting once minimum deposit is met
4. **Tallying:** Results calculated based on quorum and voting thresholds

<Info> To find out all about the governance process on Paxeer, go to the [governance explainer](/learn/general-governance).</Info>

<Warning>
**Critical Mainnet Considerations:**

- **High Stakes:** Mainnet governance involves real HPX tokens and binding decisions
- **Minimum Deposit:** 3500 HPX minimum, 7000 HPX for expedited
- **Deposit Risk:** Deposits will be burned if your proposal receives >33.4% NoWithVeto votes
- **Voting Power Required:** Must stake HPX with validators to participate
- **Time Limits:** Strict 2-day deposit period and 3-day voting period
- **Real Impact:** Successful proposals can change network parameters

</Warning>

## Functions

The governance precompile exposes the following functions:

### Transaction Functions

```solidity
/// Cast a vote on the specified proposal.
/// @param proposalID The ID of the proposal to vote on.
/// @param option The option to vote for. (1=Yes, 2=Abstain, 3=No, 4=NoWithVeto)
/// @return Whether the vote was successfully cast.
function vote(
    uint64 proposalID,
    int32 option
) external returns (bool success);

struct WeightedVoteOption {
    int32 option;   // Vote option (1=Yes, 2=Abstain, 3=No, 4=NoWithVeto)
    string weight;  // Weight as decimal string (e.g., "0.7") - MUST sum to exactly 1.0 across all options
}

/// Cast a weighted vote on a governance proposal (vote splitting)
/// @param proposalID The ID of the proposal to vote on
/// @param options Array of weighted vote options, weights MUST sum to exactly 1.0 or transaction will fail
/// @return success Whether the vote was successfully cast
function voteWeighted(
    uint64 proposalID,
    WeightedVoteOption[] calldata options
) external returns (bool success);

/// Deposit funds into the specified proposal.
/// @param proposalID The ID of the proposal to deposit to.
/// @return Whether the tokens were successfully deposited.
function deposit(
    uint64 proposalID
) payable external returns (bool success);

/// Submit a new governance proposal. Deposit should be provided via msg.value
/// @param proposalJSON JSON string containing proposal details e.g.:
///        {
///          "title": "Proposal Title",
///          "description": "Proposal Description",
///          "type": "Text", // Optional, defaults to "Text" if empty
///          "is_expedited": false // Optional
///        }
/// @return proposalID The ID of the created proposal

function submitProposal(
    string calldata proposalJSON
) payable external returns (uint64 proposalID);
```

## Using the Contract

### Setup

#### Prerequisites

Before getting started, ensure you have:

- **Node.js** (v18 or higher)
- **npm** or **yarn** package manager
- **MetaMask** or compatible EVM wallet configured for Paxeer Mainnet
- **HPX tokens** for gas and governance deposits (minimum 3,500 HPX for proposals)

#### Install Dependencies

Install the required packages for interacting with Paxeer precompiles:

```bash
# Install ethers.js for smart contract interactions
npm install ethers

# Install Paxeer EVM bindings for precompile addresses and ABIs
npm install @sei-js/precompiles@2.1.2

# Install dotenv for managing private keys (optional but recommended)
npm install dotenv
```

#### Import Precompile Components

```typescript
// Import Governance precompile address and ABI
// View the entire ABI here: https://github.com/paxeer-network/paxeer-chain/tree/main/precompiles/gov
import { GOVERNANCE_PRECOMPILE_ABI, GOVERNANCE_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';
import { ethers } from 'ethers';
```

<Info>**Precompile Address:** The governance precompile is deployed at `0x0000000000000000000000000000000000001006`</Info>

#### Get HPX Tokens

Purchase HPX tokens from supported exchanges:

- **Centralized Exchanges:** Binance, Coinbase, KuCoin, Gate.io
- **Decentralized Exchanges:** Astroport, Dragonswap (on Paxeer)
- **Bridge Options:** Various cross-chain bridges support HPX

<Warning>**Minimum Requirements:** You need at least 3,500 HPX to submit a governance proposal, plus additional tokens for gas and potential additional deposits.</Warning>

### Contract Initialization

Set up your provider, signer, and contract instance:

```typescript
// Using MetaMask as the signer and provider (browser environment)
const provider = new ethers.BrowserProvider(window.ethereum);
await provider.send('eth_requestAccounts', []);
const signer = await provider.getSigner();

// Or for Node.js environment
const provider = new ethers.JsonRpcProvider('https://evm-rpc.sei-apis.com');
const signer = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);

// Create a contract instance for the governance precompile
const governance = new ethers.Contract(GOVERNANCE_PRECOMPILE_ADDRESS, GOVERNANCE_PRECOMPILE_ABI, signer);
```

## Vote Options

The governance system uses the following vote options:

| Option | Value | Description | Impact |
| --- | --- | --- | --- |
| Yes | 1 | Vote in favor of the proposal | Proposal passes if threshold met |
| Abstain | 2 | Abstain from voting | Counts toward quorum only |
| No | 3 | Vote against the proposal | Opposes proposal |
| NoWithVeto | 4 | Vote against with veto | Opposes Proposal & burns deposit if > 33.4% |


### Voting Power

Your voting power is determined by:

- **Staked HPX:** Amount of HPX you have staked with validators
- **Delegation:** HPX delegated to validators counts toward voting power
- **Liquid HPX:** Unstaked HPX does not provide voting power

<Info>**Important:** Only staked HPX provides voting power. You must delegate your tokens to validators to participate in governance voting.</Info>

## Validation Functions

Before making governance transactions, use these helper functions to validate inputs:

```typescript
// Validate vote option
function isValidVoteOption(option: number): boolean {
  return option >= 1 && option <= 4;
}

// Validate weighted vote options sum to 1.0 - CRITICAL FOR TRANSACTION SUCCESS
function validateWeightedOptions(options: Array<{ option: number; weight: string }>): boolean {
  const totalWeight = options.reduce((sum, opt) => sum + parseFloat(opt.weight), 0);

  // Check if total weight equals 1.0 (with small tolerance for floating point precision)
  // Note: Paxeer governance is strict - even small deviations will cause transaction failure
  const isValidTotal = Math.abs(totalWeight - 1.0) < 0.000001;

  // Check if all options are valid
  const allOptionsValid = options.every((opt) => isValidVoteOption(opt.option));

  if (!isValidTotal) {
    console.error(`Weights sum to ${totalWeight}, but MUST equal exactly 1.0`);
  }

  return isValidTotal && allOptionsValid;
}

// Validate proposal JSON structure
function validateProposalJSON(proposalJSON: string): boolean {
  try {
    const proposal = JSON.parse(proposalJSON);
    return proposal.title && proposal.description && typeof proposal.title === 'string' && typeof proposal.description === 'string' && proposal.title.length > 0 && proposal.description.length > 0;
  } catch {
    return false;
  }
}

// Check if deposit meets minimum requirement
function validateDepositAmount(depositAmount: bigint, isExpedited: boolean = false): boolean {
  const MINIMUM_DEPOSIT = ethers.parseUnits('3500', 18); // 3,500 HPX minimum
  const EXPEDITED_DEPOSIT = ethers.parseUnits('7000', 18); // 7,000 HPX for expedited

  const requiredAmount = isExpedited ? EXPEDITED_DEPOSIT : MINIMUM_DEPOSIT;
  return depositAmount >= requiredAmount;
}

// Check if user has sufficient voting power
async function checkVotingPower(userAddress: string): Promise<bigint> {
  // This would typically query staking information
  // Implementation depends on your specific setup
  console.log(`Checking voting power for ${userAddress}`);
  return ethers.parseUnits('0', 18); // Placeholder - implement actual check
}
```

## Step-by-Step Guide: Using the Governance Precompile

### Submit a Proposal

<Info>
**Important Deposit Requirements:**

- **Minimum deposit:** 3,500 HPX required for proposal to enter voting period
- **Expedited processing:** 7,000 HPX if the voting period should only be 1 day long
- **Deposit period:** 2 days to meet minimum or proposal fails and deposits are burned
- **Multiple deposits:** Anyone can contribute to reach the minimum threshold

</Info>

```typescript
async function submitGovernanceProposal(title: string, description: string, depositAmount: bigint, isExpedited: boolean = false): Promise<bigint> {
  // Validate inputs
  if (!title || !description) {
    throw new Error('Title and description are required');
  }

  if (title.length < 5 || title.length > 200) {
    throw new Error('Title must be between 5 and 200 characters');
  }

  if (description.length < 20 || description.length > 10000) {
    throw new Error('Description must be between 20 and 10,000 characters');
  }

  // Proposal details
  const proposal = {
    title: title.trim(),
    description: description.trim(),
    type: 'Text',
    is_expedited: isExpedited
  };

  // Convert to JSON string and validate
  const proposalJSON = JSON.stringify(proposal);
  if (!validateProposalJSON(proposalJSON)) {
    throw new Error('Invalid proposal JSON structure');
  }

  // Validate deposit amount
  if (!validateDepositAmount(depositAmount, isExpedited)) {
    const required = isExpedited ? '7,000 HPX' : '3,500 HPX';
    const provided = ethers.formatEther(depositAmount);
    throw new Error(`Insufficient deposit. Required: ${required}, Provided: ${provided} HPX`);
  }

  // Check balance before submitting
  const balance = await provider.getBalance(await signer.getAddress());
  const totalCost = depositAmount + ethers.parseUnits('0.1', 18); // Add gas buffer

  if (balance < totalCost) {
    throw new Error(`Insufficient balance. Need ${ethers.formatEther(totalCost)} HPX (including gas)`);
  }

  try {
    console.log('Submitting governance proposal...');
    console.log(`Title: ${title}`);
    console.log(`Deposit: ${ethers.formatEther(depositAmount)} HPX`);
    console.log(`Expedited: ${isExpedited}`);

    const tx = await governance.submitProposal(proposalJSON, {
      value: depositAmount,
      gasLimit: 500000
    });

    console.log('Transaction submitted:', tx.hash);
    console.log('Waiting for confirmation...');

    const receipt = await tx.wait();

    // Extract proposal ID from events
    let proposalID: bigint | null = null;
    for (const log of receipt.logs) {
      try {
        const parsed = governance.interface.parseLog(log);
        if (parsed && parsed.name === 'ProposalSubmitted') {
          proposalID = parsed.args.proposalID;
          break;
        }
      } catch {
        continue;
      }
    }

    if (!proposalID) {
      throw new Error('Could not extract proposal ID from transaction receipt');
    }

    console.log('✅ Proposal submitted successfully!');
    console.log(`Proposal ID: ${proposalID.toString()}`);
    console.log(`Transaction hash: ${receipt.hash}`);
    console.log(`View proposal: https://paxeer.explorers.guru/proposal/${proposalID.toString()}`);

    return proposalID;
  } catch (error: any) {
    console.error('Failed to submit proposal:', error);

    if (error.message.includes('insufficient funds')) {
      throw new Error('Insufficient funds for proposal deposit and gas fees');
    } else if (error.message.includes('invalid deposit')) {
      throw new Error('Deposit amount does not meet minimum requirements');
    } else {
      throw error;
    }
  }
}

// Usage example
const proposalTitle = 'Increase Block Size Limit';
const proposalDescription = `
This proposal suggests increasing the block size limit from the current value to improve transaction throughput on the Paxeer network.

## Rationale
Current network usage patterns show we are approaching capacity limits during peak times. Increasing the block size will:

1. Reduce transaction fees during high usage periods
2. Improve user experience with faster confirmation times
3. Support growing ecosystem adoption

## Implementation
The parameter change would be implemented through the existing governance mechanism with a 2-week transition period.

## Risks
- Slightly increased hardware requirements for validators
- Potential centralization concerns (mitigated by current validator distribution)

The benefits significantly outweigh the minimal risks involved.
`.trim();

const depositAmount = ethers.parseUnits('4000', 18); // 4,000 HPX deposit
await submitGovernanceProposal(proposalTitle, proposalDescription, depositAmount, false);
```

### Vote on a Proposal

```typescript
// Simple voting with comprehensive validation
async function voteOnProposal(proposalID: bigint, voteOption: number): Promise<void> {
  // Validate vote option
  if (!isValidVoteOption(voteOption)) {
    throw new Error('Invalid vote option. Must be 1 (Yes), 2 (Abstain), 3 (No), or 4 (NoWithVeto)');
  }

  // Check voting power (implement based on your staking setup)
  const userAddress = await signer.getAddress();
  console.log(`Checking voting eligibility for ${userAddress}...`);

  // Verify proposal exists and is in voting period
  try {
    // You would typically query proposal status here
    console.log(`Voting on proposal ${proposalID.toString()}...`);

    const voteOptionNames = {
      1: 'Yes',
      2: 'Abstain',
      3: 'No',
      4: 'NoWithVeto'
    };

    console.log(`Vote option: ${voteOptionNames[voteOption as keyof typeof voteOptionNames]}`);

    const tx = await governance.vote(proposalID, voteOption, {
      gasLimit: 200000
    });

    console.log('Transaction submitted:', tx.hash);
    const receipt = await tx.wait();

    console.log('✅ Vote cast successfully!');
    console.log(`Proposal ID: ${proposalID.toString()}`);
    console.log(`Vote: ${voteOptionNames[voteOption as keyof typeof voteOptionNames]}`);
    console.log(`Transaction hash: ${receipt.hash}`);
    console.log(`View on explorer: https://paxscan.io/tx/${receipt.hash}`);
  } catch (error: any) {
    console.error('Failed to cast vote:', error);

    if (error.message.includes('proposal does not exist')) {
      throw new Error('Proposal does not exist or voting period has ended');
    } else if (error.message.includes('already voted')) {
      throw new Error('You have already voted on this proposal');
    } else if (error.message.includes('insufficient voting power')) {
      throw new Error('No voting power - you must stake HPX to participate in governance');
    } else {
      throw error;
    }
  }
}

// Usage examples
const proposalID = 1n;

// Vote Yes
await voteOnProposal(proposalID, 1);

// Vote No with Veto (burns deposit if >33.4% of votes)
await voteOnProposal(proposalID, 4);
```

### Weighted Voting

<Danger>**Critical Requirement:** Weighted vote options MUST sum to exactly 1.0 or the transaction will fail. The Paxeer governance module enforces this strictly - even small rounding errors will cause rejection.</Danger>

```typescript
// Weighted voting with comprehensive validation
async function castWeightedVote(proposalID: bigint, weightedOptions: Array<{ option: number; weight: string }>): Promise<void> {
  // Comprehensive validation
  if (weightedOptions.length === 0) {
    throw new Error('At least one vote option is required');
  }

  if (weightedOptions.length > 4) {
    throw new Error('Cannot have more than 4 vote options');
  }

  // Validate each option and check for duplicates
  const seenOptions = new Set<number>();
  let totalWeight = 0;

  for (const { option, weight } of weightedOptions) {
    // Validate option
    if (!isValidVoteOption(option)) {
      throw new Error(`Invalid vote option: ${option}. Must be 1-4`);
    }

    // Check for duplicates
    if (seenOptions.has(option)) {
      throw new Error(`Duplicate vote option: ${option}`);
    }
    seenOptions.add(option);

    // Validate weight
    const weightNum = parseFloat(weight);
    if (isNaN(weightNum) || weightNum <= 0 || weightNum > 1) {
      throw new Error(`Invalid weight: ${weight}. Must be number between 0 and 1`);
    }

    totalWeight += weightNum;
  }

  // CRITICAL: Check total weight
  if (Math.abs(totalWeight - 1.0) > 0.000001) {
    throw new Error(`CRITICAL: Total weight must equal exactly 1.0, got ${totalWeight.toFixed(6)}. Transaction will fail.`);
  }

  try {
    console.log('Casting weighted vote...');
    console.log(`Proposal ID: ${proposalID.toString()}`);
    console.log('Vote distribution:');

    const voteOptionNames = { 1: 'Yes', 2: 'Abstain', 3: 'No', 4: 'NoWithVeto' };
    let totalPercent = 0;

    for (const { option, weight } of weightedOptions) {
      const percentage = (parseFloat(weight) * 100).toFixed(1);
      console.log(`  ${percentage}% ${voteOptionNames[option as keyof typeof voteOptionNames]}`);
      totalPercent += parseFloat(percentage);
    }

    console.log(`Total: ${totalPercent.toFixed(1)}%`);

    const tx = await governance.voteWeighted(proposalID, weightedOptions, {
      gasLimit: 300000 // Higher gas limit for weighted voting
    });

    console.log('Transaction submitted:', tx.hash);
    const receipt = await tx.wait();

    console.log('✅ Weighted vote cast successfully!');
    console.log(`Transaction hash: ${receipt.hash}`);
    console.log(`View on explorer: https://paxscan.io/tx/${receipt.hash}`);
  } catch (error: any) {
    console.error('Failed to cast weighted vote:', error);

    if (error.message.includes('weights must sum to 1')) {
      throw new Error('Vote weights must sum to exactly 1.0. Check your weight calculations.');
    } else {
      throw error;
    }
  }
}

// Usage examples

// Example 1: Split decision (60% Yes, 40% Abstain)
const splitVote = [
  { option: 1, weight: '0.6' }, // 60% Yes
  { option: 2, weight: '0.4' } // 40% Abstain
  // Total: 0.6 + 0.4 = 1.0 ✅
];

await castWeightedVote(proposalID, splitVote);

// Example 2: Complex distribution
const complexVote = [
  { option: 1, weight: '0.45' }, // 45% Yes
  { option: 2, weight: '0.25' }, // 25% Abstain
  { option: 3, weight: '0.20' }, // 20% No
  { option: 4, weight: '0.10' } // 10% NoWithVeto
  // Total: 0.45 + 0.25 + 0.20 + 0.10 = 1.0 ✅
];

await castWeightedVote(proposalID, complexVote);

// Example 3: This would FAIL - weights don't sum to 1.0
const badVote = [
  { option: 1, weight: '0.7' },
  { option: 2, weight: '0.2' }
  // Total: 0.7 + 0.2 = 0.9 ❌ WILL FAIL
];
// await castWeightedVote(proposalID, badVote); // Don't run this!
```

### Deposit to a Proposal

```typescript
// Add deposit to help proposal reach minimum threshold
async function addDepositToProposal(proposalID: bigint, depositAmount: bigint): Promise<void> {
  if (depositAmount <= 0) {
    throw new Error('Deposit amount must be greater than 0');
  }

  // Check balance
  const userAddress = await signer.getAddress();
  const balance = await provider.getBalance(userAddress);
  const totalCost = depositAmount + ethers.parseUnits('0.05', 18); // Add gas buffer

  if (balance < totalCost) {
    throw new Error(`Insufficient balance. Need ${ethers.formatEther(totalCost)} HPX (including gas), ` + `but have ${ethers.formatEther(balance)} HPX`);
  }

  try {
    console.log('Adding deposit to proposal...');
    console.log(`Proposal ID: ${proposalID.toString()}`);
    console.log(`Deposit amount: ${ethers.formatEther(depositAmount)} HPX`);

    const tx = await governance.deposit(proposalID, {
      value: depositAmount,
      gasLimit: 200000
    });

    console.log('Transaction submitted:', tx.hash);
    const receipt = await tx.wait();

    console.log('✅ Deposit added successfully!');
    console.log(`Proposal ID: ${proposalID.toString()}`);
    console.log(`Amount deposited: ${ethers.formatEther(depositAmount)} HPX`);
    console.log(`Transaction hash: ${receipt.hash}`);
    console.log(`View proposal: https://paxeer.explorers.guru/proposal/${proposalID.toString()}`);
  } catch (error: any) {
    console.error('Failed to add deposit:', error);

    if (error.message.includes('proposal does not exist')) {
      throw new Error('Proposal does not exist');
    } else if (error.message.includes('deposit period ended')) {
      throw new Error('Deposit period has ended for this proposal');
    } else {
      throw error;
    }
  }
}

// Usage example
const proposalID = 1n;
const additionalDeposit = ethers.parseUnits('1000', 18); // 1,000 HPX
await addDepositToProposal(proposalID, additionalDeposit);
```

## Complete Integration Example

Create a comprehensive governance interaction script:

```javascript title="governance-mainnet-demo.js"
const { ethers } = require('ethers');
const { GOVERNANCE_PRECOMPILE_ABI, GOVERNANCE_PRECOMPILE_ADDRESS } = require('@sei-js/precompiles');
require('dotenv').config();

// Validation functions
function isValidVoteOption(option) {
  return option >= 1 && option <= 4;
}

function validateWeightedOptions(options) {
  const totalWeight = options.reduce((sum, opt) => sum + parseFloat(opt.weight), 0);
  const isValidTotal = Math.abs(totalWeight - 1.0) < 0.000001;
  const allOptionsValid = options.every((opt) => isValidVoteOption(opt.option));
  return isValidTotal && allOptionsValid;
}

function validateProposalJSON(proposalJSON) {
  try {
    const proposal = JSON.parse(proposalJSON);
    return proposal.title && proposal.description && typeof proposal.title === 'string' && typeof proposal.description === 'string' && proposal.title.length > 0 && proposal.description.length > 0;
  } catch {
    return false;
  }
}

function validateDepositAmount(depositAmount, isExpedited = false) {
  const MINIMUM_DEPOSIT = ethers.parseUnits('3500', 18); // 3,500 HPX
  const EXPEDITED_DEPOSIT = ethers.parseUnits('7000', 18); // 7,000 HPX
  const required = isExpedited ? EXPEDITED_DEPOSIT : MINIMUM_DEPOSIT;
  return depositAmount >= required;
}

async function main() {
  try {
    // Connect to Paxeer Mainnet
    console.log('🌐 Connecting to Paxeer Mainnet...');
    const provider = new ethers.JsonRpcProvider('https://evm-rpc.sei-apis.com');

    // Use your private key from environment variable
    const privateKey = process.env.PRIVATE_KEY;
    if (!privateKey) {
      throw new Error('Please set PRIVATE_KEY in .env file');
    }

    const wallet = new ethers.Wallet(privateKey, provider);
    const userAddress = wallet.address;

    console.log(`👤 Wallet address: ${userAddress}`);

    // Check balance
    const balance = await provider.getBalance(userAddress);
    const balanceEther = ethers.formatEther(balance);
    console.log(`💰 Wallet balance: ${balanceEther} HPX\n`);

    // Verify sufficient balance for mainnet governance
    const minimumRequired = ethers.parseUnits('3600', 18); // 3,600 HPX (3,500 + buffer)
    if (balance < minimumRequired) {
      console.log('❌ Insufficient balance for mainnet governance participation');
      console.log(`   Required: At least 3,600 HPX (3,500 for proposal + 100 buffer)`);
      console.log(`   Current: ${balanceEther} HPX`);
      console.log('   Please acquire more HPX tokens from exchanges or DEXs');
      return;
    }

    // Initialize governance precompile contract
    const governance = new ethers.Contract(GOVERNANCE_PRECOMPILE_ADDRESS, GOVERNANCE_PRECOMPILE_ABI, wallet);

    console.log('🏛️  === Paxeer Mainnet Governance Demo ===\n');

    // 1. Submit a governance proposal
    console.log('1️⃣  Submitting a governance proposal...');

    const proposal = {
      title: 'Demo: EVM Governance Integration Test',
      description: `This is a demonstration proposal submitted through the governance precompile to showcase seamless EVM-Cosmos governance integration.

## Purpose
This proposal demonstrates:
- EVM smart contract governance participation
- Cross-environment compatibility
- Native governance functionality through precompiles

## Technical Details
- Submitted via governance precompile at ${GOVERNANCE_PRECOMPILE_ADDRESS}
- Using ethers.js for transaction management
- Mainnet deployment with real HPX deposits

## Voting Recommendation
This is a test proposal. Vote according to your preference to test the system.`,
      type: 'Text',
      is_expedited: false
    };

    const proposalJSON = JSON.stringify(proposal);

    // Validate proposal
    if (!validateProposalJSON(proposalJSON)) {
      throw new Error('Invalid proposal JSON structure');
    }

    // Use mainnet-appropriate deposit
    const depositAmount = ethers.parseUnits('3500', 18); // Exactly minimum required

    if (!validateDepositAmount(depositAmount)) {
      throw new Error('Deposit amount insufficient for mainnet');
    }

    try {
      console.log(`   📋 Title: ${proposal.title}`);
      console.log(`   💵 Deposit: ${ethers.formatEther(depositAmount)} HPX`);
      console.log('   🚀 Submitting transaction...');

      const submitTx = await governance.submitProposal(proposalJSON, {
        value: depositAmount,
        gasLimit: 500000,
        gasPrice: ethers.parseUnits('100', 'gwei') // Set appropriate gas price
      });

      console.log(`   📝 Transaction hash: ${submitTx.hash}`);
      console.log('   ⏳ Waiting for confirmation...');

      const submitReceipt = await submitTx.wait();

      // Extract proposal ID safely
      let proposalID = null;
      for (const log of submitReceipt.logs) {
        try {
          const parsed = governance.interface.parseLog(log);
          if (parsed && parsed.name === 'ProposalSubmitted') {
            proposalID = parsed.args.proposalID;
            break;
          }
        } catch {
          continue;
        }
      }

      if (!proposalID) {
        console.log('   ⚠️  Could not extract proposal ID. Check transaction manually.');
        console.log(`   🔗 Transaction: https://paxscan.io/tx/${submitReceipt.hash}`);
        return;
      }

      console.log(`   ✅ Proposal submitted successfully!`);
      console.log(`   🆔 Proposal ID: ${proposalID.toString()}`);
      console.log(`   🔗 View proposal: https://paxeer.explorers.guru/proposal/${proposalID.toString()}`);

      // 2. Demonstrate voting
      console.log(`\n2️⃣  Voting on proposal ${proposalID.toString()}...`);

      const voteOption = 1; // Yes
      const voteNames = { 1: 'Yes', 2: 'Abstain', 3: 'No', 4: 'NoWithVeto' };

      console.log(`   🗳️  Vote option: ${voteNames[voteOption]}`);
      console.log('   🚀 Submitting vote...');

      const voteTx = await governance.vote(proposalID, voteOption, {
        gasLimit: 200000,
        gasPrice: ethers.parseUnits('100', 'gwei')
      });

      console.log(`   📝 Transaction hash: ${voteTx.hash}`);
      await voteTx.wait();

      console.log('   ✅ Vote cast successfully!');
      console.log(`   🔗 Transaction: https://paxscan.io/tx/${voteTx.hash}`);

      // 3. Demonstrate weighted voting
      console.log(`\n3️⃣  Casting weighted vote on proposal ${proposalID.toString()}...`);

      const weightedOptions = [
        { option: 1, weight: '0.7' }, // 70% Yes
        { option: 2, weight: '0.2' }, // 20% Abstain
        { option: 3, weight: '0.1' } // 10% No
        // CRITICAL: Total = 0.7 + 0.2 + 0.1 = 1.0 ✅
      ];

      if (!validateWeightedOptions(weightedOptions)) {
        throw new Error('CRITICAL: Invalid weighted options - transaction would fail');
      }

      console.log('   📊 Vote distribution:');
      weightedOptions.forEach(({ option, weight }) => {
        const percent = (parseFloat(weight) * 100).toFixed(1);
        console.log(`      ${percent}% ${voteNames[option]}`);
      });

      console.log('   🚀 Submitting weighted vote...');

      const weightedTx = await governance.voteWeighted(proposalID, weightedOptions, {
        gasLimit: 300000,
        gasPrice: ethers.parseUnits('100', 'gwei')
      });

      console.log(`   📝 Transaction hash: ${weightedTx.hash}`);
      await weightedTx.wait();

      console.log('   ✅ Weighted vote cast successfully!');
      console.log(`   🔗 Transaction: https://paxscan.io/tx/${weightedTx.hash}`);

      // 4. Add additional deposit
      console.log(`\n4️⃣  Adding deposit to proposal ${proposalID.toString()}...`);

      const additionalDeposit = ethers.parseUnits('500', 18); // 500 HPX

      console.log(`   💵 Additional deposit: ${ethers.formatEther(additionalDeposit)} HPX`);
      console.log('   🚀 Submitting deposit...');

      const depositTx = await governance.deposit(proposalID, {
        value: additionalDeposit,
        gasLimit: 200000,
        gasPrice: ethers.parseUnits('100', 'gwei')
      });

      console.log(`   📝 Transaction hash: ${depositTx.hash}`);
      await depositTx.wait();

      console.log('   ✅ Additional deposit added successfully!');
      console.log(`   🔗 Transaction: https://paxscan.io/tx/${depositTx.hash}`);

      // Summary
      console.log('\n🎉 === Governance Demo Completed Successfully! ===');
      console.log(`📊 Proposal ID: ${proposalID.toString()}`);
      console.log(`💰 Total deposited: ${ethers.formatEther(depositAmount + additionalDeposit)} HPX`);
      console.log('🔗 View all governance proposals: https://paxeer.explorers.guru/proposals');
    } catch (error) {
      if (error.message.includes('insufficient funds')) {
        console.log('\n❌ Insufficient funds for governance participation');
        console.log('   Ensure you have enough HPX for deposits and gas fees');
      } else if (error.message.includes('already voted')) {
        console.log('\n⚠️  You have already voted on this proposal');
      } else {
        throw error;
      }
    }
  } catch (error) {
    console.error('\n❌ Error:', error.message);
    console.log('\n🔧 Troubleshooting tips:');
    console.log('1. Ensure PRIVATE_KEY is set in .env file');
    console.log('2. Verify sufficient HPX balance (minimum 3,600 HPX)');
    console.log('3. Check network connectivity to Paxeer mainnet');
    console.log('4. Confirm wallet has staked HPX for voting power');
    process.exit(1);
  }
}

// Run the demo
main().catch(console.error);
```

### Running the Example

1. **Create a new directory and initialize npm:**

```bash
mkdir paxeer-governance-mainnet
cd paxeer-governance-mainnet
npm init -y
```

2. **Install dependencies:**

```bash
npm install ethers @sei-js/precompiles@^2.1.2 dotenv
```

3. **Create a `.env` file:**

```bash
PRIVATE_KEY=your_private_key_here
```

4. **Create the demo file:**
   Copy the complete integration example above into `governance-mainnet-demo.js`

5. **Ensure you have sufficient HPX:**

   - Minimum 3,500 HPX for proposal deposit
   - Additional HPX for gas and optional additional deposits
   - Staked HPX for voting power

6. **Run the script:**

```bash
node governance-mainnet-demo.js
```

### Expected Output

```
🌐 Connecting to Paxeer Mainnet...
👤 Wallet address: 0x742d35Cc6634C0532925a3b844Bc6789e065f3B
💰 Wallet balance: 5000.5 HPX

🏛️  === Paxeer Mainnet Governance Demo ===

1️⃣  Submitting a governance proposal...
   📋 Title: Demo: EVM Governance Integration Test
   💵 Deposit: 3500.0 HPX
   🚀 Submitting transaction...
   📝 Transaction hash: 0x123...abc
   ⏳ Waiting for confirmation...
   ✅ Proposal submitted successfully!
   🆔 Proposal ID: 42
   🔗 View proposal: https://paxeer.explorers.guru/proposal/42

2️⃣  Voting on proposal 42...
   🗳️  Vote option: Yes
   🚀 Submitting vote...
   📝 Transaction hash: 0x456...def
   ✅ Vote cast successfully!
   🔗 Transaction: https://paxscan.io/tx/0x456...def

3️⃣  Casting weighted vote on proposal 42...
   📊 Vote distribution:
      70.0% Yes
      20.0% Abstain
      10.0% No
   🚀 Submitting weighted vote...
   📝 Transaction hash: 0x789...ghi
   ✅ Weighted vote cast successfully!
   🔗 Transaction: https://paxscan.io/tx/0x789...ghi

4️⃣  Adding deposit to proposal 42...
   💵 Additional deposit: 500.0 HPX
   🚀 Submitting deposit...
   📝 Transaction hash: 0xabc...123
   ✅ Additional deposit added successfully!
   🔗 Transaction: https://paxscan.io/tx/0xabc...123

🎉 === Governance Demo Completed Successfully! ===
📊 Proposal ID: 42
💰 Total deposited: 4000.0 HPX
🔗 View all governance proposals: https://paxeer.explorers.guru/proposals
```

## Troubleshooting

### Common Issues and Solutions

#### Insufficient Deposit

```typescript
// Check minimum deposit requirement based on proposal type
const MINIMUM_DEPOSIT = ethers.parseUnits('3500', 18); // 3,500 HPX minimum
const EXPEDITED_DEPOSIT = ethers.parseUnits('7000', 18); // 7,000 HPX for expedited

function checkDepositRequirement(depositAmount: bigint, isExpedited: boolean = false): void {
  const requiredAmount = isExpedited ? EXPEDITED_DEPOSIT : MINIMUM_DEPOSIT;
  const networkName = 'mainnet';

  if (depositAmount < requiredAmount) {
    const required = ethers.formatEther(requiredAmount);
    const provided = ethers.formatEther(depositAmount);
    throw new Error(`Deposit too low for ${networkName}${isExpedited ? ' (expedited)' : ''}. Required: ${required} HPX, Provided: ${provided} HPX`);
  }
}
```

#### No Voting Power

```typescript
// Check if user has staked HPX for voting power
async function checkVotingEligibility(userAddress: string): Promise<void> {
  console.log('Checking voting eligibility...');

  // Note: You would typically integrate with staking queries here
  // This is a placeholder for the actual implementation

  console.log('⚠️  Reminder: You must have staked HPX to participate in governance voting');
  console.log('   Liquid HPX does not provide voting power');
  console.log('   Delegate your HPX to validators to gain voting power');
  console.log('   Visit: https://docs.paxeer.app/stake to stake your tokens');
}
```

#### Invalid Vote Option

```typescript
// Validate vote option with descriptive error
function validateVoteOptionWithDescription(option: number): void {
  const voteOptions = {
    1: 'Yes - Vote in favor of the proposal',
    2: 'Abstain - Neutral vote that counts toward quorum',
    3: 'No - Vote against the proposal',
    4: 'NoWithVeto - Strong opposition that can burn deposits'
  };

  if (!(option in voteOptions)) {
    const validOptions = Object.entries(voteOptions)
      .map(([key, value]) => `${key}: ${value}`)
      .join('\n');

    throw new Error(`Invalid vote option: ${option}\n\nValid options:\n${validOptions}`);
  }
}
```

#### Weighted Vote Validation

```typescript
// Comprehensive weighted vote validation with helpful errors
function validateWeightedVoteComprehensive(options: Array<{ option: number; weight: string }>): void {
  if (options.length === 0) {
    throw new Error('At least one vote option is required');
  }

  if (options.length > 4) {
    throw new Error('Cannot have more than 4 vote options');
  }

  let totalWeight = 0;
  const seenOptions = new Set<number>();
  const voteOptionNames = { 1: 'Yes', 2: 'Abstain', 3: 'No', 4: 'NoWithVeto' };

  for (let i = 0; i < options.length; i++) {
    const { option, weight } = options[i];

    // Validate option
    if (option < 1 || option > 4 || !Number.isInteger(option)) {
      throw new Error(
        `Invalid vote option at index ${i}: ${option}. Must be integer 1-4\n` +
          `Valid options: ${Object.entries(voteOptionNames)
            .map(([k, v]) => `${k}=${v}`)
            .join(', ')}`
      );
    }

    // Check for duplicate options
    if (seenOptions.has(option)) {
      throw new Error(`Duplicate vote option: ${option} (${voteOptionNames[option as keyof typeof voteOptionNames]})\n` + `Each vote option can only be used once`);
    }
    seenOptions.add(option);

    // Validate weight
    const weightNum = parseFloat(weight);
    if (isNaN(weightNum)) {
      throw new Error(`Invalid weight at index ${i}: "${weight}" is not a valid number`);
    }

    if (weightNum <= 0) {
      throw new Error(`Invalid weight at index ${i}: ${weight}. Weight must be greater than 0`);
    }

    if (weightNum > 1) {
      throw new Error(`Invalid weight at index ${i}: ${weight}. Weight cannot exceed 1.0`);
    }

    totalWeight += weightNum;
  }

  // Check total weight - CRITICAL for transaction success
  if (Math.abs(totalWeight - 1.0) > 0.000001) {
    const weightSummary = options.map(({ option, weight }) => `${voteOptionNames[option as keyof typeof voteOptionNames]}: ${weight}`).join(', ');

    throw new Error(`CRITICAL: Total weight must equal exactly 1.0, got ${totalWeight.toFixed(6)}\n` + `Current weights: ${weightSummary}\n` + `Sum: ${totalWeight.toFixed(6)}\n` + `Transaction will fail if weights don't sum to 1.0`);
  }
}
```

### Error Code Reference

| Error | Cause | Solution |
| --- | --- | --- |
| `proposal does not exist` | Invalid proposal ID or proposal expired | Verify proposal ID and ensure voting period is still active |
| `inactive proposal` | Voting or deposit period has ended | Check proposal status and timeline |
| `insufficient deposit` | Deposit below 3,500 HPX | Increase deposit to the minimum required amount |
| `invalid vote option` | Vote option not 1-4 | Use a valid option (1-Yes, 2-Abstain, 3-No, 4-NoWithVeto) |
| `already voted` | Address has already voted on this proposal | Each address can vote only once per proposal |
| `weights must sum to 1` | Weighted votes don’t sum to 1.0 | **CRITICAL  - ** adjust weights so they total exactly 1.0 |
| `insufficient voting power` | No staked HPX | Delegate HPX to validators to gain voting power |
| `deposit period ended` | Deposits no longer accepted | Deposit period closes 2 days after submission |


<Info>

**Need Help?** If you encounter issues:

- **Discord:** [Paxeer Community Discord](https://discord.gg/paxeer)
- **GitHub:** [Paxeer Protocol Repository](https://github.com/paxeer-network/paxeer-chain)
- **Explorer:** [View Proposals on Paxeer Explorer](https://paxeer.explorers.guru/proposals)

</Info>

---

## JSON Precompile Usage

*Learn how to use the Paxeer JSON precompile at address 0x1003 to parse and query JSON data directly within EVM smart contracts.*

**Address:** `0x0000000000000000000000000000000000001003`

The Paxeer JSON precompile allows EVM applications to efficiently parse and query JSON data directly within smart contracts. This enables complex data handling capabilities that are not natively available in Solidity, making it easier to work with structured data from external sources or APIs.

<Info>**What is a precompile?** A precompile is a special smart contract deployed at a fixed address by the Paxeer protocol itself, that exposes custom native chain logic to EVM-based applications. It acts like a regular contract from the EVM's perspective, but executes privileged, low-level logic efficiently.</Info>

## How Does the JSON Precompile Work?

The JSON precompile at address `0x0000000000000000000000000000000000001003` exposes functions like `extractAsBytes()`, `extractAsBytesList()`, and `extractAsUint256()`.

- **Direct Integration:** EVM contracts and dApps can parse JSON data like any other smart contract method.
- **Native Execution:** JSON parsing is executed at the native level for maximum efficiency.
- **Seamless Bridge:** No need for complex workarounds or external libraries for JSON handling.

## Use Cases

- **Oracle Integration:** Parse complex oracle responses containing multiple data points.
- **DeFi Applications:** Process structured price feeds and market data.
- **Gaming:** Handle complex game state and player data stored in JSON format.
- **Cross-Chain Communication:** Parse messages and data from other chains.
- **NFT Metadata:** Extract and manipulate NFT metadata stored in JSON format.

## Functions

The JSON precompile exposes the following functions:

### Query Functions

```solidity
/// Extracts data as bytes from the input using the specified key.
/// @param input The input data.
/// @param key The key to extract.
/// @return The extracted data as bytes.
function extractAsBytes(
    bytes memory input,
    string memory key
) external view returns (bytes memory response);

/// Extracts data as a list of bytes from the input using the specified key.
/// @param input The input data.
/// @param key The key to extract.
/// @return The extracted data as bytes collection.
function extractAsBytesList(
    bytes memory input,
    string memory key
) external view returns (bytes[] memory response);

/// Extracts data as a uint256 from the input using the specified key.
/// @param input The input data.
/// @param key The key to extract.
/// @return The extracted uint256.
function extractAsUint256(
    bytes memory input,
    string memory key
) external view returns (uint256 response);
```

## Using the Precompile

### Setup

#### Prerequisites

Before getting started, ensure you have:

- **Node.js** (v18 or higher)
- **npm** or **yarn** package manager
- **MetaMask** or compatible EVM wallet configured for Paxeer Mainnet
- **HPX tokens** for gas

#### Install Dependencies

Install the required packages for interacting with Paxeer precompiles:

```bash
# Install ethers.js for smart contract interactions
npm install ethers

# Install Paxeer EVM bindings for precompile addresses and ABIs
npm install @sei-js/precompiles@^2.1.2

# Install dotenv for managing private keys (recommended for security)
npm install dotenv
```

#### Import Precompile Components

```typescript
// Import JSON precompile address and ABI
// View the entire ABI here: https://github.com/paxeer-network/paxeer-chain/tree/main/precompiles/json
import { JSON_PRECOMPILE_ABI, JSON_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';
import { ethers } from 'ethers';
```

<Info>**Precompile Address:** The JSON precompile is deployed at `0x0000000000000000000000000000000000001003`</Info>

### Contract Initialization

Set up your provider, signer, and contract instance:

```typescript
// Using MetaMask as the signer and provider (browser environment)
const provider = new ethers.BrowserProvider(window.ethereum);
await provider.send('eth_requestAccounts', []);
const signer = await provider.getSigner();

// Or for Node.js environment
const provider = new ethers.JsonRpcProvider('https://evm-rpc.sei-apis.com');
const signer = new ethers.Wallet(process.env.PRIVATE_KEY, provider);

// Create a contract instance for the JSON precompile
const jsonPrecompile = new ethers.Contract(JSON_PRECOMPILE_ADDRESS, JSON_PRECOMPILE_ABI, signer);
```

## Data Type Handling

The JSON precompile has specific limitations for different data types:

### Supported Data Types

| Function | Supports | Limitations |
| --- | --- | --- |
| extractAsBytes | Strings, Objects, Arrays | Returns raw bytes - needs conversion |
| extractAsUint256 | Integers only | No decimals, booleans, or negative numbers |
| extractAsBytesList | Arrays of strings/objects | Each element returned as bytes |


### Data Type Conversion Strategies

```typescript
// For decimal numbers - store as integers with known precision
const priceData = { price: 250 }; // Represents 2.50 with 2 decimal places
const price = await jsonPrecompile.extractAsUint256(inputData, 'price');
const actualPrice = parseFloat(price.toString()) / 100; // Convert back to 2.50

// For boolean values - use 0/1 integers
const statusData = { isActive: 1 }; // 1 = true, 0 = false
const isActiveInt = await jsonPrecompile.extractAsUint256(inputData, 'isActive');
const isActive = isActiveInt === 1n;

// For complex objects - extract as bytes and parse
const userData = { user: { name: 'Alice', balance: 1000 } };
const userBytes = await jsonPrecompile.extractAsBytes(inputData, 'user');
const userString = ethers.toUtf8String(userBytes);
const userObject = JSON.parse(userString);
```

## Error Handling Utilities

Create comprehensive error handling for all extraction functions:

```typescript
// Safe extraction for bytes data
async function safeExtractBytes(jsonPrecompile: ethers.Contract, data: any, key: string, defaultValue: string = ''): Promise<string> {
  try {
    const inputData = ethers.toUtf8Bytes(JSON.stringify(data));
    const result = await jsonPrecompile.extractAsBytes(inputData, key);
    return ethers.toUtf8String(result);
  } catch (error: any) {
    console.log(`Key "${key}" not found or invalid, using default value`);
    return defaultValue;
  }
}

// Safe extraction for uint256 data
async function safeExtractUint256(jsonPrecompile: ethers.Contract, data: any, key: string, defaultValue: bigint = 0n): Promise<bigint> {
  try {
    const inputData = ethers.toUtf8Bytes(JSON.stringify(data));
    const result = await jsonPrecompile.extractAsUint256(inputData, key);
    return result;
  } catch (error: any) {
    console.log(`Key "${key}" not found or not a valid integer, using default value`);
    return defaultValue;
  }
}

// Safe extraction for array data
async function safeExtractBytesList(jsonPrecompile: ethers.Contract, data: any, key: string, defaultValue: string[] = []): Promise<string[]> {
  try {
    const inputData = ethers.toUtf8Bytes(JSON.stringify(data));
    const result = await jsonPrecompile.extractAsBytesList(inputData, key);
    return result.map((bytes: any) => ethers.toUtf8String(bytes));
  } catch (error: any) {
    console.log(`Key "${key}" not found or not a valid array, using default value`);
    return defaultValue;
  }
}
```

## Step-by-Step Guide: Using the JSON Precompile

### Extract String Data

```typescript
// JSON data with string values
const data = { name: 'Paxeer Token', symbol: 'HPX' };
const inputData = ethers.toUtf8Bytes(JSON.stringify(data));

// Extract string using safe method
const name = await safeExtractBytes(jsonPrecompile, data, 'name');
console.log('Name:', name); // Output: "Paxeer Token"

// Or direct extraction with error handling
try {
  const symbolBytes = await jsonPrecompile.extractAsBytes(inputData, 'symbol');
  const symbol = ethers.toUtf8String(symbolBytes);
  console.log('Symbol:', symbol); // Output: "HPX"
} catch (error) {
  console.error('Failed to extract symbol:', error.message);
}
```

### Extract Numeric Data

```typescript
// JSON data with numbers (integers only)
const data = { price: 42, volume: 1000000 };
const inputData = ethers.toUtf8Bytes(JSON.stringify(data));

// Extract integer using safe method
const price = await safeExtractUint256(jsonPrecompile, data, 'price');
console.log('Price:', price.toString()); // Output: "42"

// Handle decimal numbers by using integer representation
const decimalData = { rate: 275 }; // Represents 2.75 with 2 decimal places
const rate = await safeExtractUint256(jsonPrecompile, decimalData, 'rate');
const actualRate = Number(rate) / 100; // Convert to 2.75
console.log('Rate:', actualRate);
```

### Extract Array Data

```typescript
// JSON data with array
const data = { tokens: ['HPX', 'USDC', 'USDT'] };
const inputData = ethers.toUtf8Bytes(JSON.stringify(data));

// Extract array using safe method
const tokens = await safeExtractBytesList(jsonPrecompile, data, 'tokens');
console.log('Tokens:', tokens); // Output: ["HPX", "USDC", "USDT"]

// Handle mixed arrays by extracting as bytes and parsing
const mixedData = { values: [42, 'test', 100] };
const valuesBytes = await jsonPrecompile.extractAsBytes(ethers.toUtf8Bytes(JSON.stringify(mixedData)), 'values');
const valuesString = ethers.toUtf8String(valuesBytes);
const valuesArray = JSON.parse(valuesString);
console.log('Mixed values:', valuesArray); // Output: [42, "test", 100]
```

### Extract Nested Data

<Warning>**Important:** The JSON precompile does not support dot notation for nested objects. Instead, extract the parent object and parse it manually.</Warning>

```typescript
// For nested data, extract the parent object first
const data = {
  user: {
    wallet: {
      balance: 1000,
      currency: 'HPX'
    }
  }
};

// Method 1: Extract parent object and parse manually (recommended)
const userBytes = await jsonPrecompile.extractAsBytes(ethers.toUtf8Bytes(JSON.stringify(data)), 'user');
const userData = JSON.parse(ethers.toUtf8String(userBytes));
const balance = userData.wallet.balance;
const currency = userData.wallet.currency;

console.log('Balance:', balance); // Output: 1000
console.log('Currency:', currency); // Output: "HPX"

// Method 2: Extract deeper nested object
const walletBytes = await jsonPrecompile.extractAsBytes(
  ethers.toUtf8Bytes(JSON.stringify(data)),
  'wallet' // Direct key, not dot notation
);
const walletData = JSON.parse(ethers.toUtf8String(walletBytes));
console.log('Wallet data:', walletData); // Output: { balance: 1000, currency: "HPX" }
```

## Complete Integration Example

Create a comprehensive JSON parsing application for mainnet:

```javascript title="json-precompile-mainnet.js"
// json-precompile-mainnet.js
const { ethers } = require('ethers');
const { JSON_PRECOMPILE_ABI, JSON_PRECOMPILE_ADDRESS } = require('@sei-js/precompiles');
require('dotenv').config();

// Safe extraction utilities
async function safeExtractBytes(jsonPrecompile, data, key, defaultValue = '') {
  try {
    const inputData = ethers.toUtf8Bytes(JSON.stringify(data));
    const result = await jsonPrecompile.extractAsBytes(inputData, key);
    return ethers.toUtf8String(result);
  } catch (error) {
    console.log(`   ⚠️  Key "${key}" not found, using default: "${defaultValue}"`);
    return defaultValue;
  }
}

async function safeExtractUint256(jsonPrecompile, data, key, defaultValue = 0n) {
  try {
    const inputData = ethers.toUtf8Bytes(JSON.stringify(data));
    const result = await jsonPrecompile.extractAsUint256(inputData, key);
    return result;
  } catch (error) {
    console.log(`   ⚠️  Key "${key}" not found or invalid integer, using default: ${defaultValue}`);
    return defaultValue;
  }
}

async function safeExtractBytesList(jsonPrecompile, data, key, defaultValue = []) {
  try {
    const inputData = ethers.toUtf8Bytes(JSON.stringify(data));
    const result = await jsonPrecompile.extractAsBytesList(inputData, key);
    return result.map((bytes) => ethers.toUtf8String(bytes));
  } catch (error) {
    console.log(`   ⚠️  Key "${key}" not found or invalid array, using default: [${defaultValue.join(', ')}]`);
    return defaultValue;
  }
}

async function main() {
  try {
    // Connect to Paxeer Mainnet
    console.log('🌐 Connecting to Paxeer Mainnet...');
    const provider = new ethers.JsonRpcProvider('https://evm-rpc.sei-apis.com');

    // Use private key from environment variables (secure approach)
    const privateKey = process.env.PRIVATE_KEY;
    if (!privateKey) {
      throw new Error('Please set PRIVATE_KEY in .env file');
    }

    const wallet = new ethers.Wallet(privateKey, provider);
    console.log(`👤 Wallet address: ${wallet.address}`);

    // Check balance
    const balance = await provider.getBalance(wallet.address);
    const balanceEther = ethers.formatEther(balance);
    console.log(`💰 Wallet balance: ${balanceEther} HPX\n`);

    // Initialize JSON precompile contract
    const jsonPrecompile = new ethers.Contract(JSON_PRECOMPILE_ADDRESS, JSON_PRECOMPILE_ABI, wallet);

    console.log('📄 === Paxeer Mainnet JSON Precompile Demo ===\n');

    // Complex sample data - simulating a real-world oracle response
    const oracleData = {
      market: {
        prices: {
          HPX: 275, // 2.75 USD (stored as integer with 2 decimal places)
          BTC: 5000000, // 50,000.00 USD
          ETH: 300000 // 3,000.00 USD
        },
        volume: {
          daily: 1500000000, // $15M daily volume
          weekly: 8500000000 // $85M weekly volume
        }
      },
      metadata: {
        timestamp: '2024-12-27T12:00:00Z',
        source: 'MainnetPriceOracle',
        version: '2.1.0',
        isLive: 1 // 1 = true, 0 = false
      },
      assets: ['HPX', 'BTC', 'ETH', 'USDC'],
      validators: {
        active: 125,
        total: 200
      }
    };

    console.log('📋 Input JSON Data:');
    console.log(JSON.stringify(oracleData, null, 2));
    console.log();

    // 1. Extract string data with error handling
    console.log('1️⃣  Extracting String Data...');

    // Extract metadata object first, then parse individual fields
    const metadataBytes = await jsonPrecompile.extractAsBytes(ethers.toUtf8Bytes(JSON.stringify(oracleData)), 'metadata');
    const metadata = JSON.parse(ethers.toUtf8String(metadataBytes));

    console.log(`   📊 Source: ${metadata.source}`);
    console.log(`   🔢 Version: ${metadata.version}`);
    console.log(`   ⏰ Timestamp: ${metadata.timestamp}`);
    console.log(`   🟢 Is Live: ${metadata.isLive === 1 ? 'Yes' : 'No'}`);

    // Test missing key
    const missingKey = await safeExtractBytes(jsonPrecompile, oracleData, 'nonexistent', 'N/A');
    console.log(`   ❓ Missing Key: ${missingKey}`);

    // 2. Extract numeric data with proper object parsing
    console.log('\n2️⃣  Extracting Numeric Data...');

    // Extract market object first
    const marketBytes = await jsonPrecompile.extractAsBytes(ethers.toUtf8Bytes(JSON.stringify(oracleData)), 'market');
    const market = JSON.parse(ethers.toUtf8String(marketBytes));

    // Extract validators object
    const validatorsBytes = await jsonPrecompile.extractAsBytes(ethers.toUtf8Bytes(JSON.stringify(oracleData)), 'validators');
    const validators = JSON.parse(ethers.toUtf8String(validatorsBytes));

    // Convert integers back to decimals
    const paxeerPrice = market.prices.HPX / 100; // 2 decimal places
    const btcPrice = market.prices.BTC / 100; // 2 decimal places
    const isLive = metadata.isLive === 1; // Convert to boolean

    console.log(`   💰 HPX Price: ${paxeerPrice} (raw: ${market.prices.HPX})`);
    console.log(`   ₿ BTC Price: ${btcPrice.toLocaleString()} (raw: ${market.prices.BTC})`);
    console.log(`   💹 Daily Volume: ${market.volume.daily.toLocaleString()}`);
    console.log(`   ✅ Active Validators: ${validators.active}`);
    console.log(`   🔴 Is Live: ${isLive} (raw: ${metadata.isLive})`);

    // 3. Extract array data
    console.log('\n3️⃣  Extracting Array Data...');
    const assets = await safeExtractBytesList(jsonPrecompile, oracleData, 'assets');
    const invalidArray = await safeExtractBytesList(jsonPrecompile, oracleData, 'invalid.array', ['DEFAULT']);

    console.log(`   🪙 Assets: [${assets.join(', ')}]`);
    console.log(`   ❌ Invalid Array: [${invalidArray.join(', ')}]`);

    // 4. Extract complex nested objects
    console.log('\n4️⃣  Extracting Complex Nested Data...');
    console.log('   📈 Market Data:');
    console.log(`      Prices: HPX=${market.prices.HPX / 100}, BTC=${market.prices.BTC / 100}, ETH=${market.prices.ETH / 100}`);
    console.log(`      Volume: Daily=${market.volume.daily.toLocaleString()}, Weekly=${market.volume.weekly.toLocaleString()}`);
    console.log(`   👥 Validator Data:`);
    console.log(`      Active: ${validators.active}, Total: ${validators.total}`);

    // 5. Gas optimization demonstration
    console.log('\n5️⃣  Gas Usage Analysis...');
    const gasEstimates = {
      small: 50000, // Simple key extraction
      medium: 80000, // Nested object extraction
      large: 120000 // Complex array/object processing
    };

    console.log('   ⛽ Recommended Gas Limits:');
    console.log(`      Simple extraction: ${gasEstimates.small.toLocaleString()} gas`);
    console.log(`      Nested extraction: ${gasEstimates.medium.toLocaleString()} gas`);
    console.log(`      Complex processing: ${gasEstimates.large.toLocaleString()} gas`);

    // 6. Performance test with corrected key extraction
    console.log('\n6️⃣  Performance & Error Testing...');
    const testCases = [
      { key: 'metadata', expected: 'object', description: 'metadata object' },
      { key: 'market', expected: 'object', description: 'market data' },
      { key: 'assets', expected: 'array', description: 'assets array' },
      { key: 'nonexistent', expected: 'error', description: 'missing key' }
    ];

    for (const testCase of testCases) {
      try {
        const start = Date.now();
        const result = await safeExtractBytes(jsonPrecompile, oracleData, testCase.key);
        const duration = Date.now() - start;
        const preview = result.length > 50 ? result.substring(0, 47) + '...' : result;
        console.log(`   ✅ ${testCase.description}: "${preview}" (${duration}ms)`);
      } catch (error) {
        console.log(`   ❌ ${testCase.description}: ${error.message}`);
      }
    }

    console.log('\n🎉 === JSON Precompile Demo Completed Successfully! ===');
  } catch (error) {
    console.error('\n❌ Error:', error.message);
    console.log('\n🔧 Troubleshooting tips:');
    console.log('1. Ensure PRIVATE_KEY is set in .env file');
    console.log('2. Verify sufficient HPX balance for gas fees');
    console.log('3. Check network connectivity to Paxeer mainnet');
    console.log('4. Validate JSON structure before processing');
    process.exit(1);
  }
}

// Run the demo
main().catch(console.error);
```

### Running the Mainnet Example

1. **Create a new directory and initialize npm:**

```bash
mkdir paxeer-json-mainnet
cd paxeer-json-mainnet
npm init -y
```

2. **Install dependencies:**

```bash
npm install ethers @sei-js/precompiles@^2.1.2 dotenv
```

3. **Create a `.env` file:**

```bash
PRIVATE_KEY=your_private_key_here
```

<Warning>**Security Note:** Never commit private keys to version control! The `.env` file should be added to your `.gitignore`.</Warning>

4. **Create the demo file:**
   Copy the complete integration example above into `json-precompile-mainnet.js`

5. **Ensure you have HPX tokens:**

   - HPX for gas (small amounts needed for view functions)

6. **Run the script:**

```bash
node json-precompile-mainnet.js
```

### Expected Output

```
🌐 Connecting to Paxeer Mainnet...
👤 Wallet address: 0x742d35Cc6634C0532925a3b844Bc6789e065f3B
💰 Wallet balance: 15.5 HPX

📄 === Paxeer Mainnet JSON Precompile Demo ===

📋 Input JSON Data:
{
  "market": {
    "prices": {
      "HPX": 275,
      "BTC": 5000000,
      "ETH": 300000
    },
    "volume": {
      "daily": 1500000000,
      "weekly": 8500000000
    }
  },
  "metadata": {
    "timestamp": "2024-12-27T12:00:00Z",
    "source": "MainnetPriceOracle",
    "version": "2.1.0",
    "isLive": 1
  },
  "assets": ["HPX", "BTC", "ETH", "USDC"],
  "validators": {
    "active": 125,
    "total": 200
  }
}

1️⃣  Extracting String Data...
   📊 Source: MainnetPriceOracle
   🔢 Version: 2.1.0
   ⏰ Timestamp: 2024-12-27T12:00:00Z
   🟢 Is Live: Yes
   ⚠️  Key "nonexistent" not found, using default: "N/A"
   ❓ Missing Key: N/A

2️⃣  Extracting Numeric Data...
   💰 HPX Price: $2.75 (raw: 275)
   ₿ BTC Price: $50,000 (raw: 5000000)
   💹 Daily Volume: $1,500,000,000
   ✅ Active Validators: 125
   🔴 Is Live: true (raw: 1)

3️⃣  Extracting Array Data...
   🪙 Assets: [HPX, BTC, ETH, USDC]
   ⚠️  Key "invalid.array" not found or invalid array, using default: [DEFAULT]
   ❌ Invalid Array: [DEFAULT]

4️⃣  Extracting Complex Nested Data...
   📈 Market Data:
      Prices: HPX=$2.75, BTC=$50000, ETH=$3000
      Volume: Daily=$1,500,000,000, Weekly=$8,500,000,000

5️⃣  Gas Usage Analysis...
   ⛽ Recommended Gas Limits:
      Simple extraction: 50,000 gas
      Nested extraction: 80,000 gas
      Complex processing: 120,000 gas

6️⃣  Performance & Error Testing...
   ✅ metadata object: "{"timestamp":"2024-12-27T12:00:00Z","source":"..." (15ms)
   ✅ market data: "{"prices":{"HPX":275,"BTC":5000000,"ETH":30000..." (12ms)
   ✅ assets array: "["HPX","BTC","ETH","USDC"]" (18ms)
   ⚠️  Key "nonexistent" not found, using default: ""
   ✅ missing key: "" (8ms)

🎉 === JSON Precompile Demo Completed Successfully! ===
```

## Advanced Usage Examples

### Oracle Price Feed Integration

```typescript
// Advanced oracle integration with comprehensive error handling
class PaxeerPriceOracle {
  private jsonPrecompile: ethers.Contract;

  constructor(jsonPrecompile: ethers.Contract) {
    this.jsonPrecompile = jsonPrecompile;
  }

  async parsePriceFeed(oracleResponse: any): Promise<{
    prices: Map<string, number>;
    timestamp: string;
    isValid: boolean;
  }> {
    try {
      // The precompile does not support dot notation for nested keys.
      // Extract the parent "metadata" object as bytes, then parse it manually.
      const metadataJson = await safeExtractBytes(this.jsonPrecompile, oracleResponse, 'metadata', '{}');
      const metadata = JSON.parse(metadataJson);
      const timestamp = metadata.timestamp ?? '';
      const isValid = metadata.isLive === 1;

      // Extract the parent "market" object the same way, then read its prices.
      const marketJson = await safeExtractBytes(this.jsonPrecompile, oracleResponse, 'market', '{}');
      const market = JSON.parse(marketJson);
      const rawPrices = market.prices ?? {};

      const prices = new Map<string, number>();
      const assets = await safeExtractBytesList(this.jsonPrecompile, oracleResponse, 'assets');

      for (const asset of assets) {
        // Convert from integer with 6 decimal places
        prices.set(asset, Number(rawPrices[asset] ?? 0) / 1000000);
      }

      return { prices, timestamp, isValid };
    } catch (error) {
      console.error('Failed to parse oracle response:', error);
      return {
        prices: new Map(),
        timestamp: '',
        isValid: false
      };
    }
  }
}
```

## Troubleshooting

### Common Issues and Solutions

#### Key Not Found

```typescript
// Comprehensive error handling for missing keys
async function handleMissingKeys(jsonPrecompile: ethers.Contract, data: any) {
  const keys = ['required.key', 'optional.key', 'deeply.nested.key'];

  for (const key of keys) {
    try {
      const result = await jsonPrecompile.extractAsBytes(ethers.toUtf8Bytes(JSON.stringify(data)), key);
      console.log(`✅ ${key}: ${ethers.toUtf8String(result)}`);
    } catch (error: any) {
      if (error.message.includes('key not found')) {
        console.log(`⚠️  Key "${key}" not found in JSON structure`);
      } else {
        console.log(`❌ Error extracting "${key}": ${error.message}`);
      }
    }
  }
}
```

### Error Code Reference

| Error | Cause | Solution |
| --- | --- | --- |
| `key not found` | Specified key doesn't exist in JSON | Verify key path and JSON structure |
| `invalid JSON format` | Malformed JSON input | Use `JSON.stringify()` to ensure valid format |
| `execution reverted` | Gas limit too low | Increase gas limit based on data complexity |
| `invalid integer` | Non-numeric value for `extractAsUint256` | Ensure the value is a valid integer |
| `out of gas` | Insufficient gas for large JSON | Use `calculateGasLimit()` for dynamic estimation |


## Key Considerations and Tricks

<Info>

- **Integers Only:** `extractAsUint256` only handles integers - no decimals, booleans, or negative numbers
- **Decimal Handling:** Store decimal numbers as integers with known precision (e.g., 275 for 2.75 with 2 decimal places)
- **Boolean Values:** Use 0/1 integers to represent false/true
- **Key Paths:** Extract parent objects first, then parse manually - dot notation may not be supported
- **Arrays:** Must use `extractAsBytesList()` for array data
- **Gas Costs:** Large JSON objects require higher gas limits
- **Encoding:** Always use UTF-8 encoding with `ethers.toUtf8Bytes()`
- **Error Handling:** Always implement fallback values for production applications

</Info>

<Info>**Need Help?** If you encounter issues not covered here, check the [Paxeer Discord](https://discord.gg/paxeer) or [GitHub repository](https://github.com/paxeer-network/paxeer-chain) for community support.</Info>

---

## Oracle Precompile Usage

*Query native exchange rates, TWAPs, and denomination data from EVM contracts using the Oracle precompile at address 0x404. Supports current and historical rates with delegate call access.*

**Address:** `0x0000000000000000000000000000000000001008`

<Danger>**Deprecation Notice:** The native Paxeer Oracle is deprecated and will be shut off soon. We strongly recommend migrating to one of the third-party oracle providers, such as [Chainlink](/evm), [Pyth](/evm), [Redstone](/evm), or [API3](/evm).</Danger>

---

## P256 Precompile

*Learn how to use the P256 precompile at address 0x1011 to verify secp256r1 signatures efficiently in Solidity smart contracts.*

**Address**: `0x0000000000000000000000000000000000001011`

This is the implementation of [RIP-7212](https://github.com/ethereum/RIPs/blob/master/RIPS/rip-7212.md), which provides a precompiled contract for verifying signatures in the `secp256r1` or `P-256` elliptic curve.

## Overview

The P256 precompile enables efficient signature verification for the `secp256r1` curve, which is widely used in modern security systems including:

- Apple's Secure Enclave
- WebAuthn/FIDO2
- Android Keychain
- Various hardware security modules (HSMs)
- PassKeys

This precompile implementation is significantly more gas efficient (up to 60x) compared to Solidity-based implementations.

## Interface

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

address constant P256VERIFY_PRECOMPILE_ADDRESS = 0x0000000000000000000000000000000000001011;

IP256VERIFY constant P256VERIFY_CONTRACT = IP256VERIFY(P256VERIFY_PRECOMPILE_ADDRESS);

interface IP256VERIFY {
    function verify(
        bytes memory signature
    ) external view returns (bytes memory response);
}
```

## Implementation Library

Here's a complete implementation of the P256 library that provides a convenient wrapper around the precompile:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.23;

import "./ECDSA.sol";
import "./P256Verify.sol";

/// @title P256
/// @author klkvr <https://github.com/klkvr>
/// @author jxom <https://github.com/jxom>
/// @notice Wrapper function to abstract low level details of call to the P256
///         signature verification precompile as defined in EIP-7212, see
///         <https://eips.ethereum.org/EIPS/eip-7212>.
library P256 {
    /// @notice P256VERIFY operation
    /// @param digest 32 bytes of the signed data hash
    /// @param signature Signature of the signer
    /// @param publicKey Public key of the signer
    /// @return success Represents if the operation was successful
    function verify(bytes32 digest, ECDSA.Signature memory signature, ECDSA.PublicKey memory publicKey)
        internal
        view
        returns (bool)
    {
        bytes memory input = abi.encode(digest, signature.r, signature.s, publicKey.x, publicKey.y);
        // On invalid signatures the precompile returns no data, which would
        // make a high-level interface call revert when decoding the `bytes`
        // return value. Use a low-level staticcall and treat empty return
        // data as "invalid signature" instead.
        (bool success, bytes memory output) = P256VERIFY_PRECOMPILE_ADDRESS.staticcall(
            abi.encodeWithSelector(IP256VERIFY.verify.selector, input)
        );

        return success && output.length > 0;
    }
}
```

## Basic Usage

### Using the P256 Library

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.23;

import "./P256.sol";
import "./ECDSA.sol";

contract P256Example {
    using P256 for bytes32;

    function verifySignature(
        bytes32 messageHash,
        ECDSA.Signature memory signature,
        ECDSA.PublicKey memory publicKey
    ) public view returns (bool) {
        return P256.verify(messageHash, signature, publicKey);
    }
}
```

### Direct Precompile Usage

For more control, you can call the precompile directly:

```solidity
pragma solidity ^0.8.0;

interface IP256Verify {
    function verify(bytes calldata input) external view returns (bytes memory response);
}

contract P256Verifier {
    IP256Verify constant P256_PRECOMPILE = IP256Verify(0x0000000000000000000000000000000000001011);

    function verifySignature(
        bytes32 messageHash,
        bytes32 r,
        bytes32 s,
        bytes32 publicKeyX,
        bytes32 publicKeyY
    ) external view returns (bool) {
        bytes memory input = abi.encodePacked(
            messageHash,
            r,
            s,
            publicKeyX,
            publicKeyY
        );

        // Success returns a non-empty (ABI-encoded 32-byte) value; invalid
        // signatures return no data, which would revert a high-level call.
        (bool ok, bytes memory output) = address(P256_PRECOMPILE).staticcall(
            abi.encodeWithSelector(IP256Verify.verify.selector, input)
        );
        return ok && output.length > 0;
    }
}
```

## Signature Format

The signature verification requires the following components:

- `digest`: 32 bytes of the signed data hash
- `signature`: Contains the r and s components of the signature
- `publicKey`: Contains the x and y coordinates of the public key

The precompile expects these components to be encoded in a specific format:

- First 32 bytes: message hash
- Next 32 bytes: `r` component of the signature
- Next 32 bytes: `s` component of the signature
- Next 32 bytes: `x` coordinate of the public key
- Next 32 bytes: `y` coordinate of the public key

Total length: 160 bytes

## Gas Costs

The precompile is highly gas efficient compared to Solidity implementations. The exact gas cost per byte of verified data is set to `GasCostPerByte = 300`, which gives us:

- **Total Cost**: 300 × 160 = **48,000 gas** per verification
- **Efficiency**: Up to 60x more efficient than pure Solidity implementations

## Real-World Use Cases

### WebAuthn/PassKeys Authentication

```solidity
pragma solidity ^0.8.0;

contract WebAuthnAuth {
    IP256Verify constant P256_PRECOMPILE = IP256Verify(0x0000000000000000000000000000000000001011);

    struct PublicKey {
        bytes32 x;
        bytes32 y;
    }

    mapping(address => PublicKey) public userKeys;

    function registerPasskey(
        bytes32 keyX,
        bytes32 keyY
    ) external {
        userKeys[msg.sender] = PublicKey(keyX, keyY);
    }

    function authenticateWithPasskey(
        bytes32 challengeHash,
        bytes32 r,
        bytes32 s
    ) external view returns (bool) {
        PublicKey memory userKey = userKeys[msg.sender];
        require(userKey.x != 0 && userKey.y != 0, "No passkey registered");

        bytes memory input = abi.encodePacked(
            challengeHash,
            r,
            s,
            userKey.x,
            userKey.y
        );

        (bool ok, bytes memory output) = address(P256_PRECOMPILE).staticcall(
            abi.encodeWithSelector(IP256Verify.verify.selector, input)
        );
        return ok && output.length > 0;
    }
}
```

### Apple Secure Enclave Integration

```solidity
contract SecureEnclaveAuth {
    IP256Verify constant P256_PRECOMPILE = IP256Verify(0x0000000000000000000000000000000000001011);

    event SecureOperation(address indexed user, bytes32 indexed operationHash);

    function executeSecureOperation(
        bytes32 operationHash,
        bytes32 r,
        bytes32 s,
        bytes32 enclaveKeyX,
        bytes32 enclaveKeyY
    ) external {
        require(
            verifyEnclaveSignature(operationHash, r, s, enclaveKeyX, enclaveKeyY),
            "Invalid Secure Enclave signature"
        );

        emit SecureOperation(msg.sender, operationHash);
    }

    function verifyEnclaveSignature(
        bytes32 hash,
        bytes32 r,
        bytes32 s,
        bytes32 x,
        bytes32 y
    ) internal view returns (bool) {
        bytes memory input = abi.encodePacked(hash, r, s, x, y);
        (bool ok, bytes memory output) = address(P256_PRECOMPILE).staticcall(
            abi.encodeWithSelector(IP256Verify.verify.selector, input)
        );
        return ok && output.length > 0;
    }
}
```

### Multi-Signature with Hardware Keys

```solidity
contract HardwareMultiSig {
    IP256Verify constant P256_PRECOMPILE = IP256Verify(0x0000000000000000000000000000000000001011);

    struct Signature {
        bytes32 r;
        bytes32 s;
    }

    struct PublicKey {
        bytes32 x;
        bytes32 y;
    }

    function verifyMultipleHardwareKeys(
        bytes32 messageHash,
        Signature[] calldata signatures,
        PublicKey[] calldata publicKeys,
        uint256 threshold
    ) external view returns (bool) {
        require(signatures.length == publicKeys.length, "Mismatched arrays");
        require(threshold <= signatures.length, "Invalid threshold");

        uint256 validSignatures = 0;

        for (uint i = 0; i < signatures.length; i++) {
            bytes memory input = abi.encodePacked(
                messageHash,
                signatures[i].r,
                signatures[i].s,
                publicKeys[i].x,
                publicKeys[i].y
            );

            (bool ok, bytes memory output) = address(P256_PRECOMPILE).staticcall(
                abi.encodeWithSelector(IP256Verify.verify.selector, input)
            );
            if (ok && output.length > 0) {
                validSignatures++;
            }
        }

        return validSignatures >= threshold;
    }
}
```

## Security Considerations

<Warning>**Important**: Always validate public keys and signature components before verification to prevent invalid curve point attacks.</Warning>

### Public Key Validation

```solidity
function isValidPublicKey(bytes32 x, bytes32 y) internal pure returns (bool) {
    // Ensure point is not at infinity
    if (x == 0 && y == 0) return false;

    // Additional validation should be performed for production use
    // The precompile will reject invalid curve points
    return true;
}
```

### Signature Malleability

P256 signatures can be malleable. If your application requires unique signatures, implement additional checks:

```solidity
function isLowS(bytes32 s) internal pure returns (bool) {
    // Check if s is in the lower half of the curve order (n / 2, where n is
    // the P-256 group order). This prevents signature malleability.
    return uint256(s) <= 0x7FFFFFFF800000007FFFFFFFFFFFFFFFDE737D56D38BCF4279DCE5617E3192A8;
}
```

## JavaScript Integration

### Preparing Input Data

```javascript
// Example: Preparing P256 verification input (ethers v6)
function prepareP256Input(messageHash, signature, publicKey) {
  // Ensure all components are 32 bytes
  const hash = ethers.zeroPadValue(messageHash, 32);
  const r = ethers.zeroPadValue(signature.r, 32);
  const s = ethers.zeroPadValue(signature.s, 32);
  const x = ethers.zeroPadValue(publicKey.x, 32);
  const y = ethers.zeroPadValue(publicKey.y, 32);

  // Concatenate all components
  return ethers.concat([hash, r, s, x, y]);
}

// Usage with ethers.js
const P256_VERIFY_ADDRESS = '0x0000000000000000000000000000000000001011';
const P256_VERIFY_ABI = ['function verify(bytes input) view returns (bytes response)'];

async function verifyP256Signature(provider, messageHash, signature, publicKey) {
  const precompile = new ethers.Contract(P256_VERIFY_ADDRESS, P256_VERIFY_ABI, provider);
  const input = prepareP256Input(messageHash, signature, publicKey);
  try {
    const result = await precompile.verify(input);
    // Success returns 32 bytes ending in 0x01
    return result === '0x0000000000000000000000000000000000000000000000000000000000000001';
  } catch (err) {
    // Invalid signatures return no data, which ethers cannot decode as `bytes`
    // (BAD_DATA) - treat that as a failed verification.
    return false;
  }
}
```

## Error Handling

The P256 precompile returns no data on failure. Because `verify` is declared as returning `bytes`, a high-level Solidity interface call reverts when it tries to decode that empty return data - always use a low-level `staticcall` (as in the examples above) so invalid signatures resolve to `false` instead of reverting. Common failure cases include:

1. **Invalid Input Length**: Input must be exactly 160 bytes
2. **Invalid Public Key**: Point not on the P256 curve
3. **Invalid Signature**: r or s values out of valid range
4. **Verification Failure**: Signature doesn't match message and public key

```solidity
function safeVerifyP256(
    bytes32 messageHash,
    bytes32 r,
    bytes32 s,
    bytes32 publicKeyX,
    bytes32 publicKeyY
) internal view returns (bool success, string memory error) {
    // Validate inputs
    if (!isValidPublicKey(publicKeyX, publicKeyY)) {
        return (false, "Invalid public key");
    }

    if (r == 0 || s == 0) {
        return (false, "Invalid signature components");
    }

    // Prepare input and verify
    bytes memory input = abi.encodePacked(
        messageHash, r, s, publicKeyX, publicKeyY
    );

    (bool ok, bytes memory output) = address(P256_PRECOMPILE).staticcall(
        abi.encodeWithSelector(IP256Verify.verify.selector, input)
    );
    bool verified = ok && output.length > 0;
    return (verified, verified ? "" : "Verification failed");
}
```

## Testing

### Unit Tests

```solidity
contract P256Test {
    IP256Verify constant P256_PRECOMPILE = IP256Verify(0x0000000000000000000000000000000000001011);

    function testValidSignature() public {
        // Test with known valid P256 signature
        bytes32 messageHash = 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef;
        // Use actual test vectors for production tests
        bytes32 r = 0x...; // Valid r component
        bytes32 s = 0x...; // Valid s component
        bytes32 x = 0x...; // Valid public key x
        bytes32 y = 0x...; // Valid public key y

        bytes memory input = abi.encodePacked(messageHash, r, s, x, y);
        (bool ok, bytes memory output) = address(P256_PRECOMPILE).staticcall(
            abi.encodeWithSelector(IP256Verify.verify.selector, input)
        );

        assert(ok && output.length > 0);
    }
}
```

## Performance Considerations

- **Gas Efficiency**: 48,000 gas per verification vs 2M+ gas for Solidity implementations
- **Batch Operations**: Consider batching multiple verifications in a single transaction
- **Caching**: Cache public keys on-chain to reduce calldata for repeated verifications
- **Hardware Integration**: Particularly efficient for applications using hardware-backed keys

<Info>For more information about the P256 precompile implementation, visit the [Paxeer Chain repository](https://github.com/paxeer-network/paxeer-chain/tree/main/precompiles/p256).</Info>

---

## Staking Precompile

*Learn how Paxeer's Staking Precompile at 0x...1005 lets EVM dApps delegate, undelegate, redelegate, and manage validators natively.*

**Address:** `0x0000000000000000000000000000000000001005`

The Paxeer staking precompile allows EVM applications to interact directly with Paxeer's native staking module through standard smart contract calls. This enables delegation, undelegation, redelegation, validator management, and staking queries directly from your dApps without needing separate Cosmos SDK integration.

<Info> **What is a precompile?** A precompile is a special smart contract deployed at a fixed address by the Paxeer protocol itself, that exposes custom native chain logic to EVM-based applications. It acts like a regular contract from the EVM's perspective, but executes privileged, low-level logic efficiently. </Info>

## How Does the Staking Precompile Work?

The staking precompile at address `0x0000000000000000000000000000000000001005` exposes a comprehensive set of staking functions including `delegate()`, `undelegate()`, `redelegate()`, `createValidator()`, `editValidator()`, and various query functions like `validators()`, `delegatorDelegations()`, `pool()`, and `params()`.

- **Direct Integration:** EVM contracts and dApps can call staking functions like any other smart contract method.
- **Native Execution:** Operations are executed at the Cosmos SDK level for maximum efficiency and security.
- **Seamless Bridge:** No need for separate wallet integrations or complex cross-chain interactions.
- **Event Emission:** All staking operations emit events (`Delegate`, `Undelegate`, `Redelegate`, `ValidatorCreated`, `ValidatorEdited`) for easy tracking and indexing.

## Use Cases

- **DeFi Integration:** Build liquid staking protocols and yield farming strategies.
- **Delegation Services:** Create user-friendly interfaces for staking operations.
- **Portfolio Management:** Automate staking strategies and delegation rebalancing.
- **Validator Management:** Create and manage validators programmatically.

## What You'll Learn in This Guide

By the end of this guide, you'll be able to:

- **Integrate Staking Operations** - Call delegation, undelegation, and redelegation functions directly from your EVM contracts and dApps
- **Handle Decimal Precision** - Master the critical precision patterns for different operations to avoid common formatting errors
- **Create and Manage Validators** - Create new validators and edit their parameters programmatically
- **Query Staking State** - Use the comprehensive query functions to fetch validators, delegations, unbonding info, pool statistics, and staking parameters
- **Listen for Staking Events** - Track staking operations using emitted events for indexing and notifications
- **Build Portfolio Tools** - Implement automated rebalancing and delegation tracking for staking management applications
- **Navigate Staking Risks** - Understand unbonding periods, slashing mechanics, and validator selection for safe staking operations

## Events

The staking precompile emits the following events:

```solidity
/**
 * @notice Emitted when tokens are delegated to a validator
 * @param delegator The address of the delegator
 * @param validator The validator address
 * @param amount The amount delegated in base units
 */
event Delegate(address indexed delegator, string validator, uint256 amount);

/**
 * @notice Emitted when tokens are redelegated from one validator to another
 * @param delegator The address of the delegator
 * @param srcValidator The source validator address
 * @param dstValidator The destination validator address
 * @param amount The amount redelegated in base units
 */
event Redelegate(
    address indexed delegator,
    string srcValidator,
    string dstValidator,
    uint256 amount
);

/**
 * @notice Emitted when tokens are undelegated from a validator
 * @param delegator The address of the delegator
 * @param validator The validator address
 * @param amount The amount undelegated in base units
 */
event Undelegate(
    address indexed delegator,
    string validator,
    uint256 amount
);

/**
 * @notice Emitted when a new validator is created
 * @param creator The address of the validator creator
 * @param validatorAddress The validator address
 * @param moniker The validator moniker
 */
event ValidatorCreated(
    address indexed creator,
    string validatorAddress,
    string moniker
);

/**
 * @notice Emitted when a validator is edited
 * @param editor The address of the validator editor
 * @param validatorAddress The validator address
 * @param moniker The new validator moniker
 */
event ValidatorEdited(
    address indexed editor,
    string validatorAddress,
    string moniker
);
```

### Listening for Events

You can listen for these events in your dApp to track staking operations:

```typescript
// Listen for delegation events
staking.on('Delegate', (delegator, validator, amount) => {
  console.log(`${delegator} delegated ${amount} to ${validator}`);
});

// Listen for redelegation events
staking.on('Redelegate', (delegator, srcValidator, dstValidator, amount) => {
  console.log(`${delegator} redelegated ${amount} from ${srcValidator} to ${dstValidator}`);
});

// Listen for undelegation events
staking.on('Undelegate', (delegator, validator, amount) => {
  console.log(`${delegator} undelegated ${amount} from ${validator}`);
});

// Listen for validator creation events
staking.on('ValidatorCreated', (creator, validatorAddress, moniker) => {
  console.log(`New validator ${moniker} created at ${validatorAddress} by ${creator}`);
});

// Listen for validator edit events
staking.on('ValidatorEdited', (editor, validatorAddress, moniker) => {
  console.log(`Validator ${validatorAddress} edited by ${editor}, new moniker: ${moniker}`);
});
```

## Functions

The staking precompile exposes the following functions:

### Transaction Functions

```solidity
/// Delegates Paxeer to the specified validator.
/// @dev This function truncates msg.value to 6 decimal places for interaction with the staking module
/// @param valAddress The Paxeer address of the validator.
/// @return Whether the delegation was successful.
function delegate(
    string memory valAddress
) payable external returns (bool success);

/// Redelegates Paxeer from one validator to another.
/// @dev The amount should be in 6 decimal precision, not 18. 1 HPX = 1_000_000 uhpx
/// @param srcAddress The Paxeer address of the validator to move delegations from.
/// @param dstAddress The Paxeer address of the validator to move delegations to.
/// @param amount The amount of Paxeer to move from srcAddress to dstAddress.
/// @return Whether the redelegation was successful.
function redelegate(
    string memory srcAddress,
    string memory dstAddress,
    uint256 amount
) external returns (bool success);

/// Undelegates Paxeer from the specified validator.
/// @dev The amount should be in 6 decimal precision, not 18. 1 HPX = 1_000_000 uhpx
/// @param valAddress The Paxeer address of the validator to undelegate from.
/// @param amount The amount of Paxeer to undelegate.
/// @return Whether the undelegation was successful.
function undelegate(
    string memory valAddress,
    uint256 amount
) external returns (bool success);

/// Create a new validator. Delegation amount must be provided as value in wei.
/// @param pubKeyHex Ed25519 public key in hex format (64 characters)
/// @param moniker Validator display name
/// @param commissionRate Initial commission rate (e.g. "0.05" for 5%)
/// @param commissionMaxRate Maximum commission rate (e.g. "0.20" for 20%)
/// @param commissionMaxChangeRate Maximum commission change rate per day (e.g. "0.01" for 1%)
/// @param minSelfDelegation Minimum self-delegation amount in base units
/// @return success True if validator creation was successful
function createValidator(
    string memory pubKeyHex,
    string memory moniker,
    string memory commissionRate,
    string memory commissionMaxRate,
    string memory commissionMaxChangeRate,
    uint256 minSelfDelegation
) external payable returns (bool success);

/// Edit an existing validator's parameters
/// @param moniker New validator display name
/// @param commissionRate New commission rate (e.g. "0.10" for 10%)
///                      Pass empty string "" to not change commission rate
///                      Note: Commission can only be changed once per 24 hours
/// @param minSelfDelegation New minimum self-delegation amount
///                         Pass 0 to not change minimum self-delegation
///                         Note: Can only increase, cannot decrease below current value
/// @return success True if validator edit was successful
function editValidator(
    string memory moniker,
    string memory commissionRate,
    uint256 minSelfDelegation
) external returns (bool success);
```

### Query Functions

```solidity
struct Delegation {
    Balance balance;
    DelegationDetails delegation;
}

struct Balance {
    uint256 amount;  // Staked balance in uhpx (6 decimals)
    string denom;    // Token denomination (e.g., "uhpx")
}

struct DelegationDetails {
    string delegator_address;
    uint256 shares;    // Delegation shares (18 decimal precision)
    uint256 decimals;  // Precision for shares field (always 18)
    string validator_address;
}

struct Validator {
    string operatorAddress;      // Validator's operator address (paxvaloper...)
    string consensusPubkey;      // Consensus public key
    bool jailed;                 // Whether the validator is jailed
    int32 status;                // Bonding status (1=Unbonded, 2=Unbonding, 3=Bonded)
    string tokens;               // Total tokens delegated
    string delegatorShares;      // Total delegator shares
    string description;          // Validator description/metadata
    int64 unbondingHeight;       // Height at which unbonding started
    int64 unbondingTime;         // Time at which unbonding completes
    string commissionRate;       // Current commission rate
    string commissionMaxRate;    // Maximum commission rate
    string commissionMaxChangeRate; // Maximum daily commission change rate
    int64 commissionUpdateTime;  // Last commission update timestamp
    string minSelfDelegation;    // Minimum self-delegation requirement
}

struct ValidatorsResponse {
    Validator[] validators;      // Array of validators
    bytes nextKey;               // Pagination key for next page
}

struct DelegationsResponse {
    Delegation[] delegations;    // Array of delegations
    bytes nextKey;               // Pagination key for next page
}

struct UnbondingDelegationEntry {
    int64 creationHeight;        // Height when unbonding was initiated
    int64 completionTime;        // Timestamp when unbonding completes
    string initialBalance;       // Initial unbonding balance
    string balance;              // Current unbonding balance
}

struct UnbondingDelegation {
    string delegatorAddress;     // Delegator's address
    string validatorAddress;     // Validator's address
    UnbondingDelegationEntry[] entries; // Unbonding entries
}

struct UnbondingDelegationsResponse {
    UnbondingDelegation[] unbondingDelegations; // Array of unbonding delegations
    bytes nextKey;               // Pagination key for next page
}

struct RedelegationEntry {
    int64 creationHeight;        // Height when redelegation was initiated
    int64 completionTime;        // Timestamp when redelegation completes
    string initialBalance;       // Initial redelegation balance
    string sharesDst;            // Shares at destination validator
}

struct Redelegation {
    string delegatorAddress;     // Delegator's address
    string validatorSrcAddress;  // Source validator address
    string validatorDstAddress;  // Destination validator address
    RedelegationEntry[] entries; // Redelegation entries
}

struct RedelegationsResponse {
    Redelegation[] redelegations; // Array of redelegations
    bytes nextKey;               // Pagination key for next page
}

struct HistoricalInfo {
    int64 height;                // Block height
    Validator[] validators;      // Validators at that height
}

struct Pool {
    string notBondedTokens;      // Total tokens not bonded
    string bondedTokens;         // Total tokens bonded
}

struct Params {
    uint64 unbondingTime;        // Unbonding duration in seconds
    uint32 maxValidators;        // Maximum number of validators
    uint32 maxEntries;           // Max unbonding/redelegation entries
    uint32 historicalEntries;    // Number of historical entries to keep
    string bondDenom;            // Bond token denomination
    string minCommissionRate;    // Minimum commission rate
    string maxVotingPowerRatio;  // Maximum voting power ratio
    string maxVotingPowerEnforcementThreshold; // Enforcement threshold
}

/// Queries delegation for a given delegator and validator address.
/// @param delegator The address of the delegator.
/// @param valAddress The Paxeer address of the validator.
/// @return The delegation information.
/// @dev balance.amount is in uhpx (6 decimals). To calculate HPX: amount / 1e6
/// @dev shares uses 18 decimal precision. To calculate actual shares: shares / 1e18
function delegation(
    address delegator,
    string memory valAddress
) external view returns (Delegation delegation);

/// Get list of validators with optional status filter
/// @param status Filter by validator status ("BOND_STATUS_BONDED", "BOND_STATUS_UNBONDING", "BOND_STATUS_UNBONDED", or "" for all)
/// @param nextKey Pagination key (use empty bytes for first page)
/// @return response List of validators with pagination info
function validators(
    string memory status,
    bytes memory nextKey
) external view returns (ValidatorsResponse memory response);

/// Get validator information for a given validator address
/// @param validatorAddress The validator address
/// @return validator Validator details
function validator(
    string memory validatorAddress
) external view returns (Validator memory validator);

/// Get delegations for a specific validator
/// @param validatorAddress The validator address
/// @param nextKey Pagination key
/// @return response Delegations response with pagination
function validatorDelegations(
    string memory validatorAddress,
    bytes memory nextKey
) external view returns (DelegationsResponse memory response);

/// Get unbonding delegations for a specific validator
/// @param validatorAddress The validator address
/// @param nextKey Pagination key
/// @return response Unbonding delegations response with pagination
function validatorUnbondingDelegations(
    string memory validatorAddress,
    bytes memory nextKey
) external view returns (UnbondingDelegationsResponse memory response);

/// Get unbonding delegation information for a delegator and validator pair
/// @param delegator The delegator's address
/// @param validatorAddress The validator address
/// @return unbondingDelegation Unbonding delegation details
function unbondingDelegation(
    address delegator,
    string memory validatorAddress
) external view returns (UnbondingDelegation memory unbondingDelegation);

/// Get all delegations for a delegator
/// @param delegator The delegator's address
/// @param nextKey Pagination key
/// @return response Delegations response with pagination
function delegatorDelegations(
    address delegator,
    bytes memory nextKey
) external view returns (DelegationsResponse memory response);

/// Get validator information for a delegator and validator pair
/// @param delegator The delegator's address
/// @param validatorAddress The validator address
/// @return validator Validator details
function delegatorValidator(
    address delegator,
    string memory validatorAddress
) external view returns (Validator memory validator);

/// Get all unbonding delegations for a delegator
/// @param delegator The delegator's address
/// @param nextKey Pagination key
/// @return response Unbonding delegations response with pagination
function delegatorUnbondingDelegations(
    address delegator,
    bytes memory nextKey
) external view returns (UnbondingDelegationsResponse memory response);

/// Get redelegations with optional filters
/// @param delegator The delegator's address (empty string for all)
/// @param srcValidator The source validator address (empty string for all)
/// @param dstValidator The destination validator address (empty string for all)
/// @param nextKey Pagination key
/// @return response Redelegations response with pagination
function redelegations(
    string memory delegator,
    string memory srcValidator,
    string memory dstValidator,
    bytes memory nextKey
) external view returns (RedelegationsResponse memory response);

/// Get all validators that a delegator has delegated to
/// @param delegator The delegator's address
/// @param nextKey Pagination key
/// @return response Validators response with pagination
function delegatorValidators(
    address delegator,
    bytes memory nextKey
) external view returns (ValidatorsResponse memory response);

/// Get historical info for a given height
/// @param height The block height
/// @return historicalInfo Historical validator set info
function historicalInfo(
    int64 height
) external view returns (HistoricalInfo memory historicalInfo);

/// Get staking pool information (bonded and unbonded token totals)
/// @return pool Pool details
function pool() external view returns (Pool memory pool);

/// Get staking module parameters
/// @return params Staking parameters
function params() external view returns (Params memory params);
```

<Warning>

**Important Precision Note for `delegation()` Response:**

The response contains two different precision scales:

- `balance.amount`: **6 decimals** (uhpx) - the actual staked token amount
- `delegation.shares`: **18 decimals** - the validator pool share amount
- `delegation.decimals`: Always returns **18** (refers to shares precision, NOT balance)

To convert to HPX for display:

- Balance: `balance.amount / 1e6`
- Shares: `delegation.shares / 1e18`

</Warning>

## Using the Precompile

### Setup

#### Prerequisites

Before getting started, ensure you have:

- **Node.js** (v18 or higher)
- **npm** or **yarn** package manager
- **EVM-compatible wallet**
- **HPX tokens** for gas and staking operations

#### Install Dependencies

Install the required packages for interacting with Paxeer precompiles:

```bash
# Install ethers.js for smart contract interactions
npm install ethers

# Install Paxeer EVM bindings for precompile addresses and ABIs
npm install @sei-js/precompiles@2.1.2
```

#### Import Precompile Components

```typescript
// Import Staking precompile address and ABI
// View the entire ABI here: https://github.com/paxeer-network/paxeer-chain/tree/main/precompiles/staking
import { STAKING_PRECOMPILE_ABI, STAKING_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';
import { ethers } from 'ethers';
```

<Info> **Precompile Address:** The staking precompile is deployed at `0x0000000000000000000000000000000000001005` </Info>

### Contract Initialization

Set up your provider, signer, and contract instance:

```typescript
// Using EVM-compatible wallet as the signer and provider
const provider = new ethers.BrowserProvider(window.ethereum);
await provider.send('eth_requestAccounts', []);
const signer = await provider.getSigner();

// Create a contract instance for the staking precompile
const staking = new ethers.Contract(STAKING_PRECOMPILE_ADDRESS, STAKING_PRECOMPILE_ABI, signer);
```

## Critical: Understanding Decimal Precision

One of the most important concepts to understand when working with the Paxeer staking precompile:

### Mixed Decimal Precision System

The staking precompile operates with **different decimal precision for different operations** due to bridging EVM and Cosmos standards:

| Function | Input/Output | Decimal Precision | Example |
| --- | --- | --- | --- |
| **delegate()** | msg.value (input) | 18 decimals (wei) | `ethers.parseUnits('1', 18)` |
| **undelegate()** | amount (input) | 6 decimals (uhpx) | `1000000` (represents 1 HPX) |
| **redelegate()** | amount (input) | 6 decimals (uhpx) | `500000` (represents 0.5 HPX) |
| **createValidator()** | msg.value (input) | 18 decimals (wei) | `ethers.parseUnits('1000', 18)` |
| **delegation()** | return values (output) | Mixed (balance 6, shares 18) | `balance.amount=1000000`, `shares=1000000000000000000` |


<Warning>

**Granularity for delegate():**

`msg.value` is truncated to 6 decimals (uhpx). Always send amounts that are a multiple of `1e12` wei (last 12 digits zero) to avoid unintended truncation.

- OK: `1_000_000_000_000` wei (`0.000001000000` HPX)
- NOT OK: `1_000_000_000_001` wei (`0.000001000000000001` HPX)
- NOT OK: `1_000_000_330_000` wei (`0.000001000000330000` HPX)

Examples:

- Delegate 10 HPX → `10000000000000000000` wei (18 decimals)
- Undelegate 10 HPX → `10000000` uhpx (6 decimals)

</Warning>

### How This Works in Practice

**delegate() Function (Uses 18 decimals):**

- `delegate()` - accepts `msg.value` in wei (18 decimals)

**undelegate() and redelegate() Functions (Use 6 decimals):**

- `undelegate()` - expects amount parameter in 6 decimals (uhpx)
- `redelegate()` - expects amount parameter in 6 decimals (uhpx)

**Reading/Query Operations (Return 6 decimals):**

- `delegation()` - returns `balance.amount` in 6-decimal `uhpx` and `delegation.shares` in 18-decimal precision
- Rewards are handled by the **Distribution precompile**: `rewards()` query returns 18-decimal `DecCoins`, while withdrawn amounts (events) are 6-decimal `uhpx`

### Why This Mixed System Exists

1. **delegate() EVM Compatibility:** Uses standard 18-decimal wei format for EVM `msg.value` consistency
2. **Other Operations Cosmos Integration:** `undelegate()` and `redelegate()` use 6-decimal uhpx precision to match native Cosmos operations
3. **Staking Query Consistency:** Staking precompile query balances use 6-decimal `uhpx` (while `shares` is 18-decimal) for consistent reading

### Best Practice: Different Conversion for Different Functions

When working with user inputs, use the appropriate conversion for each function:

```typescript
// Best practice for handling user input amounts
function prepareAmountForDelegate(paxAmount: number): bigint {
  // For delegate() - convert to 18 decimals (wei)
  const fixedAmount = paxAmount.toFixed(6);
  return ethers.parseUnits(fixedAmount, 18);
}

function prepareAmountForUndelegateRedelegate(paxAmount: number): bigint {
  // For undelegate() and redelegate() - convert to 6 decimals (uhpx)
  return ethers.parseUnits(paxAmount.toFixed(6), 6);
}

// Usage examples
const userInputAmount = 1.23456789; // User enters this

// For delegate()
const delegateAmount = prepareAmountForDelegate(userInputAmount); // 18 decimals

// For undelegate() and redelegate()
const undelegateAmount = prepareAmountForUndelegateRedelegate(userInputAmount); // 6 decimals
```

### Normalization Guidelines (Clients and Indexers)

- **Normalize to a single unit** for analytics and reconciliation:
  - Display: convert to `HPX` (`wei / 1e18`, `uhpx / 1e6`)
  - Storage/aggregation: prefer `uhpx` (6 decimals)
- **Reconciling delegate vs. undelegate/redelegate/rewards:** convert delegate `msg.value` from wei to uhpx using integer division by `1e12` (floor), which matches the precompile’s internal truncation.
- **Enforce granularity at source:** construct `msg.value` as a multiple of `1e12` wei by formatting user input to 6 decimals prior to `parseUnits`.

```typescript
// Convert delegate msg.value (wei) to uhpx (6 decimals) for reconciliation
function weiToUhpxForDelegate(valueWei: bigint): bigint {
  return valueWei / 1_000_000_000_000n; // floor to 6-decimal granularity
}

// Convert uhpx to HPX for display
function uhpxToPaxString(amountUhpx: bigint): string {
  return ethers.formatUnits(amountUhpx, 6);
}

// Ensure msg.value is a multiple of 1e12 wei (last 12 digits zero)
function normalizeWeiForDelegate(valueWei: bigint): bigint {
  return (valueWei / 1_000_000_000_000n) * 1_000_000_000_000n;
}
```

## Decimal Conversion Helpers

Use these helper functions to avoid precision errors:

```typescript
// Helper functions for amount conversion
class PaxeerAmountConverter {
  // Convert HPX to wei (18 decimals) - ONLY for delegate()
  static paxToWei(paxAmount: number): bigint {
    return ethers.parseUnits(paxAmount.toFixed(6), 18);
  }

  // Convert HPX to uhpx (6 decimals) - for undelegate() and redelegate()
  static paxToUhpx(paxAmount: number): bigint {
    return ethers.parseUnits(paxAmount.toFixed(6), 6);
  }

  // Convert reading results (6 decimals) to HPX
  static uhpxToPax(upaxAmount: number | bigint): number {
    return Number(upaxAmount) / 1000000;
  }

  // Convert wei to HPX (18 decimals) - for delegate operations
  static weiToPax(weiAmount: bigint): number {
    return Number(ethers.formatEther(weiAmount));
  }
}

// Usage examples - Use correct decimals for each function
const delegateAmount = PaxeerAmountConverter.paxToWei(1); // For delegate() - 18 decimals
const undelegateAmount = PaxeerAmountConverter.paxToUhpx(0.5); // For undelegate() - 6 decimals
const redelegateAmount = PaxeerAmountConverter.paxToUhpx(2); // For redelegate() - 6 decimals
```

## Step-by-Step Guide: Using the Staking Precompile

### Delegate Tokens

<Tabs>
<Tab title="JavaScript">

```typescript
// Paxeer validator address you want to delegate to (paxvaloper... format)
const validatorAddress = 'paxvaloper1xyz...';

const amount = 1; // Amount in HPX to delegate

const amountTrimmed = amount.toFixed(6); // Ensure 6 decimal precision for msg.value

// Delegate 1 HPX - Uses 18 decimals for msg.value
const amountToDelegate = ethers.parseUnits(amountTrimmed, 18);

const tx = await staking.delegate(validatorAddress, { value: amountToDelegate });

const receipt = await tx.wait();
console.log('Delegation completed:', receipt);
```

</Tab>
<Tab title="Solidity">
```typescript
function delegateToValidator(string memory validatorAddress) external payable {
        require(msg.value > 0, "Amount must be greater than 0");
        
        bool success = ISTAKING(0x0000000000000000000000000000000000001005).delegate{value: msg.value}(validatorAddress);
        require(success, "Delegation failed");
        
        emit Delegated(msg.sender, validatorAddress, msg.value);
    }
```
</Tab>

</Tabs>

### Undelegate Tokens

<Tabs>
<Tab title="JavaScript">

```typescript
// Undelegate 1 HPX from a validator - Uses 6 decimals for amount parameter
const validatorAddress = 'paxvaloper1xyz...';

const amount = 1; // Amount in HPX to undelegate
const amountTrimmed = amount.toFixed(6); // Ensure 6 decimal precision
const amountToUndelegate = ethers.parseUnits(amountTrimmed, 6); // 1 HPX in 6 decimals

const tx = await staking.undelegate(validatorAddress, amountToUndelegate);
const receipt = await tx.wait();

console.log('Undelegation started:', receipt);
```

</Tab>
<Tab title="Solidity">
```typescript
function undelegateFromValidator(
        string memory validatorAddress, 
        uint256 amount
    ) external {
        require(amount > 0, "Amount must be greater than 0");
        
        bool success = ISTAKING(0x0000000000000000000000000000000000001005).undelegate(validatorAddress, amount);
        require(success, "Undelegation failed");
        
        emit Undelegated(msg.sender, validatorAddress, amount);
    }
    
```
</Tab>

</Tabs>

<Warning> **IMPORTANT:** Undelegated tokens are subject to a **21-day unbonding period** during which they cannot be transferred and do not earn rewards. </Warning>

### Redelegate Tokens

<Tabs>
<Tab title="JavaScript">

```typescript
// Redelegate 0.5 HPX from one validator to another - Uses 6 decimals for amount parameter
const srcValidator = 'paxvaloper1abc...';
const dstValidator = 'paxvaloper1xyz...';

const amount = 0.5; // Amount in HPX to redelegate
const amountTrimmed = amount.toFixed(6); // Ensure 6 decimal precision
const amountToRedelegate = ethers.parseUnits(amountTrimmed, 6); // 0.5 HPX in 6 decimals

const tx = await staking.redelegate(srcValidator, dstValidator, amountToRedelegate);
const receipt = await tx.wait();

console.log('Redelegation completed:', receipt);
```

</Tab>
<Tab title="Solidity">
```typescript
function redelegateBetweenValidators(
        string memory fromValidator,
        string memory toValidator,
        uint256 amount
    ) external {
        require(amount > 0, "Amount must be greater than 0");
        
        bool success = ISTAKING(0x0000000000000000000000000000000000001005).redelegate(fromValidator, toValidator, amount);
        require(success, "Redelegation failed");
        
        emit Redelegated(msg.sender, fromValidator, toValidator, amount);
    }
```
</Tab>

</Tabs>

<Warning> 
**Redelegation restrictions:**

- Maximum 7 redelegations per validator pair per 21-day period

- After redelegating from Validator A to Validator B, you cannot redelegate from Validator B to another validator for 21 days

- Each redelegation has its own 21-day cooldown period

</Warning>

### Query a Delegation

<Tabs>
<Tab title="JavaScript">

```typescript
// Get your EVM address as the delegator
const delegator = await signer.getAddress();

try {
  const delegationInfo = await staking.delegation(delegator, validatorAddress);

  console.log('Delegation details:', {
    amount: delegationInfo.balance.amount.toString(),
    denom: delegationInfo.balance.denom,
    shares: delegationInfo.delegation.shares.toString(),
    decimals: delegationInfo.delegation.decimals.toString(),
    delegator_address: delegationInfo.delegation.delegator_address,
    validator_address: delegationInfo.delegation.validator_address
  });

  // Convert delegation amount from uhpx to HPX for readable display
  const delegationAmountPax = ethers.formatUnits(delegationInfo.balance.amount, 6);
  console.log('Delegation amount (HPX):', delegationAmountPax);
} catch (error) {
  if (error.message.includes('delegation not found') || error.message.includes('no delegation')) {
    console.log('No delegation found for this validator');
  } else {
    console.error('Error querying delegation:', error);
  }
}
```

</Tab>
<Tab title="Solidity">
```typescript
function getDelegationInfo(
        address delegator,
        string memory validatorAddress
    ) external view returns (IStakingPrecompile.Delegation memory) {
        return ISTAKING(0x0000000000000000000000000000000000001005).delegation(delegator, validatorAddress);
    }
```
</Tab>

</Tabs>

### Create a Validator

<Warning> Creating a validator requires significant HPX for self-delegation and proper validator infrastructure setup. Only proceed if you understand the responsibilities of running a validator node. </Warning>

<Tabs>
<Tab title="JavaScript">

```typescript
// Ed25519 public key in hex format (64 characters)
// This comes from your validator node's priv_validator_key.json
const pubKeyHex = 'your_ed25519_public_key_hex_64_chars';
const moniker = 'MyValidator';

// Commission rates as decimal strings
const commissionRate = '0.05'; // 5% commission
const commissionMaxRate = '0.20'; // Maximum 20% commission
const commissionMaxChangeRate = '0.01'; // Can change by 1% per day max

// Minimum self-delegation in base units (uhpx)
const minSelfDelegation = BigInt(1000000); // 1 HPX minimum

// Initial self-delegation amount in wei (18 decimals)
const selfDelegationAmount = ethers.parseUnits('1000', 18); // 1000 HPX

const tx = await staking.createValidator(pubKeyHex, moniker, commissionRate, commissionMaxRate, commissionMaxChangeRate, minSelfDelegation, { value: selfDelegationAmount });

const receipt = await tx.wait();
console.log('Validator created:', receipt);
```

</Tab>
<Tab title="Solidity">

```solidity
function createNewValidator(
    string memory pubKeyHex,
    string memory moniker,
    string memory commissionRate,
    string memory commissionMaxRate,
    string memory commissionMaxChangeRate,
    uint256 minSelfDelegation
) external payable {
    require(msg.value > 0, "Self-delegation required");

    bool success = STAKING.createValidator{value: msg.value}(
        pubKeyHex,
        moniker,
        commissionRate,
        commissionMaxRate,
        commissionMaxChangeRate,
        minSelfDelegation
    );
    require(success, "Validator creation failed");
}
```

</Tab>
</Tabs>

### Edit a Validator

```typescript
// Update validator parameters
const newMoniker = 'MyUpdatedValidator';
const newCommissionRate = '0.08'; // 8% commission (or "" to keep current)
const newMinSelfDelegation = BigInt(2000000); // 2 HPX (or 0 to keep current)

const tx = await staking.editValidator(newMoniker, newCommissionRate, newMinSelfDelegation);

const receipt = await tx.wait();
console.log('Validator updated:', receipt);
```

<Info>**Edit Validator Constraints:** - Commission can only be changed once every 24 hours - `minSelfDelegation` can only be increased, never decreased - Pass empty string `""` for `commissionRate` to keep current rate - Pass `0` for `minSelfDelegation` to keep current value</Info>

### Query Validators

```typescript
// Get all bonded validators
const bondedValidators = await staking.validators('BOND_STATUS_BONDED', '0x');
console.log('Bonded validators:', bondedValidators.validators);

// Get all validators (no filter)
const allValidators = await staking.validators('', '0x');
console.log('Total validators:', allValidators.validators.length);

// Pagination - get next page if available
if (allValidators.nextKey.length > 0) {
  const nextPage = await staking.validators('', allValidators.nextKey);
  console.log('Next page validators:', nextPage.validators);
}
```

### Query a Specific Validator

```typescript
const validatorAddress = 'paxvaloper1xyz...';
const validatorInfo = await staking.validator(validatorAddress);

console.log('Validator details:', {
  moniker: validatorInfo.description,
  tokens: validatorInfo.tokens,
  commission: validatorInfo.commissionRate,
  jailed: validatorInfo.jailed,
  status: validatorInfo.status // 1=Unbonded, 2=Unbonding, 3=Bonded
});
```

### Query All Delegations for an Address

```typescript
const delegator = await signer.getAddress();

// Get all delegations for the connected wallet
const myDelegations = await staking.delegatorDelegations(delegator, '0x');

console.log('My delegations:');
for (const del of myDelegations.delegations) {
  const amountPax = ethers.formatUnits(del.balance.amount, 6);
  console.log(`  ${del.delegation.validator_address}: ${amountPax} HPX`);
}
```

### Query Unbonding Delegations

```typescript
const delegator = await signer.getAddress();

// Get all unbonding delegations
const unbonding = await staking.delegatorUnbondingDelegations(delegator, '0x');

console.log('Unbonding delegations:');
for (const ud of unbonding.unbondingDelegations) {
  console.log(`Validator: ${ud.validatorAddress}`);
  for (const entry of ud.entries) {
    const completionDate = new Date(Number(entry.completionTime) * 1000);
    console.log(`  Amount: ${entry.balance}, Completes: ${completionDate.toISOString()}`);
  }
}

// Query specific unbonding delegation
const validatorAddress = 'paxvaloper1xyz...';
const specificUnbonding = await staking.unbondingDelegation(delegator, validatorAddress);
```

### Query Redelegations

```typescript
// Get all redelegations for a specific delegator
const delegatorAddress = await signer.getAddress();
const delegatorBech32 = 'pax1...'; // Convert EVM address to Bech32 format

const redelegations = await staking.redelegations(
  delegatorBech32, // delegator filter (empty string for all)
  '', // source validator filter (empty string for all)
  '', // destination validator filter (empty string for all)
  '0x' // pagination key
);

console.log('Active redelegations:');
for (const redel of redelegations.redelegations) {
  console.log(`From ${redel.validatorSrcAddress} to ${redel.validatorDstAddress}`);
  for (const entry of redel.entries) {
    const completionDate = new Date(Number(entry.completionTime) * 1000);
    console.log(`  Amount: ${entry.initialBalance}, Completes: ${completionDate.toISOString()}`);
  }
}
```

### Query Staking Pool and Parameters

```typescript
// Get staking pool totals
const pool = await staking.pool();
console.log('Staking Pool:', {
  bondedTokens: pool.bondedTokens,
  notBondedTokens: pool.notBondedTokens
});

// Get staking parameters
const params = await staking.params();
console.log('Staking Parameters:', {
  unbondingTime: `${Number(params.unbondingTime) / 86400} days`,
  maxValidators: params.maxValidators,
  bondDenom: params.bondDenom,
  minCommissionRate: params.minCommissionRate
});
```

### Query Historical Validator Info

```typescript
// Get validator set at a specific block height
const blockHeight = 1000000n;
const historicalInfo = await staking.historicalInfo(blockHeight);

console.log(`Validators at block ${blockHeight}:`);
for (const val of historicalInfo.validators) {
  console.log(`  ${val.operatorAddress}: ${val.tokens} tokens`);
}
```

## Advanced Usage Examples

### Portfolio Rebalancing

```typescript
async function rebalanceStaking(
  fromValidator: string,
  toValidator: string,
  amount: number // Amount in HPX
) {
  try {
    // Convert to 6 decimal precision for redelegate (uses 6 decimals)
    const amountIn6Decimals = ethers.parseUnits(amount.toFixed(6), 6);

    const tx = await staking.redelegate(fromValidator, toValidator, amountIn6Decimals);

    const receipt = await tx.wait();
    console.log('Rebalancing completed:', receipt);

    return receipt;
  } catch (error) {
    console.error('Rebalancing failed:', error);
    throw error;
  }
}
```

### Complete Integration Example

<Tabs>
<Tab title="JavaScript">

```typescript
async function stakingExample() {
  // Setup
  const provider = new ethers.BrowserProvider(window.ethereum);
  await provider.send('eth_requestAccounts', []);
  const signer = await provider.getSigner();
  const staking = new ethers.Contract(STAKING_PRECOMPILE_ADDRESS, STAKING_PRECOMPILE_ABI, signer);

  const delegator = await signer.getAddress();
  const validatorAddress = 'paxvaloper1xyz...';

  try {
    // 1. Check current delegation (with error handling)
    console.log('=== Checking Current Delegation ===');
    try {
      const currentDelegation = await staking.delegation(delegator, validatorAddress);
      const currentAmountPax = ethers.formatUnits(currentDelegation.balance.amount, 6);
      console.log('Current delegation amount (HPX):', currentAmountPax);
    } catch (error) {
      if (error.message.includes('delegation not found') || error.message.includes('no delegation')) {
        console.log('No existing delegation found for this validator');
      } else {
        throw error; // Re-throw if it's a different error
      }
    }

    // 2. Delegate additional tokens (uses 18 decimals)
    console.log('=== Delegating Tokens ===');
    const amount = 1;
    const amountTrimmed = amount.toFixed(6); // Ensure 6 decimal precision
    const amountToDelegate = ethers.parseUnits(amountTrimmed, 18);
    const delegateTx = await staking.delegate(validatorAddress, {
      value: amountToDelegate,
      gasLimit: 300000
    });
    await delegateTx.wait();
    console.log('Delegation successful:', delegateTx.hash);

    // 3. Check updated delegation
    const updatedDelegation = await staking.delegation(delegator, validatorAddress);
    const updatedAmountPax = ethers.formatUnits(updatedDelegation.balance.amount, 6);
    console.log('Updated delegation amount (HPX):', updatedAmountPax);

    // 4. Undelegate partial amount (uses 6 decimals)
    console.log('=== Undelegating Tokens ===');
    const undelegateAmount = ethers.parseUnits('0.5', 6); // 0.5 HPX in 6 decimals
    const undelegateTx = await staking.undelegate(validatorAddress, undelegateAmount);
    await undelegateTx.wait();
    console.log('Undelegation successful:', undelegateTx.hash);
  } catch (error) {
    console.error('Operation failed:', error);
  }
}
```

</Tab>
<Tab title="Solidity">

**Contract Example**

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IStakingPrecompile {
    // Events
    event Delegate(address indexed delegator, string validator, uint256 amount);
    event Redelegate(address indexed delegator, string srcValidator, string dstValidator, uint256 amount);
    event Undelegate(address indexed delegator, string validator, uint256 amount);
    event ValidatorCreated(address indexed creator, string validatorAddress, string moniker);
    event ValidatorEdited(address indexed editor, string validatorAddress, string moniker);

    // Structs
    struct Delegation {
        Balance balance;
        DelegationDetails delegation;
    }

    struct Balance {
        uint256 amount;
        string denom;
    }

    struct DelegationDetails {
        string delegator_address;
        uint256 shares;
        uint256 decimals;
        string validator_address;
    }

    struct Validator {
        string operatorAddress;
        string consensusPubkey;
        bool jailed;
        int32 status;
        string tokens;
        string delegatorShares;
        string description;
        int64 unbondingHeight;
        int64 unbondingTime;
        string commissionRate;
        string commissionMaxRate;
        string commissionMaxChangeRate;
        int64 commissionUpdateTime;
        string minSelfDelegation;
    }

    struct ValidatorsResponse {
        Validator[] validators;
        bytes nextKey;
    }

    struct Pool {
        string notBondedTokens;
        string bondedTokens;
    }

    struct Params {
        uint64 unbondingTime;
        uint32 maxValidators;
        uint32 maxEntries;
        uint32 historicalEntries;
        string bondDenom;
        string minCommissionRate;
        string maxVotingPowerRatio;
        string maxVotingPowerEnforcementThreshold;
    }

    // Transaction functions
    function delegate(string memory valAddress) payable external returns (bool success);

    function undelegate(
        string memory valAddress,
        uint256 amount
    ) external returns (bool success);

    function redelegate(
        string memory srcAddress,
        string memory dstAddress,
        uint256 amount
    ) external returns (bool success);

    function createValidator(
        string memory pubKeyHex,
        string memory moniker,
        string memory commissionRate,
        string memory commissionMaxRate,
        string memory commissionMaxChangeRate,
        uint256 minSelfDelegation
    ) external payable returns (bool success);

    function editValidator(
        string memory moniker,
        string memory commissionRate,
        uint256 minSelfDelegation
    ) external returns (bool success);

    // Query functions
    function delegation(
        address delegator,
        string memory valAddress
    ) external view returns (Delegation memory);

    function validators(
        string memory status,
        bytes memory nextKey
    ) external view returns (ValidatorsResponse memory);

    function validator(
        string memory validatorAddress
    ) external view returns (Validator memory);

    function pool() external view returns (Pool memory);

    function params() external view returns (Params memory);
}

contract StakingManager {
    IStakingPrecompile constant STAKING = IStakingPrecompile(0x0000000000000000000000000000000000001005);

    event Delegated(address indexed user, string validator, uint256 amount);
    event Undelegated(address indexed user, string validator, uint256 amount);
    event Redelegated(address indexed user, string fromValidator, string toValidator, uint256 amount);

    // Delegate user's HPX to a validator
    function delegateToValidator(string memory validatorAddress) external payable {
        require(msg.value > 0, "Amount must be greater than 0");

        bool success = STAKING.delegate{value: msg.value}(validatorAddress);
        require(success, "Delegation failed");

        emit Delegated(msg.sender, validatorAddress, msg.value);
    }

    // Undelegate HPX from a validator (amount in 6 decimal precision - uhpx)
    function undelegateFromValidator(
        string memory validatorAddress,
        uint256 amount
    ) external {
        require(amount > 0, "Amount must be greater than 0");

        bool success = STAKING.undelegate(validatorAddress, amount);
        require(success, "Undelegation failed");

        emit Undelegated(msg.sender, validatorAddress, amount);
    }

    // Redelegate HPX between validators (amount in 6 decimal precision - uhpx)
    function redelegateBetweenValidators(
        string memory fromValidator,
        string memory toValidator,
        uint256 amount
    ) external {
        require(amount > 0, "Amount must be greater than 0");

        bool success = STAKING.redelegate(fromValidator, toValidator, amount);
        require(success, "Redelegation failed");

        emit Redelegated(msg.sender, fromValidator, toValidator, amount);
    }

    // Get delegation info for a user and validator
    function getDelegationInfo(
        address delegator,
        string memory validatorAddress
    ) external view returns (IStakingPrecompile.Delegation memory) {
        return STAKING.delegation(delegator, validatorAddress);
    }

    // Helper function to convert HPX to uhpx (6 decimals)
    function paxToUhpx(uint256 paxAmount) public pure returns (uint256) {
        return paxAmount * 1e6;
    }

    // Helper function to convert uhpx to HPX
    function uhpxToPax(uint256 upaxAmount) public pure returns (uint256) {
        return upaxAmount / 1e6;
    }
}
```

<Info> **Note:** This is a simplified example for demonstration purposes. The above example works such that when someone delegates through the above contract, the delegation will be recorded under the above contract address and not the user. So maintain correct mapping in the contract for tracking user delegations </Info>

**Client Integration Example**

```javascript
import { network } from 'hardhat';

// Hardhat 3 exposes ethers through a network connection rather than a global import
const { ethers } = await network.create();

async function main() {
  const [deployer] = await ethers.getSigners();
  console.log('Deploying contracts with the account:', deployer.address);

  const balance = await deployer.provider.getBalance(deployer.address);
  console.log('Account balance:', ethers.formatEther(balance));

  const StakingManager = await ethers.getContractFactory('StakingManager');
  console.log('Deploying StakingManager...');
  const stakingManager = await StakingManager.deploy();

  await stakingManager.waitForDeployment();
  console.log('StakingManager deployed to:', await stakingManager.getAddress());

  const validatorAddress = 'paxval......123';

  const amount = 1;
  const trimmedAmount = amount.toFixed(6);
  const formattedAmount = ethers.parseEther(trimmedAmount.toString());

  const delegate = await stakingManager.delegateToValidator(validatorAddress, { value: formattedAmount });

  await delegate.wait();
  console.log('Delegation transaction hash:', delegate.hash);

  // Use deployer address for querying delegation
  const queryDelegation = await stakingManager.getDelegationInfo(deployer.address, validatorAddress);
  console.log('Delegation Info:', queryDelegation);

  const undelegateAmount = ethers.parseUnits(trimmedAmount.toString(), 6);
  const undelegate = await stakingManager.undelegateFromValidator(validatorAddress, undelegateAmount);

  await undelegate.wait();
  console.log('Undelegation transaction hash:', undelegate.hash);

  const redelegate = await stakingManager.redelegateBetweenValidators(
    validatorAddress,
    'paxval.....123', // Replace with the new validator address
    undelegateAmount
  );

  await redelegate.wait();
  console.log('Redelegation transaction hash:', redelegate.hash);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

</Tab>
</Tabs>

## Security Considerations & Risks

### Unbonding Period

- **21-day lock:** Undelegated tokens cannot be transferred or earn rewards for 21 days
- **No exceptions:** This cannot be canceled once initiated
- **Planning:** Consider this when managing liquidity needs

### Validator Selection Criteria

- **Commission Rate:** Lower commission means more rewards for you (typically 1-10%)
- **Uptime:** Check for validators with high uptime (99%+)

### Redelegation Complexity

- **7-transaction limit:** You can only redelegate from the same validator to the same destination validator 7 times in 21 days
- **Serial blocking:** After redelegating A→B, you cannot redelegate B→C for 21 days
- **Each redelegation starts its own 21-day timer**

## Troubleshooting

### Common Issues and Solutions

#### Gas-Related Issues

```typescript
// Set appropriate gas limits for different operations
const delegateTx = await staking.delegate(validatorAddress, {
  value: amount,
  gasLimit: 300000
});
```

### Error Code Reference

| Error | Cause | Solution |
| --- | --- | --- |
| `insufficient funds` | Not enough HPX for operation | Check balance and reduce amount |
| `validator does not exist` | Invalid validator address | Verify validator address format |
| `invalid delegation amount` | Amount formatting issue | Use correct decimal precision |
| `commission rate too high` | Commission above max rate | Lower commission rate |
| `commission change too frequent` | Changing commission within 24h | Wait 24 hours between changes |
| `self delegation too low` | Below minimum self-delegation | Increase self-delegation amount |
| `too many redelegations` | Exceeded 7 redelegation limit | Wait for earliest redelegation to expire |


## FAQ: Precision and Normalization

- **What are the base units and precision standards defined for HPX across operations?**
  - `delegate()`: accepts `msg.value` in wei (18 decimals), but is internally truncated to 6-decimal `uhpx`. Effective granularity is 1 uhpx = `1e12` wei.
  - `undelegate()` / `redelegate()`: amounts use 6-decimal `uhpx`.
  - Staking queries: balances are 6-decimal `uhpx` (and shares are 18-decimal). Distribution `rewards()` query returns 18-decimal `DecCoins`, but withdrawn amounts are 6-decimal `uhpx`.
- **Should applications normalize between 18 and 6 decimals?**
  - Yes. For reconciliation, convert delegate `wei` to `uhpx` via integer division by `1e12` (floor). For display, convert to HPX (`wei → /1e18`, `uhpx → /1e6`).
- **Is this behavior consistent and intentional?**
  - Yes. This is intentional and not planned to change. Delegation uses EVM-native `msg.value` (18 decimals), while staking operations are executed in the Cosmos staking module, which uses 6-decimal `uhpx`.
- **Why multiple decimal precisions on one chain?**
  - To bridge EVM conventions (18-decimal `msg.value`) with the Cosmos staking module’s native 6-decimal accounting while keeping queries and non-`delegate()` writes consistent at 6 decimals.

## Important Notes

<Info> Remember the key rule: delegate() uses 18 decimals, undelegate()/redelegate() use 6 decimals, delegation() returns 6 decimals! </Info>

### Decimal Precision

- **delegate()** uses 18 decimals (wei) for msg.value
- **undelegate() and redelegate()** use 6 decimals (uhpx) for amount parameters
- **Query results** return amounts in 6 decimal precision
- **Best practice:** Use appropriate conversion functions for each operation
- **Rewards/claims (Distribution precompile):** `rewards()` query returns 18-decimal `DecCoins`; withdrawn amounts (events) are 6-decimal `uhpx`
- **Granularity:** `delegate()` `msg.value` must be a multiple of `1e12` wei (last 12 digits zero) because the precompile truncates to 6 decimals internally

### Validator Addresses

- Use valid Paxeer validator addresses with `paxvaloper1...` prefix
- These are Cosmos-format addresses, not EVM addresses

### Staking Risks

- **Unbonding:** 21-day waiting period for undelegated tokens
- **Redelegation limits:** Complex rules around frequency and serial operations

### Commission and Rewards

- Validators keep a commission percentage
- Rewards are distributed proportionally to delegation amounts
- Choose validators wisely based on commission, uptime, and governance participation

---

## EVM Compatibility

*Learn how Paxeer supports standard EVM tooling and where its transaction, gas, finality, and proof behaviors differ from Ethereum defaults.*

## EVM Compatibility

This page documents Paxeer's EVM feature support. Each row shows whether a capability works as on standard Ethereum, behaves differently in a documented way, or is not available on Paxeer.

Standard EVM tooling - viem, wagmi, ethers, Foundry, Hardhat - works on Paxeer for all rows marked **Supported**. Where Paxeer differs from Ethereum, the difference is noted so you can account for it in your application.

## Status Legend

| Status | Meaning |
| --- | --- |
| Supported | Works on Paxeer EVM with standard Ethereum behavior. |
| Supported - differences | Available on Paxeer, but intentionally differs from Ethereum. See the notes. |
| Paxeer extension | A Paxeer-specific capability with no standard Ethereum equivalent. |
| Not supported | Not available on Paxeer EVM. |

## Transactions

| Feature | Paxeer status | Notes |
| --- | --- | --- |
| Legacy transactions (type 0) | Supported - differences | Minimum gas price is set by Paxeer governance parameters, not a fixed floor. [See Gas and Fees.](/evm/evm-parity/gas-and-fees) |
| EIP-2930 access list transactions (type 1) | Supported | |
| EIP-1559 fee market transactions (type 2) | Supported - differences | No base-fee burning. Fees go to validators rather than being burned. [See Gas and Fees.](/evm/evm-parity/gas-and-fees) |
| EIP-4844 blob transactions (type 3) | Not supported | Paxeer runs Pectra without blob transactions. [See Transaction Types.](/evm/evm-parity/transaction-types) |
| EIP-7702 set-code transactions (type 4) | Supported | |

## Account and State

| Feature | Paxeer status | Notes |
| --- | --- | --- |
| `eth_getBalance` | Supported | |
| `eth_getTransactionCount` (nonce) | Supported | |
| `eth_getCode` | Supported | |
| `eth_getStorageAt` | Supported - differences | SSTORE cost is governance-adjustable; do not hard-code gas assumptions. [See Gas and Fees.](/evm/evm-parity/gas-and-fees) |
| `eth_getProof` | Supported - differences | Returns IAVL proof data rather than Ethereum Merkle Patricia Trie proofs. Proof verification logic must account for this. [See State Proofs.](/evm/evm-parity/state-proofs) |

## Blocks and Finality

| Feature | Paxeer status | Notes |
| --- | --- | --- |
| `eth_getBlockByHash`, `eth_getBlockByNumber` | Supported | |
| `eth_blockNumber` | Supported | |
| Finality tags (`latest`, `safe`, `finalized`) | Supported - differences | Paxeer has instant finality. All three tags refer to the same commitment level. [See Finality.](/evm/evm-parity/finality) |
| Pending block state | Supported - differences | Ethereum-style pending state visibility is not guaranteed. Do not rely on pending transaction ordering. [See Finality.](/evm/evm-parity/finality) |

## Logs, Filters, and Subscriptions

| Feature | Paxeer status | Notes |
| --- | --- | --- |
| `eth_getLogs` | Supported | |
| Filter lifecycle (`eth_newFilter`, `eth_getFilterChanges`, `eth_getFilterLogs`, `eth_uninstallFilter`) | Supported | |
| WebSocket subscriptions (`eth_subscribe`) | Supported | [See WebSocket Connections.](/evm/evm-parity/websocket) |

## Execution and Simulation

| Feature | Paxeer status | Notes |
| --- | --- | --- |
| `eth_call` | Supported | |
| `eth_estimateGas` | Supported | |
| `debug_traceTransaction` | Supported | |
| Block-level tracing | Supported | |

## Signing

| Feature | Paxeer status | Notes |
| --- | --- | --- |
| EIP-155 replay protection | Supported | |
| Personal sign (`personal_sign`, `eth_sign`) | Supported | Depends on the connected wallet exposing the method. [See Signing.](/evm/evm-parity/signing) |
| EIP-712 typed data signing (`eth_signTypedData_v4`) | Supported | Depends on the connected wallet exposing the method. [See Signing.](/evm/evm-parity/signing) |
| EIP-1271 contract signature validation | Supported | [See Signing.](/evm/evm-parity/signing) |

## Token Standards

| Feature | Paxeer status | Notes |
| --- | --- | --- |
| ERC-20 | Supported | |
| ERC-721 | Supported | |
| ERC-1155 | Supported | |

## Account Abstraction

| Feature | Paxeer status | Notes |
| --- | --- | --- |
| ERC-4337 | Supported | Requires a compatible bundler. Paxeer EVM is ERC-4337 compatible. |

## Name Services

| Feature | Paxeer status | Notes |
| --- | --- | --- |
| ENS | Not supported | Paxeer does not run Ethereum mainnet ENS. Application-level name services can be deployed as contracts. |

## Paxeer Extensions

These capabilities are Paxeer-specific and have no standard Ethereum equivalent. They are exposed through `@sei-js` packages layered on top of standard EVM tooling.

| Feature | Notes |
| --- | --- |
| Paxeer precompiles (staking, governance, distribution, oracle, P256, JSON, CosmWasm bridge) | EVM contracts at deterministic addresses. ABIs and contract addresses are exported from `@sei-js/precompiles` for use with any standard EVM library. |
| Pointer contracts (CW20 ↔ ERC-20, CW721 ↔ ERC-721) | Bridge between CosmWasm and EVM token standards. Standard ERC interfaces work against pointer contracts. |
| Native address association (EVM ↔ Cosmos address) | Links an EVM address and a Cosmos address for the same account. Required before some Paxeer-native flows. |
| TokenFactory native token creation | Create native Paxeer tokens that are usable across EVM and CosmWasm without a wrapper contract. |

## Unsupported RPC Methods

The following JSON-RPC methods are either not available on Paxeer or will return errors:

### Blob / EIP-4844

| Method | Reason |
| --- | --- |
| `eth_blobBaseFee` | Paxeer runs Pectra without blob transaction support. This method does not exist on Paxeer. |
| `engine_getBlobsV1` | Blob data availability endpoints are not supported. |

### Pending State

| Method | Behavior on Paxeer |
| --- | --- |
| `eth_getBlockByNumber("pending")` | Returns `null` or the latest committed block. Paxeer does not maintain an Ethereum-style pending block. |
| `eth_getTransactionCount(address, "pending")` | Returns the same value as `"latest"`. Pending nonce does not differ from confirmed nonce on Paxeer. |
| `eth_newPendingTransactionFilter` | The filter can be created but will not reliably emit pending transactions. Use `eth_newBlockFilter` or WebSocket block subscriptions instead. |
| `eth_subscribe("newPendingTransactions")` | Supported at the RPC level but Paxeer does not guarantee Ethereum-style pending transaction visibility. Treat results as best-effort. |

### Proof Verification

| Method | Behavior on Paxeer |
| --- | --- |
| `eth_getProof` | Returns IAVL tree proofs, not Ethereum Merkle Patricia Trie proofs. The method itself works, but the proof format is incompatible with standard Ethereum MPT verifiers. [See State Proofs.](/evm/evm-parity/state-proofs) |

### Deprecated / Removed Opcodes

| Method | Reason |
| --- | --- |
| `eth_accounts` | Returns an empty array on Paxeer RPC nodes. Use a wallet library (`eth_requestAccounts`) to get accounts from the connected user's wallet instead. |

---

## Finality and Block Tags

*Paxeer's Twin Turbo Consensus delivers instant finality, so latest, safe, and finalized block tags all resolve identically with no reorg risk.*

## Finality and Block Tags

Paxeer uses Twin Turbo Consensus, which provides instant finality. Every committed block is final immediately - there is no period where a block could be reorganized away.

This changes how block tags behave compared to Ethereum.

## Block Tags

On Ethereum, `latest`, `safe`, and `finalized` refer to different points in the chain:

- `latest` - the most recent block, possibly not yet safe
- `safe` - a block unlikely to be reorganized
- `finalized` - a block that is permanently committed

On Paxeer, all three tags resolve to the same block. There is no reorg risk at any point after a block is committed, so the distinction does not exist.

<CodeGroup>

```ts viem
import { createPublicClient, http } from 'viem';
import { sei } from 'viem/chains';

const client = createPublicClient({ chain: sei, transport: http() });

// All three return the same block on Paxeer
const latest    = await client.getBlock({ blockTag: 'latest' });
const safe      = await client.getBlock({ blockTag: 'safe' });
const finalized = await client.getBlock({ blockTag: 'finalized' });
```

```ts ethers
import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider('https://evm-rpc.sei-apis.com');

// All three return the same block on Paxeer
const latest    = await provider.getBlock('latest');
const safe      = await provider.getBlock('safe');
const finalized = await provider.getBlock('finalized');
```

</CodeGroup>

## Waiting for Confirmation

Because finality is instant, you do not need to wait for multiple confirmations. `waitForTransactionReceipt` resolves as soon as the transaction is included in a block.

<CodeGroup>

```ts viem
const receipt = await client.waitForTransactionReceipt({ hash });
// receipt is already final - no further confirmation needed
```

```ts ethers
const tx = await signer.sendTransaction({ /* ... */ });
const receipt = await tx.wait(1); // 1 confirmation is final on Paxeer
```

</CodeGroup>

## Pending State

Paxeer does not expose Ethereum-style pending state. Do not rely on:

- Reading pending transactions from the mempool
- `eth_getBlockByNumber` with `'pending'`
- Pending nonce differing from the confirmed nonce

If your application polls pending transactions or depends on pending state visibility, replace that pattern with confirmed-block polling or WebSocket subscriptions on committed blocks.

## Practical Impact

| Pattern | On Ethereum | On Paxeer |
| --- | --- | --- |
| Wait for `finalized` tag | Waits ~13 minutes | Returns immediately |
| Check `safe` vs `latest` | Different blocks | Same block |
| Read pending mempool | Supported | Not reliable |
| Confirmation count | Meaningful | 1 is sufficient |

---

## Gas and Fees

*Learn how Paxeer's gas and fee model differs from Ethereum, including legacy gas floors, EIP-1559 fees, and adjustable SSTORE costs.*

## Gas and Fees

Paxeer supports both legacy and EIP-1559 transactions, but the fee model differs from Ethereum in three ways that affect how you estimate and set gas.

## Legacy Gas Price Floor

Legacy transactions (type 0) on Paxeer must meet a minimum gas price set by on-chain governance. This floor can change via governance proposals - do not hard-code a specific value.

Use `eth_gasPrice` to read the current minimum:

<CodeGroup>

```ts viem
import { createPublicClient, http } from 'viem';
import { sei } from 'viem/chains';

const client = createPublicClient({ chain: sei, transport: http() });
const gasPrice = await client.getGasPrice();
```

```ts ethers
import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider('https://evm-rpc.sei-apis.com');
const feeData = await provider.getFeeData();
const gasPrice = feeData.gasPrice;
```

</CodeGroup>

## EIP-1559 Fee Model

Paxeer supports EIP-1559 transactions (type 2), but does not burn the base fee. Fees go entirely to validators rather than being partially burned as on Ethereum.

This does not affect how you construct or send transactions - `maxFeePerGas` and `maxPriorityFeePerGas` work as expected. It is relevant only if your application models token supply or displays fee-burn information to users.

<CodeGroup>

```ts viem
const fees = await client.estimateFeesPerGas();
// fees.maxFeePerGas and fees.maxPriorityFeePerGas are usable as-is
```

```ts ethers
const feeData = await provider.getFeeData();
// feeData.maxFeePerGas and feeData.maxPriorityFeePerGas are usable as-is
```

</CodeGroup>

## SSTORE Cost

The gas cost of `SSTORE` (writing to contract storage) is governance-adjustable on Paxeer. It is currently **72,000 gas** - the same on mainnet and testnet (see [Divergence from Ethereum](/evm/differences-with-ethereum#gas-model--fees)) - but treat that as the current value, not a constant: do not hard-code storage write estimates in your application.

Always use `eth_estimateGas` for any transaction that writes to storage:

<CodeGroup>

```ts viem
const gas = await client.estimateGas({
  account,
  to: contractAddress,
  data: encodedCalldata,
});

// Add a buffer for governance changes during high-activity periods
const gasWithBuffer = (gas * 120n) / 100n; // 20% buffer
```

```ts ethers
const gas = await provider.estimateGas({
  from: signer.address,
  to: contractAddress,
  data: encodedCalldata,
});
```

</CodeGroup>

<Warning>A Foundry `forge test --gas-report --fork-url <paxeer rpc>` report forks chain *state* but runs revm's standard EVM gas schedule, so it shows `SSTORE` at the Ethereum cost (~22,100) rather than Paxeer's ~72,000. Use it for relative profiling of your own logic; estimate the absolute storage-write cost with a live `eth_estimateGas` against a Paxeer RPC.</Warning>

## Summary

| Behavior | Ethereum | Paxeer |
| --- | --- | --- |
| Legacy gas floor | Protocol minimum | Governance-set, can change |
| Base fee | Burned | Paid to validators |
| SSTORE cost | Fixed by EIP | Governance-adjustable |
| `estimateGas` | Always correct to use | Required - do not hard-code storage costs |

---

## Signing

*Learn how to implement message and typed data signing on Paxeer using EIP-191 and EIP-712 standards with viem and ethers examples.*

## Signing

Signing on Paxeer works through standard EVM libraries and wallet standards. The methods available depend on which wallet the user has connected.

## Wallet Signing Support

| Method | Standard | Paxeer Global Wallet | MetaMask | WalletConnect wallets |
| --- | --- | --- | --- | --- |
| `personal_sign` | EIP-191 | Supported | Supported | Wallet-dependent |
| `eth_signTypedData_v4` | EIP-712 | Supported | Supported | Wallet-dependent |
| `eth_sign` | Legacy | Not recommended | Supported | Wallet-dependent |
| Transaction signing | - | Supported | Supported | Supported |

Do not assume all wallets support all methods. Always handle rejection gracefully.

## Personal Sign

<CodeGroup>

```ts viem
import { createWalletClient, custom } from 'viem';
import { sei } from 'viem/chains';

const client = createWalletClient({
  chain: sei,
  transport: custom(window.ethereum),
});

const [account] = await client.getAddresses();

const signature = await client.signMessage({
  account,
  message: 'Hello Paxeer',
});
```

```ts ethers
import { ethers } from 'ethers';

const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

const signature = await signer.signMessage('Hello Paxeer');
```

</CodeGroup>

## EIP-712 Typed Data

<CodeGroup>

```ts viem
const [account] = await client.getAddresses();

const signature = await client.signTypedData({
  account,
  domain: {
    name: 'My App',
    version: '1',
    chainId: 1329, // Paxeer mainnet
    verifyingContract: '0xContractAddress',
  },
  types: {
    Order: [
      { name: 'maker', type: 'address' },
      { name: 'amount', type: 'uint256' },
      { name: 'expiry', type: 'uint256' },
    ],
  },
  primaryType: 'Order',
  message: {
    maker: account,
    amount: 1000000n,
    expiry: BigInt(Math.floor(Date.now() / 1000) + 3600),
  },
});
```

```ts ethers
import { ethers } from 'ethers';

const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

const domain = {
  name: 'My App',
  version: '1',
  chainId: 1329,
  verifyingContract: '0xContractAddress',
};

const types = {
  Order: [
    { name: 'maker', type: 'address' },
    { name: 'amount', type: 'uint256' },
    { name: 'expiry', type: 'uint256' },
  ],
};

const value = {
  maker: await signer.getAddress(),
  amount: 1000000n,
  expiry: BigInt(Math.floor(Date.now() / 1000) + 3600),
};

const signature = await signer.signTypedData(domain, types, value);
```

</CodeGroup>

## Verifying Signatures

```ts viem
import { verifyMessage, verifyTypedData } from 'viem';

// Verify personal sign
const valid = await verifyMessage({
  address: '0xSignerAddress',
  message: 'Hello Paxeer',
  signature,
});

// Verify EIP-712
const validTyped = await verifyTypedData({
  address: '0xSignerAddress',
  domain,
  types,
  primaryType: 'Order',
  message: value,
  signature,
});
```

## EIP-1271 Contract Signatures

Smart contract wallets on Paxeer can validate signatures via EIP-1271 (`isValidSignature`). Use viem's `verifyMessage` with a contract address - it automatically uses EIP-1271 when the address is a contract.

```ts viem
const valid = await verifyMessage({
  address: '0xSmartContractWallet',
  message: 'Hello Paxeer',
  signature,
});
// viem calls isValidSignature if the address is a contract
```

---

## State Proofs

*Learn how Paxeer's eth_getProof returns IAVL proofs instead of Ethereum MPT proofs, and what this means for verification.*

## State Proofs

Paxeer supports `eth_getProof` but returns a different proof format from Ethereum. If your application verifies proofs on-chain or off-chain, you need to account for this difference.

## The Difference

Ethereum stores state in a Merkle Patricia Trie (MPT) and `eth_getProof` returns MPT inclusion proofs. Paxeer stores state in an IAVL tree and returns IAVL proofs instead.

The RPC method exists and responds correctly, but the proof data structure is not compatible with Ethereum MPT proof verifiers.

## What This Affects

Most applications do not call `eth_getProof` directly. It is primarily used by:

- Light clients verifying state without trusting an RPC node
- Cross-chain bridges proving inclusion of state on Paxeer
- Applications verifying contract storage values trustlessly

If you are doing standard contract reads, event queries, or transaction lookups, this difference does not affect you.

## Calling eth_getProof

The call works through standard libraries:

<CodeGroup>

```ts viem
import { createPublicClient, http } from 'viem';
import { sei } from 'viem/chains';

const client = createPublicClient({ chain: sei, transport: http() });

const proof = await client.getProof({
  address: '0xContractAddress',
  storageKeys: ['0xStorageSlot'],
});

// proof.accountProof and proof.storageProof contain IAVL proof data,
// not Ethereum MPT proofs - do not pass to an MPT verifier
```

```ts ethers
import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider('https://evm-rpc.sei-apis.com');

const proof = await provider.send('eth_getProof', [
  '0xContractAddress',
  ['0xStorageSlot'],
  'latest',
]);

// Same caveat - proof data is IAVL format
```

</CodeGroup>

## Verifying Proofs

To verify Paxeer state proofs, use an IAVL-compatible verifier. Standard Ethereum MPT verifier libraries (e.g. those used in Solidity or in Ethereum bridge contracts) will reject Paxeer proofs.

Refer to the [Paxeer RPC reference](/evm/reference) for the exact proof schema returned.

---

## Transaction Types

*Paxeer supports Ethereum transaction types 0, 1, 2, and 4, but not blob transactions (type 3), under the Pectra hardfork.*

## Transaction Types

Paxeer supports most Ethereum transaction types. The one notable exception is blob transactions.

## Supported Types

| Type | EIP | Name | Paxeer support |
| --- | --- | --- | --- |
| 0 | - | Legacy | Supported - governance-set minimum gas price applies |
| 1 | EIP-2930 | Access list | Supported |
| 2 | EIP-1559 | Fee market | Supported - base fee is not burned |
| 4 | EIP-7702 | Set code | Supported |

## Not Supported

| Type | EIP | Name | Notes |
| --- | --- | --- | --- |
| 3 | EIP-4844 | Blob | Not supported - Paxeer runs Pectra without blob transactions |

## Blob Transactions

Paxeer runs the Pectra hardfork without blob transaction support. Attempting to send a type 3 transaction will be rejected at the RPC level.

If you are porting code from Ethereum that uses blob transactions (e.g. rollup data availability), that path does not apply to Paxeer.

## Sending Transactions

Standard library defaults work correctly. viem, wagmi, and ethers all default to type 2 (EIP-1559) transactions on chains that support it, which Paxeer does.

<CodeGroup>

```ts viem
import { createWalletClient, http, parseEther } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { sei } from 'viem/chains';

const account = privateKeyToAccount('0xYourPrivateKey');
const client = createWalletClient({ account, chain: sei, transport: http() });

// Sends a type 2 transaction - correct default for Paxeer
const hash = await client.sendTransaction({
  to: '0xRecipient',
  value: parseEther('1'),
});
```

```ts ethers
import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider('https://evm-rpc.sei-apis.com');
const wallet = new ethers.Wallet('0xYourPrivateKey', provider);

// ethers defaults to EIP-1559 where supported - correct for Paxeer
const tx = await wallet.sendTransaction({
  to: '0xRecipient',
  value: ethers.parseEther('1'),
});
```

</CodeGroup>

---

## WebSocket Connections

*Learn how to use eth_subscribe over WebSocket on Paxeer to watch new blocks, contract events, and ERC-20 transfers in real time.*

## WebSocket Connections

Paxeer supports `eth_subscribe` over WebSocket. You can subscribe to new blocks, event logs, and pending transactions using standard library WebSocket transports.

## Endpoints

| Network | WebSocket endpoint |
| --- | --- |
| Mainnet | `wss://evm-ws.sei-apis.com` |
| Testnet | `wss://evm-ws-testnet.sei-apis.com` |
| Devnet | `wss://evm-ws-arctic-1.sei-apis.com` |

## Connecting

<CodeGroup>

```ts viem
import { createPublicClient, webSocket } from 'viem';
import { sei } from 'viem/chains';

const client = createPublicClient({
  chain: sei,
  transport: webSocket('wss://evm-ws.sei-apis.com'),
});
```

```ts ethers
import { ethers } from 'ethers';

const provider = new ethers.WebSocketProvider('wss://evm-ws.sei-apis.com');
```

</CodeGroup>

## Watching New Blocks

<CodeGroup>

```ts viem
const unwatch = client.watchBlocks({
  onBlock: (block) => {
    console.log('New block:', block.number);
  },
});

// Stop watching
unwatch();
```

```ts ethers
provider.on('block', (blockNumber) => {
  console.log('New block:', blockNumber);
});

// Stop watching
provider.off('block');
```

</CodeGroup>

## Watching Contract Events

<CodeGroup>

```ts viem
import { parseAbiItem } from 'viem';

const unwatch = client.watchEvent({
  address: '0xContractAddress',
  event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
  onLogs: (logs) => {
    console.log('Transfer events:', logs);
  },
});
```

```ts ethers
import { ethers } from 'ethers';

const ERC20_ABI = ['event Transfer(address indexed from, address indexed to, uint256 value)'];
const contract = new ethers.Contract('0xContractAddress', ERC20_ABI, provider);

contract.on('Transfer', (from, to, value, event) => {
  console.log('Transfer:', { from, to, value });
});

// Stop watching
contract.off('Transfer');
```

</CodeGroup>

## Watching ERC-20 Transfers Across All Contracts

```ts viem
import { parseAbiItem } from 'viem';

const unwatch = client.watchEvent({
  event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
  onLogs: (logs) => {
    logs.forEach((log) => {
      console.log(`Transfer on ${log.address}:`, log.args);
    });
  },
});
```

## Notes

- Paxeer's instant finality means every block emitted over WebSocket is already final - no need to wait for additional confirmations before acting on an event.
- Pending transaction subscriptions (`newPendingTransactions`) are supported at the RPC level but Paxeer does not guarantee Ethereum-style pending state visibility.

---

## Debug Tracing Overview

*Learn how to use Paxeer's debug JSON-RPC endpoints to trace EVM transactions, analyze gas usage, and debug smart contract execution.*

## Requirements

The examples in this guide call the debug JSON-RPC endpoints directly with `curl` - no SDK or additional libraries are required. Optionally install [`jq`](https://jqlang.github.io/jq/) to pretty-print the JSON responses:

```bash
# macOS
brew install jq

# Debian/Ubuntu
sudo apt-get install jq
```

Debug tracing is your primary tool for understanding EVM transaction execution on Paxeer. This comprehensive system allows you to analyze transaction flow, optimize gas usage, debug smart contract interactions, and troubleshoot production issues.

## What You Can Trace

### Transaction Execution

- Step-by-step opcode execution
- Contract call hierarchy
- Gas consumption breakdown
- State changes and storage access

### Contract Interactions

- Cross-contract calls and returns
- Event emission analysis
- Precompile usage tracking
- External library calls

### Performance Analysis

- Gas optimization opportunities
- Bottleneck identification
- Cache hit/miss patterns
- State access efficiency

### Security Analysis

- Suspicious operation detection
- Reentrancy pattern analysis
- Access control verification
- Vulnerability scanning

## Available Tracing Methods

| Method                     | Purpose                    | Use Case                      |
| -------------------------- | -------------------------- | ----------------------------- |
| `debug_traceTransaction`   | Trace specific transaction | Debugging failed transactions |
| `debug_traceBlockByNumber` | Trace entire block         | Block-level analysis          |
| `debug_traceCall`          | Simulate and trace         | Testing before execution      |
| `debug_traceStateAccess`   | State access patterns      | Performance optimization      |

## Transaction Analysis Example

Tracing an ERC-20 transfer transaction:

<Tabs>
<Tab title="Transaction Details">
```bash
# Real transaction on Paxeer mainnet
TRANSACTION_HASH="0x75b7ba10248e90db85b224eae587db1728520b6f72c795b9185064f444cee7c3"

# Transaction details

curl -X POST -H "Content-Type: application/json" \
 --data '{
"jsonrpc": "2.0",
"method": "eth_getTransactionByHash",
"params": ["'$TRANSACTION_HASH'"],
"id": 1
}' \
 https://evm-rpc.sei-apis.com

````

**Response:**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "blockHash": "0xbc229fe41605ba2b46fcd7aa7ce328dc2f6da78385dfea84ca8dbef7b4325462",
    "blockNumber": "0x97aefcf",
    "from": "0x4cbee7ad42d33e9d3b41e8b6faca2f6f173c8a94",
    "gas": "0x66f24",
    "gasPrice": "0x565dd756",
    "maxFeePerGas": "0x565dd756",
    "maxPriorityFeePerGas": "0x5e679d6",
    "hash": "0x75b7ba10248e90db85b224eae587db1728520b6f72c795b9185064f444cee7c3",
    "input": "0x733214a3e5f551789f7ee58322679a2b141e64533098b8ba41d9e10cf8061a18a777d6ce00000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000001000000000000000000000000004cbee7ad42d33e9d3b41e8b6faca2f6f173c8a940000000000000000000000000000000000000000000000000dd26083bfc745570000000000000000000000000000000000000000000000000000000000000160000000000000000000000000000000000000000000000000000000000000000f6a756d7065722e65786368616e67650000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002a30783030303030303030303030303030303030303030303030303030303030303030303030303030303000000000000000000000000000000000000000000000000000000000000000000000fde9ce4e17b650efdca13d524f132876700d806f000000000000000000000000fde9ce4e17b650efdca13d524f132876700d806f0000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f10000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004faaa00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000001642646478b0000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f1000000000000000000000000000000000000000000000000000000000004faaa000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000000000000000000000000000000000000000000000000dd26083bfc745570000000000000000000000001231deb6f5749ef6ce6943a275a1d3e7486f4eae00000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000070023894085ef7ff0f0aedf52e2a2704928d1ec074f101ffff015cfa8db453c9904511c4ea9eb0bfc903e36b9f5f01fde9ce4e17b650efdca13d524f132876700d806f01e30fedd158a2e3b13e9badaeabafc5516e95e8c701ffff02001231deb6f5749ef6ce6943a275a1d3e7486f4eae0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "nonce": "0x4",
    "to": "0x1231deb6f5749ef6ce6943a275a1d3e7486f4eae",
    "transactionIndex": "0x14",
    "value": "0x0",
    "type": "0x2",
    "accessList": [],
    "chainId": "0x531",
    "v": "0x0",
    "r": "0x3a107aca9cd554a9171a65ea2e8ef56ebeca8cfdc17f4bbecfb0f86837ca90d6",
    "s": "0x426134cf65b701bc8d43162f78bcf787319ff17cc6293188bcbb30fd99feb60",
    "yParity": "0x0"
  }
}
````

</Tab>
<Tab title="Basic Trace">
```bash
# Trace the transaction execution
curl -X POST -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "debug_traceTransaction",
    "params": [
      "'$TRANSACTION_HASH'",
      {
        "tracer": "callTracer",
        "tracerConfig": {
          "withLog": true
        }
      }
    ],
    "id": 1
  }' \
  https://evm-rpc.sei-apis.com
```

**Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "from": "0x4cbee7ad42d33e9d3b41e8b6faca2f6f173c8a94",
    "gas": "0x66f24",
    "gasUsed": "0x40f98",
    "to": "0x1231deb6f5749ef6ce6943a275a1d3e7486f4eae",
    "input": "0x733214a3e5f551789f7ee58322679a2b141e64533098b8ba41d9e10cf8061a18a777d6ce00000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000001000000000000000000000000004cbee7ad42d33e9d3b41e8b6faca2f6f173c8a940000000000000000000000000000000000000000000000000dd26083bfc745570000000000000000000000000000000000000000000000000000000000000160000000000000000000000000000000000000000000000000000000000000000f6a756d7065722e65786368616e67650000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002a30783030303030303030303030303030303030303030303030303030303030303030303030303030303000000000000000000000000000000000000000000000000000000000000000000000fde9ce4e17b650efdca13d524f132876700d806f000000000000000000000000fde9ce4e17b650efdca13d524f132876700d806f0000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f10000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004faaa00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000001642646478b0000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f1000000000000000000000000000000000000000000000000000000000004faaa000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000000000000000000000000000000000000000000000000dd26083bfc745570000000000000000000000001231deb6f5749ef6ce6943a275a1d3e7486f4eae00000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000070023894085ef7ff0f0aedf52e2a2704928d1ec074f101ffff015cfa8db453c9904511c4ea9eb0bfc903e36b9f5f01fde9ce4e17b650efdca13d524f132876700d806f01e30fedd158a2e3b13e9badaeabafc5516e95e8c701ffff02001231deb6f5749ef6ce6943a275a1d3e7486f4eae0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "calls": [
      {
        "from": "0x1231deb6f5749ef6ce6943a275a1d3e7486f4eae",
        "gas": "0x5d03f",
        "gasUsed": "0x3b0cc",
        "to": "0x31a9b1835864706af10103b31ea2b79bdb995f5f",
        "input": "0x733214a3e5f551789f7ee58322679a2b141e64533098b8ba41d9e10cf8061a18a777d6ce00000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000001000000000000000000000000004cbee7ad42d33e9d3b41e8b6faca2f6f173c8a940000000000000000000000000000000000000000000000000dd26083bfc745570000000000000000000000000000000000000000000000000000000000000160000000000000000000000000000000000000000000000000000000000000000f6a756d7065722e65786368616e67650000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002a30783030303030303030303030303030303030303030303030303030303030303030303030303030303000000000000000000000000000000000000000000000000000000000000000000000fde9ce4e17b650efdca13d524f132876700d806f000000000000000000000000fde9ce4e17b650efdca13d524f132876700d806f0000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f10000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004faaa00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000001642646478b0000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f1000000000000000000000000000000000000000000000000000000000004faaa000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000000000000000000000000000000000000000000000000dd26083bfc745570000000000000000000000001231deb6f5749ef6ce6943a275a1d3e7486f4eae00000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000070023894085ef7ff0f0aedf52e2a2704928d1ec074f101ffff015cfa8db453c9904511c4ea9eb0bfc903e36b9f5f01fde9ce4e17b650efdca13d524f132876700d806f01e30fedd158a2e3b13e9badaeabafc5516e95e8c701ffff02001231deb6f5749ef6ce6943a275a1d3e7486f4eae0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
        "calls": [
          {
            "from": "0x1231deb6f5749ef6ce6943a275a1d3e7486f4eae",
            "gas": "0x5aa48",
            "gasUsed": "0xa724",
            "to": "0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1",
            "input": "0x23b872dd0000000000000000000000004cbee7ad42d33e9d3b41e8b6faca2f6f173c8a940000000000000000000000001231deb6f5749ef6ce6943a275a1d3e7486f4eae000000000000000000000000000000000000000000000000000000000004faaa",
            "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
            "calls": [
              {
                "from": "0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1",
                "gas": "0x54283",
                "gasUsed": "0x4ad6",
                "to": "0x0000000000000000000000000000000000001001",
                "input": "0x5c05961b0000000000000000000000004cbee7ad42d33e9d3b41e8b6faca2f6f173c8a940000000000000000000000001231deb6f5749ef6ce6943a275a1d3e7486f4eae0000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000004faaa00000000000000000000000000000000000000000000000000000000000000446962632f4341364642464146333939343734413036323633453130443043453541454242453135313839443644344232444439414445363130303745363845423944423000000000000000000000000000000000000000000000000000000000",
                "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
                "value": "0x0",
                "type": "CALL"
              }
            ],
            "logs": [
              {
                "address": "0x3894085ef7ff0f0aedf52e2a2704928d1ec074f1",
                "topics": [
                  "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
                  "0x0000000000000000000000004cbee7ad42d33e9d3b41e8b6faca2f6f173c8a94",
                  "0x0000000000000000000000001231deb6f5749ef6ce6943a275a1d3e7486f4eae"
                ],
                "data": "0x000000000000000000000000000000000000000000000000000000000004faaa",
                "position": "0x1"
              }
            ],
            "value": "0x0",
            "type": "CALL"
          },
          ...
        ]
      }
    ]
  }
}
```

</Tab>
<Tab title="Gas Analysis">
```bash
# Analyze gas usage patterns
curl -X POST -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "debug_traceTransaction",
    "params": [
      "0x75b7ba10248e90db85b224eae587db1728520b6f72c795b9185064f444cee7c3",
      {
        "tracer": "{gasUsed: 0, operations: {}, step: function(log, db) { var op = log.op.toString(); var cost = log.getCost(); this.gasUsed += cost; if (!this.operations[op]) { this.operations[op] = { count: 0, totalGas: 0 }; } this.operations[op].count++; this.operations[op].totalGas += cost; }, fault: function(log, db) {}, result: function(ctx, db) { return { totalGas: this.gasUsed, operations: this.operations, efficiency: this.gasUsed / ctx.gasUsed }; }}"
      }
    ],
    "id": 1
  }' \
  https://evm-rpc.sei-apis.com
```

**Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "totalGas": 6346011,
    "operations": {
      "PUSH1": {
        "count": 1476,
        "totalGas": 4428
      },
      "MSTORE": {
        "count": 342,
        "totalGas": 1690
      },
      "CALLDATASIZE": {
        "count": 41,
        "totalGas": 82
      },
      "PUSH2": {
        "count": 1400,
        "totalGas": 4200
      },

      ...


      "STOP": {
        "count": 5,
        "totalGas": 0
      },
      "LOG2": {
        "count": 2,
        "totalGas": 5578
      },
      "LOG4": {
        "count": 1,
        "totalGas": 2899
      },
      "LOG1": {
        "count": 1,
        "totalGas": 2542
      }
    },
    "efficiency": 23.84499278564343
  }
}
```

</Tab>
</Tabs>

## Debugging Failed Transactions

Steps to analyze and resolve transaction failures:

### Step 1: Identify the Problem

```bash
# Get transaction receipt
FAILED_TX="0xb2a6f4f7f37d8df728968126c05d1a8b0391003cf375ed5abb1b5e02fe66c717"

curl -X POST -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getTransactionReceipt",
    "params": ["'$FAILED_TX'"],
    "id": 1
  }' \
  https://evm-rpc.sei-apis.com
```

### Step 2: Trace the Execution

```bash
# Trace to see where it failed
curl -X POST -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "debug_traceTransaction",
    "params": [
      "'$FAILED_TX'",
      {
        "tracer": "callTracer",
        "tracerConfig": {
          "withLog": true
        }
      }
    ],
    "id": 1
  }' \
  https://evm-rpc.sei-apis.com
```

Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "from": "0x2c80b1b0473bb765ef536d2526ec63195794d945",
    "gas": "0xc3500",
    "gasUsed": "0x2863d",
    "to": "0xd1efe48b71acd98db16fcb9e7152b086647ef544",
    "input": "0x414bf3890000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f1000000000000000000000000e30fedd158a2e3b13e9badaeabafc5516e95e8c70000000000000000000000000000000000000000000000000000000000000bb80000000000000000000000002c80b1b0473bb765ef536d2526ec63195794d94500000000000000000000000000000000000000000000000000000000688a24580000000000000000000000000000000000000000000000000000000031aba85500000000000000000000000000000000000000000000009556d1a971e567965b0000000000000000000000000000000000000000000000000000000000000000",
    "output": "0x08c379a000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000013546f6f206c6974746c6520726563656976656400000000000000000000000000",
    "error": "execution reverted",
    "revertReason": "Too little received",
    "calls": [
      ...
    ]
  }
}
```

### Step 3: Fix and Test

```bash
# Simulate the fix with debug_traceCall
curl -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "debug_traceCall",
    "params": [
      {
        "from": "0x2c80b1b0473bb765ef536d2526ec63195794d945",
        "to": "0xd1efe48b71acd98db16fcb9e7152b086647ef544",
        "gas": "0xc3500",
        "gasPrice": "0x2127ddd32",
        "value": "0x0"
      },
      "0x98a87cc",
      {
        "tracer": "callTracer",
        "tracerConfig": {
          "onlyTopCall": false,
          "withLog": true
        }
      }
    ],
    "id": 1
  }' \
  https://evm-rpc.sei-apis.com
```

## Common Debugging Scenarios

### Transaction Reverted

**Problem**: Transaction failed with revert
**Solution**: Use `callTracer` to find the exact revert reason

### Out of Gas

**Problem**: Transaction ran out of gas
**Solution**: Use gas analysis tracer to optimize gas usage

### Unexpected Behavior

**Problem**: Transaction succeeded but wrong result
**Solution**: Use opcode tracer for step-by-step analysis

### Slow Performance

**Problem**: Transaction uses too much gas
**Solution**: Use state access tracer to find inefficiencies

## Quick Reference

### Essential Commands

```bash
# Trace transaction
debug_traceTransaction(hash, {tracer: "callTracer"})

# Trace block
debug_traceBlockByNumber("latest", {tracer: "callTracer"})

# Simulate call
debug_traceCall(tx, "latest", {tracer: "callTracer"})

# State access
debug_traceStateAccess(hash)
```

### Common Tracers

- **`callTracer`**: Contract call hierarchy
- **`opcodeTracer`**: Opcode-level execution
- **Custom JS**: Custom analysis logic

## Next Steps

1. **[JavaScript Tracers](/evm/tracing/javascript-tracers)** - Custom analysis scripts
2. **[Troubleshooting](/evm/tracing/troubleshooting)** - Common issues and solutions

<Info>Start with `callTracer` for general debugging, then use specialized tracers for specific analysis needs.</Info>

---

## JavaScript Tracers

*Learn to build custom JavaScript tracers for Paxeer, enabling advanced EVM transaction analysis, state tracking, and security auditing beyond built-in*

JavaScript tracers allow you to create custom debugging logic for analyzing EVM transactions on Paxeer. This powerful feature enables sophisticated analysis patterns beyond what built-in tracers provide.

## Interface Overview

Every JavaScript tracer follows this structure:

```javascript
{
  "tracer": `{
    // Initialize variables
    data: [],

    // Called for each opcode execution
    step: function(log, db) {
      // Your analysis logic here
    },

    // Called when execution fails (optional)
    fault: function(log, db) {
      return {};
    },

    // Called at the end to return results
    result: function(ctx, db) {
      return {
        // Your analysis results
      };
    }
  }`
}
```

## Core Methods

### step(log, db)

Called for each EVM opcode execution. This is where your main analysis logic goes.

**Parameters:**

- `log`: Current execution context with methods like `getPC()`, `op.toString()`, `getCost()`
- `db`: Database interface for querying state

**Gas Cost**: Varies by tracer complexity

### result(ctx, db)

Called at the end of execution to return your analysis results.

**Parameters:**

- `ctx`: Execution context with `gasUsed`, transaction info
- `db`: Database interface for final queries

## Advanced Tracer Examples

### State Change Tracker

Monitor all state modifications with detailed analysis:

```javascript
{
  "tracer": `{
    stateChanges: {},

    step: function(log, db) {
      if (log.op.toString() == "SSTORE") {
        var key = log.stack.peek(0).toString(16);
        var value = log.stack.peek(1).toString(16);
        var address = log.contract.getAddress().toString();

        if (!this.stateChanges[address]) {
          this.stateChanges[address] = {};
        }

        this.stateChanges[address][key] = {
          oldValue: db.getState(address, key),
          newValue: value,
          pc: log.getPC()
        };
      }
    },

    result: function(ctx, db) {
      return {
        modifiedAccounts: Object.keys(this.stateChanges).length,
        stateChanges: this.stateChanges
      };
    }
  }`
}
```

### DeFi Transaction Analysis

Analyze complex DeFi transactions with multiple contract interactions:

```javascript
{
  "tracer": `{
    transfers: [],

    step: function(log, db) {
      // Track ERC20 Transfer events (LOG3 with Transfer signature)
      if (log.op.toString() == "LOG3") {
        var topic0 = log.stack.peek(2).toString(16);
        // ERC20 Transfer event signature
        if (topic0 == "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef") {
          this.transfers.push({
            from: log.stack.peek(3).toString(16),
            to: log.stack.peek(4).toString(16),
            value: log.memory.slice(log.stack.peek(0), log.stack.peek(1)),
            contract: log.contract.getAddress().toString()
          });
        }
      }
    },

    result: function(ctx, db) {
      return {
        totalTransfers: this.transfers.length,
        transfers: this.transfers,
        gasEfficiency: this.transfers.length > 0 ? ctx.gasUsed / this.transfers.length : 0
      };
    }
  }`
}
```

### Security Analysis Tracer

Detect suspicious patterns and potential vulnerabilities:

```javascript
{
  "tracer": `{
    suspiciousOps: [],
    externalCalls: 0,
    selfDestructs: 0,

    step: function(log, db) {
      var op = log.op.toString();

      // Track external calls
      if (op == "CALL" || op == "DELEGATECALL" || op == "STATICCALL") {
        this.externalCalls++;

        // Flag suspicious delegate calls
        if (op == "DELEGATECALL") {
          this.suspiciousOps.push({
            type: "DELEGATECALL",
            target: log.stack.peek(1).toString(16),
            pc: log.getPC()
          });
        }
      }

      // Track self-destructs
      if (op == "SELFDESTRUCT") {
        this.selfDestructs++;
        this.suspiciousOps.push({
          type: "SELFDESTRUCT",
          beneficiary: log.stack.peek(0).toString(16),
          pc: log.getPC()
        });
      }
    },

    result: function(ctx, db) {
      return {
        riskScore: this.suspiciousOps.length * 10 + this.selfDestructs * 50,
        externalCalls: this.externalCalls,
        suspiciousOperations: this.suspiciousOps,
        recommendations: this.suspiciousOps.length > 0 ?
          ["Review delegate calls", "Verify contract security"] :
          ["Transaction appears safe"]
      };
    }
  }`
}
```

### Gas Optimization Tracer

Identify expensive operations for gas optimization:

```javascript
{
  "tracer": `{
    expensive: [],
    threshold: 1000, // Gas cost threshold

    step: function(log, db) {
      var cost = log.getCost();
      if (cost > this.threshold) {
        this.expensive.push({
          pc: log.getPC(),
          op: log.op.toString(),
          cost: cost,
          gas: log.getGas()
        });
      }
    },

    result: function(ctx, db) {
      // Sort by cost descending
      this.expensive.sort((a, b) => b.cost - a.cost);

      return {
        expensiveOperations: this.expensive.slice(0, 20),
        totalExpensiveCost: this.expensive.reduce((sum, op) => sum + op.cost, 0),
        optimizationPotential: this.expensive.length > 0
      };
    }
  }`
}
```

## Performance Optimization

<Warning>**Performance**: JavaScript tracers can significantly slow down tracing. Optimize your tracer code and use timeouts for production use.</Warning>

### Memory-Efficient Patterns

```javascript
// ✅ Efficient - Use summary data
{
  "tracer": `{
    summary: {
      totalGas: 0,
      operationCounts: {},
      maxStackDepth: 0
    },

    step: function(log, db) {
      // Update counters instead of storing arrays
      this.summary.totalGas += log.getCost();

      var op = log.op.toString();
      this.summary.operationCounts[op] = (this.summary.operationCounts[op] || 0) + 1;

      var stackDepth = log.stack.length();
      if (stackDepth > this.summary.maxStackDepth) {
        this.summary.maxStackDepth = stackDepth;
      }
    },

    result: function(ctx, db) {
      return this.summary;
    }
  }`
}
```

### Selective Operation Tracking

```javascript
{
  "tracer": `{
    data: [],
    counter: 0,
    maxEntries: 1000, // Limit data collection

    step: function(log, db) {
      // Only track specific operations
      var op = log.op.toString();
      if ((op == "SSTORE" || op == "SLOAD") && this.counter < this.maxEntries) {
        this.data.push([
          log.getPC(),
          op,
          log.getCost()
        ]);
        this.counter++;
      }
    },

    result: function(ctx, db) {
      return {
        operations: this.data,
        truncated: this.counter >= this.maxEntries
      };
    }
  }`
}
```

## Configuration Options

### Basic Configuration

```json
{
  "tracer": "your-javascript-tracer",
  "tracerConfig": {
    "timeout": "30s",
    "enableMemory": false,
    "enableStack": false,
    "enableStorage": false,
    "enableReturnData": true
  }
}
```

### Production Settings

```json
{
  "tracerConfig": {
    "timeout": "60s", // Longer timeout for complex traces
    "enableMemory": false, // Disable to save memory
    "enableStack": false, // Disable to save memory
    "enableStorage": true, // Enable only if needed
    "enableReturnData": true // Usually safe to enable
  }
}
```

## Practical Integration Examples

### Smart Contract Debugger

```solidity
contract TransactionAnalyzer {
    struct TraceResult {
        uint256 gasUsed;
        uint256 operationCount;
        bool hasErrors;
    }

    event TransactionTraced(
        bytes32 indexed txHash,
        uint256 gasUsed,
        uint256 operationCount
    );

    function analyzeTransaction(
        bytes32 txHash,
        string memory tracerCode
    ) external {
        // Off-chain: Use the tracer to analyze the transaction
        // On-chain: Process and store the results

        // This would typically be called by an oracle or off-chain service
        // that performs the tracing and submits results
    }
}
```

### DeFi Analytics Dashboard

```javascript
// Off-chain analytics service
class DeFiAnalytics {
  async analyzeSwap(txHash) {
    const swapTracer = `{
            swaps: [],
            
            step: function(log, db) {
                if (log.op.toString() == "LOG3") {
                    // Detect swap events
                    var topic0 = log.stack.peek(2).toString(16);
                    if (topic0 == "swap_event_signature") {
                        this.swaps.push({
                            contract: log.contract.getAddress().toString(),
                            // ... extract swap data
                        });
                    }
                }
            },
            
            result: function(ctx, db) {
                return { swaps: this.swaps };
            }
        }`;

    const result = await this.traceTransaction(txHash, swapTracer);
    return this.processSwapData(result);
  }
}
```

## Best Practices

1. **Start Simple**: Begin with basic tracers before adding complexity
2. **Limit Data Collection**: Only collect necessary information
3. **Use Efficient Data Structures**: Prefer counters over arrays when possible
4. **Set Appropriate Timeouts**: Balance thoroughness with performance
5. **Test Incrementally**: Validate tracers on simple transactions first
6. **Handle Errors Gracefully**: Include error handling in your tracers

## Common Use Cases

### Gas Profiling

```javascript
const gasProfiler = `{
  profile: {},
  
  step: function(log, db) {
    var op = log.op.toString();
    var cost = log.getCost();
    
    if (!this.profile[op]) {
      this.profile[op] = { count: 0, totalCost: 0 };
    }
    
    this.profile[op].count++;
    this.profile[op].totalCost += cost;
  },
  
  result: function(ctx, db) {
    // Calculate averages
    for (var op in this.profile) {
      this.profile[op].avgCost = this.profile[op].totalCost / this.profile[op].count;
    }
    return this.profile;
  }
}`;
```

### Event Extraction

```javascript
const eventExtractor = `{
  events: [],
  
  step: function(log, db) {
    var op = log.op.toString();
    if (op.startsWith("LOG")) {
      this.events.push({
        address: log.contract.getAddress().toString(),
        topics: this.extractTopics(log),
        data: this.extractData(log)
      });
    }
  },
  
  extractTopics: function(log) {
    // Implementation depends on log structure
    return [];
  },
  
  result: function(ctx, db) {
    return { events: this.events };
  }
}`;
```

<Info>**Need Help?** If you encounter issues with JavaScript tracers, check out our [Troubleshooting Guide](/evm/tracing/troubleshooting) for common solutions and debugging tips.</Info>

---

## Troubleshooting Guide

*Resolve common EVM transaction tracing errors on Paxeer, including timeouts, memory limits, and JavaScript tracer issues, with practical fixes.*

This guide covers common issues encountered when using EVM transaction tracing on Paxeer and provides practical solutions to resolve them.

## Common Error Categories

### 1. Timeout Errors

**Error**: `execution timeout`

**Cause**: Tracer execution exceeded the configured timeout duration.

**Solutions**:

```json
{
  "tracerConfig": {
    "timeout": "120s" // Increase timeout for complex traces
  }
}
```

**Best Practices**:

- Start with shorter timeouts (30s) for testing
- Increase gradually based on transaction complexity
- Use built-in tracers when possible (they're faster)
- Optimize JavaScript tracer code for performance

### 2. Memory Limit Errors

**Error**: `out of memory` or `memory limit exceeded`

**Cause**: Tracer collected too much data or inefficient memory usage.

**Solutions**:

```json
{
  "tracerConfig": {
    "enableMemory": false, // Disable memory tracing
    "enableStack": false, // Disable stack tracing
    "enableStorage": false // Disable storage tracing
  }
}
```

**Memory-Efficient Tracer Pattern**:

```javascript
{
  "tracer": `{
    // Use counters instead of arrays
    summary: {
      totalGas: 0,
      operationCount: 0,
      expensiveOps: 0
    },

    step: function(log, db) {
      this.summary.totalGas += log.getCost();
      this.summary.operationCount++;

      // Only track expensive operations
      if (log.getCost() > 1000) {
        this.summary.expensiveOps++;
      }
    },

    result: function(ctx, db) {
      return this.summary; // Return summary, not raw data
    }
  }`
}
```

### 3. JavaScript Tracer Errors

**Error**: `SyntaxError` or `ReferenceError` in JavaScript tracer

**Common Issues**:

```javascript
// ❌ Incorrect - Missing quotes
{
  "tracer": `{
    step: function(log, db) {
      var op = log.op.toString();
      if (op == SSTORE) { // Missing quotes around SSTORE
        // ...
      }
    }
  }`
}

// ✅ Correct - Proper quotes
{
  "tracer": `{
    step: function(log, db) {
      var op = log.op.toString();
      if (op == "SSTORE") { // Quoted properly
        // ...
      }
    }
  }`
}
```

**Debugging JavaScript Tracers**:

```javascript
{
  "tracer": `{
    errors: [],

    step: function(log, db) {
      try {
        // Your tracer logic here
        var op = log.op.toString();
        // ...
      } catch (e) {
        this.errors.push({
          error: e.toString(),
          pc: log.getPC(),
          op: log.op.toString()
        });
      }
    },

    result: function(ctx, db) {
      return {
        data: this.data,
        errors: this.errors // Check for errors
      };
    }
  }`
}
```

### 4. Network and Connection Issues

**Error**: `connection refused` or `network timeout`

**Solutions**:

```bash
# Check if node is running
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://localhost:8545

# Test with different timeout
curl --connect-timeout 30 --max-time 120 \
  -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":["0x..."],"id":1}' \
  http://localhost:8545
```

### 5. Transaction Not Found

**Error**: `transaction not found`

**Debugging Steps**:

```bash
# 1. Verify transaction exists
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0x..."],"id":1}' \
  http://localhost:8545

# 2. Check if transaction is in a finalized block
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x..."],"id":1}' \
  http://localhost:8545

# 3. Ensure node is fully synced
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
  http://localhost:8545
```

## Performance Optimization

### Tracer Performance Tips

1. **Limit Data Collection**:

```javascript
{
  "tracer": `{
    data: [],
    maxEntries: 1000, // Limit data collection

    step: function(log, db) {
      if (this.data.length < this.maxEntries) {
        // Only collect limited data
        this.data.push({
          pc: log.getPC(),
          op: log.op.toString(),
          gas: log.getGas()
        });
      }
    }
  }`
}
```

2. **Use Efficient Data Structures**:

```javascript
// ❌ Inefficient - Object lookups
{
  "tracer": `{
    operations: {},

    step: function(log, db) {
      var op = log.op.toString();
      if (!this.operations[op]) {
        this.operations[op] = 0;
      }
      this.operations[op]++;
    }
  }`
}

// ✅ Efficient - Direct assignment
{
  "tracer": `{
    operations: {},

    step: function(log, db) {
      var op = log.op.toString();
      this.operations[op] = (this.operations[op] || 0) + 1;
    }
  }`
}
```

3. **Selective Tracing**:

```javascript
{
  "tracer": `{
    step: function(log, db) {
      var op = log.op.toString();

      // Only trace specific operations
      if (op == "SSTORE" || op == "SLOAD" || op == "CALL") {
        // Process only important operations
        this.processOperation(log, db);
      }
    }
  }`
}
```

### Node Configuration for Better Performance

```toml
# In your node configuration
[evm]
# Increase trace timeout
trace-timeout = "300s"

# Increase memory limits
trace-memory-limit = "1GB"

# Enable trace caching
trace-cache-size = 1000
```

## Debugging Workflows

### 1. Failed Transaction Analysis

```bash
#!/bin/bash

TX_HASH="0x..."

echo "1. Checking if transaction exists..."
curl -s -X POST -H "Content-Type: application/json" \
  --data "{\"jsonrpc\":\"2.0\",\"method\":\"eth_getTransactionByHash\",\"params\":[\"$TX_HASH\"],\"id\":1}" \
  http://localhost:8545 | jq '.result'

echo "2. Getting transaction receipt..."
curl -s -X POST -H "Content-Type: application/json" \
  --data "{\"jsonrpc\":\"2.0\",\"method\":\"eth_getTransactionReceipt\",\"params\":[\"$TX_HASH\"],\"id\":1}" \
  http://localhost:8545 | jq '.result.status'

echo "3. Tracing transaction..."
curl -s -X POST -H "Content-Type: application/json" \
  --data "{\"jsonrpc\":\"2.0\",\"method\":\"debug_traceTransaction\",\"params\":[\"$TX_HASH\",{\"tracer\":\"callTracer\"}],\"id\":1}" \
  http://localhost:8545 | jq '.result'
```

### 2. Gas Optimization Workflow

```javascript
// Step 1: Identify expensive operations
const expensiveOpsTracer = `{
  expensive: [],
  threshold: 1000,
  
  step: function(log, db) {
    var cost = log.getCost();
    if (cost > this.threshold) {
      this.expensive.push({
        pc: log.getPC(),
        op: log.op.toString(),
        cost: cost
      });
    }
  },
  
  result: function(ctx, db) {
    this.expensive.sort((a, b) => b.cost - a.cost);
    return {
      totalExpensive: this.expensive.length,
      topExpensive: this.expensive.slice(0, 10)
    };
  }
}`;

// Step 2: Analyze storage operations
const storageTracer = `{
  storageOps: 0,
  storageGas: 0,
  
  step: function(log, db) {
    var op = log.op.toString();
    if (op == "SSTORE" || op == "SLOAD") {
      this.storageOps++;
      this.storageGas += log.getCost();
    }
  },
  
  result: function(ctx, db) {
    return {
      storageOperations: this.storageOps,
      storageGasCost: this.storageGas,
      averageCost: this.storageOps > 0 ? this.storageGas / this.storageOps : 0
    };
  }
}`;
```

## Error Code Reference

### Common HTTP Error Codes

| Code | Error                 | Solution                                     |
| ---- | --------------------- | -------------------------------------------- |
| 400  | Bad Request           | Check JSON-RPC format and parameters         |
| 404  | Not Found             | Verify transaction hash and node sync status |
| 500  | Internal Server Error | Check node logs and resource limits          |
| 503  | Service Unavailable   | Node may be syncing or overloaded            |

### Tracer-Specific Errors

| Error               | Cause                         | Solution                                         |
| ------------------- | ----------------------------- | ------------------------------------------------ |
| `execution timeout` | Tracer took too long          | Increase timeout or optimize tracer              |
| `out of memory`     | Too much data collected       | Reduce data collection or disable memory tracing |
| `invalid tracer`    | JavaScript syntax error       | Validate tracer syntax                           |
| `tracer not found`  | Built-in tracer doesn't exist | Check available tracers                          |

## Best Practices Summary

### ✅ Do's

- **Start Simple**: Begin with built-in tracers before custom JavaScript
- **Set Timeouts**: Always configure appropriate timeouts
- **Limit Data**: Collect only necessary information
- **Test Incrementally**: Test tracers on simple transactions first
- **Monitor Resources**: Watch memory and CPU usage
- **Cache Results**: Store expensive trace results when possible

### ❌ Don'ts

- **Don't Collect Everything**: Avoid tracing all operations unnecessarily
- **Don't Ignore Errors**: Always handle tracer errors gracefully
- **Don't Use Complex Logic**: Keep tracer step functions simple
- **Don't Forget Timeouts**: Never run tracers without timeout limits
- **Don't Trace in Production**: Avoid heavy tracing on production nodes

## Getting Help

If you encounter issues not covered in this guide:

1. **Check Node Logs**: Look for error messages in your Paxeer node logs
2. **Verify Configuration**: Ensure your node has tracing enabled
3. **Test Connectivity**: Confirm RPC endpoints are accessible
4. **Simplify Tracers**: Try built-in tracers first
5. **Community Support**: Ask in the [Paxeer Discord](https://discord.gg/paxeer) #dev-support channel

<Info>When reporting issues, include your tracer code, the transaction hash, and any error messages you receive. This helps the community provide better assistance.</Info>

---

## Address Precompile

*Learn how the Paxeer Address precompile lets EVM contracts associate and query Cosmos and EVM addresses for seamless cross-chain identity management.*

**Address:** `0x0000000000000000000000000000000000001004`

The Paxeer Address precompile allows EVM applications to interact directly with Paxeer's address association system through standard smart contract calls. This enables querying and creating mappings between EVM addresses and their corresponding Cosmos addresses, enabling seamless cross-chain address management without needing separate Cosmos SDK integration.

<Info> **What is a precompile?** A precompile is a special smart contract deployed at a fixed address by the Paxeer protocol itself, that exposes custom native chain logic to EVM-based applications. It acts like a regular contract from the EVM's perspective, but executes privileged, low-level logic efficiently. </Info>

## How Does the Address Precompile Work?

The Address precompile at address `0x0000000000000000000000000000000000001004` exposes functions like `associate()`, `associatePubKey()`, `getSeiAddr()`, and `getEvmAddr()`.

- **Direct Integration:** EVM contracts and dApps can call address association functions like any other smart contract method.
- **Native Execution:** Operations are executed at the Cosmos SDK level for maximum efficiency and security.
- **Seamless Bridge:** No need for separate wallet integrations or complex cross-chain interactions.

## Use Cases

- **Cross-Chain Identity:** Link EVM and Cosmos addresses for unified user experiences across both execution environments.
- **Address Resolution:** Build applications that can seamlessly work with both EVM and Cosmos address formats.
- **Wallet Integration:** Enable users to associate their addresses once and use both EVM and native Paxeer functionality.
- **DeFi Applications:** Create protocols that can interact with users regardless of their preferred address format.

## What You'll Learn in This Guide

By the end of this guide, you'll be able to:

- **Integrate Address Operations** - Call association and lookup functions directly from your EVM contracts and dApps
- **Handle Signature Verification** - Master the signature format requirements for secure address association
- **Manage Address Mappings** - Query and validate address relationships between EVM and Cosmos formats
- **Build Cross-Chain Tools** - Implement unified address management for applications spanning both execution environments
- **Navigate Association Requirements** - Understand when and how address association occurs automatically vs. manually

## Functions

The Address precompile exposes the following functions:

### Transaction Functions

```solidity
/// Associates an account given it's signature of any custom message.
/// @param v The v component of the signature.
/// @param r The r component of the signature.
/// @param s The s component of the signature.
/// @param customMessage A custom message that was signed by the address to be associated.
/// @return seiAddr The associated Paxeer address.
/// @return evmAddr The associated EVM address.
function associate(
    string memory v,
    string memory r,
    string memory s,
    string memory customMessage
) external returns (string memory seiAddr, address evmAddr);

/// Associates an account given it's compressed pubkey in hex format (excluding the '0x')
/// @param pubKeyHex The Hex-encoded compressed pubkey of the account to be associated, excluding the '0x'
/// @return seiAddr The associated Paxeer address.
/// @return evmAddr The associated EVM address.
function associatePubKey(
    string memory pubKeyHex
) external returns (string memory seiAddr, address evmAddr);
```

### Query Functions

```solidity
/// Queries the corresponding Paxeer Address for some EVM address.
/// @param addr The EVM Address for which we want the corresponding Paxeer address.
/// @return response The corresponding Paxeer address.
function getSeiAddr(
    address addr
) external view returns (string memory response);

/// Queries the corresponding EVM Address for some Paxeer address.
/// @param addr The Paxeer Address for which we want the corresponding EVM address.
/// @return response The corresponding EVM address.
function getEvmAddr(
    string memory addr
) external view returns (address response);
```

## Using the Precompile

### Setup

#### Prerequisites

Before getting started, ensure you have:

- **Node.js** (v18 or higher)
- **npm** or **yarn** package manager
- **EVM-compatible wallet**
- **HPX tokens** for gas
- **Hardhat** development environment set up

#### Install Dependencies

Install the required packages for interacting with Paxeer precompiles:

```bash
# Initiate a Hardhat 3 project (choose "Hardhat 3" and the Mocha + Ethers.js TypeScript setup)
npx hardhat --init

# Install ethers.js for smart contract interactions
npm install ethers

# Install Paxeer EVM bindings for precompile addresses and ABIs
npm install @sei-js/precompiles@2.1.2
```

#### Setup Hardhat Environment

Create a `hardhat.config.ts` file with the following content:

```typescript
import { defineConfig, configVariable } from 'hardhat/config';
import hardhatToolboxMochaEthers from '@nomicfoundation/hardhat-toolbox-mocha-ethers';

export default defineConfig({
  solidity: '0.8.28',
  networks: {
    hpx: {
      type: 'http',
      chainId: 1329,
      url: 'https://evm-rpc.sei-apis.com',
      accounts: [configVariable('PRIVATE_KEY')]
    }
  },
  plugins: [hardhatToolboxMochaEthers]
});
```

Store your private key in Hardhat's encrypted keystore (no plaintext `.env` file needed):

```bash
npx hardhat keystore set PRIVATE_KEY
```

#### Import Precompile Components

<Tabs>
<Tab title="JavaScript">
```typescript
// Import Address precompile address and ABI
// View the entire ABI here: https://github.com/paxeer-network/paxeer-chain/tree/main/precompiles/addr
import { ADDRESS_PRECOMPILE_ABI, ADDRESS_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';
import { ethers } from 'ethers';
```

</Tab>
<Tab title="Solidity">
```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IAddrPrecompile {
function associate(
string memory v,
string memory r,
string memory s,
string memory customMessage
) external returns (string memory seiAddr, address evmAddr);

function associatePubKey(
string memory pubKeyHex
) external returns (string memory seiAddr, address evmAddr);

function getSeiAddr(address addr) external view returns (string memory response);

function getEvmAddr(string memory addr) external view returns (address response);

}

````
</Tab>
</Tabs>

<Info> **Precompile Address:** The address precompile is deployed at `0x0000000000000000000000000000000000001004` </Info>

### Contract Initialization

<Tabs>
<Tab title="JavaScript">
Set up your provider, signer, and contract instance:

```typescript
// Using EVM-compatible wallet as the signer and provider
const provider = new ethers.BrowserProvider(window.ethereum);
await provider.send('eth_requestAccounts', []);
const signer = await provider.getSigner();

// Create a contract instance for the addr precompile
const addr = new ethers.Contract(ADDRESS_PRECOMPILE_ADDRESS, ADDRESS_PRECOMPILE_ABI, signer);
````

</Tab>
<Tab title="Solidity">
```solidity
// Initialize the contract instance in your Solidity code
contract CrossChainAddressManager {
  IAddrPrecompile constant ADDR = IAddrPrecompile(0x0000000000000000000000000000000000001004);
}
```
</Tab>
</Tabs>

#### When Does Association Happen?

Address association between EVM and Cosmos addresses occurs automatically in most cases:

| Method | Trigger | Requirements |
| --- | --- | --- |
| **Automatic** | First transaction broadcast | Wallet signs any transaction |
| **Manual (Signature)** | associate() function | Custom message signature |
| **Manual (PubKey)** | associatePubKey() function | Compressed public key |


### How Association Works

**Automatic Association:**

- Occurs when a wallet first signs and broadcasts any transaction on Paxeer
- No additional steps required for most users
- Association is permanent once created

**Manual Association:**

- Use `associate()` for signature-based association
- Use `associatePubKey()` for public key-based association
- Useful for advanced applications or when automatic association hasn't occurred

### Address Format Requirements

**EVM Addresses:**

- Standard Ethereum format: `0x1234...` (20 bytes, 40 hex characters)
- Case-insensitive but typically lowercase

**Paxeer Addresses:**

- Cosmos format with `pax1...` prefix for regular addresses
- Validator addresses use `paxvaloper1...` prefix
- Bech32 encoding format

## Step-by-Step Guide: Using the Address Precompile

### Associate Address with Signature

<Tabs>
<Tab title="JavaScript">

```typescript
// Associate addresses using a custom message signature
const message = `Associate my addresses - ${Date.now()}`;

try {
  // Get signature from user's wallet
  const signature = await signer.signMessage(message);
  const sig = ethers.Signature.from(signature);

  // Reconstruct the EIP-191 prefixed message that signMessage() actually signed:
  // "\x19Ethereum Signed Message:\n" + message length + message
  const customMessage = `\x19Ethereum Signed Message:\n${message.length}${message}`;

  // Convert signature components to strings
  const v = (sig.v - 27).toString();
  const r = sig.r;
  const s = sig.s;

  // Call associate function
  const tx = await addr.associate(v, r, s, customMessage);
  const receipt = await tx.wait();

  console.log('Association successful:', receipt);
} catch (error) {
  console.error('Association failed:', error);
}
```

</Tab>
<Tab title="Solidity">

```solidity
contract AddressManager {
    IAddrPrecompile constant ADDR = IAddrPrecompile(0x0000000000000000000000000000000000001004);

    event AddressAssociated(address indexed evmAddr, string seiAddr);

    function associateMyAddress(
        string memory v,
        string memory r,
        string memory s,
        string memory customMessage
    ) external {
        (string memory seiAddr, address evmAddr) = ADDR.associate(v, r, s, customMessage);

        // Verify the association is for the caller
        require(evmAddr == msg.sender, "Association mismatch");

        emit AddressAssociated(evmAddr, seiAddr);
    }
}
```

</Tab>
</Tabs>

### Associate Address with Public Key

<Tabs>
<Tab title="JavaScript">

```typescript
// Associate addresses using a public key
try {
  // Create or get a wallet's public key
  const wallet = ethers.Wallet.createRandom();
  const pubKeyWithout0x = wallet.signingKey.compressedPublicKey.slice(2);

  // Call associatePubKey function
  const tx = await addr.associatePubKey(pubKeyWithout0x);
  const receipt = await tx.wait();

  console.log('Public key association successful:', receipt);
} catch (error) {
  console.error('Public key association failed:', error);
}
```

</Tab>
<Tab title="Solidity">

```solidity
contract AddressManager {
    IAddrPrecompile constant ADDR = IAddrPrecompile(0x0000000000000000000000000000000000001004);

    event AddressAssociated(address indexed evmAddr, string seiAddr);

    function associateWithPubKey(string memory pubKeyHex) external {
        (string memory seiAddr, address evmAddr) = ADDR.associatePubKey(pubKeyHex);

        // Store or emit the association
        emit AddressAssociated(evmAddr, seiAddr);
    }
}
```

</Tab>
</Tabs>

### Query Paxeer Address from EVM Address

<Tabs>
<Tab title="JavaScript">

```typescript
// Query the Paxeer address for a given EVM address
const evmAddress = '0x1234567890123456789012345678901234567890';

try {
  const seiAddress = await addr.getSeiAddr(evmAddress);
  console.log('Corresponding Paxeer address:', seiAddress);
} catch (error) {
  if (error.message.includes('not found') || error.message.includes('no association')) {
    console.log('No association found for this EVM address');
  } else {
    console.error('Error querying Paxeer address:', error);
  }
}
```

</Tab>
<Tab title="Solidity">

```solidity
contract AddressManager {
    IAddrPrecompile constant ADDR = IAddrPrecompile(0x0000000000000000000000000000000000001004);

    function getUserSeiAddress(address evmAddr) external view returns (string memory) {
        return ADDR.getSeiAddr(evmAddr);
    }

    // Safe version with error handling
    function tryGetUserSeiAddress(address evmAddr) external view returns (bool success, string memory seiAddr) {
        try ADDR.getSeiAddr(evmAddr) returns (string memory result) {
            return (true, result);
        } catch {
            return (false, "");
        }
    }
}
```

</Tab>
</Tabs>

### Query EVM Address from Paxeer Address

<Tabs>
<Tab title="JavaScript">

```typescript
// Query the EVM address for a given Paxeer address
const seiAddress = 'pax1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq6s8dpw';

try {
  const evmAddress = await addr.getEvmAddr(seiAddress);
  console.log('Corresponding EVM address:', evmAddress);
} catch (error) {
  if (error.message.includes('not found') || error.message.includes('no association')) {
    console.log('No association found for this Paxeer address');
  } else {
    console.error('Error querying EVM address:', error);
  }
}
```

</Tab>
<Tab title="Solidity">

```solidity
contract AddressManager {
    IAddrPrecompile constant ADDR = IAddrPrecompile(0x0000000000000000000000000000000000001004);

    function getEvmFromSei(string memory seiAddr) external view returns (address) {
        return ADDR.getEvmAddr(seiAddr);
    }

    // Safe version with error handling
    function tryGetEvmFromSei(string memory seiAddr) external view returns (bool success, address evmAddr) {
        try ADDR.getEvmAddr(seiAddr) returns (address result) {
            return (true, result);
        } catch {
            return (false, address(0));
        }
    }
}
```

</Tab>
</Tabs>

### Complete Integration Example

<Tabs>
<Tab title="JavaScript">

```typescript
import { ADDRESS_PRECOMPILE_ABI, ADDRESS_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';
import { ethers } from 'ethers';

async function addrExample() {
  // Setup
  const provider = new ethers.BrowserProvider(window.ethereum);
  await provider.send('eth_requestAccounts', []);
  const signer = await provider.getSigner();
  const addr = new ethers.Contract(ADDRESS_PRECOMPILE_ADDRESS, ADDRESS_PRECOMPILE_ABI, signer);

  const evmAddress = await signer.getAddress();

  try {
    // 1. Check if current EVM address has an associated Paxeer address
    console.log('=== Checking Current Association ===');
    try {
      const associatedPax = await addr.getSeiAddr(evmAddress);
      console.log('EVM address:', evmAddress);
      console.log('Associated Paxeer address:', associatedPax);

      // Verify reverse lookup
      const reverseEvm = await addr.getEvmAddr(associatedPax);
      console.log('Reverse lookup EVM address:', reverseEvm);
    } catch (error) {
      if (error.message.includes('not found') || error.message.includes('no association')) {
        console.log('No association found. You may need to make a transaction first or associate manually.');

        // 2. Demonstrate manual association with public key
        console.log('=== Creating Manual Association ===');
        const wallet = ethers.Wallet.createRandom();
        const pubKeyWithout0x = wallet.signingKey.compressedPublicKey.slice(2);

        const associateTx = await addr.associatePubKey(pubKeyWithout0x);
        const receipt = await associateTx.wait();
        console.log('Manual association completed:', receipt.transactionHash);
      } else {
        throw error;
      }
    }

    // 3. Demonstrate address resolution for different formats
    console.log('=== Address Resolution Examples ===');

    // Test with known Paxeer address format
    const testSeiAddr = 'pax1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq6s8dpw';
    try {
      const correspondingEvm = await addr.getEvmAddr(testSeiAddr);
      console.log('Test Paxeer address:', testSeiAddr);
      console.log('Corresponding EVM address:', correspondingEvm);
    } catch (error) {
      console.log('Test address not associated:', testSeiAddr);
    }
  } catch (error) {
    console.error('Operation failed:', error);
  }
}
```

</Tab>
<Tab title="Solidity">

**Contract Example**

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IAddrPrecompile {
    function associate(
        string memory v,
        string memory r,
        string memory s,
        string memory customMessage
    ) external returns (string memory seiAddr, address evmAddr);

    function associatePubKey(
        string memory pubKeyHex
    ) external returns (string memory seiAddr, address evmAddr);

    function getSeiAddr(address addr) external view returns (string memory response);

    function getEvmAddr(string memory addr) external view returns (address response);
}

contract CrossChainAddressManager {
    IAddrPrecompile constant ADDR = IAddrPrecompile(0x0000000000000000000000000000000000001004);

    struct UserProfile {
        address evmAddress;
        string seiAddress;
        bool isVerified;
    }

    mapping(address => UserProfile) public userProfiles;
    mapping(string => address) public paxToEvm;

    event UserRegistered(address indexed evmAddr, string seiAddr);
    event AddressAssociated(address indexed evmAddr, string seiAddr);

    /**
     * @dev Register user with automatic address association lookup
     */
    function registerUser() external {
        address userEvm = msg.sender;

        // Try to get associated Paxeer address
        try ADDR.getSeiAddr(userEvm) returns (string memory seiAddr) {
            // Association exists
            userProfiles[userEvm] = UserProfile({
                evmAddress: userEvm,
                seiAddress: seiAddr,
                isVerified: true
            });

            paxToEvm[seiAddr] = userEvm;
            emit UserRegistered(userEvm, seiAddr);

        } catch {
            // No association found
            revert("Address not associated. Please associate your addresses first.");
        }
    }

    /**
     * @dev Batch query multiple EVM addresses
     */
    function batchGetSeiAddresses(
        address[] memory evmAddresses
    ) external view returns (string[] memory seiAddresses) {
        seiAddresses = new string[](evmAddresses.length);

        for (uint256 i = 0; i < evmAddresses.length; i++) {
            try ADDR.getSeiAddr(evmAddresses[i]) returns (string memory seiAddr) {
                seiAddresses[i] = seiAddr;
            } catch {
                seiAddresses[i] = ""; // Empty string if not associated
            }
        }
    }

    /**
     * @dev Check if an address pair is associated
     */
    function areAddressesAssociated(
        address evmAddr,
        string memory seiAddr
    ) external view returns (bool) {
        try ADDR.getSeiAddr(evmAddr) returns (string memory result) {
            return keccak256(bytes(result)) == keccak256(bytes(seiAddr));
        } catch {
            return false;
        }
    }
}
```

**Client Integration Example**

Deploy the contract:

```javascript
import { network } from 'hardhat';

// Hardhat 3 exposes ethers through a network connection rather than a global import
const { ethers } = await network.create();

async function main() {
  // The signer comes from the network config (encrypted keystore)
  const [deployer] = await ethers.getSigners();
  console.log('Deploying contracts with the account:', deployer.address);

  const balance = await deployer.provider.getBalance(deployer.address);
  console.log('Account balance:', ethers.formatEther(balance));

  const AddressManager = await ethers.getContractFactory('CrossChainAddressManager');
  console.log('Deploying AddressManager...', AddressManager);
  const addressManager = await AddressManager.deploy({
    gasLimit: 5000000n // Set a reasonable gas limit
  });
  await addressManager.waitForDeployment();

  console.log('AddressManager deployed to:', await addressManager.getAddress());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

Then run:

```bash
npx hardhat run scripts/deploy.js --network paxeer
```

```javascript
import { network } from 'hardhat';
// Path is relative to this file in scripts/ - Hardhat writes artifacts to the project root
import addressManagerAbi from '../artifacts/evm/evm-general/CrossChainAddressManager.sol/CrossChainAddressManager.json' with { type: 'json' };

// Hardhat 3 exposes ethers through a network connection rather than a global import
const { ethers } = await network.create();

async function main() {
  // The signer comes from the network config (encrypted keystore)
  const [deployer] = await ethers.getSigners();
  console.log('Interacting with the account:', deployer.address);

  const balance = await deployer.provider.getBalance(deployer.address);
  console.log('Account balance:', ethers.formatEther(balance));

  const addressManagerAddress = '0xYourAddressManagerContractAddress'; // Replace with your deployed contract address
  const addressManager = new ethers.Contract(addressManagerAddress, addressManagerAbi.abi, deployer);
  console.log('AddressManager deployed to:', await addressManager.getAddress());

  // Register user (requires existing address association)
  try {
    const registerTx = await addressManager.registerUser();
    await registerTx.wait();
    console.log('User registered successfully');

    // Get user's profile
    const userProfile = await addressManager.userProfiles(deployer.address);
    console.log('User profile:', userProfile);
  } catch (error) {
    console.error('Registration failed:', error);
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

Then run the interaction script:

```bash
npx hardhat run scripts/interact.js --network paxeer
```

</Tab>
</Tabs>

## Security Considerations & Risks

### Association Permanence

- **Permanent Mapping:** Once addresses are associated, the mapping cannot be changed or removed
- **Single Association:** Each address can only be associated with one counterpart
- **Verification:** Always verify associations before depending on them in critical operations

### Signature Security

- **Custom Messages:** Use unique, timestamped messages to prevent replay attacks
- **Message Format:** Follow exact Ethereum Signed Message format for compatibility

## Troubleshooting

### Common Issues and Solutions

#### Gas-Related Issues

```typescript
// Set appropriate gas limits for different operations
const associateTx = await addr.associate(v, r, s, customMessage, {
  gasLimit: 200000 // Association operations
});

const pubKeyTx = await addr.associatePubKey(pubKeyHex, {
  gasLimit: 150000 // Public key association
});
```

### Error Code Reference

| Error | Cause | Solution |
| --- | --- | --- |
| `invalid signature` | Malformed v, r, s components | Verify signature parsing and format |
| `already associated` | Address already has association | Check existing association instead |
| `not found` | No association exists | Create association first |
| `invalid public key` | Malformed public key format | Use compressed format without 0x prefix |
| `invalid address format` | Wrong address format | Use proper EVM (0x...) or Paxeer (pax1...) format |


## Important Notes

<Info> Remember: Address associations are permanent and cannot be changed once created! </Info>

### Address Formats

- **EVM Addresses:** Use standard Ethereum format with `0x` prefix
- **Paxeer Addresses:** Use Cosmos format with `pax1` prefix for regular addresses
- **Case Sensitivity:** EVM addresses are case-insensitive, Paxeer addresses are case-sensitive

### Association Timing

- **Automatic:** Most users get associated automatically on their first transaction
- **Manual:** Use precompile functions for programmatic association or when automatic association hasn't occurred
- **Verification:** Always verify associations exist before depending on them

### Signature Requirements

- **Message Format:** Must include Ethereum Signed Message prefix for `associate()` function
- **Component Format:** v, r, s must be properly formatted hex strings
- **Replay Protection:** Use unique messages to prevent signature replay attacks

### Gas Considerations

- **Association operations:** ~200,000 gas limit recommended
- **Query operations:** Standard view function gas usage
- **Batch operations:** Scale gas limits based on array size

<Info>View the Address precompile source code and the contract ABI [here](https://github.com/paxeer-network/paxeer-chain/tree/main/precompiles/addr).</Info>

---

## Bank Precompile

*Learn how Paxeer's Bank Precompile at 0x1001 lets EVM contracts send tokens, query balances, and fetch metadata for HPX and IBC assets.*

**Address:** `0x0000000000000000000000000000000000001001`

The Paxeer bank precompile allows EVM applications to interact directly with Paxeer's native banking system through standard smart contract calls. This enables querying balances, transferring tokens, and accessing token metadata for both native HPX tokens and Cosmos SDK-based assets, providing seamless integration between EVM and Cosmos ecosystems.

<Info> **What is a precompile?** A precompile is a special smart contract deployed at a fixed address by the Paxeer protocol itself, that exposes custom native chain logic to EVM-based applications. It acts like a regular contract from the EVM's perspective, but executes privileged, low-level logic efficiently. </Info>

## How Does the Bank Precompile Work?

The bank precompile at address `0x0000000000000000000000000000000000001001` exposes functions like `send()`, `sendNative()`, `balance()`, `all_balances()`, and token metadata queries.

- **Direct Integration:** EVM contracts and dApps can call banking functions like any other smart contract method.
- **Native Execution:** Operations are executed at the Cosmos SDK level for maximum efficiency and security.
- **Cross-Chain Assets:** Manage both native HPX tokens and IBC assets seamlessly from EVM contracts.

**When to use `send` vs `sendNative`:** `send` moves an arbitrary `denom` (any IBC or factory token) between two EVM addresses (`0x...`) by reading the balance directly from the bank module - no `msg.value` is attached. It is gated to the registered ERC20 native pointer for that denom, so it is typically invoked from the auto-deployed pointer contract rather than from arbitrary user code. `sendNative` is for sending native HPX (the attached `msg.value`) from the EVM caller to a Cosmos bech32 (`pax1...`) destination, which is useful for crossing the EVM→Cosmos boundary when the recipient has no associated EVM address (for example, paying a Cosmos-only contract or account).

## Use Cases

- **DeFi Applications:** Build decentralized finance protocols that can handle native HPX and Cosmos assets.
- **Portfolio Management:** Build tools to track and manage multi-asset portfolios across Cosmos and EVM.
- **Token Information Services:** Query comprehensive token metadata for UI display and analytics.

## What You'll Learn in This Guide

By the end of this guide, you'll be able to:

- **Execute Token Transfers** - Send both native HPX and custom tokens between addresses
- **Query Account Balances** - Check single and multi-asset balances for any address
- **Access Token Metadata** - Retrieve names, symbols, decimals, and supply information

## Functions

The bank precompile exposes the following functions:

### Transaction Functions

```solidity
/// Sends non-native tokens from one address to another. Callable only by the
/// registered ERC20 native pointer contract for the given denom.
/// @param fromAddress The EVM address (0x...) to send funds from.
/// @param toAddress The EVM address (0x...) to send funds to.
/// @param denom The denomination of funds to send.
/// @param amount The amount of the above denom to send.
/// @return success Whether the send was successfully executed.
function send(
    address fromAddress,
    address toAddress,
    string memory denom,
    uint256 amount
) external returns (bool success);

/// Sends native HPX (the attached msg.value) from the EVM caller to a Cosmos
/// bech32 recipient. Requires a non-zero msg.value.
/// @param toNativeAddress The bech32 (pax1...) address of the recipient.
/// @return success Whether the tokens were successfully sent.
function sendNative(
    string memory toNativeAddress
) payable external returns (bool success);
```

### Query Functions

```solidity
/// Queries the balance of the given account for the specified denom.
/// @param acc The EVM address (0x...) of the account to query.
/// @param denom The denomination to query for.
/// @return amount The amount of denom held by acc.
function balance(
    address acc,
    string memory denom
) external view returns (uint256 amount);

/// Queries the balance of the given account for all balances.
/// @param acc The EVM address (0x...) of the account to query.
/// @return response Balances for all coins/denoms.
function all_balances(
    address acc
) external view returns (Coin[] memory response);

/// Queries the name of the specified denom.
/// @param denom The denomination to query about.
/// @return response The name of the specified denom.
function name(
    string memory denom
) external view returns (string memory response);

/// Queries the symbol of the specified denom.
/// @param denom The denomination to query about.
/// @return response The symbol of the specified denom.
function symbol(
    string memory denom
) external view returns (string memory response);

/// Queries the number of decimal places for the specified denom.
/// @param denom The denomination to query about.
/// @return response The number of decimals for the specified denom.
function decimals(
    string memory denom
) external view returns (uint8 response);

/// Queries the total supply of the specified denom.
/// @param denom The denomination to query about.
/// @return response The total supply of the specified denom.
function supply(
    string memory denom
) external view returns (uint256 response);
```

## Using the Precompile

### Setup

#### Prerequisites

Before getting started, ensure you have:

- **Node.js** (v18 or higher)
- **npm** or **yarn** package manager
- **EVM-compatible wallet**
- **HPX tokens** for gas and testing transfers
- **Hardhat** for development and testing

#### Install Dependencies

Install the required packages for interacting with Paxeer precompiles:

```bash
# Instantiate a new Hardhat 3 project (choose "Hardhat 3" and the Mocha + Ethers.js TypeScript setup)
npx hardhat --init

# Install ethers.js for smart contract interactions
npm install ethers

# Install Paxeer EVM bindings for precompile addresses and ABIs
npm install @sei-js/precompiles@2.1.2
```

#### Setup Hardhat Environment

Create a `hardhat.config.ts` file with the following content:

```typescript
import { defineConfig, configVariable } from 'hardhat/config';
import hardhatToolboxMochaEthers from '@nomicfoundation/hardhat-toolbox-mocha-ethers';

export default defineConfig({
  solidity: '0.8.28',
  networks: {
    hpx: {
      type: 'http',
      chainId: 1329,
      url: 'https://evm-rpc.sei-apis.com',
      accounts: [configVariable('PRIVATE_KEY')]
    }
  },
  plugins: [hardhatToolboxMochaEthers]
});
```

Store your private key in Hardhat's encrypted keystore (no plaintext `.env` file needed):

```bash
npx hardhat keystore set PRIVATE_KEY
```

#### Import Precompile Components

<Tabs>
<Tab title="JavaScript">
```typescript
// Import Bank precompile address and ABI
// View the entire ABI here: https://github.com/paxeer-network/paxeer-chain/tree/main/precompiles/bank
import { BANK_PRECOMPILE_ABI, BANK_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';
import { ethers } from 'ethers';
```

</Tab>
<Tab title="Solidity">
```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

struct Coin {
uint256 amount;
string denom;
}

interface IBankPrecompile {
function send(
address fromAddress,
address toAddress,
string memory denom,
uint256 amount
) external returns (bool success);

    function sendNative(
        string memory toNativeAddress
    ) payable external returns (bool success);

    function balance(
        address acc,
        string memory denom
    ) external view returns (uint256 amount);

    function all_balances(
        address acc
    ) external view returns (Coin[] memory response);

    function name(
        string memory denom
    ) external view returns (string memory response);

    function symbol(
        string memory denom
    ) external view returns (string memory response);

    function decimals(
        string memory denom
    ) external view returns (uint8 response);

    function supply(
        string memory denom
    ) external view returns (uint256 response);

}

````
</Tab>
</Tabs>

<Info> **Precompile Address:** The bank precompile is deployed at `0x0000000000000000000000000000000000001001` </Info>

### Contract Initialization

<Tabs>
<Tab title="JavaScript">
Set up your provider, signer, and contract instance:

```typescript
// Using EVM-compatible wallet as the signer and provider
const provider = new ethers.BrowserProvider(window.ethereum);
await provider.send('eth_requestAccounts', []);
const signer = await provider.getSigner();

// Create a contract instance for the bank precompile
const bank = new ethers.Contract(BANK_PRECOMPILE_ADDRESS, BANK_PRECOMPILE_ABI, signer);
````

</Tab>
<Tab title="Solidity">
```solidity
// Initialize the contract instance in your Solidity code
contract TokenManager {
    IBankPrecompile constant BANK = IBankPrecompile(0x0000000000000000000000000000000000001001);
}
```
</Tab>
</Tabs>

### Native HPX vs Custom Tokens

**Native HPX Transfers:**

- Use `sendNative()` with payable value
- Denomination is always `uhpx` (micro-HPX)
- Parse to 18 digits when calling `sendNative()`

**Custom Token Transfers:**

- Use `send()` with specific denomination
- Requires prior token approval or ownership
- Support various decimal configurations

## Step-by-Step Guide: Using the Bank Precompile

### Send Native HPX Tokens

<Tabs>
<Tab title="JavaScript">

```typescript
// Send native HPX tokens to another address
const recipientAddress = 'pax1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq6s8dpw';
const amountInPax = '0.1'; // 0.1 HPX

try {
  // msg.value is in wei (18 decimals), like any other EVM transaction
  const amountInWei = ethers.parseUnits(amountInPax, 18); // equivalent to ethers.parseEther(amountInPax)

  // Send native HPX
  const tx = await bank.sendNative(recipientAddress, {
    value: amountInWei,
    gasLimit: 300000n
  });

  const receipt = await tx.wait();
  console.log('Native HPX transfer successful:', receipt.hash);
  console.log(`Sent ${amountInPax} HPX to ${recipientAddress}`);
} catch (error) {
  console.error('Native HPX transfer failed:', error);
}
```

</Tab>
<Tab title="Solidity">

```solidity
contract PaymentProcessor {
    IBankPrecompile constant BANK = IBankPrecompile(0x0000000000000000000000000000000000001001);

    event PaymentSent(address indexed from, string to, uint256 amount);

    function sendHpxPayment(string memory recipient) external payable {
        require(msg.value > 0, "Payment amount must be greater than 0");

        bool success = BANK.sendNative{value: msg.value}(recipient);
        require(success, "Payment failed");

        emit PaymentSent(msg.sender, recipient, msg.value);
    }
}
```

</Tab>
</Tabs>

### Send Custom Tokens

<Tabs>
<Tab title="JavaScript">

<Warning>`send()` can only be called by the registered ERC20 native pointer contract for the given denom - calling it from a regular wallet will revert. The snippet below only illustrates the arguments a pointer contract passes. As a user, transfer native denoms through the denom's ERC20 pointer contract (`transfer()`), or use `sendNative()` for HPX.</Warning>

```typescript
// Illustration: how a registered ERC20 pointer contract calls send()
const fromAddress = '0x1234567890123456789012345678901234567890';
const toAddress = '0x9876543210987654321098765432109876543210';
const tokenDenom = 'uhpx';
const amount = '1';

// Amounts are in the denom's base units - check decimals() for each denom.
// uhpx has 6 decimals (1 HPX = 1,000,000 uhpx)
const tx = await bank.send(
  fromAddress,
  toAddress,
  tokenDenom,
  ethers.parseUnits(amount, 6),
  {
    gasLimit: 300000n
  }
);

const receipt = await tx.wait();
console.log('Custom token transfer successful:', receipt.hash);
console.log(`Sent ${amount} ${tokenDenom} from ${fromAddress} to ${toAddress}`);
```

</Tab>
<Tab title="Solidity">

```solidity
contract TokenTransferManager {
    IBankPrecompile constant BANK = IBankPrecompile(0x0000000000000000000000000000000000001001);

    event TokenTransfer(
        address indexed from,
        address indexed to,
        string denom,
        uint256 amount
    );

    function transferTokens(
        address to,
        string memory denom,
        uint256 amount
    ) external {
        // Transfer tokens from sender to recipient
        bool success = BANK.send(msg.sender, to, denom, amount);
        require(success, "Token transfer failed");

        emit TokenTransfer(msg.sender, to, denom, amount);
    }

    function batchTransfer(
        address[] memory recipients,
        string memory denom,
        uint256[] memory amounts
    ) external {
        require(recipients.length == amounts.length, "Array length mismatch");

        for (uint256 i = 0; i < recipients.length; i++) {
            bool success = BANK.send(msg.sender, recipients[i], denom, amounts[i]);
            require(success, "Batch transfer failed");

            emit TokenTransfer(msg.sender, recipients[i], denom, amounts[i]);
        }
    }
}
```

</Tab>
</Tabs>

### Query Account Balance

<Tabs>
<Tab title="JavaScript">

```typescript
// Query specific token balance
const accountAddress = '0x1234567890123456789012345678901234567890';
const tokenDenom = 'uhpx';

try {
  const balance = await bank.balance(accountAddress, tokenDenom);

  // Convert uhpx to HPX for display
  if (tokenDenom === 'uhpx') {
    const hpxBalance = ethers.formatUnits(balance, 6);
    console.log(`HPX Balance: ${hpxBalance} HPX`);
  } else {
    console.log(`${tokenDenom} Balance: ${balance.toString()}`);
  }
} catch (error) {
  console.error('Balance query failed:', error);
}
```

</Tab>
<Tab title="Solidity">

```solidity
contract BalanceChecker {
    IBankPrecompile constant BANK = IBankPrecompile(0x0000000000000000000000000000000000001001);

    function getUserHpxBalance(address user) external view returns (uint256) {
        return BANK.balance(user, "uhpx");
    }

    function getUserTokenBalance(
        address user,
        string memory denom
    ) external view returns (uint256) {
        return BANK.balance(user, denom);
    }

    function hasMinimumBalance(
        address user,
        string memory denom,
        uint256 minAmount
    ) external view returns (bool) {
        uint256 balance = BANK.balance(user, denom);
        return balance >= minAmount;
    }
}
```

</Tab>
</Tabs>

### Query All Balances

<Tabs>
<Tab title="JavaScript">

```typescript
// Query all token balances for an account
const accountAddress = '0x1234567890123456789012345678901234567890';

try {
  const allBalances = await bank.all_balances(accountAddress);

  console.log(`Account: ${accountAddress}`);
  console.log('All Balances:');

  allBalances.forEach((coin, index) => {
    if (coin.denom === 'uhpx') {
      const paxAmount = ethers.formatUnits(coin.amount, 6);
      console.log(`  ${index + 1}. ${paxAmount} HPX (${coin.denom})`);
    } else {
      console.log(`  ${index + 1}. ${coin.amount.toString()} ${coin.denom}`);
    }
  });
} catch (error) {
  console.error('All balances query failed:', error);
}
```

</Tab>
<Tab title="Solidity">

```solidity
contract PortfolioManager {
    IBankPrecompile constant BANK = IBankPrecompile(0x0000000000000000000000000000000000001001);

    struct Portfolio {
        address owner;
        Coin[] balances;
        uint256 totalValue; // In uhpx equivalent
    }

    function getPortfolio(address user) external view returns (Coin[] memory) {
        return BANK.all_balances(user);
    }

    function hasAnyBalance(address user) external view returns (bool) {
        Coin[] memory balances = BANK.all_balances(user);
        return balances.length > 0;
    }

    function countTokenTypes(address user) external view returns (uint256) {
        Coin[] memory balances = BANK.all_balances(user);
        return balances.length;
    }

    function findTokenBalance(
        address user,
        string memory targetDenom
    ) external view returns (uint256) {
        Coin[] memory balances = BANK.all_balances(user);

        for (uint256 i = 0; i < balances.length; i++) {
            if (keccak256(bytes(balances[i].denom)) == keccak256(bytes(targetDenom))) {
                return balances[i].amount;
            }
        }

        return 0; // Token not found
    }
}
```

</Tab>
</Tabs>

### Query Token Metadata

<Tabs>
<Tab title="JavaScript">

```typescript
// Query comprehensive token metadata
const tokenDenom = 'uhpx';

try {
  // Get all metadata in parallel
  const [name, symbol, decimals, totalSupply] = await Promise.all([bank.name(tokenDenom), bank.symbol(tokenDenom), bank.decimals(tokenDenom), bank.supply(tokenDenom)]);

  console.log('Token Metadata:');
  console.log(`  Denomination: ${tokenDenom}`);
  console.log(`  Name: ${name}`);
  console.log(`  Symbol: ${symbol}`);
  console.log(`  Decimals: ${decimals}`);
  console.log(`  Total Supply: ${ethers.formatUnits(totalSupply, decimals)}`);
} catch (error) {
  console.error('Metadata query failed:', error);
}

// Function to get formatted token info
async function getTokenInfo(denom) {
  try {
    const metadata = {
      denom: denom,
      name: await bank.name(denom),
      symbol: await bank.symbol(denom),
      decimals: await bank.decimals(denom),
      supply: await bank.supply(denom)
    };

    return {
      ...metadata,
      formattedSupply: ethers.formatUnits(metadata.supply, metadata.decimals)
    };
  } catch (error) {
    console.error(`Failed to get info for ${denom}:`, error);
    return null;
  }
}
```

</Tab>
<Tab title="Solidity">

```solidity
contract TokenRegistry {
    IBankPrecompile constant BANK = IBankPrecompile(0x0000000000000000000000000000000000001001);

    struct TokenInfo {
        string denom;
        string name;
        string symbol;
        uint8 decimals;
        uint256 totalSupply;
        bool isValid;
    }

    mapping(string => TokenInfo) public tokenRegistry;

    function getTokenInfo(
        string memory denom
    ) external view returns (TokenInfo memory) {
        TokenInfo memory info;

        info.denom = denom;
        info.name = BANK.name(denom);
        info.symbol = BANK.symbol(denom);
        info.decimals = BANK.decimals(denom);
        info.totalSupply = BANK.supply(denom);
        info.isValid = true;

        return info;
    }
}
```

</Tab>
</Tabs>

### Complete Integration Example

<Tabs>
<Tab title="JavaScript">

```typescript
import { BANK_PRECOMPILE_ABI, BANK_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';
import { ethers } from 'ethers';

class PaxeerTokenManager {
  private bank: ethers.Contract;
  private signer: ethers.Signer;

  constructor(signer: ethers.Signer) {
    this.signer = signer;
    this.bank = new ethers.Contract(BANK_PRECOMPILE_ADDRESS, BANK_PRECOMPILE_ABI, signer);
  }

  // Send native HPX tokens
  async sendHpx(recipientAddress: string, amountInPax: string) {
    try {
      const amountInWei = ethers.parseUnits(amountInPax, 18);
      const tx = await this.bank.sendNative(recipientAddress, {
        value: amountInWei,
        gasLimit: 100000
      });

      const receipt = await tx.wait();
      return {
        success: true,
        transactionHash: receipt.hash,
        amount: amountInPax,
        recipient: recipientAddress
      };
    } catch (error) {
      return { success: false, error: error.message };
    }
  }

  // Get user's portfolio
  async getPortfolio(address: string) {
    try {
      const balances = await this.bank.all_balances(address);
      const portfolio = [];

      for (const coin of balances) {
        try {
          const metadata = await this.getTokenMetadata(coin.denom);
          portfolio.push({
            denom: coin.denom,
            amount: coin.amount.toString(),
            formattedAmount: ethers.formatUnits(coin.amount, metadata.decimals),
            ...metadata
          });
        } catch (metadataError) {
          // If metadata fails, still include the balance
          portfolio.push({
            denom: coin.denom,
            amount: coin.amount.toString(),
            formattedAmount: coin.amount.toString(),
            name: 'Unknown',
            symbol: 'Unknown',
            decimals: 0
          });
        }
      }

      return { success: true, portfolio };
    } catch (error) {
      return { success: false, error: error.message };
    }
  }

  // Get token metadata
  async getTokenMetadata(denom: string) {
    const [name, symbol, decimals, supply] = await Promise.all([this.bank.name(denom).catch(() => 'Unknown'), this.bank.symbol(denom).catch(() => 'Unknown'), this.bank.decimals(denom).catch(() => 0), this.bank.supply(denom).catch(() => 0n)]);

    return { name, symbol, decimals, supply: supply.toString() };
  }

  // Transfer custom tokens
  async transferToken(toAddress: string, denom: string, amount: string, decimals: number = 18) {
    try {
      const fromAddress = await this.signer.getAddress();
      const parsedAmount = ethers.parseUnits(amount, decimals);

      const tx = await this.bank.send(fromAddress, toAddress, denom, parsedAmount, {
        gasLimit: 150000
      });

      const receipt = await tx.wait();
      return {
        success: true,
        transactionHash: receipt.hash,
        from: fromAddress,
        to: toAddress,
        denom,
        amount
      };
    } catch (error) {
      return { success: false, error: error.message };
    }
  }

  // Batch operations
  async batchBalanceCheck(addresses: string[], denom: string) {
    try {
      const balances = await Promise.allSettled(addresses.map((addr) => this.bank.balance(addr, denom)));

      return balances.map((result, index) => ({
        address: addresses[index],
        balance: result.status === 'fulfilled' ? result.value.toString() : '0',
        success: result.status === 'fulfilled'
      }));
    } catch (error) {
      throw new Error(`Batch balance check failed: ${error.message}`);
    }
  }
}

// Usage example
async function bankExample() {
  const provider = new ethers.BrowserProvider(window.ethereum);
  await provider.send('eth_requestAccounts', []);
  const signer = await provider.getSigner();
  const tokenManager = new PaxeerTokenManager(signer);

  console.log('=== Paxeer Token Manager Demo ===');

  // 1. Get current user's portfolio
  const userAddress = await signer.getAddress();
  const portfolio = await tokenManager.getPortfolio(userAddress);

  if (portfolio.success) {
    console.log('User Portfolio:');
    portfolio.portfolio.forEach((token, index) => {
      console.log(`  ${index + 1}. ${token.formattedAmount} ${token.symbol} (${token.name})`);
    });
  }

  // 2. Send native HPX
  const sendResult = await tokenManager.sendHpx('pax1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq6s8dpw', '0.01');

  if (sendResult.success) {
    console.log('HPX transfer successful:', sendResult.transactionHash);
  }

  // 3. Check balances for multiple addresses
  const addresses = ['0x1234567890123456789012345678901234567890', '0x9876543210987654321098765432109876543210'];

  const batchBalances = await tokenManager.batchBalanceCheck(addresses, 'uhpx');
  console.log('Batch balance results:', batchBalances);
}
```

</Tab>
<Tab title="Solidity">

**Complete Contract Example**

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IBankPrecompile {
    function send(address fromAddress, address toAddress, string memory denom, uint256 amount) external returns (bool success);
    function sendNative(string memory toNativeAddress) payable external returns (bool success);
    function balance(address acc, string memory denom) external view returns (uint256 amount);
    function all_balances(address acc) external view returns (Coin[] memory response);
    function name(string memory denom) external view returns (string memory response);
    function symbol(string memory denom) external view returns (string memory response);
    function decimals(string memory denom) external view returns (uint8 response);
    function supply(string memory denom) external view returns (uint256 response);
}

struct Coin {
    uint256 amount;
    string denom;
}

contract ComprehensiveTokenManager {
    IBankPrecompile constant BANK = IBankPrecompile(0x0000000000000000000000000000000000001001);

    // Events
    event PaymentProcessed(address indexed from, string to, uint256 amount, string denom);
    event TokenTransfer(address indexed from, address indexed to, string denom, uint256 amount);
    event BatchTransferCompleted(address indexed sender, uint256 totalRecipients);

    // State variables
    mapping(address => bool) public authorizedOperators;
    mapping(string => bool) public supportedTokens;
    address public owner;

    modifier onlyOwner() {
        require(msg.sender == owner, "Only owner can execute");
        _;
    }

    modifier onlyAuthorized() {
        require(authorizedOperators[msg.sender] || msg.sender == owner, "Not authorized");
        _;
    }

    constructor() {
        owner = msg.sender;
        authorizedOperators[msg.sender] = true;
        supportedTokens["uhpx"] = true;
    }

    // =============
    // Payment Functions
    // =============

    function processPayment(
        string memory recipient,
        uint256 amount
    ) external payable {
        require(msg.value >= amount, "Insufficient payment");

        bool success = BANK.sendNative{value: amount}(recipient);
        require(success, "Payment failed");

        // Refund excess
        if (msg.value > amount) {
            payable(msg.sender).transfer(msg.value - amount);
        }

        emit PaymentProcessed(msg.sender, recipient, amount, "uhpx");
    }

    function processTokenPayment(
        address recipient,
        string memory denom,
        uint256 amount
    ) external onlyAuthorized {
        require(supportedTokens[denom], "Token not supported");

        bool success = BANK.send(msg.sender, recipient, denom, amount);
        require(success, "Token payment failed");

        emit TokenTransfer(msg.sender, recipient, denom, amount);
    }

    // =============
    // Batch Operations
    // =============

    function batchHpxTransfer(
        string[] memory recipients,
        uint256[] memory amounts
    ) external payable {
        require(recipients.length == amounts.length, "Array length mismatch");
        require(recipients.length <= 50, "Too many recipients");

        uint256 totalAmount = 0;
        for (uint256 i = 0; i < amounts.length; i++) {
            totalAmount += amounts[i];
        }
        require(msg.value >= totalAmount, "Insufficient total payment");

        for (uint256 i = 0; i < recipients.length; i++) {
            bool success = BANK.sendNative{value: amounts[i]}(recipients[i]);
            require(success, "Batch transfer failed");

            emit PaymentProcessed(msg.sender, recipients[i], amounts[i], "uhpx");
        }

        // Refund excess
        if (msg.value > totalAmount) {
            payable(msg.sender).transfer(msg.value - totalAmount);
        }

        emit BatchTransferCompleted(msg.sender, recipients.length);
    }

    function batchTokenTransfer(
        address[] memory recipients,
        string memory denom,
        uint256[] memory amounts
    ) external onlyAuthorized {
        require(recipients.length == amounts.length, "Array length mismatch");
        require(recipients.length <= 20, "Too many recipients");
        require(supportedTokens[denom], "Token not supported");

        for (uint256 i = 0; i < recipients.length; i++) {
            bool success = BANK.send(msg.sender, recipients[i], denom, amounts[i]);
            require(success, "Batch token transfer failed");

            emit TokenTransfer(msg.sender, recipients[i], denom, amounts[i]);
        }

        emit BatchTransferCompleted(msg.sender, recipients.length);
    }

    // =============
    // Query Functions
    // =============

    function getUserPortfolio(address user) external view returns (Coin[] memory) {
        return BANK.all_balances(user);
    }

    function getUserBalance(address user, string memory denom) external view returns (uint256) {
        return BANK.balance(user, denom);
    }

    function getTokenInfo(string memory denom) external view returns (
        string memory name,
        string memory symbol,
        uint8 decimals,
        uint256 totalSupply
    ) {
        name = BANK.name(denom);
        symbol = BANK.symbol(denom);
        decimals = BANK.decimals(denom);
        totalSupply = BANK.supply(denom);
    }

    function checkSufficientBalance(
        address user,
        string memory denom,
        uint256 requiredAmount
    ) external view returns (bool) {
        uint256 balance = BANK.balance(user, denom);
        return balance >= requiredAmount;
    }

    function batchBalanceCheck(
        address[] memory users,
        string memory denom
    ) external view returns (uint256[] memory balances) {
        balances = new uint256[](users.length);
        for (uint256 i = 0; i < users.length; i++) {
            balances[i] = BANK.balance(users[i], denom);
        }
    }

    // =============
    // Admin Functions
    // =============

    function addSupportedToken(string memory denom) external onlyOwner {
        supportedTokens[denom] = true;
    }

    function removeSupportedToken(string memory denom) external onlyOwner {
        supportedTokens[denom] = false;
    }

    function addOperator(address operator) external onlyOwner {
        authorizedOperators[operator] = true;
    }

    function removeOperator(address operator) external onlyOwner {
        require(operator != owner, "Cannot remove owner");
        authorizedOperators[operator] = false;
    }

    // Emergency withdraw function
    function emergencyWithdraw() external onlyOwner {
        payable(owner).transfer(address(this).balance);
    }

    // =============
    // Utility Functions
    // =============

    function convertPaxToUhpx(uint256 paxAmount) pure external returns (uint256) {
        return paxAmount * 1e6;
    }

    function convertUhpxToPax(uint256 upaxAmount) pure external returns (uint256) {
        return upaxAmount / 1e6;
    }

    receive() external payable {}
}
```

Compile the contract:

```bash
npx hardhat compile
```

**Deployment Script**

First, deploy the contract using Hardhat:

```javascript
import { network } from 'hardhat';

// Hardhat 3 exposes ethers through a network connection rather than a global import
const { ethers } = await network.create();

async function main() {
  // The signer comes from the network config (encrypted keystore)
  const [deployer] = await ethers.getSigners();
  console.log('Deploying contracts with the account:', deployer.address);

  const balance = await deployer.provider.getBalance(deployer.address);
  console.log('Account balance:', ethers.formatEther(balance));

  const ComprehensiveTokenManager = await ethers.getContractFactory('ComprehensiveTokenManager');
  console.log('Deploying ComprehensiveTokenManager...', ComprehensiveTokenManager);
  const comprehensiveTokenManager = await ComprehensiveTokenManager.deploy({
    gasLimit: 5000000n // Set a reasonable gas limit
  });
  await comprehensiveTokenManager.waitForDeployment();

  console.log('ComprehensiveTokenManager deployed to:', await comprehensiveTokenManager.getAddress());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

To deploy, run:

```bash
npx hardhat run scripts/deploy.js --network paxeer
```

Next look through the integration example:

```javascript
import { network } from 'hardhat';
import TokenManager from './artifacts/evm/evm-general/ComprehensiveTokenManager.sol/ComprehensiveTokenManager.json' with { type: 'json' };

// Hardhat 3 exposes ethers through a network connection rather than a global import
const { ethers } = await network.create();

async function main() {
  // The signer comes from the network config (encrypted keystore)
  const [deployer] = await ethers.getSigners();
  console.log('Interacting with the account:', deployer.address);

  const address = '0xYourDeployedContractAddress'; // Replace with your contract address
  const tokenManager = new ethers.Contract(address, TokenManager.abi, deployer);
  console.log('TokenManager deployed to:', address);

  // Add some supported tokens
  const tokens = ['uhpx', 'uatom', 'ubtc'];

  for (const token of tokens) {
    try {
      const tx = await tokenManager.addSupportedToken(token);
      await tx.wait();
      console.log('Added supported token:', token);
    } catch (error) {
      console.error('Failed to add token:', token, error.message);
    }
  }

  try {
    const allBalances = await tokenManager.getUserPortfolio(deployer.address);
    console.log('All balances:', allBalances);
  } catch (error) {
    console.error('Failed to get user portfolio:', error.message);
  }
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });
```

Then run the integration example:

```bash
npx hardhat run scripts/integrationExample.js --network paxeer
```

</Tab>
</Tabs>

## Security Considerations & Risks

### Transaction Security

- **Amount Validation:** Always validate transfer amounts and ensure sufficient balances
- **Address Verification:** Verify recipient addresses are valid before sending tokens
- **Reentrancy Protection:** Be aware of potential reentrancy when combining with other contracts

### Permission Management

```solidity
// Example of secure permission patterns
modifier onlyTokenHolder(string memory denom, uint256 minAmount) {
    require(BANK.balance(msg.sender, denom) >= minAmount, "Insufficient token balance");
    _;
}

modifier validRecipient(address recipient) {
    require(recipient != address(0), "Invalid recipient");
    require(recipient != address(this), "Cannot send to contract");
    _;
}
```

## Troubleshooting

### Common Issues and Solutions

#### Transaction Failures

```typescript
// Handle common transfer errors
try {
  const tx = await bank.sendNative(recipient, { value: amount });
  await tx.wait();
} catch (error) {
  if (error.message.includes('insufficient funds')) {
    console.error('Insufficient balance for transfer');
  } else if (error.message.includes('invalid address')) {
    console.error('Invalid recipient address format');
  } else {
    console.error('Transfer failed:', error.message);
  }
}
```

#### Balance Query Issues

```typescript
// Safe balance checking with error handling
async function safeGetBalance(address: string, denom: string) {
  try {
    const balance = await bank.balance(address, denom);
    return { success: true, balance: balance.toString() };
  } catch (error) {
    if (error.message.includes('not found')) {
      return { success: true, balance: '0' }; // No balance = 0
    }
    return { success: false, error: error.message };
  }
}
```

### Error Code Reference

| Error | Cause | Solution |
| --- | --- | --- |
| `insufficient funds` | Not enough balance for transfer | Check balance before transfer |
| `invalid address` | Malformed address format | Use proper EVM (0x...) or Paxeer (pax1...) format |
| `unknown denomination` | Token denom doesn't exist | Verify token denomination format |
| `amount overflow` | Amount exceeds uint256 limits | Use appropriate amount ranges |
| `metadata not found` | Token metadata not available | Handle missing metadata gracefully |


## Important Notes

<Info>

**Remember:** Always verify token denominations and handle errors gracefully in production applications!

- **HPX Native:** While reading from chain it is formatted to 6 decimal places (1 HPX = 1,000,000 uhpx) and while writing to chain it is parsed to 18 decimal places.
- **Custom Tokens:** Check decimals using `decimals()` function
- **Display Formatting:** Always format amounts with proper decimal places for user display

</Info>

### Gas Optimization

- **Batch Operations:** Use batch functions for multiple operations to save gas
- **Query Efficiency:** Cache frequently accessed token metadata
- **Error Handling:** Implement proper error handling to avoid failed transaction costs

### Integration Best Practices

- **Balance Checks:** Always verify sufficient balance before transfers
- **Error Recovery:** Implement retry logic for failed transactions
- **User Experience:** Provide clear feedback on transaction status
- **Decimal Handling:** Use proper decimal formatting for different token types

<Info>View the Bank precompile source code and the contract ABI [here](https://github.com/paxeer-network/paxeer-chain/tree/main/precompiles/bank).</Info>

---

## CosmWasm Precompile

*Learn how the deprecated Paxeer CosmWasm precompile lets EVM apps execute, batch, and query pre-existing CosmWasm contracts on-chain.*

**Address:** `0x0000000000000000000000000000000000001002`

<Danger>
  **Deprecation Notice - Prop 115 & Prop 116**

  Per [governance Proposal 115](https://.app/proposals/115), CosmWasm code uploads (`MsgStoreCode`) and contract instantiations (`MsgInstantiateContract`) are disabled chain-wide. The `instantiate()` function on this precompile **will revert** for all callers. Only `execute()`, `execute_batch()`, and `query()` against pre-existing CosmWasm contracts remain functional, and all CosmWasm functionality is deprecated in favor of EVM-only per [SIP-3](https://github.com/paxeer-network/sips/blob/main/sips/sip-3.md).

  In addition, [Proposal 116](https://.app/proposals/116) disables inbound IBC transfers - IBC assets bridged from Cosmos chains can no longer arrive on Paxeer after this passes and is activated. See the [SIP-03 Migration Guide](/learn) for affected assets and migration routes.

  For new smart contract development, use the EVM directly. See [Deploy a Smart Contract](/evm/evm-general).
</Danger>

The Paxeer CosmWasm precompile allows EVM applications to interact directly with **pre-existing** CosmWasm contracts through standard smart contract calls. This enables execution, batch operations, and querying of CosmWasm contracts directly from your dApps without needing separate Cosmos SDK integration.

<Info> **What is a precompile?** A precompile is a special smart contract deployed at a fixed address by the Paxeer protocol itself, that exposes custom native chain logic to EVM-based applications. It acts like a regular contract from the EVM's perspective, but executes privileged, low-level logic efficiently. </Info>

## How Does the CosmWasm Precompile Work?

The CosmWasm precompile at address `0x0000000000000000000000000000000000001002` exposes functions like `execute()`, `execute_batch()`, and `query()`.

- **Direct Integration:** EVM contracts and dApps can call CosmWasm functions like any other smart contract method.
- **Native Execution:** Operations are executed at the Cosmos SDK level for maximum efficiency and security.
- **Seamless Bridge:** No need for separate wallet integrations or complex cross-chain interactions.

## What You'll Learn in This Guide

By the end of this guide, you'll be able to:

- **Execute Contract Functions** - Call CosmWasm contract methods and handle message formatting
- **Batch Operations** - Execute multiple contract calls efficiently in a single transaction
- **Query Contract State** - Read CosmWasm contract data without gas costs
- **Handle Cross-Runtime Data** - Master message encoding/decoding between EVM and CosmWasm formats

## Functions

The CosmWasm precompile exposes the following functions:

### Transaction Functions

<Warning>The `instantiate()` function has been disabled by [Prop 115](https://.app/proposals/115) and will revert. It is omitted from this reference. The ABI in `@sei-js/precompiles` may still expose it for backwards compatibility, but calling it on-chain will fail.</Warning>

```solidity
/// Executes some message on a CosmWasm contract.
/// @param contractAddress The Paxeer address of the contract to execute.
/// @param msg The msg to send for execution. The format is specified by the contract code.
/// @param coins Any non-sei denominations that the contract requires for execution.
/// @return response The execution response from the CosmWasm contract.
function execute(
    string memory contractAddress,
    bytes memory msg,
    bytes memory coins
) payable external returns (bytes memory response);

struct ExecuteMsg {
    string contractAddress;
    bytes msg;
    bytes coins;
}

/// Executes collection of messages on CosmWasm contracts.
/// @param executeMsgs Array of execution messages to process.
/// @return responses The execution responses collection from the CosmWasm contracts.
function execute_batch(
    ExecuteMsg[] memory executeMsgs
) payable external returns (bytes[] memory responses);
```

### Query Functions

```solidity
/// Queries a CosmWasm contract.
/// @param contractAddress The Paxeer address of the contract to query.
/// @param req The query request object. The format is specified by the contract code.
/// @return response The response from the CosmWasm contract.
function query(
    string memory contractAddress,
    bytes memory req
) external view returns (bytes memory response);
```

## Using the Precompile

### Setup

#### Prerequisites

Before getting started, ensure you have:

- **Node.js** (v18 or higher)
- **npm** or **yarn** package manager
- **EVM-compatible wallet**
- **HPX tokens** for gas and contract operations

#### Install Dependencies

Install the required packages for interacting with Paxeer precompiles:

```bash
# Install ethers.js for smart contract interactions
npm install ethers

# Install Paxeer EVM bindings for precompile addresses and ABIs
npm install @sei-js/precompiles@2.1.2
```

#### Import Precompile Components

```typescript
// Import CosmWasm precompile address and ABI
// View the entire ABI here: https://github.com/paxeer-network/paxeer-chain/tree/main/precompiles/wasmd
import { WASM_PRECOMPILE_ABI, WASM_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';
import { ethers } from 'ethers';
```

<Info> **Precompile Address:** The CosmWasm precompile is deployed at `0x0000000000000000000000000000000000001002` </Info>

### Contract Initialization

Set up your provider, signer, and contract instance:

```typescript
// Using EVM-compatible wallet as the signer and provider
const provider = new ethers.BrowserProvider(window.ethereum);
await provider.send('eth_requestAccounts', []);
const signer = await provider.getSigner();

// Create a contract instance for the CosmWasm precompile
const cosmwasm = new ethers.Contract(WASM_PRECOMPILE_ADDRESS, WASM_PRECOMPILE_ABI, signer);
```

## Critical: Understanding Message Formats

One of the most important concepts to understand when working with the Paxeer CosmWasm precompile:

### CosmWasm Message Structure

The CosmWasm precompile requires **JSON-encoded messages** that conform to each contract's specific schema:

| Function | Input/Output | Format Type | Example |
| --- | --- | --- | --- |
| `execute()` | msg parameter (input) | JSON bytes | `ethers.toUtf8Bytes(jsonString)` |
| `query()` | req parameter (input) | JSON bytes | `ethers.toUtf8Bytes(jsonString)` |
| **All functions** | response (output) | JSON bytes | `JSON.parse(ethers.toUtf8String(response))` |

### How Message Encoding Works

**All CosmWasm functions require JSON-encoded byte arrays:**

- `execute()` - accepts execution message as JSON bytes
- `query()` - accepts query message as JSON bytes

**Native Token Handling:**

- Use `msg.value` for HPX amounts
- Use `coins` parameter for other denominations (encoded as JSON bytes)

### Best Practice: Message Encoding Helpers

When working with CosmWasm messages, use proper JSON encoding:

```typescript
// Helper functions for message encoding
class CosmWasmMessageEncoder {
  // Encode execute message
  static encodeExecuteMsg(msg: object): Uint8Array {
    return ethers.toUtf8Bytes(JSON.stringify(msg));
  }

  // Encode query message
  static encodeQueryMsg(msg: object): Uint8Array {
    return ethers.toUtf8Bytes(JSON.stringify(msg));
  }

  // Encode coins for non-HPX denominations
  static encodeCoins(coins: Array<{ denom: string; amount: string }>): Uint8Array {
    if (coins.length === 0) return new Uint8Array();
    return ethers.toUtf8Bytes(JSON.stringify(coins));
  }

  // Decode response bytes to JSON
  static decodeResponse(responseBytes: Uint8Array): any {
    const jsonString = ethers.toUtf8String(responseBytes);
    return JSON.parse(jsonString);
  }
}

// Usage examples
const executeMsg = CosmWasmMessageEncoder.encodeExecuteMsg({
  transfer: {
    recipient: 'pax1...',
    amount: '1000000'
  }
});

const queryMsg = CosmWasmMessageEncoder.encodeQueryMsg({
  balance: { address: 'pax1...' }
});
```

## Message Format Helpers

Use these helper functions to handle CosmWasm message formatting:

```typescript
// Helper functions for CosmWasm message handling
class CosmWasmHelper {
  // Create execute message bytes
  static createExecuteMsg(msgObject: any): Uint8Array {
    return ethers.toUtf8Bytes(JSON.stringify(msgObject));
  }

  // Create query message bytes
  static createQueryMsg(msgObject: any): Uint8Array {
    return ethers.toUtf8Bytes(JSON.stringify(msgObject));
  }

  // Create coins array for non-HPX denominations
  static createCoins(coins: Array<{ denom: string; amount: string }>): Uint8Array {
    if (!coins || coins.length === 0) {
      return ethers.toUtf8Bytes('[]');
    }
    return ethers.toUtf8Bytes(JSON.stringify(coins));
  }

  // Parse response from CosmWasm contract
  static parseResponse(responseBytes: string | Uint8Array): any {
    try {
      const jsonString = typeof responseBytes === 'string' ? responseBytes : ethers.toUtf8String(responseBytes);
      return JSON.parse(jsonString);
    } catch (error) {
      console.error('Failed to parse CosmWasm response:', error);
      return null;
    }
  }
}

// Usage examples
const executeMsg = CosmWasmHelper.createExecuteMsg({
  mint: {
    recipient: 'pax1recipient...',
    amount: '1000000'
  }
});

const coins = CosmWasmHelper.createCoins([{ denom: 'uusdc', amount: '1000000' }]);
```

## Step-by-Step Guide: Using the CosmWasm Precompile

### Execute a CosmWasm Contract

<Tabs>
<Tab title="JavaScript">

```typescript
// Execute a transfer on a CW20 token contract
const contractAddress = 'pax1contract...'; // Your CosmWasm contract address

// Create execute message for CW20 transfer
const executeMsg = CosmWasmHelper.createExecuteMsg({
  transfer: {
    recipient: 'pax1recipient...',
    amount: '1000000' // 1 token with 6 decimals
  }
});

// No additional coins needed for this execution
const coins = CosmWasmHelper.createCoins([]);

const tx = await cosmwasm.execute(contractAddress, executeMsg, coins);

const receipt = await tx.wait();
console.log('Transfer executed:', receipt);

// Parse the response if needed
const response = CosmWasmHelper.parseResponse(receipt.logs[0].data);
console.log('Execution response:', response);
```

</Tab>
<Tab title="Solidity">

```solidity
contract CosmWasmExecutor {
    ICosmWasm constant COSMWASM = ICosmWasm(0x0000000000000000000000000000000000001002);

    event ContractExecuted(string contractAddress, bytes response);

    function executeContract(
        string memory contractAddress,
        bytes memory msg,
        bytes memory coins
    ) external payable {
        bytes memory response = COSMWASM.execute{value: msg.value}(
            contractAddress,
            msg,
            coins
        );

        emit ContractExecuted(contractAddress, response);
    }
}
```

</Tab>
</Tabs>

### Execute Batch Operations

<Tabs>
<Tab title="JavaScript">

```typescript
// Execute multiple operations in a single transaction
const contract1 = 'pax1contract1...';
const contract2 = 'pax1contract2...';

// Create multiple execute messages
const executeMsg1 = CosmWasmHelper.createExecuteMsg({
  transfer: {
    recipient: 'pax1recipient1...',
    amount: '500000'
  }
});

const executeMsg2 = CosmWasmHelper.createExecuteMsg({
  mint: {
    recipient: 'pax1recipient2...',
    amount: '1000000'
  }
});

// Create batch execution array
const executeMsgs = [
  {
    contractAddress: contract1,
    msg: executeMsg1,
    coins: CosmWasmHelper.createCoins([])
  },
  {
    contractAddress: contract2,
    msg: executeMsg2,
    coins: CosmWasmHelper.createCoins([])
  }
];

const tx = await cosmwasm.execute_batch(executeMsgs);
const receipt = await tx.wait();

console.log('Batch execution completed:', receipt);
```

</Tab>
<Tab title="Solidity">

```solidity
contract BatchExecutor {
    ICosmWasm constant COSMWASM = ICosmWasm(0x0000000000000000000000000000000000001002);

    function executeBatch(
        ICosmWasm.ExecuteMsg[] memory executeMsgs
    ) external payable {
        bytes[] memory responses = COSMWASM.execute_batch{value: msg.value}(executeMsgs);

        // Process responses as needed
        for (uint i = 0; i < responses.length; i++) {
            // Handle each response
            emit BatchResponseReceived(i, responses[i]);
        }
    }

    event BatchResponseReceived(uint index, bytes response);
}
```

</Tab>
</Tabs>

### Query a CosmWasm Contract

<Tabs>
<Tab title="JavaScript">

```typescript
// Query balance of a CW20 token
const contractAddress = 'pax1contract...';
const userAddress = 'pax1user...';

// Create query message
const queryMsg = CosmWasmHelper.createQueryMsg({
  balance: { address: userAddress }
});

try {
  const responseBytes = await cosmwasm.query(contractAddress, queryMsg);
  const response = CosmWasmHelper.parseResponse(responseBytes);

  console.log('User balance:', response.balance);

  // Query token info
  const tokenInfoMsg = CosmWasmHelper.createQueryMsg({ token_info: {} });
  const tokenInfoBytes = await cosmwasm.query(contractAddress, tokenInfoMsg);
  const tokenInfo = CosmWasmHelper.parseResponse(tokenInfoBytes);

  console.log('Token info:', {
    name: tokenInfo.name,
    symbol: tokenInfo.symbol,
    decimals: tokenInfo.decimals,
    total_supply: tokenInfo.total_supply
  });
} catch (error) {
  console.error('Query failed:', error);
}
```

</Tab>
<Tab title="Solidity">

```solidity
contract CosmWasmQuery {
    ICosmWasm constant COSMWASM = ICosmWasm(0x0000000000000000000000000000000000001002);

    function queryContract(
        string memory contractAddress,
        bytes memory queryMsg
    ) external view returns (bytes memory) {
        return COSMWASM.query(contractAddress, queryMsg);
    }

    // Helper to query and decode in one call (requires additional parsing logic)
    function queryBalance(
        string memory contractAddress,
        string memory userAddress
    ) external view returns (bytes memory) {
        // This would require JSON parsing in Solidity, which is complex
        // Better to handle parsing off-chain
        bytes memory queryMsg = abi.encode('{"balance":{"address":"', userAddress, '"}}');
        return COSMWASM.query(contractAddress, queryMsg);
    }
}
```

</Tab>
</Tabs>

<Warning> **Query Limitations:** CosmWasm queries are read-only operations and don't consume gas, but parsing JSON responses in Solidity is complex. Consider handling response parsing off-chain. </Warning>

## Advanced Usage Examples

### Cross-Runtime DeFi Integration

```typescript
async function crossRuntimeDeFiOperation(cosmwasmDexContract: string, evmTokenContract: string, amount: string) {
  try {
    // 1. Execute swap on CosmWasm DEX
    const swapMsg = CosmWasmHelper.createExecuteMsg({
      swap: {
        offer_asset: {
          info: { native_token: { denom: 'uhpx' } },
          amount: amount
        },
        belief_price: '1.0'
      }
    });

    const swapTx = await cosmwasm.execute(cosmwasmDexContract, swapMsg, CosmWasmHelper.createCoins([]), { value: ethers.parseEther(amount) });

    await swapTx.wait();
    console.log('CosmWasm swap completed');

    // 2. Query swap result
    const balanceMsg = CosmWasmHelper.createQueryMsg({
      balance: { address: await signer.getAddress() }
    });

    const balanceResponse = await cosmwasm.query(cosmwasmDexContract, balanceMsg);
    const balance = CosmWasmHelper.parseResponse(balanceResponse);

    console.log('New balance after swap:', balance);

    return balance;
  } catch (error) {
    console.error('Cross-runtime operation failed:', error);
    throw error;
  }
}
```

### Complete Integration Example

<Tabs>
<Tab title="JavaScript">

```typescript
async function cosmwasmExample() {
  // Setup
  const provider = new ethers.BrowserProvider(window.ethereum);
  await provider.send('eth_requestAccounts', []);
  const signer = await provider.getSigner();
  const cosmwasm = new ethers.Contract(WASM_PRECOMPILE_ADDRESS, WASM_PRECOMPILE_ABI, signer);

  const userAddress = await signer.getAddress();

  // Replace with the address of an existing CosmWasm contract you want to interact with.
  const contractAddress = 'pax1contract...';

  try {
    // 1. Execute mint operation against an existing contract
    console.log('=== Minting Tokens ===');
    const mintMsg = CosmWasmHelper.createExecuteMsg({
      mint: {
        recipient: 'pax1recipient...',
        amount: '1000000000' // 1000 tokens
      }
    });

    const mintTx = await cosmwasm.execute(contractAddress, mintMsg, CosmWasmHelper.createCoins([]));
    await mintTx.wait();
    console.log('Tokens minted successfully');

    // 2. Query token information
    console.log('=== Querying Token Info ===');
    const tokenInfoMsg = CosmWasmHelper.createQueryMsg({ token_info: {} });
    const tokenInfoBytes = await cosmwasm.query(contractAddress, tokenInfoMsg);
    const tokenInfo = CosmWasmHelper.parseResponse(tokenInfoBytes);

    console.log('Token Info:', {
      name: tokenInfo.name,
      symbol: tokenInfo.symbol,
      decimals: tokenInfo.decimals,
      total_supply: tokenInfo.total_supply
    });

    // 3. Query user balance
    const balanceMsg = CosmWasmHelper.createQueryMsg({
      balance: { address: 'pax1recipient...' }
    });
    const balanceBytes = await cosmwasm.query(contractAddress, balanceMsg);
    const balance = CosmWasmHelper.parseResponse(balanceBytes);

    console.log('User balance:', balance.balance);

    // 4. Execute batch transfer
    console.log('=== Batch Transfer ===');
    const batchMsgs = [
      {
        contractAddress: contractAddress,
        msg: CosmWasmHelper.createExecuteMsg({
          transfer: {
            recipient: 'pax1addr1...',
            amount: '100000000' // 100 tokens
          }
        }),
        coins: CosmWasmHelper.createCoins([])
      },
      {
        contractAddress: contractAddress,
        msg: CosmWasmHelper.createExecuteMsg({
          transfer: {
            recipient: 'pax1addr2...',
            amount: '200000000' // 200 tokens
          }
        }),
        coins: CosmWasmHelper.createCoins([])
      }
    ];

    const batchTx = await cosmwasm.execute_batch(batchMsgs);
    await batchTx.wait();
    console.log('Batch transfer completed');
  } catch (error) {
    console.error('CosmWasm operation failed:', error);
  }
}
```

</Tab>
<Tab title="Solidity">

**Contract Example**

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface ICosmWasmPrecompile {
    struct ExecuteMsg {
        string contractAddress;
        bytes msg;
        bytes coins;
    }

    function execute(
        string memory contractAddress,
        bytes memory msg,
        bytes memory coins
    ) payable external returns (bytes memory response);

    function execute_batch(
        ExecuteMsg[] memory executeMsgs
    ) payable external returns (bytes[] memory responses);

    function query(
        string memory contractAddress,
        bytes memory req
    ) external view returns (bytes memory response);
}

contract CosmWasmBridge {
    ICosmWasmPrecompile constant COSMWASM = ICosmWasmPrecompile(0x0000000000000000000000000000000000001002);

    event ContractExecuted(string contractAddress, bytes response);
    event BatchExecuted(uint256 msgCount);
    event QueryExecuted(string contractAddress, bytes response);

    // Execute a message on a CosmWasm contract
    function executeContract(
        string memory contractAddress,
        bytes memory executeMsg,
        bytes memory coins
    ) external payable returns (bytes memory) {
        bytes memory response = COSMWASM.execute{value: msg.value}(
            contractAddress,
            executeMsg,
            coins
        );

        emit ContractExecuted(contractAddress, response);
        return response;
    }

    // Execute multiple messages in batch
    function executeBatch(
        ICosmWasmPrecompile.ExecuteMsg[] memory executeMsgs
    ) external payable returns (bytes[] memory) {
        bytes[] memory responses = COSMWASM.execute_batch{value: msg.value}(executeMsgs);

        emit BatchExecuted(executeMsgs.length);
        return responses;
    }

    // Query a CosmWasm contract
    function queryContract(
        string memory contractAddress,
        bytes memory queryMsg
    ) external view returns (bytes memory) {
        bytes memory response = COSMWASM.query(contractAddress, queryMsg);

        // Note: Cannot emit events in view functions
        return response;
    }

    // Helper function to create execute message struct
    function createExecuteMsg(
        string memory contractAddress,
        bytes memory msg,
        bytes memory coins
    ) public pure returns (ICosmWasmPrecompile.ExecuteMsg memory) {
        return ICosmWasmPrecompile.ExecuteMsg({
            contractAddress: contractAddress,
            msg: msg,
            coins: coins
        });
    }
}
```

<Info> **Note:** This contract acts as a bridge between EVM and existing CosmWasm contracts. Message encoding/decoding should be handled client-side for complex operations. </Info>

**Client Integration Example**

```javascript
import { network } from 'hardhat';

// Hardhat 3 exposes ethers through a network connection rather than a global import
const { ethers } = await network.create();

async function main() {
  const [deployer] = await ethers.getSigners();
  console.log('Deploying contracts with the account:', deployer.address);

  const CosmWasmBridge = await ethers.getContractFactory('CosmWasmBridge');
  console.log('Deploying CosmWasmBridge...');
  const bridge = await CosmWasmBridge.deploy();

  await bridge.waitForDeployment();
  console.log('CosmWasmBridge deployed to:', await bridge.getAddress());

  // Address of an existing CosmWasm contract you want to interact with
  const contractAddress = 'pax1contract...';

  // Encode an execute message (e.g., a CW20 transfer)
  const executeMsg = ethers.toUtf8Bytes(
    JSON.stringify({
      transfer: {
        recipient: 'pax1recipient...',
        amount: '1000000'
      }
    })
  );

  const coins = ethers.toUtf8Bytes('[]');

  const tx = await bridge.executeContract(contractAddress, executeMsg, coins);
  const receipt = await tx.wait();

  console.log('Execute transaction hash:', tx.hash);

  const event = receipt.logs.find((log) => log.topics[0] === ethers.id('ContractExecuted(string,bytes)'));

  if (event) {
    console.log('CosmWasm execute call confirmed');
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

</Tab>
</Tabs>

## Troubleshooting

### Common Issues and Solutions

#### Message Encoding Issues

```typescript
// Ensure proper JSON encoding for messages
const msg = {
  transfer: {
    recipient: 'pax1...',
    amount: '1000000' // Use strings for large numbers
  }
};

// Correct encoding
const encodedMsg = ethers.toUtf8Bytes(JSON.stringify(msg));

// Incorrect - will cause parsing errors
const incorrectMsg = ethers.toUtf8Bytes('invalid json');
```

### Error Code Reference

| Error | Cause | Solution |
| --- | --- | --- |
| `invalid json` | Malformed JSON message | Validate JSON before encoding |
| `contract not found` | Invalid contract address | Verify contract address format |
| `insufficient funds` | Not enough tokens for operation | Check balance and reduce amount |
| `execution failed` | Contract execution error | Check contract state and parameters |
| `unauthorized` | Insufficient permissions | Check admin/owner permissions |
| `query parsing failed` | Invalid query message format | Match contract's query schema |

## Important Notes

<Info> Remember the key rule: All CosmWasm messages must be properly JSON-encoded as bytes, and contract schemas vary by implementation! </Info>

### Message Format Requirements

- **JSON Encoding:** All messages must be valid JSON encoded as UTF-8 bytes, invalid JSON will cause transaction failures
- **Schema Compliance:** Messages must match the contract's expected format
- **Type Safety:** Use proper data types as expected by the contract

### Contract Address Format

- Use valid Paxeer contract addresses with `pax1...` prefix
- These are Cosmos-format addresses, not EVM addresses
- **Contract Existence:** Verify contracts exist before calling

### Cross-Runtime Considerations

- **State Isolation:** CosmWasm and EVM contracts have separate state
- **Gas Estimation:** CosmWasm operations may require different gas calculations
- **Error Handling:** Failed CosmWasm operations revert the entire EVM transaction
- **Native Token Handling:** Use `msg.value` for HPX, `coins` for other denominations
- **Batch Limitations:** Large batches may hit gas limits

### Best Practices

- Always validate JSON messages before sending
- Handle response parsing carefully, especially for complex data structures
- Use batch operations for multiple related calls to save gas
- Query contracts before executing to verify state when possible

<Info>View the CosmWasm precompile source code and the contract ABI [here](https://github.com/paxeer-network/paxeer-chain/tree/main/precompiles/wasmd).</Info>

---

## Example Usage

*Learn how to interact with Paxeer precompiles using ethers.js to query and execute CosmWasm contracts from the EVM.*

<Info>
Per [Proposal 115](https://.app/proposals/115), no new CosmWasm contracts can be deployed on Paxeer. The examples below apply to **pre-existing CosmWasm contracts** only - `instantiate()` will revert. Separately, [Proposal 116](https://.app/proposals/116) disables inbound IBC transfers as part of the [SIP-03](/learn) migration.
</Info>

The Paxeer precompiles can be used like any standard smart contract on the EVM. For
example, using [ethers.js](https://docs.ethers.org/v6/), you can query and
execute actions on an existing CosmWasm contract as follows:

## Setup

To install `ethers`, run the following command in your project directory
terminal:

```bash
npm install ethers
npm install @sei-js/evm
```

Next, you'll need to use one of the precompiles in `EVM Precompiles` section. In
this example, we're going to be using the [wasmd precompile](/evm/precompiles/cosmwasm-precompiles/cosmwasm):

```typescript
// Import Wasm precompile address and ABI
// View the entire ABI here: https://github.com/paxeer-network/paxeer-chain/tree/evm/precompiles/wasmd
import { WASM_PRECOMPILE_ABI, WASM_PRECOMPILE_ADDRESS } from '@sei-js/evm';
```

## Using the contract

Next, we'll set up a provider and contract to interact with the blockchain:

```typescript
import { ethers, toUtf8Bytes, toUtf8String } from 'ethers';

// Using MetaMask as the signer and provider
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

// Create a contract with the signer
const contract = new ethers.Contract(WASM_PRECOMPILE_ADDRESS, WASM_PRECOMPILE_ABI, signer);
```

### Querying & Executing a CosmWasm Contract

Once you have the contract, you can query and execute messages to any CosmWasm
smart contract. In the below example we assume there is a counter contract with a `get_count` function

```typescript
// Replace with your contract
const COUNTER_CONTRACT_ADDRESS = 'pax1eyf...xff';

// Query to get the count on the counter contract (replace with function from your ABI)
const queryMsg = { get_count: {} };
const queryResponse = await contract.query(COUNTER_CONTRACT_ADDRESS, toUtf8Bytes(JSON.stringify(queryMsg)));
console.log(toUtf8String(queryResponse));

// Execute message to increment the count on the contract. (Replace with any function from your ABI)
// No funds are attached since the increment method does not require HPX. (Your ABI may require funds)
const executeMsg = { increment: {} };
const executeResponse = await contract.execute(
  COUNTER_CONTRACT_ADDRESS,
  toUtf8Bytes(JSON.stringify(executeMsg)),
  toUtf8Bytes(JSON.stringify([])) // Used for sending funds if needed
);

// Wait for the transaction to be confirmed
await executeResponse.wait();
console.log(executeResponse);
```

### Executing a payable function

In this example, we execute the 'donate' method on our contract. This is similar
to the `increment` method, but also receives funds from the user and stores it
in the contract.

```typescript
// Execute a message to donate to the contract.
const executeMsg = { donate: {} };

// Funds are attached via overrides. This example is specific to ethers.js
const overrides = {
  value: ethers.parseEther('3.2') // Sending 3.2 HPX
};
const executeResponse = await contract.execute(
  COUNTER_CONTRACT_ADDRESS,
  toUtf8Bytes(JSON.stringify(executeMsg)),
  toUtf8Bytes(JSON.stringify([{ denom: 'uusdc', amount: '100' }])), // Also send 100 uusdc
  overrides
);

await executeResponse.wait();
const receipt = await provider.getTransactionReceipt(executeResponse.hash);
```

For payable contracts, Paxeer amounts have to be sent directly to the contract
while other denoms should use the `coins` field.

---