# Bridge Hub - Polkadot Interoperability

## Bridge Hub RPC plans and rate limits

- **Free plan:** 20 responses per second, up to 100,000 responses a day.
- **Plans:** $49/mo, $299/mo, $999/mo with 25M, 150M, and 500M included responses. Overages billed at $5/$3/$2 per million responses respectively.
- **Paid rate limits:** 100 to 5,000 responses per second (bursts from 500 to 10,000), no daily limit.
- **Billing:** 1 response = 1 API credit on every shared plan, over HTTPS or WebSocket (WSS) where Bridge Hub supports it.

Details: [Pricing](https://www.dwellir.com/docs/getting-started/pricing) · [Rate limits](https://www.dwellir.com/docs/getting-started/rate-limits) · [Authentication](https://www.dwellir.com/docs/getting-started/authentication) · [Archive nodes](https://www.dwellir.com/docs/getting-started/archive-nodes)

## Why Build on Bridge Hub?

Bridge Hub is Polkadot's system parachain dedicated to secure cross-network connectivity. It hosts bridge light clients, routing logic, and XCM tooling that allow ecosystems such as Kusama and Ethereum to interoperate without trusted third parties.

### **Trustless Finality**

- **On-chain GRANDPA & BEEFY verification** – Embedded light clients validate both Polkadot and bridged consensus, enabling permissionless relayers.
- **Optimistic root tracking** – Finality proofs are persisted so downstream chains can verify historical headers.
- **Governed suspension modes** – Bridge operators can pause lanes per pallet when anomalies are detected.

### **Multi-Chain Connectors**

- **Polkadot  Kusama routing** – Bridge Westend/Bridge Bulletin pallets exchange relay-chain and parachain headers between ecosystems.
- **Snowbridge (Polkadot  Ethereum)** – Native integration of Snowbridge pallets for ERC-20 asset movement and message passing with Ethereum mainnet.
- **Message fan-out** – Bridge Bulletin instances distribute payloads to partner chains without duplicating relayer work.

### **Specialized Pallets**

- `pallet_bridge_grandpa` – Stores bridged finality proofs and validator sets.
- `pallet_bridge_parachains` – Syncs parachain headers required for XCM and HRMP messaging.
- `pallet_bridge_messages` – Manages outbound/inbound lanes, delivery proofs, and fee accounting for cross-chain messages.
- `pallet_xcm_bridge_hub` – Provides XCM helpers for routing assets and arbitrary instructions over bridge lanes.

## Quick Start with Bridge Hub

Connect to Bridge Hub using Dwellir's low-latency infrastructure:

Dwellir maintains Bridge Hub connectivity across Polkadot environments:

- **Polkadot Bridge Hub** – Production-grade routing parachain for trustless bridging.
- **Westend Bridge Hub** – Official Polkadot testnet used for validating upgrades before mainnet rollout.
- **Paseo Bridge Hub** – Community-driven public testnet mirroring upcoming Polkadot features.
- **Kusama Bridge Hub** – Economic canary network that ships features before Polkadot.

### Installation & Setup

Direct JSON-RPC
Polkadot.js
Substrate API (Rust)
Python (py-substrate-interface)

```bash
# Discover supported RPC namespaces
curl -X POST https://api-bridge-hub-polkadot.n.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "rpc_methods",
    "params": [],
    "id": 1
  }'

# Fetch latest bridged Westend block hash
curl -X POST https://api-bridge-hub-polkadot.n.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "state_call",
    "params": [
      "BridgeWestendGrandpa_finalityApi_bestFinalized",
      "0x"
    ],
    "id": 2
  }'
```

```typescript
import { ApiPromise, WsProvider } from '@polkadot/api';

// Connect to Bridge Hub
const provider = new WsProvider('wss://api-bridge-hub-polkadot.n.dwellir.com/YOUR_API_KEY');
const api = await ApiPromise.create({ provider });

// Confirm we are on Bridge Hub
const [chain, version] = await Promise.all([
  api.rpc.system.chain(),
  api.rpc.system.version()
]);
console.log(`Connected to ${chain} v${version}`);

// Inspect the latest bridged Westend finality proof
const bestWestendFinality = await api.query.bridgeWestendGrandpa.bestFinalized();
console.log('Best Westend header finalized on Bridge Hub:', bestWestendFinality.toString());

// Track Snowbridge outbound lane metrics
const outboundLanes = await api.query.bridgeWestendMessages.outboundLanes.entries();
outboundLanes.slice(0, 1).forEach(([key, value]) => {
  console.log('Outbound lane', key.args[0].toString(), value.toHuman());
});
```

```rust
use jsonrpsee::rpc_params;
use substrate_api_client::{rpc::JsonrpseeClient, Api, GetBlockHash};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = JsonrpseeClient::with_url("https://api-bridge-hub-polkadot.n.dwellir.com/YOUR_API_KEY").await?;
    let api = Api::new(client).await?;

    // Fetch parachain head
    let head = api.get_finalized_head().await?;
    println!("Latest Bridge Hub head: {head}");

    // Query BEEFY justification root published by Bridge Hub
    let beefy_head: Option<String> = api
        .rpc()
        .request("beefy_getFinalizedHead", rpc_params![])
        .await?;
    println!("Latest BEEFY finalized head: {:?}", beefy_head);

    // Inspect permissionless lane pallet state
    let storage_key = api.metadata().storage_map_key(
        "BridgeRelayersForPermissionlessLanes",
        "RelayerConfig",
        &0u32,
    )?;
    let config: Option<Vec<u8>> = api.get_storage_by_key(storage_key, None).await?;
    println!("Permissionless relayer config: {:?}", config);

    Ok(())
}
```

```python
from substrateinterface import SubstrateInterface

substrate = SubstrateInterface(
    url="wss://api-bridge-hub-polkadot.n.dwellir.com/YOUR_API_KEY"
)

chain_name = substrate.rpc_request("system_chain", [])
print("Chain:", chain_name["result"])

# Retrieve head committed to the Kusama bridge lane
best_header = substrate.query(
    module='BridgeWestendGrandpa',
    storage_function='BestFinalized'
)
print("Best bridged Westend header:", best_header)

# Check outbound message lane status for Snowbridge
lane_status = substrate.query(
    module='EthereumOutboundQueue',
    storage_function='Outbox',
    params=[0]
)
print("Snowbridge outbound lane 0 status:", lane_status.value)
```

## Network Information

| Parameter    | Value         | Details                   |
| ------------ | ------------- | ------------------------- |
| Genesis Hash | 0xdcf691b5... | Bridge Hub (Polkadot)     |
| Block Time   | 6 seconds     | Aura + Relay finality     |
| Native Token | DOT           | Fees paid via Relay Chain |
| Parachain ID | 1002          | Polkadot system parachain |

### Network Details

| Parameter            | Value                                                                | Details |
| -------------------- | -------------------------------------------------------------------- | ------- |
| Relay Chain          | Polkadot                                                             |         |
| Genesis Hash         | `0xdcf691b5a3fbe24adc99ddc959c0561b973e329b1aef4c4b22e7bb2ddecb4464` |         |
| Consensus            | Collator-produced blocks with Polkadot relay GRANDPA finality        |         |
| Bridged Counterparts | Kusama (Westend), Bridge Bulletin, Ethereum (Snowbridge)             |         |
| Security             | On-chain slashable relayer incentives via `pallet_bridge_relayers`   |         |

## API Reference

Bridge Hub exposes the standard Substrate namespaces alongside bridge-specific RPCs for GRANDPA, BEEFY, and Snowbridge messaging. Public `bridge_*` proof namespaces are not yet exposed on current nodes.

## Bridge Protocols

### Snowbridge (Ethereum  Polkadot)

- **BEEFY light client** verifies Ethereum finality proofs and publishes outbound commitments.
- **Inbound queue** accepts ERC-20 and arbitrary message payloads via event proofs.
- **Outbound queue** batches Polkadot-origin messages and anchors them on Ethereum.

### Kusama Bridge (Westend  Polkadot)

- **BridgeWestendGrandpa** pallet syncs Westend finality headers and validator sets.
- **BridgeWestendParachains** tracks parachain heads to validate XCM and HRMP messages.
- **BridgeWestendMessages** exposes lane metrics, delivery confirmations, and fee accounting.

### Bridge Bulletin

- **Polkadot Bulletin** acts as a hub-and-spoke relay for partners requiring broadcast style delivery.
- **Permissionless lanes** allow new chains to request connectivity without runtime upgrades.

## XCM Integration

Bridge Hub exposes `pallet_xcm_bridge_hub` helpers for routing XCM messages over bridge lanes.

```typescript
import { ApiPromise, WsProvider } from '@polkadot/api';
import { BN } from '@polkadot/util';

const api = await ApiPromise.create({
  provider: new WsProvider('wss://api-bridge-hub-polkadot.n.dwellir.com/YOUR_API_KEY')
});

const laneId = 0; // Snowbridge outbound lane
const beneficiary = {
  parents: 2,
  interior: { X1: { AccountId32: { network: 'Any', id: '0x...' } } }
};
const assets = {
  parents: 1,
  interior: 'Here'
};

const tx = api.tx.xcmBridgeHub.sendAssetsOverBridge(
  laneId,
  beneficiary,
  assets,
  new BN('100000000000'),
  'Unlimited'
);

await tx.signAndSend('//Alice', ({ status }) => {
  if (status.isInBlock) {
    console.log('Bridge XCM submitted in block', status.asInBlock.toString());
  }
});
```

## Development Guides

### 1. Finality Relayer Checklist

- Subscribe to `bridgeWestendGrandpa.bestFinalized` and `bridgePolkadotBulletinGrandpa.bestFinalized` storage changes.
- Submit new proofs via `BridgeGrandpa.submit_finality_proof` extrinsics when headers advance by configured intervals.
- Monitor `pallet_bridge_relayers::Rewards` to reconcile payments.

### 2. Message Relayer Operations

- Watch `bridgeWestendMessages.outboundLanes(laneId)` for `latest_generated_nonce` vs `latest_received_nonce`.
- When public proof RPCs are released, fetch Merkle lane proofs before submitting to bridged chains (currently relayers must build proofs off-chain).
- Handle rejections by inspecting `bridgeHub` events: `MessageDispatched` and `MessageRejected`.

### 3. Observability & Alerting

- Track BEEFY justifications with `beefy_subscribeJustifications` for Snowbridge health.
- Use `state_traceBlock` on Bridge Hub to replay block execution when diagnosing bridge stalls.
- Surface metrics such as `MessageQueue.Processed` events to confirm queue throughput.

## Monitoring & Troubleshooting

| Scenario                       | Diagnostic Steps                                                                | Resolution                                                         |
| ------------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Lane backpressure              | Compare `latest_generated_nonce` and `latest_confirmed_nonce` on outbound lanes | Increase relayer frequency or investigate failed proofs            |
| Proof rejected on target chain | Rebuild proofs off-chain and verify against the target runtime                  | Re-submit with corrected payload or wait for next finalized header |
| BEEFY stalled                  | Check `beefy_subscribeJustifications` stream and collator logs                  | Restart Snowbridge relayer or investigate validator availability   |

With Dwellir endpoints you get globally replicated infrastructure, WebSocket support for proof streaming, and archive access for rebuilding historical proofs.
