@healchain/sdk 0.5.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @healchain/sdk
 
-JavaScript SDK for [HealChain](https://healchain.org) — self-healing decentralized storage using Reed-Solomon erasure coding on Ethereum and Arbitrum.
+JavaScript SDK for [HealChain](https://healchain.org) — self-healing decentralized storage using Reed-Solomon erasure coding across multiple EVM chains.
 
 ## Install
 
@@ -13,7 +13,10 @@ npm install @healchain/sdk
 ```javascript
 import HealChain from '@healchain/sdk';
 
-const hc = new HealChain({ apiUrl: 'https://api.healchain.org' });
+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', {
@@ -33,8 +36,9 @@ console.log(`Retrieved from chain ${retrievedFrom}: ${text}`);
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `apiUrl` | string | `https://api.healchain.org` | API base URL |
-| `apiKey` | string | — | Optional API key |
-| `network` | string | `'sepolia'` | Default network: `'sepolia'` or `'arbitrum'` |
+| `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 |
@@ -49,156 +53,101 @@ Store data on-chain. Polls until the oracle fulfills the request.
 **Parameters:**
 - `data` — `string` or `Uint8Array`
 - `options.label` — record label (default: `'sdk upload'`)
-- `options.network` — override network for this call
-- `options.dataShards` / `options.parityShards` — override shard config
-- `options.onPending(info)` — callback when tx is submitted
-- `options.onFulfilled(result)` — callback when oracle fulfills
-
-**Returns:** `Promise<StoreResult>`
-
-```typescript
-{
-  recordId:     string   // on-chain record ID
-  requestId:    string   // oracle request ID
-  tx:           string   // submission transaction hash
-  chainId:      string   // chain where data is stored
-  originalSize: string   // original data size in bytes
-  encodedSize:  string   // encoded shard size in bytes
-}
-```
+- `options.chain` — override chain for this store
+- `options.preference` — override preference for this store
+- `options.onFulfilled` — callback when oracle fulfills: `(result) => void`
 
-**Example with progress callbacks:**
-
-```javascript
-const result = await hc.store('my data', {
-  label: 'important file',
-  network: 'arbitrum',           // ~75x cheaper than Sepolia
-  onPending: ({ requestId }) => {
-    console.log(`Submitted, oracle processing requestId=${requestId}...`);
-  },
-  onFulfilled: ({ recordId }) => {
-    console.log(`Fulfilled! Record ID: ${recordId}`);
-  },
-});
-```
+**Returns:** `{ recordId, tx, chainId, originalSize, encodedSize, ciDigestHash }`
 
 ---
 
 ### `hc.retrieve(id)`
 
-Retrieve a record by ID. Automatically queries the GlobalRegistry to find which chain holds the data and fetches from there.
+Retrieve data by record ID. Auto-discovers which chain the record lives on.
 
-**Parameters:**
-- `id` — `string` or `number`
+**Returns:** `{ text, hex, chainId, originalSize, label }`
 
-**Returns:** `Promise<RetrieveResult>`
+---
 
-```typescript
-{
-  recordId: string   // record ID
-  data:     string   // hex-encoded original data (0x...)
-  text:     string   // UTF-8 decoded text
-  bytes:    number   // original data size in bytes
-  chainId:  string   // chain where data was stored ('11155111' or '421614')
-}
+### `hc.estimateFee(sizeBytes, chain?)`
+
+Estimate the fee for storing data of a given size.
+
+**Returns:** `{ feeCents, feeUsd, sizeBytes, chain }`
+
+```javascript
+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)`
 
-Fetch record metadata without retrieving the full data payload.
+Get record metadata without retrieving the data.
 
-**Returns:** `Promise<object>` — label, owner, sizes, shards, timestamp, dataHash
+**Returns:** `{ id, label, originalSize, encodedSize, dataShards, parityShards, owner, timestamp, chainId }`
 
 ---
 
 ### `hc.list(page?, limit?)`
 
-List records with pagination.
+List stored records.
 
-**Parameters:**
-- `page` — page number, 0-indexed (default: `0`)
-- `limit` — records per page, max 50 (default: `10`)
-
-**Returns:**
-```typescript
-{
-  records: object[]  // record summaries
-  total:   number    // total record count
-  pages:   number    // total page count
-  page:    number    // current page
-}
-```
+**Returns:** `{ records, total, pages }`
+
+---
+
+### `hc.getBillingBalance(walletAddress)`
+
+Get testnet credit balance for a wallet.
 
 ---
 
 ### `hc.health()`
 
-Check service health.
+Check API health.
 
-**Returns:** `Promise<{ status, version, geth, lastBlock }>`
+**Returns:** `{ status, version, lastBlock }`
 
 ---
 
 ## Error Handling
 
-All methods throw `HealChainError` on failure:
-
 ```javascript
-import { HealChain, HealChainError } from '@healchain/sdk';
+import HealChain, { HealChainError } from '@healchain/sdk';
 
 try {
-  const result = await hc.retrieve(999);
+  const result = await hc.store('my data', { label: 'test' });
 } catch (err) {
   if (err instanceof HealChainError) {
-    console.error(err.message);   // human-readable message
-    console.error(err.status);    // HTTP status code (if applicable)
-    console.error(err.code);      // 'NETWORK_ERROR' | 'FULFILLMENT_TIMEOUT' | null
+    console.error(err.message, err.status, err.code);
   }
 }
 ```
 
----
-
-## Browser (ESM)
-
-```html
-<script type="module">
-  import HealChain from 'https://esm.sh/@healchain/sdk';
-
-  const hc = new HealChain({ apiUrl: 'https://api.healchain.org' });
-  const { text } = await hc.retrieve(0);
-  console.log(text);
-</script>
-```
-
----
-
-## Networks
+## Supported Chains
 
-| Network | Chain ID | Notes |
+| Chain | ID | Identifier |
 |---|---|---|
-| `sepolia` | 11155111 | Ethereum Sepolia testnet |
-| `arbitrum` | 421614 | Arbitrum Sepolia testnet — ~75x cheaper gas |
-
-Store on Arbitrum for lower cost. Retrieve works automatically regardless of which chain the data is on — the SDK doesn't need to know.
-
----
-
-## Roadmap
+| 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 |
 
-- **v0.1** — REST API client (store, retrieve, list, health) ✅
-- **v0.2** — Direct wallet signing via ethers.js (no service required)
-- **v0.3** — Streaming large file support
-- **v1.0** — Mainnet support
-
----
+Use `chain: 'auto'` (default) to let the scoring engine pick the optimal chain.
 
 ## License
 
-MIT — see [LICENSE](LICENSE)
-
----
-
-*Built on [HealChain](https://healchain.org) · [GitHub](https://github.com/karmaxul/ci-quantum-storage)*
+MIT © [HealChain](https://healchain.org)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@healchain/sdk",
-  "version": "0.5.0",
+  "version": "1.1.0",
   "description": "JavaScript SDK for HealChain — self-healing decentralized storage via Reed-Solomon erasure coding",
   "main": "src/index.js",
   "module": "src/index.js",

package/src/index.js

@@ -1,5 +1,5 @@
 /**
- * HealChain SDK v0.4.0
+ * HealChain SDK v1.1.0
  * REST API client for HealChain — self-healing decentralized storage.
  *
  * Browser (ESM) and Node.js compatible.
@@ -76,7 +76,10 @@ class HealChain {
     this.dataShards   = options.dataShards   ?? DEFAULT_DATA_SHARDS;
     this.parityShards = options.parityShards ?? DEFAULT_PARITY_SHARDS;
     this.chain        = options.chain ?? options.network ?? 'auto';
-    this.network      = this.chain; // backward compat
+    this.network      = this.chain; // backward compat — use chain instead
+    if (options.network && !options.chain) {
+      console.warn('[HealChain] options.network is deprecated — use options.chain instead');
+    }
     this.preference   = options.preference   ?? '';
   }
 
@@ -238,14 +241,82 @@ class HealChain {
    * @property {number} bytes    - Original data size in bytes
    * @property {string} chainId  - Chain where data was stored
    */
-  async retrieve(id) {
-    const result = await this._fetch(`/retrieve?id=${encodeURIComponent(String(id))}`);
-    return {
+  async retrieve(id, options = {}) {
+    const chain = options.chain ?? this.chain ?? 'auto';
+    const result = await this._fetch(
+      `/retrieve?id=${encodeURIComponent(String(id))}&chain=${encodeURIComponent(chain)}`
+    );
+    const record = {
       recordId: String(result.recordId),
       data:     result.data,
       text:     result.text,
       bytes:    result.bytes,
       chainId:  result.chainId ?? null,
+      storageType: result.storageType ?? 'on_chain',
+      shards:   result.shards ?? null,
+    };
+    // Fetch full ci-sha4096 digest — best-effort, non-blocking
+    try {
+      record.ciDigestHash = await this.getCiDigest(id);
+    } catch (_) {
+      // digest not yet available for old records — silently omit
+    }
+    return record;
+  }
+
+  // ── storeFile() ────────────────────────────────────────────────────────────
+
+  /**
+   * Store a file (raw bytes) on-chain or via IPFS hybrid (auto-detected by size).
+   * Files ≤1MB go on-chain. Files >1MB use IPFS hybrid storage.
+   *
+   * @param {Uint8Array|ArrayBuffer|Buffer} buffer - File bytes
+   * @param {object} [options]
+   * @param {string}  [options.label='sdk upload'] - Record label
+   * @param {number}  [options.dataShards]         - Override RS data shards
+   * @param {number}  [options.parityShards]       - Override RS parity shards
+   * @param {string}  [options.chain]              - Chain name or 'auto'
+   * @param {string}  [options.preference]         - Chain selection preference
+   * @returns {Promise<StoreResult>}
+   */
+  async storeFile(buffer, options = {}) {
+    const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+    return this.store(bytes, options);
+  }
+
+  // ── getCiDigest() ──────────────────────────────────────────────────────────
+
+  /**
+   * Get the full 512-byte ci-sha4096 digest hex for a record.
+   * This is the authoritative digest stored at oracle fulfillment time.
+   *
+   * @param {string|number} recordId - Record ID
+   * @returns {Promise<string>} Full digest hex (1024 hex chars = 512 bytes)
+   */
+  async getCiDigest(recordId) {
+    const result = await this._fetch(`/ciDigest?recordId=${encodeURIComponent(String(recordId))}`);
+    return result.ciDigestHash;
+  }
+
+  // ── verifyIntegrity() ──────────────────────────────────────────────────────
+
+  /**
+   * High-level audit helper: retrieve a record and its ci-sha4096 digest.
+   *
+   * @param {string|number} recordId - Record ID
+   * @param {object} [options]
+   * @param {string} [options.chain] - Chain name or 'auto'
+   * @returns {Promise<{record: RetrieveResult, ciDigestHash: string|null}>}
+   */
+  async verifyIntegrity(recordId, options = {}) {
+    const chain = options.chain ?? this.chain ?? 'auto';
+    const [record, ciDigestHash] = await Promise.allSettled([
+      this._fetch(`/retrieve?id=${encodeURIComponent(String(recordId))}&chain=${encodeURIComponent(chain)}`),
+      this.getCiDigest(recordId),
+    ]);
+    return {
+      record:       record.status === 'fulfilled' ? record.value : null,
+      ciDigestHash: ciDigestHash.status === 'fulfilled' ? ciDigestHash.value : null,
     };
   }