@pons-network/pons.js

Pons Network SDK - Decentralized cross-chain execution layer.

Overview

Pons Network is a decentralized cross-chain execution layer that enables DApps to build seamless cross-chain experiences where users:

• Sign once on the source chain
• Execute anywhere on the destination chain
• Pay fees in USDC - dynamic fees like Ethereum gas

How It Works

┌─────────────────────────────────────────────────────────────────────────────┐
│                        PONS NETWORK ARCHITECTURE                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  SOURCE CHAIN                 PONS NETWORK              DESTINATION CHAIN  │
│  ┌───────────────┐           ┌───────────────┐         ┌───────────────┐   │
│  │               │           │               │         │               │   │
│  │ 1. User signs │           │ 3. Message    │         │ 5. Message    │   │
│  │    action     │  ──────►  │    relayed    │ ──────► │    indexed    │   │
│  │               │           │               │         │               │   │
│  │ 2. Message    │           │ 4. Attestation│         │ 6. Action     │   │
│  │    sent       │           │    verified   │         │    executed   │   │
│  │               │           │               │         │               │   │
│  └───────────────┘           └───────────────┘         └───────────────┘   │
│                                                                             │
│  User stays on source chain - no network switching required!               │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Decentralized Operators

Pons Network is permissionless - anyone can participate and earn:

┌─────────────────────────────────────────────────────────────────────────┐
│                    DECENTRALIZED OPERATORS                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  🔍 INDEXERS                          ⚡ RESOLVERS                       │
│  • Monitor cross-chain messages       • Execute user actions            │
│  • Index messages on destination      • Provide ETH/tokens if needed    │
│  • Earn indexer fees                  • Earn resolver fees              │
│                                                                         │
│  Anyone can run an indexer or resolver and earn income!                │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Why Decentralization Matters

• Permissionless - Anyone can publish messages, run indexers, or become a resolver
• Censorship Resistant - No single entity controls message relay or execution
• Competitive Fees - Multiple operators compete to provide best service
• Resilient - System continues operating even if some operators go offline

Installation

npm install @pons-network/pons.js viem

Quick Start

import { 
  PonsClient, 
  Chain, 
  calculateFeesSync 
} from '@pons-network/pons.js';
import { parseUnits } from 'viem';

// Initialize Pons client
const pons = await PonsClient.create({
  from: Chain.SEPOLIA,
  to: Chain.ARC_TESTNET,
  sourceRpcUrl: 'https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY',
  destinationRpcUrl: 'https://rpc.testnet.arc.network',
});

// Calculate fees (dynamic like ETH gas)
const fees = calculateFeesSync(parseUnits('15', 6));

// Execute cross-chain action
const result = await pons.execute({
  amount: fees.burnAmount,
  action: {
    target: CONTRACT_ADDRESS,
    callData: encodedCalldata,
    feeConfig: {
      paymentToken: USDC_ADDRESS,
      indexerFee: fees.indexerFee,
      resolverFee: fees.resolverFee,
    },
    funding: {
      maxReimbursement: fees.amountForAction,
    },
  },
}, walletClient);

// Track transfer across chains
const tracker = pons.trackTransfer(result.txHash, result.smartAccountAddress, result.nonce);
tracker.on('statusChange', (update) => console.log(update.status));

---

Table of Contents

• Installation
• How Pons Works
• Fee System
• Becoming an Operator
• API Reference
• Chain Support

---

Fee System

Pons uses dynamic fees similar to Ethereum gas. Pay more for faster execution, or pay less to save money.

Dynamic Fee Model

┌─────────────────────────────────────────────────────────────────────────────┐
│                          DYNAMIC FEE MODEL                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ⚡ FAST (Higher fees)                                                      │
│     Pay above market rate → Operators prioritize your transaction          │
│                                                                             │
│  🔄 STANDARD (Market rate)                                                  │
│     Pay market rate → Normal execution speed                               │
│                                                                             │
│  🐢 ECONOMY (Lower fees)                                                    │
│     Pay below market rate → Slower execution, but cheaper                  │
│                                                                             │
│  Just like Ethereum gas - you choose speed vs cost!                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Fee Breakdown

User sends: 15.00 USDC
    │
    ├── Network Fee (~0.01%)      → Cross-chain relay
    │
    └── Expected Amount           → Arrives at Smart Account
            │
            ├── Protocol Fee (~0.1%)  → Pons treasury
            ├── Indexer Fee (dynamic) → Indexer operator
            ├── Resolver Fee (dynamic) → Resolver operator
            │
            └── Amount for Action     → Available for your action

Fee Calculation

import { calculateFeesSync, calculateBurnForAction } from '@pons-network/pons.js';

// Calculate with default fees
const fees = calculateFeesSync(parseUnits('15', 6));

// Custom fees for faster execution
const fastFees = calculateFeesSync(parseUnits('15', 6), {
  indexerFee: parseUnits('0.2', 6),  // 2x default → faster indexing
  resolverFee: parseUnits('0.3', 6),  // 2x default → faster execution
});

// Economy fees for cost savings
const economyFees = calculateFeesSync(parseUnits('15', 6), {
  indexerFee: parseUnits('0.05', 6), // 0.5x default → slower but cheaper
  resolverFee: parseUnits('0.08', 6), // 0.5x default → slower but cheaper
});

---

Becoming an Operator

Pons Network is permissionless - anyone can become an indexer or resolver and earn income!

Indexers

Indexers monitor cross-chain messages and index them on the destination chain.

What indexers do:

1. Watch for messages on source chains
2. Wait for attestation verification
3. Index the message on destination chain
4. Earn indexer fee for each message

Requirements:

• RPC access to source and destination chains
• ETH for gas on destination chain
• Run the Pons resolver in indexer mode

# Run as indexer
docker run -d pons/resolver:latest \
  --mode indexer \
  --chains sepolia,arc-testnet

Resolvers

Resolvers execute user actions after messages are indexed.

What resolvers do:

1. Monitor for indexed messages
2. Validate action profitability
3. Execute user's signed action
4. Optionally provide ETH/tokens upfront (reimbursed in USDC)
5. Earn resolver fee for each execution

Requirements:

• RPC access to destination chain
• ETH for gas
• Optional: USDC/ETH/tokens for funding actions
• Run the Pons resolver in resolver mode

# Run as resolver
docker run -d pons/resolver:latest \
  --mode executor \
  --chains arc-testnet

Operator Economics

Operators compete for transactions by offering competitive fees:

• Higher fees = operators prioritize your transaction
• Lower fees = slower execution but still processed
• Market finds equilibrium based on supply/demand

---

API Reference

PonsClient

Main client for cross-chain operations.

import { PonsClient, Chain } from '@pons-network/pons.js';

// Initialize
const pons = await PonsClient.create({
  from: Chain.SEPOLIA,
  to: Chain.ARC_TESTNET,
  sourceRpcUrl: 'https://...',
  destinationRpcUrl: 'https://...',
});

// Execute cross-chain transfer
const result = await pons.execute(params, walletClient);

// Track transfer status
const tracker = pons.trackTransfer(txHash, smartAccount, nonce);

// Get Smart Account address
const address = await pons.calculateSmartAccountAddress(owner, salt);

// Cleanup
await pons.stop();

ActionBuilder

Build complex cross-chain actions.

import { ActionBuilder } from '@pons-network/pons.js';

// Simple contract call
const action = new ActionBuilder()
  .addCall(contractAddress, calldata)
  .withFees(USDC_ADDRESS, indexerFee, resolverFee)
  .build(nonce, deadline, expectedAmount);

// Batch actions (approve + swap + stake)
const batchAction = new ActionBuilder()
  .addCall(USDC_ADDRESS, approveCalldata)
  .addCall(UNISWAP_ROUTER, swapCalldata)
  .addCall(STAKING_CONTRACT, stakeCalldata)
  .withFees(USDC_ADDRESS, indexerFee, resolverFee)
  .needsEth(ethAmount, reimbursement)
  .build(nonce, deadline, expectedAmount);

TransferTracker

Track cross-chain transfer status.

import { TransferStatus } from '@pons-network/pons.js';

const tracker = pons.trackTransfer(txHash, smartAccount, nonce);

tracker.on('statusChange', (status) => {
  switch (status) {
    case TransferStatus.PENDING:
      console.log('Message sent, waiting for relay...');
      break;
    case TransferStatus.INDEXED:
      console.log('Message indexed on destination!');
      break;
    case TransferStatus.EXECUTED:
      console.log('Action executed by resolver!');
      break;
  }
});

Fee Functions

Function	Use Case
calculateFeesSync(amount, options?)	Calculate fees with custom rates
calculateBurnForAction(amount, options?)	Reverse: action cost → send amount
validateActionFeasibility(send, need)	Pre-validate before signing
DEFAULT_FEES	Default fee constants

---

Chain Support

Built-in Chains

import { Chain, arcTestnet, sepolia } from '@pons-network/pons.js';

// Use chain constants
const pons = await PonsClient.create({
  from: Chain.SEPOLIA,
  to: Chain.ARC_TESTNET,
  // ...
});

// Available chains
Chain.SEPOLIA      // Ethereum Sepolia testnet
Chain.ARC_TESTNET  // Arc Network testnet
Chain.ETHEREUM     // Ethereum mainnet (coming soon)

---

Documentation

• Examples & Integration Guide
• Fee Calculations Guide
• Integration Guide
• API Reference

---

Why Pons Network?

Traditional Bridging	Pons Network
Centralized resolvers	Decentralized operators
Fixed fees	Dynamic fees (like ETH gas)
Switch networks manually	Stay on your chain
Multiple transactions	One signature
Need gas on destination	Fees in USDC only

Pons Network provides a decentralized execution layer, giving your users a trustless multi-chain experience.

---

Links

• Website: https://pons.sh/
• Documentation: https://docs.pons.sh/
• Twitter/X: https://x.com/Pons_Network
• Discord: https://discord.com/invite/ponsnetwork
• GitHub: https://github.com/PonsNetwork

---

License

MIT