@healchain/sdk

JavaScript SDK for HealChain — self-healing decentralized storage using Reed-Solomon erasure coding across multiple EVM chains.

Install

npm install @healchain/sdk

Quick Start

import HealChain from '@healchain/sdk';

const hc = new HealChain({
  apiUrl: 'https://api.healchain.org',
  apiKey: 'your-api-key',
});

// Store data — oracle fulfills automatically
const { recordId, chainId } = await hc.store('Hello World', {
  label: 'my first record',
});
console.log(`Stored as record #${recordId} on chain ${chainId}`);

// Retrieve — auto-discovers chain from GlobalRegistry
const { text, chainId: retrievedFrom } = await hc.retrieve(recordId);
console.log(`Retrieved from chain ${retrievedFrom}: ${text}`);

API

new HealChain(options)

| Option | Type | Default | Description | |---|---|---|---| | apiUrl | string | https://api.healchain.org | API base URL | | apiKey | string | — | API key (required for store/retrieve) | | chain | string | 'auto' | Chain: 'auto', 'sepolia', 'arbitrum', 'base', etc. | | preference | string | '' | 'cheapest' | 'fastest' | 'redundant' | '' (auto weighted) | | pollInterval | number | 4000 | Oracle poll interval in ms | | pollTimeout | number | 120000 | Max wait for oracle fulfillment in ms | | dataShards | number | 10 | Default RS data shards | | parityShards | number | 4 | Default RS parity shards |

hc.store(data, options?)

Store data on-chain. Polls until the oracle fulfills the request.

Parameters:

• data — string or Uint8Array
• options.label — record label (default: 'sdk upload')
• options.chain — override chain for this store
• options.preference — override preference for this store
• options.onFulfilled — callback when oracle fulfills: (result) => void

Returns: { recordId, tx, chainId, originalSize, encodedSize, ciDigestHash }

hc.retrieve(id)

Retrieve data by record ID. Auto-discovers which chain the record lives on.

Returns: { text, hex, chainId, originalSize, label }

hc.estimateFee(sizeBytes, chain?)

Estimate the fee for storing data of a given size.

Returns: { feeCents, feeUsd, sizeBytes, chain }

const fee = await hc.estimateFee(1024, 'auto');
console.log(`Fee: ${fee.feeUsd}`); // e.g. "$0.05"

hc.chainScores()

Get current chain scoring data (cost, reliability, latency).

Returns: array of chain score objects

hc.getMetadata(id)

Get record metadata without retrieving the data.

Returns: { id, label, originalSize, encodedSize, dataShards, parityShards, owner, timestamp, chainId }

hc.list(page?, limit?)

List stored records.

Returns: { records, total, pages }

hc.getBillingBalance(walletAddress)

Get testnet credit balance for a wallet.

hc.health()

Check API health.

Returns: { status, version, lastBlock }

Error Handling

import HealChain, { HealChainError } from '@healchain/sdk';

try {
  const result = await hc.store('my data', { label: 'test' });
} catch (err) {
  if (err instanceof HealChainError) {
    console.error(err.message, err.status, err.code);
  }
}

Supported Chains

| Chain | ID | Identifier | |---|---|---| | Ethereum Sepolia | 11155111 | sepolia | | Arbitrum Sepolia | 421614 | arbitrum | | Base Sepolia | 84532 | base | | Optimism Sepolia | 11155420 | optimism | | Unichain Sepolia | 1301 | unichain | | Avalanche Fuji | 43113 | avalanche | | And 7 more testnets... | | auto selects best |

Use chain: 'auto' (default) to let the scoring engine pick the optimal chain.

License

MIT © HealChain