@ramestta/bridge-sdk

Official Ramestta Bridge SDK for cross-chain deposits and withdrawals between Polygon (L2) and Ramestta (L3).

Installation

npm install @ramestta/bridge-sdk
# or
yarn add @ramestta/bridge-sdk

Quick Start

Read-Only Client

import { createBridgeClient, formatRama } from '@ramestta/bridge-sdk';

// Create client (uses default RPC endpoints)
const bridge = createBridgeClient();

// Check balances
const polygonBalance = await bridge.getPolygonBalance(
  '0x55a5CC06801bBa4C030568f1A7ee1c753FDcbe36', // RAMA token
  '0xYourAddress'
);
console.log('Polygon RAMA Balance:', formatRama(polygonBalance));

const ramesttaBalance = await bridge.getRamesttaBalance('0xYourAddress');
console.log('Ramestta Native Balance:', formatRama(ramesttaBalance));

// Check checkpoint status
const checkpoint = await bridge.getLastCheckpoint();
console.log('Latest Checkpoint:', checkpoint);

With Signer (For Transactions)

import { createBridgeClientFromPrivateKey, parseRama } from '@ramestta/bridge-sdk';

// Create client with private key
const bridge = createBridgeClientFromPrivateKey(
  'your-private-key',
  'https://polygon-rpc.com',
  'https://blockchain.ramestta.com'
);

// ========================================
// Deposit: Polygon (L2) → Ramestta (L3)
// ========================================

// 1. Approve tokens
const approveTx = await bridge.approveMaxDeposit('0xRootTokenAddress');
await approveTx.wait();

// 2. Deposit ERC20 tokens
const depositTx = await bridge.depositERC20(
  '0xRootTokenAddress',
  parseRama('100')
);
await depositTx.wait();
console.log('Deposit initiated:', depositTx.hash);

// ========================================
// Withdraw: Ramestta (L3) → Polygon (L2)
// ========================================

// 1. Start withdrawal (burn tokens on Ramestta)
const burnTx = await bridge.startWithdraw(
  '0xChildTokenAddress',
  parseRama('50')
);
await burnTx.wait();
console.log('Burn initiated:', burnTx.hash);

// 2. Wait for checkpoint (~30 min)
const isCheckpointed = await bridge.waitForCheckpoint(burnTx.blockNumber);

// 3. Process exit on Polygon (after checkpoint)
// Note: Exit proof generation requires additional SDK like matic.js

API Reference

BridgeClient

Constructor

const bridge = new BridgeClient({
  polygonProvider: ethersProvider,
  ramesttaProvider: ethersProvider,
  polygonSigner?: ethersSigner,  // Required for deposits
  ramesttaSigner?: ethersSigner, // Required for withdrawals
});

Read Methods

| Method | Description | |--------|-------------| | getLastCheckpoint() | Get latest checkpoint on RootChain | | isCheckpointed(blockNumber) | Check if block has been checkpointed | | getChildToken(rootToken) | Get child token address for a root token | | isERC721(rootToken) | Check if token is ERC721 | | getPolygonBalance(token, user) | Get token balance on Polygon | | getRamesttaBalance(user) | Get native RAMA balance on Ramestta | | getChildTokenBalance(childToken, user) | Get child token balance | | getExitInfo(exitId) | Get exit info by ID | | getTokenInfo(token, isRoot?) | Get token metadata |

Deposit Methods (L2 → L3)

| Method | Description | |--------|-------------| | approveDeposit(token, amount) | Approve tokens for deposit | | approveMaxDeposit(token) | Approve unlimited tokens | | depositERC20(token, amount, user?) | Deposit ERC20 tokens | | depositERC721(token, tokenId) | Deposit ERC721 NFT | | depositRAMA(amount) | Deposit native RAMA |

Withdraw Methods (L3 → L2)

| Method | Description | |--------|-------------| | startWithdraw(childToken, amount) | Burn tokens to start withdrawal | | startRAMAWithdraw(amount) | Start native RAMA withdrawal | | processExits(token, maxExits?) | Process pending exits |

Utility Methods

| Method | Description | |--------|-------------| | waitForTransaction(hash, provider, confirmations?) | Wait for tx confirmation | | waitForCheckpoint(blockNumber, maxWaitMs?) | Wait for checkpoint inclusion | | getContractAddresses() | Get all contract addresses | | getNetworkInfo() | Get network configuration |

Factory Functions

// Read-only client
createBridgeClient(polygonProviderOrUrl?, ramesttaProviderOrUrl?)

// Client with signers
createBridgeClientWithSigners(polygonSigner, ramesttaSigner)

// Client from private key
createBridgeClientFromPrivateKey(privateKey, polygonProviderOrUrl?, ramesttaProviderOrUrl?)

Utility Functions

// Format/parse with custom decimals
formatAmount(amount: BigNumber, decimals?: number): string
parseAmount(amount: string, decimals?: number): BigNumber

// Format/parse RAMA (18 decimals)
formatRama(amount: BigNumber): string
parseRama(amount: string): BigNumber

// Estimate bridge time
estimateBridgeTime(direction: 'deposit' | 'withdraw'): string

// Validate address
isValidAddress(address: string): boolean

Bridge Flow

Deposit Flow (L2 → L3)

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Polygon   │────▶│   Deposit    │────▶│  Ramestta   │
│    (L2)     │     │   Manager    │     │    (L3)     │
└─────────────┘     └──────────────┘     └─────────────┘
     │                     │                    │
     │  1. Approve         │  2. Deposit        │  3. Receive
     │     Tokens          │     (Lock)         │     Tokens
     ▼                     ▼                    ▼
   User                StateSender          ChildChain
  Wallet              (State Sync)         (Token Mint)

Time: ~5-10 minutes

Withdraw Flow (L3 → L2)

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Ramestta   │────▶│  Checkpoint  │────▶│   Polygon   │
│    (L3)     │     │   (30 min)   │     │    (L2)     │
└─────────────┘     └──────────────┘     └─────────────┘
     │                     │                    │
     │  1. Burn            │  2. Wait for       │  3. Exit
     │     Tokens          │     Checkpoint     │     (Unlock)
     ▼                     ▼                    ▼
  ChildChain           RootChain           Withdraw
  (Token Burn)        (Verify Proof)       Manager

Time: ~30-45 minutes

Example: Full Bridge Flow

import { 
  createBridgeClientFromPrivateKey, 
  parseRama, 
  formatRama,
  estimateBridgeTime 
} from '@ramestta/bridge-sdk';

async function bridgeExample() {
  const bridge = createBridgeClientFromPrivateKey(
    process.env.PRIVATE_KEY!,
    'https://polygon-rpc.com',
    'https://blockchain.ramestta.com'
  );

  const RAMA_TOKEN = '0x55a5CC06801bBa4C030568f1A7ee1c753FDcbe36';
  const myAddress = '0x...';

  // Check balance on Polygon
  const polygonBalance = await bridge.getPolygonBalance(RAMA_TOKEN, myAddress);
  console.log('Polygon Balance:', formatRama(polygonBalance));

  // Deposit to Ramestta
  console.log('Estimated time:', estimateBridgeTime('deposit'));

  // 1. Approve
  const approveTx = await bridge.approveMaxDeposit(RAMA_TOKEN);
  await approveTx.wait();
  console.log('Approved!');

  // 2. Deposit
  const depositTx = await bridge.depositERC20(RAMA_TOKEN, parseRama('10'));
  const receipt = await depositTx.wait();
  console.log('Deposited! Block:', receipt.blockNumber);

  // Check balance on Ramestta (after state sync)
  setTimeout(async () => {
    const ramesttaBalance = await bridge.getRamesttaBalance(myAddress);
    console.log('Ramestta Balance:', formatRama(ramesttaBalance));
  }, 5 * 60 * 1000); // Wait 5 minutes
}

Contract Addresses

Polygon (L2)

| Contract | Address | |----------|---------| | RootChain | 0x32BC23e5FFf7D567313dB4F41A5125Ad9D9Bca63 | | DepositManager | 0x81ebFB0c73d3165c4719E9604cDa55eF91226dAf | | WithdrawManager | 0x6e07F852bAC263492e8C710dB7c0d59275268db8 | | StateSender | 0xE0C9051E655380D1d880b9B0f4b500cEbD09278f | | ERC20Predicate | 0xC0dA09523c92714d0Df17e72966B3B80f228df8e | | RamaToken | 0x55a5CC06801bBa4C030568f1A7ee1c753FDcbe36 |

Ramestta (L3)

| Contract | Address | |----------|---------| | ChildChain | 0x0000000000000000000000000000000000001001 | | MRC20 | 0x0000000000000000000000000000000000001010 |

Networks

| Network | Chain ID | RPC | |---------|----------|-----| | Polygon Mainnet | 137 | https://polygon-rpc.com | | Ramestta Mainnet | 1370 | https://blockchain.ramestta.com | | Ramestta Testnet | 1371 | https://testnet.ramestta.com |

License

MIT © Ramestta Team