@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