{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_tip_header",
  "params": []
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "number": "0xb1a3c0",
    "hash": "0x4f3e...a1b2",
    "timestamp": "0x18f1d3a4e00"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}

// CKB RPC returns hex strings
const tipHeader = await callRpc("get_tip_header");
console.log(tipHeader.number);    // "0xb1a3c0"  (not 11640768)
console.log(tipHeader.timestamp); // "0x18f1d3a4e00"  (milliseconds since epoch)

// Convert using BigInt for safe 64-bit math
const blockNum = BigInt(tipHeader.number);   // 11640768n
const timestampMs = BigInt(tipHeader.timestamp);
const date = new Date(Number(timestampMs));

async function callRpc<T>(
  url: string,
  method: string,
  params: unknown[] = []
): Promise<T> {
  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: Date.now(),
      method,
      params,
    }),
  });

  const json = await response.json();

  if (json.error) {
    throw new Error(`RPC ${json.error.code}: ${json.error.message}`);
  }

  return json.result;
}

const header = await callRpc("get_tip_header");

// Header fields:
// number          — block height (hex)
// hash            — block hash (0x + 64 hex chars)
// timestamp       — Unix timestamp in MILLISECONDS (hex)
// parent_hash     — previous block's hash
// transactions_root — Merkle root of all transactions
// proposals_hash  — hash of the proposal zone
// compact_target  — PoW difficulty target (hex)
// epoch           — epoch number/index/length packed into uint64 (hex)
// nonce           — PoW nonce (hex)
// dao             — DAO deposit/withdraw accounting data
// extra_hash      — hash of extension data

console.log("Block number:", BigInt(header.number));
console.log("Timestamp:", new Date(Number(BigInt(header.timestamp))));

// verbosity=0: serialized binary (most compact, for relaying)
const serialized = await callRpc("get_block_by_number", ["0x100", "0x0"]);

// verbosity=1: JSON with only transaction hashes (lighter)
const withHashes = await callRpc("get_block_by_number", ["0x100", "0x1"]);

// verbosity=2: Full JSON with all transaction data (largest)
const full = await callRpc("get_block_by_number", ["0x100", "0x2"]);

// Block structure:
// {
//   header: Header,
//   transactions: TransactionWithHash[],
//   uncles: UncleBlock[],
//   proposals: string[],
//   extension: HexBytes | null
// }

// The first transaction is always the cellbase (block reward)
const cellbase = full.transactions[0];
const userTxs = full.transactions.slice(1);

const result = await callRpc("get_transaction", ["0xabcd..."]);

// Result structure:
// {
//   transaction: Transaction | null,
//   cycles: HexUint64 | null,      // compute cycles used
//   time_added_to_pool: HexUint64 | null,
//   min_replace_fee: HexUint64 | null,
//   tx_status: {
//     block_hash: Hash | null,
//     block_number: HexUint64 | null,
//     status: "pending" | "proposed" | "committed" | "rejected" | "unknown",
//     reason: string | null,
//     time_added_to_pool: HexUint64 | null
//   }
// }

if (result.tx_status.status === "committed") {
  console.log("Confirmed in block:", result.tx_status.block_number);
} else if (result.tx_status.status === "pending") {
  console.log("Still in mempool");
} else if (result.tx_status.status === "rejected") {
  console.log("Rejected:", result.tx_status.reason);
}

const result = await callRpc("get_live_cell", [
  { tx_hash: "0xabc...", index: "0x0" },
  true  // include data field
]);

// Result:
// {
//   cell: LiveCell | null,  // null if not found
//   status: "live" | "dead" | "unknown"
// }

if (result.status === "live") {
  const cell = result.cell;
  console.log("Capacity:", BigInt(cell.output.capacity) / 10n**8n, "CKB");
  console.log("Lock hash type:", cell.output.lock.hash_type);
  console.log("Data:", cell.data?.content);  // hex-encoded bytes
  console.log("Type script:", cell.output.type); // null if no type script
} else if (result.status === "dead") {
  console.log("Cell has already been spent");
}

const capacity = await callRpc("get_cells_capacity", [{
  script: {
    // secp256k1/blake160 lock script (standard address type)
    code_hash: "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",
    hash_type: "type",
    // 20-byte blake160 hash of the user's public key
    args: "0x36c329ed630d6ce750712a477543672adab57f4c"
  },
  script_type: "lock"
}]);

// Result:
// {
//   capacity: HexUint64,    // total shannons
//   block_hash: Hash256,    // block at which snapshot was taken
//   block_number: HexUint64 // block height
// }

const ckb = Number(BigInt(capacity.capacity)) / 1e8;
console.log(`Balance: ${ckb.toFixed(8)} CKB`);

const txHash = await callRpc("send_transaction", [
  {
    version: "0x0",
    cell_deps: [
      {
        out_point: {
          tx_hash: "0x71a7ba8fc96349fea0ed3a5c47992e3b4084b031a42264a018e0072e8172e46c",
          index: "0x0"
        },
        dep_type: "dep_group"
      }
    ],
    header_deps: [],
    inputs: [
      {
        previous_output: {
          tx_hash: "0xabc...",
          index: "0x0"
        },
        since: "0x0"
      }
    ],
    outputs: [
      {
        capacity: "0x174876e800",  // 100 CKB in shannons
        lock: {
          code_hash: "0x9bd7e...",
          hash_type: "type",
          args: "0x36c329..."
        },
        type: null
      }
    ],
    outputs_data: ["0x"],
    witnesses: [
      "0x5500000010000000550000005500000041000000..."
      // secp256k1 witness: WitnessArgs with lock_sig filled
    ]
  },
  "passthrough"  // outputs_validator: "passthrough" or "well_known_scripts_only"
]);

console.log("Submitted transaction:", txHash);

Your Application
      |
      v
CCC SDK (ccc.ClientPublicTestnet)
      |
      v
CkbRpcClient (internal)
      |
      v
JSON-RPC POST requests
      |
      v
CKB Node (https://testnet.ckb.dev)

import { ccc } from "@ckb-ccc/core";

// SDK abstracts get_tip_header + get_block internally
const client = new ccc.ClientPublicTestnet();

// This single SDK call may invoke multiple RPC methods:
await tx.completeInputsByCapacity(signer);
// Internally calls:
//   get_cells (indexer) to find spendable cells
//   get_cells_capacity to check balance
//   get_tip_header for fee estimation

// For tasks the SDK does not cover, use raw RPC:
const rawClient = new CkbRpcClient("https://testnet.ckb.dev");
const peers = await rawClient.getPeers();  // Not available in CCC SDK

const ws = new WebSocket("ws://localhost:18114");

let subscriptionId: string;

ws.onopen = () => {
  // Subscribe to new block headers
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "subscribe",
    params: ["new_tip_header"]
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  // The first message is the subscription confirmation
  if (msg.id === 1 && msg.result) {
    subscriptionId = msg.result;
    console.log("Subscribed with ID:", subscriptionId);
    return;
  }

  // Subsequent messages are subscription events
  if (msg.method === "subscribe") {
    const header = msg.params.result;
    console.log("New block:", BigInt(header.number).toLocaleString());
  }
};

ws.onerror = (err) => console.error("WebSocket error:", err);

// To unsubscribe:
function unsubscribe() {
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    id: 2,
    method: "unsubscribe",
    params: [subscriptionId]
  }));
}

async function getAllCells(
  client: CkbRpcClient,
  searchKey: SearchKey
): Promise<Cell[]> {
  const allCells: Cell[] = [];
  let cursor: string | undefined = undefined;
  const pageSize = "0x40"; // 64 cells per page

  while (true) {
    const params: unknown[] = cursor
      ? [searchKey, "asc", pageSize, cursor]
      : [searchKey, "asc", pageSize];

    const page = await client.call("get_cells", params);

    allCells.push(...page.objects);

    // "0x" (empty cursor) signals the last page
    if (page.last_cursor === "0x" || page.objects.length === 0) {
      break;
    }

    cursor = page.last_cursor;
  }

  return allCells;
}

class RpcError extends Error {
  constructor(
    public readonly code: number,
    message: string
  ) {
    super(`RPC Error ${code}: ${message}`);
  }
}

// Common CKB-specific error codes:
// -1: Invalid transaction (script execution failed)
// -2: Non-existent cell
// -3: Conflicting transaction (double-spend)
// -101: Transaction pool is full

async function callWithRetry<T>(
  fn: () => Promise<T>,
  options: { maxRetries?: number; retryDelay?: number } = {}
): Promise<T> {
  const { maxRetries = 3, retryDelay = 1000 } = options;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const isRpcError = err instanceof RpcError;
      const isLastAttempt = attempt === maxRetries;

      // Do not retry protocol errors (bad params, invalid tx, etc.)
      if (isRpcError && err.code < -100) throw err;

      if (isLastAttempt) throw err;

      // Exponential backoff for transient errors
      const delay = retryDelay * Math.pow(2, attempt);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error("unreachable");
}

class RateLimitedRpcClient {
  private queue: Array<() => void> = [];
  private activeRequests = 0;
  private readonly maxConcurrent = 5;
  private readonly minDelayMs = 100; // 10 req/sec max

  async call<T>(method: string, params: unknown[] = []): Promise<T> {
    // Wait if at capacity
    if (this.activeRequests >= this.maxConcurrent) {
      await new Promise<void>(resolve => this.queue.push(resolve));
    }

    this.activeRequests++;

    try {
      const result = await this.rawCall<T>(method, params);
      await new Promise(r => setTimeout(r, this.minDelayMs));
      return result;
    } finally {
      this.activeRequests--;
      // Release one queued request
      this.queue.shift()?.();
    }
  }
}

const results = await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify([
    { jsonrpc: "2.0", id: 1, method: "get_header_by_number", params: ["0x100"] },
    { jsonrpc: "2.0", id: 2, method: "get_header_by_number", params: ["0x101"] },
    { jsonrpc: "2.0", id: 3, method: "get_header_by_number", params: ["0x102"] },
  ])
});
const [h1, h2, h3] = await results.json();

async function callRpc<T>(
  url: string,
  method: string,
  params: unknown[] = []
): Promise<T> {
  const res = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
  });
  const json = await res.json();
  if (json.error) throw new Error(json.error.message);
  return json.result;
}

const RPC_URL = "https://testnet.ckb.dev";

const tip = await callRpc(RPC_URL, "get_tip_header");
const blockNum = BigInt(tip.number);
const ts = new Date(Number(BigInt(tip.timestamp)));

console.log(`Current block: #${blockNum.toLocaleString()}`);
console.log(`Block time: ${ts.toISOString()}`);
console.log(`Block hash: ${tip.hash}`);

const hexNum = "0x" + blockNum.toString(16);
const block = await callRpc(RPC_URL, "get_block_by_number", [hexNum, "0x2"]);

console.log(`Transactions: ${block.transactions.length}`);
console.log(`Uncle blocks: ${block.uncles.length}`);

// Decode block reward from cellbase
const cellbase = block.transactions[0].transaction;
const reward = BigInt(cellbase.outputs[0].capacity);
console.log(`Block reward: ${Number(reward) / 1e8} CKB`);

const txHash = block.transactions[0].hash;
const txResult = await callRpc(RPC_URL, "get_transaction", [txHash]);

console.log(`Status: ${txResult.tx_status.status}`);
console.log(`Block: #${BigInt(txResult.tx_status.block_number)}`);

const balance = await callRpc(RPC_URL, "get_cells_capacity", [{
  script: {
    code_hash: "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",
    hash_type: "type",
    args: "0x36c329ed630d6ce750712a477543672adab57f4c"
  },
  script_type: "lock"
}]);

const ckb = Number(BigInt(balance.capacity)) / 1e8;
console.log(`Balance: ${ckb.toFixed(8)} CKB`);

let lastBlock = blockNum;

const poll = setInterval(async () => {
  const tip = await callRpc(RPC_URL, "get_tip_header");
  const current = BigInt(tip.number);

  if (current > lastBlock) {
    console.log(`New block! #${current.toLocaleString()}`);
    lastBlock = current;
  }
}, 5000);

// Stop after 60 seconds
setTimeout(() => clearInterval(poll), 60_000);