@znd/sdk

Official TypeScript/JavaScript SDK for Z-Node RPC endpoints.

Installation

npm install @znd/sdk
# or
pnpm add @znd/sdk
# or
yarn add @znd/sdk

Quick Start

import { ZNodeClient } from "@znd/sdk";

const client = new ZNodeClient({
  apiKey: "your-api-key",
});

// Get the latest block number
const blockNumber = await client.getBlockNumber();
console.log("Block number:", blockNumber);

// Get account balance
const balance = await client.getBalance("0x...");
console.log("Balance:", balance);

Configuration

const client = new ZNodeClient({
  // Required: Your Z-Node API key
  apiKey: "your-api-key",

  // Optional: Region for the endpoint
  region: "us-east",

  // Optional: Base domain (defaults to znode.dev)
  baseDomain: "znode.dev",

  // Optional: Request timeout in milliseconds (default: 30000)
  timeout: 30000,

  // Optional: Custom headers
  headers: {
    "X-Custom-Header": "value",
  },
});

Available Regions

Region ID	Location
us-east	US East (Virginia)
us-west	US West (California)
eu-west	Europe (Frankfurt)
asia-southeast	Asia Pacific (Singapore)
sa-east	South America (São Paulo)
me-south	Middle East (Dubai)
af-south	Africa (Cape Town)

Endpoint URL Format

The SDK constructs endpoint URLs as https://{region}-rpc.znode.dev/v1/{apiKey}

Default region is eu-west if not specified.

Ethereum JSON-RPC Methods

Block Methods

// Get latest block number
const blockNumber = await client.getBlockNumber();

// Get block by number
const block = await client.getBlockByNumber("latest");
const blockWithTxs = await client.getBlockByNumber("latest", true);

// Get block by hash
const block = await client.getBlockByHash("0x...");

// Get all receipts for a block
const receipts = await client.getBlockReceipts("latest");

// Get transaction count in a block
const txCount = await client.getBlockTransactionCountByNumber("latest");
const txCountByHash = await client.getBlockTransactionCountByHash("0x...");

Account Methods

// Get balance
const balance = await client.getBalance("0x...");
const balanceAtBlock = await client.getBalance("0x...", "0x1000");

// Get transaction count (nonce)
const nonce = await client.getTransactionCount("0x...");

// Get code at address
const code = await client.getCode("0x...");

// Get storage at position
const storage = await client.getStorageAt("0x...", "0x0");

Transaction Methods

// Get transaction by hash
const tx = await client.getTransactionByHash("0x...");

// Get transaction by block hash and index
const tx = await client.getTransactionByBlockHashAndIndex("0x...", 0);

// Get transaction by block number and index
const tx = await client.getTransactionByBlockNumberAndIndex("latest", 0);

// Get transaction receipt
const receipt = await client.getTransactionReceipt("0x...");

// Send raw transaction
const txHash = await client.sendRawTransaction("0x...");

// Estimate gas
const gas = await client.estimateGas({
  from: "0x...",
  to: "0x...",
  data: "0x...",
});

Call Methods

// Execute a call
const result = await client.call({
  to: "0x...",
  data: "0x...",
});

Log Methods

// Get logs
const logs = await client.getLogs({
  fromBlock: "0x1000",
  toBlock: "latest",
  address: "0x...",
  topics: ["0x..."],
});

Fee Methods

// Get gas price
const gasPrice = await client.getGasPrice();

// Get max priority fee per gas (EIP-1559)
const maxPriorityFee = await client.getMaxPriorityFeePerGas();

// Get blob base fee (EIP-4844)
const blobBaseFee = await client.getBlobBaseFee();

// Get fee history
const feeHistory = await client.getFeeHistory(10, "latest", [25, 50, 75]);

Chain Methods

// Get chain ID
const chainId = await client.getChainId();

// Get network version
const netVersion = await client.getNetVersion();

// Get client version
const clientVersion = await client.getClientVersion();

// Get protocol version
const protocolVersion = await client.getProtocolVersion();

// Check sync status
const syncing = await client.getSyncing();
if (syncing !== false) {
  console.log("Syncing:", syncing.currentBlock, "/", syncing.highestBlock);
}

// Get accounts (returns empty array for RPC nodes)
const accounts = await client.getAccounts();

State Proofs

// Get Merkle proof for an account and storage keys (EIP-1186)
const proof = await client.getProof("0x...", ["0x0", "0x1"], "latest");
console.log("Balance:", proof.balance);
console.log("Storage proofs:", proof.storageProof);

Access Lists

// Create an access list for a transaction (EIP-2930)
const accessList = await client.createAccessList({
  from: "0x...",
  to: "0x...",
  data: "0x...",
});
console.log("Access list:", accessList.accessList);
console.log("Gas used:", accessList.gasUsed);

Tron API Methods

// Get current block
const block = await client.tron_getNowBlock();

// Get block by number
const block = await client.tron_getBlockByNum(1000000);

// Get node info
const nodeInfo = await client.tron_getNodeInfo();

// Get account
const account = await client.tron_getAccount("TAddress...");

// Get account balance
const balance = await client.tron_getAccountBalance("TAddress...");

// Broadcast transaction
const result = await client.tron_broadcastTransaction(signedTx);

Batch Requests

// Execute multiple calls in a single request
const [blockNumber, chainId, gasPrice] = await client.batch<[string, string, string]>([
  { method: "eth_blockNumber" },
  { method: "eth_chainId" },
  { method: "eth_gasPrice" },
]);

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import type {
  Block,
  Transaction,
  TransactionReceipt,
  Log,
  FeeHistory,
  SyncStatus,
  AccessListItem,
  AccessListResult,
  AccountProof,
  StorageProof,
  TronBlock,
  TronAccount,
} from "@znd/sdk";

Error Handling

try {
  const balance = await client.getBalance("0x...");
} catch (error) {
  if (error instanceof Error) {
    console.error("Error:", error.message);
  }
}

License

MIT