Skip to content

README.md

Latest commit

 

History

History
94 lines (68 loc) · 3.09 KB

README.md

File metadata and controls

94 lines (68 loc) · 3.09 KB
Raw

@fairco.in/rpc-client

JSON-RPC client for the FairCoin daemon (faircoind). Zero runtime dependencies, pure TypeScript, Node 20+.

Shared between the FairCoin Explorer and the WFAIR bridge as the single source of truth for faircoind wire calls.

Install

bun add @fairco.in/rpc-client
# or
npm install @fairco.in/rpc-client

Usage

Quick start: env-configured client

The library reads the standard FAIRCOIN_RPC_* / FAIRCOIN_TESTNET_RPC_* environment variables used across the FairCoin ecosystem.

import { rpcWithNetwork, getBlockCount } from '@fairco.in/rpc-client';

const height = await getBlockCount('mainnet');

const block = await rpcWithNetwork<{ hash: string; tx: string[] }>(
  'getblock',
  ['0000000000000000000000000000000000000000000000000000000000000000', true],
  'mainnet',
);

Explicit client

For tests, proxies, or multi-endpoint setups, construct a client directly:

import { FaircoinRpcClient } from '@fairco.in/rpc-client';

const client = new FaircoinRpcClient({
  rpcUser: 'fair',
  rpcPass: 'change_me',
  rpcHost: '127.0.0.1',
  rpcPort: '46373',
  rpcScheme: 'http',
});

const count = await client.call<number>('getblockcount');

Custom endpoint URL

import { FaircoinRpcClient } from '@fairco.in/rpc-client';

const client = new FaircoinRpcClient({
  url: 'https://my-proxy.example/faircoin-rpc',
  rpcUser: 'fair',
  rpcPass: 'change_me',
});

Environment variables

Variable Default Purpose
FAIRCOIN_RPC_USER fair Mainnet RPC username
FAIRCOIN_RPC_PASS change_me Mainnet RPC password
FAIRCOIN_RPC_HOST seed1.fairco.in Mainnet host
FAIRCOIN_RPC_PORT 46373 Mainnet port
FAIRCOIN_RPC_SCHEME http http or https
FAIRCOIN_TESTNET_RPC_USER ${FAIRCOIN_RPC_USER} Testnet username
FAIRCOIN_TESTNET_RPC_PASS ${FAIRCOIN_RPC_PASS} Testnet password
FAIRCOIN_TESTNET_RPC_HOST 127.0.0.1 Testnet host
FAIRCOIN_TESTNET_RPC_PORT 46375 Testnet port
FAIRCOIN_TESTNET_RPC_SCHEME http http or https

API

  • rpc(method, params?) / rpcWithNetwork(method, params?, network?) — one-shot calls using env-configured credentials.
  • FaircoinRpcClient — reusable per-endpoint client.
  • createClientForNetwork(network, env?, overrides?) — build a client from env vars with optional overrides.
  • readNetworkConfigFromEnv(network, env?) — inspect which host/credentials would be used.
  • Typed helpers: getBlockCount, getBlockHash, getBlock, getRawTransactionVerbose (and their *Mainnet aliases).

Design notes

  • Stateless. The client holds no mutable state; share instances freely.
  • No caching. Caching is the consumer's concern (e.g. Explorer backs calls with MongoDB; bridges typically don't cache).
  • Minifier-safe coercion. getblock's verbose flag is coerced to boolean; getrawtransaction's verbose flag is coerced to integer. Some minifiers rewrite booleans to 0/1, which would otherwise ship the wrong wire type.

License

MIT