@chainvue/verus-sdk 0.5.0 → 0.5.1

package/README.md

@@ -1,75 +1,59 @@
 # @chainvue/verus-sdk
 
-**100% offline Verus transaction signing.** Build and sign Verus
-transactions — native transfers, token/currency transfers, conversions,
-and the full VerusID lifecycle (name commitment, registration, sub-IDs,
-update/revoke/recover, message signing) — with no daemon and no network
-access. You bring UTXOs and a WIF; the SDK returns signed transaction hex.
-
-Serialization delegates to VerusCoin's own primitives
-(`verus-typescript-primitives`) and a fork of `@bitgo/utxo-lib`, so the
-wire format is the daemon's, not a reimplementation.
-
-## Install
+Offline Verus transaction signing. Bring UTXOs and a WIF; get back signed
+transaction hex — no daemon, no network. Native transfers, token/currency
+transfers, conversions, and the full VerusID lifecycle. Serialization uses
+VerusCoin's own primitives, so the wire format is the daemon's, not a reimpl.
 
 ```bash
-npm install @chainvue/verus-sdk
+npm i @chainvue/verus-sdk
 ```
 
-The published package is a **self-contained bundle**: the VerusCoin forks
-(utxo-lib, primitives, bitcoin-ops) are inlined, so there are no `github:`
-dependencies or install-time patches in your dependency graph. Regular npm
-dependencies (`tiny-secp256k1`, `ecpair`, `bs58check`, `bn.js`,
-`create-hash`, `wif`) install normally.
-
-> **TypeScript consumers:** the type declarations reference the fork
-> packages' types, so set `"skipLibCheck": true` in your `tsconfig.json`
-> until the declarations are rolled up. Runtime is unaffected.
-
-## Usage
-
 ```ts
-import { VerusSDK } from '@chainvue/verus-sdk';
+import { VerusSDK } from "@chainvue/verus-sdk";
 
-const sdk = new VerusSDK({ network: 'testnet' }); // or 'mainnet'
+const sdk = new VerusSDK({ network: "testnet" }); // or "mainnet"
 
-// Native transfer — returns { signedTx, txid, fee, inputsUsed, nativeChange }
-const result = sdk.transfer({
-  wif: '<WIF>',
-  to: 'R...recipient',
-  amount: 100_000_000,          // satoshis
-  utxos: [/* { txid, outputIndex, satoshis, script } */],
-  changeAddress: 'R...change',
+const { signedTx, txid, fee } = sdk.transfer({
+  wif: "<WIF>",
+  to: "R…recipient",
+  amount: 100_000_000n, // satoshis (bigint)
+  utxos: [{ txid, outputIndex, satoshis: 500_000_000n, script }],
+  changeAddress: "R…change",
 });
-// broadcast result.signedTx via your own RPC (e.g. verus-rpc sendrawtransaction)
-
-// Decode a signed tx for a wallet ledger:
-import { utils } from '@chainvue/verus-sdk';
-const summary = utils.summarizeSignedTransaction(result.signedTx, 'testnet');
-// { txid, inputs: [{txid, vout}], outputs: [{valueSat, scriptHex, address}] }
+// broadcast signedTx yourself, e.g. verus-rpc `sendrawtransaction`
 ```
 
-Static helpers: `VerusSDK.generateWif()`, `VerusSDK.deriveAddress(wif)`,
-`VerusSDK.deriveIdentityAddress(name, parent?)`,
-`VerusSDK.validateAddress(addr)`, `VerusSDK.validateWif(wif)`.
-
-Identity lifecycle: `createCommitment`, `registerIdentity`,
-`updateIdentity` / `lockIdentity` / `unlockIdentity` / `revokeIdentity` /
-`recoverIdentity`, plus `signMessage` / `verifyMessage`.
-
-## Safety
-
-- **Every built transfer is validated** against its unfunded intent
-  (utxo-lib's own funded-transfer validator: per-currency value
-  conservation, change to the declared address) before the hex is returned
-  — a selection/change bug throws instead of producing a bad tx.
-- Signing is **offline**: the SDK never opens a socket. Broadcasting,
-  UTXO fetching and confirmation tracking are the caller's job.
-
-## Status
-
-Pre-release. The transaction wire format is proven against a live VRSCTEST
-daemon (decode round-trip + `sendrawtransaction` acceptance) — see
-[RISKS.md](./RISKS.md) for the live-proof harness and open items.
-
-License: Apache-2.0.
+**Money is `bigint` satoshis end to end — never a float.** Convert at the edges:
+`parseSats("1.5") → 150000000n`, `toCoins(150000000n) → "1.5"`.
+
+## What it does
+
+- **Transfers** — `transfer`, `transferToken`, `convert`, and `sendCurrency`
+  (full control over multi-output / cross-chain sends).
+- **VerusID** — `createCommitment` → `registerIdentity` (incl. sub-IDs), then
+  `updateIdentity` / `lockIdentity` / `unlockIdentity` / `revokeIdentity` /
+  `recoverIdentity`, plus `signMessage` / `verifyMessage`.
+- **Helpers** — `VerusSDK.generateWif()`, `deriveAddress(wif)`,
+  `deriveIdentityAddress(name, parent?)`, `validateAddress`, `validateWif`;
+  `utils.summarizeSignedTransaction(hex)` decodes a signed tx (txid, spent
+  outpoints, addressed outputs) for your ledger.
+
+Every built transfer is re-validated against its intent — per-currency value
+conservation, change to the declared address — before the hex is returned. A
+selection or change bug throws; it never hands you a bad transaction.
+
+## Good to know
+
+- **Self-contained bundle**: the VerusCoin forks (utxo-lib, primitives,
+  bitcoin-ops) are inlined — no `github:` deps or install-time patches in your
+  tree. Regular npm deps install normally.
+- **TypeScript**: self-contained declarations — no `skipLibCheck` needed and no
+  fork packages to install; the type surface for the bundled forks ships with the
+  package.
+- **Signing only**: broadcasting, UTXO fetching, and confirmation tracking are
+  yours (see [`verus-rpc`](https://www.npmjs.com/package/verus-rpc)).
+- Node ≥ 18. Wire format proven against a live VRSCTEST daemon — see
+  [RISKS.md](./RISKS.md).
+
+Apache-2.0 · see [NOTICE](./NOTICE) for the bundled forks.

package/dist/fork-shims.d.ts

@@ -0,0 +1,50 @@
+// Ambient type shims for the bundled VerusCoin forks.
+//
+// The forks (@bitgo/utxo-lib, verus-typescript-primitives) are INLINED into
+// dist/bundle.js and are not installable by consumers, yet a few of the SDK's
+// public type signatures reference them (VerusNetwork, TransactionBuilder,
+// Identity, nameAndParentAddrToIAddr). Without a shim, a consumer's `tsc`
+// reports "Cannot find module '@bitgo/utxo-lib'" unless they set
+// `skipLibCheck: true`.
+//
+// This file is copied to dist/ and referenced from dist/index.d.ts at build
+// time (scripts/finalize-types.mjs), so the published declarations are
+// self-contained: no fork packages required, no skipLibCheck. It declares only
+// the surface the public API exposes — intentionally minimal, and free of any
+// transitive type dependency (e.g. bn.js).
+
+declare module "@bitgo/utxo-lib" {
+  export interface VerusNetworkConfig {
+    messagePrefix: string;
+    bech32?: string;
+    bip32: { public: number; private: number };
+    pubKeyHash: number;
+    scriptHash: number;
+    wif: number;
+    coin: string;
+    [key: string]: unknown;
+  }
+
+  export const networks: {
+    verus: VerusNetworkConfig;
+    verustest: VerusNetworkConfig;
+    [key: string]: VerusNetworkConfig;
+  };
+
+  export class TransactionBuilder {
+    constructor(network?: VerusNetworkConfig, maximumFeeRate?: number);
+    setVersion(version: number): void;
+    setExpiryHeight(height: number): void;
+    setVersionGroupId(id: number): void;
+    addInput(txHash: string | Buffer, vout: number, sequence?: number, prevOutScript?: Buffer): number;
+    addOutput(scriptPubKeyOrAddress: Buffer | string, value: number): number;
+    build(): unknown;
+    buildIncomplete(): unknown;
+  }
+}
+
+declare module "verus-typescript-primitives" {
+  /** Opaque VerusID object — construct via the SDK's identity helpers. */
+  export class Identity {}
+  export function nameAndParentAddrToIAddr(name: string, parentIAddress?: string): string;
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./fork-shims.d.ts" />
 /**
  * @chainvue/verus-sdk
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chainvue/verus-sdk",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "100% offline, fully typed TypeScript SDK for Verus transaction signing",
   "author": "Robert Lech",
   "main": "dist/bundle.js",
@@ -38,7 +38,6 @@
     "@types/create-hash": "^1.2.6",
     "@types/node": "^20.19.33",
     "bitcoin-ops": "github:VerusCoin/bitcoin-ops#a5f8f56e658301bc39881d41740b3a0010530efd",
-    "conventional-changelog-conventionalcommits": "^10.2.1",
     "eslint": "^10.7.0",
     "globals": "^17.7.0",
     "semantic-release": "^25.0.7",
@@ -57,7 +56,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node scripts/finalize-types.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "clean": "rm -rf dist",