verus-rpc 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,139 @@
+# verus-rpc
+
+The npm-published, full-coverage, precision-honest TypeScript client for
+talking to your own `verusd` — daemon-first JSON-RPC transport and types.
+
+```bash
+npm install verus-rpc   # or: pnpm add verus-rpc
+```
+
+```ts
+import { VerusClient, formatAmount } from "verus-rpc";
+
+// Read-only against the public mainnet RPC — no daemon, no credentials.
+const client = new VerusClient({
+  url: "https://api.verus.services",
+  user: "public",
+  pass: "public",
+});
+
+const id = await client.identity.getIdentity({ nameOrAddress: "Verus Coin Foundation@" });
+console.log(id.identity.identityaddress);
+
+const balance = await client.wallet.getBalance();       // 200_000_000n  (bigint sats)
+console.log(formatAmount(balance));                      // "2.00000000"
+```
+
+## The one invariant
+
+**No float ever crosses the public API for a value field.**
+
+The daemon emits amounts as JSON decimal numbers (`{"VRSCTEST":2.00000000}`,
+and on mainnet even `relayfee:1e-6`). A client that runs those through
+`JSON.parse` puts float64 in its money path. `verus-rpc` parses the response
+body losslessly and maps every value field to an exact type:
+
+- **Curated methods** → `bigint` satoshis (Verus = 8 decimals). Helpers:
+  `parseAmount("2.00000000") === 200_000_000n`, `formatAmount(200_000_000n) === "2.00000000"`.
+- **Typed methods** → exact decimal `string`.
+- **`call()` escape hatch** → safe integers become `number`, everything else
+  an exact decimal `string`; opt into raw float64 with `{ numbers: "js" }`.
+
+Heights, counts and timestamps stay `number`. Unknown fields a newer daemon
+adds are passed through (safe integer → `number`, otherwise exact string) —
+never stripped, never rounded.
+
+## What this is (and isn't)
+
+Deliberately complementary to the official VerusCoin TypeScript stack. This
+library is the **daemon-first RPC transport + types** — the layer VerusCoin
+doesn't ship on npm. It does **not** do client-side signing, login consent,
+VerusPay invoices, or transaction construction — that is
+[`verusid-ts-client`](https://github.com/VerusCoin/verusid-ts-client) and the
+BitGo `utxo-lib-verus` fork. Link to them; don't reimplement them.
+
+| Lane | Library |
+|---|---|
+| Talk to your own `verusd` (this) | **`verus-rpc`** |
+| VerusID signing / login / VerusPay | `verusid-ts-client` |
+| Transaction building | `@bitgo/utxo-lib` (Verus fork) |
+| ZMQ block/tx events | `verus-zmq-client` |
+
+## Coverage tiers
+
+A tier is a promise about **testing**, not just typing.
+
+| Tier | Contract | Families |
+|---|---|---|
+| **T1 — curated** | Named-options params, curated response types, value fields as `bigint` sats, recorded-fixture conformance test per method | Chain reads, wallet + sends, identity (read + lifecycle), currency/conversion reads, addressindex, `getvdxfid` |
+| **T2 — typed** | Typed params/results, value fields as exact decimal strings | Shielded (`z_*`), marketplace, raw-transaction chain, network/util reads, identity signatures/trust |
+| **T3 — escape hatch** | `client.call(method, params)` — untyped, always available | everything else — mining/staking, notarization internals, `definecurrency` depth |
+
+Promotion T3→T2→T1 is demand-driven. `call()` means the client never blocks
+you on missing coverage.
+
+## Client namespaces
+
+```ts
+client.chain        // getInfo, getBlockCount
+client.blockchain   // blocks, raw-tx chain, network/util reads, getVdxfId
+client.wallet       // balances, transactions, sends, sendCurrencyAndWait, keys
+client.shielded     // z_* family + z-operation polling helpers
+client.identity     // reads, lifecycle, registerIdentityFlow
+client.currency     // getCurrency, listCurrencies, estimateConversion, marketplace
+client.addressIndex // getAddressBalance/Utxos/Deltas (arbitrary addresses)
+client.call(method, params, { numbers })  // anything else
+```
+
+### High-level helpers
+
+- `wallet.sendCurrencyAndWait(...)` — `sendcurrency` returns an operation id;
+  this polls `z_getoperationstatus` to success/failure and resolves with the
+  txid (or throws `OperationFailedError` / `OperationTimeoutError`).
+- `identity.registerIdentityFlow(...)` — `registernamecommitment` →
+  wait-for-confirmation → `registeridentity` as one guided call.
+- `shielded.zSendManyAndWait(...)` — the same opid pattern for `z_sendmany`.
+
+## Resilience (opt-in)
+
+This is a library — you own your retry/breaker posture. A circuit breaker +
+per-attempt timeout are available and **off by default**; application errors
+never trip the breaker.
+
+```ts
+new VerusClient({ url, user, pass, resilience: { timeoutMs: 5000, breaker: { failuresBeforeOpen: 5 } } });
+```
+
+## Errors
+
+- `VerusRpcError(method, code, message)` — the daemon answered with an error.
+  Branch on `error.code` via the `RpcErrorCode` enum (no message string-matching).
+- `TransportError(reason, message)` — network / timeout / bad-response / circuit-open.
+- `ResponseMappingError` — a curated response didn't match the mapper (daemon
+  drift); the raw value is still reachable via `call()`.
+
+## Testing
+
+Three rings (see `test/`):
+
+1. **Unit** — `MockTransport` (exported for your tests too); every method's
+   param marshalling, error paths, amount edge cases.
+2. **Fixture conformance** — responses recorded from a real daemon
+   (`fixtures/`), curated mappers validated **offline**. This is the
+   type-honesty check.
+3. **Gated integration** — set `VERUS_RPC_URL` to run read-only against your
+   node; `VERUS_RPC_MAINNET_SMOKE=1` runs a read-only smoke against
+   api.verus.services.
+
+Examples in `examples/` are executed as-is (guarded in the test suite) — the
+code you read is the code that runs.
+
+## Compatibility
+
+- Node ≥ 22. Isomorphic-clean core (no `Buffer`/`fs` in the client path).
+- Types are curated against **daemon v1.2.17**; `getInfo().VRSCversion` lets
+  you check at runtime. Unknown response fields pass through.
+
+## License
+
+Apache-2.0

package/dist/amount.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Exact amount handling — the library's core invariant is that no float ever
+ * crosses the public API for a value field. Curated (T1) methods surface
+ * amounts as `bigint` satoshis; these helpers convert between that and the
+ * daemon's 8-decimal notation.
+ */
+/** Verus amounts have 8 decimal places: 1 VRSC = 100_000_000 satoshis. */
+export declare const SATS_PER_COIN = 100000000n;
+export interface ParseAmountOptions {
+    /**
+     * Accept negative amounts. Off by default — most value fields are
+     * non-negative; signed fields (e.g. `gettransaction.amount`) opt in.
+     */
+    allowNegative?: boolean;
+}
+/**
+ * Parse an exact decimal amount string into bigint satoshis.
+ *
+ * `parseAmount("2.00000000") === 200_000_000n`
+ *
+ * Throws `RangeError` on anything that is not an exact amount: malformed
+ * input, more than 8 decimal places of significance, or (by default)
+ * negative values.
+ */
+export declare function parseAmount(value: string, options?: ParseAmountOptions): bigint;
+/**
+ * Format bigint satoshis as the daemon's 8-decimal notation.
+ *
+ * `formatAmount(200_000_000n) === "2.00000000"`
+ */
+export declare function formatAmount(sats: bigint): string;
+//# sourceMappingURL=amount.d.ts.map

package/dist/amount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.d.ts","sourceRoot":"","sources":["../src/amount.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,aAAa,aAAe,CAAC;AAO1C,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,MAAM,CA+B/E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMjD"}

package/dist/amount.js

@@ -0,0 +1,65 @@
+/**
+ * Exact amount handling — the library's core invariant is that no float ever
+ * crosses the public API for a value field. Curated (T1) methods surface
+ * amounts as `bigint` satoshis; these helpers convert between that and the
+ * daemon's 8-decimal notation.
+ */
+/** Verus amounts have 8 decimal places: 1 VRSC = 100_000_000 satoshis. */
+export const SATS_PER_COIN = 100000000n;
+const AMOUNT_DECIMALS = 8;
+// Full JSON number grammar plus an optional leading "+" for human input.
+const DECIMAL_RE = /^([+-]?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/;
+/**
+ * Parse an exact decimal amount string into bigint satoshis.
+ *
+ * `parseAmount("2.00000000") === 200_000_000n`
+ *
+ * Throws `RangeError` on anything that is not an exact amount: malformed
+ * input, more than 8 decimal places of significance, or (by default)
+ * negative values.
+ */
+export function parseAmount(value, options) {
+    const match = DECIMAL_RE.exec(value);
+    if (match === null) {
+        throw new RangeError(`not a decimal amount: ${JSON.stringify(value)}`);
+    }
+    const [, sign = "", intPart = "", fracPart = "", expPart] = match;
+    const exponent = expPart === undefined ? 0 : Number(expPart);
+    // Shift the decimal point right by (AMOUNT_DECIMALS + exponent) places.
+    const digits = intPart + fracPart;
+    const pointIndex = intPart.length + exponent + AMOUNT_DECIMALS;
+    if (pointIndex < 0) {
+        // Entire value sits below 1 sat — only exact zero is representable.
+        if (/^0*$/.test(digits))
+            return 0n;
+        throw new RangeError(`more than ${AMOUNT_DECIMALS} decimal places: ${value}`);
+    }
+    const head = digits.slice(0, pointIndex).padEnd(pointIndex, "0");
+    const tail = digits.slice(pointIndex);
+    if (!/^0*$/.test(tail)) {
+        throw new RangeError(`more than ${AMOUNT_DECIMALS} decimal places: ${value}`);
+    }
+    const sats = head === "" ? 0n : BigInt(head);
+    if (sign === "-") {
+        if (sats === 0n)
+            return 0n; // normalize -0
+        if (options?.allowNegative !== true) {
+            throw new RangeError(`negative amount: ${value}`);
+        }
+        return -sats;
+    }
+    return sats;
+}
+/**
+ * Format bigint satoshis as the daemon's 8-decimal notation.
+ *
+ * `formatAmount(200_000_000n) === "2.00000000"`
+ */
+export function formatAmount(sats) {
+    const negative = sats < 0n;
+    const abs = negative ? -sats : sats;
+    const coins = abs / SATS_PER_COIN;
+    const frac = abs % SATS_PER_COIN;
+    return `${negative ? "-" : ""}${coins}.${frac.toString().padStart(AMOUNT_DECIMALS, "0")}`;
+}
+//# sourceMappingURL=amount.js.map

package/dist/amount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.js","sourceRoot":"","sources":["../src/amount.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,aAAa,GAAG,UAAY,CAAC;AAE1C,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B,yEAAyE;AACzE,MAAM,UAAU,GAAG,+CAA+C,CAAC;AAUnE;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,OAA4B;IACrE,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,UAAU,CAAC,yBAAyB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,MAAM,CAAC,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,GAAG,EAAE,EAAE,QAAQ,GAAG,EAAE,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC;IAClE,MAAM,QAAQ,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAE7D,wEAAwE;IACxE,MAAM,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAClC,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,QAAQ,GAAG,eAAe,CAAC;IAC/D,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACnB,oEAAoE;QACpE,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,OAAO,EAAE,CAAC;QACnC,MAAM,IAAI,UAAU,CAAC,aAAa,eAAe,oBAAoB,KAAK,EAAE,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,MAAM,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IACjE,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,UAAU,CAAC,aAAa,eAAe,oBAAoB,KAAK,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;QACjB,IAAI,IAAI,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC,CAAC,eAAe;QAC3C,IAAI,OAAO,EAAE,aAAa,KAAK,IAAI,EAAE,CAAC;YACpC,MAAM,IAAI,UAAU,CAAC,oBAAoB,KAAK,EAAE,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,CAAC,IAAI,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAC;IAC3B,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACpC,MAAM,KAAK,GAAG,GAAG,GAAG,aAAa,CAAC;IAClC,MAAM,IAAI,GAAG,GAAG,GAAG,aAAa,CAAC;IACjC,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,EAAE,CAAC;AAC5F,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,60 @@
+import { AddressIndexApi } from "./methods/addressindex.js";
+import { BlockchainApi } from "./methods/blockchain.js";
+import { ChainApi } from "./methods/chain.js";
+import { CurrencyApi } from "./methods/currency.js";
+import { IdentityApi } from "./methods/identity.js";
+import { ShieldedApi } from "./methods/shielded.js";
+import { WalletApi } from "./methods/wallet.js";
+import { type ResilienceConfig } from "./resilience.js";
+import { type RpcTransport } from "./transport.js";
+export interface VerusClientConfig {
+    /** Daemon RPC endpoint, e.g. `http://127.0.0.1:27486`. */
+    url?: string;
+    user?: string;
+    pass?: string;
+    /** Injectable for tests and exotic runtimes; defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Plain per-request timeout (ms) of the default transport. Default 60s. */
+    timeoutMs?: number;
+    /** Opt-in circuit breaker + policy timeout. Off by default. */
+    resilience?: ResilienceConfig;
+    /** Full transport override (tests, future GatewayTransport). */
+    transport?: RpcTransport;
+}
+/**
+ * How `call()` surfaces JSON numbers:
+ *
+ * - `"lossless"` (default): safe integers become `number`, everything else
+ *   (fractional amounts, integers beyond 2^53) becomes an exact decimal
+ *   `string`. No float64 rounding — safe for value fields.
+ * - `"js"`: classic `JSON.parse` semantics, every number a float64 `number`.
+ *   Explicit opt-in; unsafe for arithmetic on amounts.
+ */
+export type CallNumbersMode = "lossless" | "js";
+export interface CallOptions {
+    numbers?: CallNumbersMode;
+}
+/**
+ * Typed client for the Verus daemon JSON-RPC interface.
+ *
+ * Curated (T1) methods live on the family namespaces (`client.chain`,
+ * `client.wallet`, `client.identity`, …); `client.call()` reaches every
+ * other daemon method untyped — nothing ever blocks on missing coverage.
+ */
+export declare class VerusClient {
+    readonly chain: ChainApi;
+    readonly wallet: WalletApi;
+    readonly identity: IdentityApi;
+    readonly currency: CurrencyApi;
+    readonly shielded: ShieldedApi;
+    readonly addressIndex: AddressIndexApi;
+    readonly blockchain: BlockchainApi;
+    private readonly transport;
+    constructor(config: VerusClientConfig);
+    /**
+     * Escape hatch: call any daemon RPC method with positional params.
+     * Untyped by design — see `CallNumbersMode` for how numbers arrive.
+     */
+    call(method: string, params?: unknown[], options?: CallOptions): Promise<unknown>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEpE,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,gEAAgE;IAChE,SAAS,CAAC,EAAE,YAAY,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,IAAI,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IAEnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,MAAM,EAAE,iBAAiB;IAyBrC;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CAI5F"}

package/dist/client.js

@@ -0,0 +1,61 @@
+import { toJsNumbers, toSafeNumbers } from "./lossless.js";
+import { AddressIndexApi } from "./methods/addressindex.js";
+import { BlockchainApi } from "./methods/blockchain.js";
+import { ChainApi } from "./methods/chain.js";
+import { CurrencyApi } from "./methods/currency.js";
+import { IdentityApi } from "./methods/identity.js";
+import { ShieldedApi } from "./methods/shielded.js";
+import { WalletApi } from "./methods/wallet.js";
+import { withResilience } from "./resilience.js";
+import { DaemonTransport } from "./transport.js";
+/**
+ * Typed client for the Verus daemon JSON-RPC interface.
+ *
+ * Curated (T1) methods live on the family namespaces (`client.chain`,
+ * `client.wallet`, `client.identity`, …); `client.call()` reaches every
+ * other daemon method untyped — nothing ever blocks on missing coverage.
+ */
+export class VerusClient {
+    chain;
+    wallet;
+    identity;
+    currency;
+    shielded;
+    addressIndex;
+    blockchain;
+    transport;
+    constructor(config) {
+        if (config.transport !== undefined) {
+            this.transport = config.transport;
+        }
+        else {
+            if (config.url === undefined || config.user === undefined || config.pass === undefined) {
+                throw new TypeError("VerusClient: url, user and pass are required (or pass a transport)");
+            }
+            const daemon = new DaemonTransport({
+                url: config.url,
+                user: config.user,
+                pass: config.pass,
+                ...(config.fetchImpl !== undefined ? { fetchImpl: config.fetchImpl } : {}),
+                ...(config.timeoutMs !== undefined ? { timeoutMs: config.timeoutMs } : {}),
+            });
+            this.transport = config.resilience !== undefined ? withResilience(daemon, config.resilience) : daemon;
+        }
+        this.chain = new ChainApi(this.transport);
+        this.wallet = new WalletApi(this.transport);
+        this.identity = new IdentityApi(this.transport);
+        this.currency = new CurrencyApi(this.transport);
+        this.shielded = new ShieldedApi(this.transport);
+        this.addressIndex = new AddressIndexApi(this.transport);
+        this.blockchain = new BlockchainApi(this.transport);
+    }
+    /**
+     * Escape hatch: call any daemon RPC method with positional params.
+     * Untyped by design — see `CallNumbersMode` for how numbers arrive.
+     */
+    async call(method, params = [], options) {
+        const raw = await this.transport.request(method, params);
+        return options?.numbers === "js" ? toJsNumbers(raw) : toSafeNumbers(raw);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Error taxonomy — the split matters for resilience:
+ *
+ * - `VerusRpcError` — the daemon answered with a JSON-RPC error (bad params,
+ *   unknown identity, insufficient funds, …). The node is HEALTHY; these never
+ *   count toward the optional circuit breaker, otherwise malformed requests
+ *   could trip it and deny service (v402 lesson).
+ * - `TransportError` — the node could not be reached, did not answer in time,
+ *   answered with an unparseable body, or the breaker is open.
+ */
+export type TransportFailureReason = "network" | "timeout" | "bad-response" | "circuit-open";
+export declare class TransportError extends Error {
+    readonly reason: TransportFailureReason;
+    constructor(reason: TransportFailureReason, message: string);
+}
+/**
+ * Common daemon error codes (Bitcoin/Zcash lineage, `rpcprotocol.h`) so
+ * consumers can branch on `error.code` without string-matching messages.
+ */
+export declare const RpcErrorCode: {
+    readonly RPC_INVALID_REQUEST: -32600;
+    readonly RPC_METHOD_NOT_FOUND: -32601;
+    readonly RPC_INVALID_PARAMS: -32602;
+    readonly RPC_INTERNAL_ERROR: -32603;
+    readonly RPC_PARSE_ERROR: -32700;
+    readonly RPC_MISC_ERROR: -1;
+    readonly RPC_FORBIDDEN_BY_SAFE_MODE: -2;
+    readonly RPC_TYPE_ERROR: -3;
+    readonly RPC_INVALID_ADDRESS_OR_KEY: -5;
+    readonly RPC_OUT_OF_MEMORY: -7;
+    readonly RPC_INVALID_PARAMETER: -8;
+    readonly RPC_DATABASE_ERROR: -20;
+    readonly RPC_DESERIALIZATION_ERROR: -22;
+    readonly RPC_VERIFY_ERROR: -25;
+    readonly RPC_VERIFY_REJECTED: -26;
+    readonly RPC_VERIFY_ALREADY_IN_CHAIN: -27;
+    readonly RPC_IN_WARMUP: -28;
+    readonly RPC_CLIENT_NOT_CONNECTED: -9;
+    readonly RPC_CLIENT_IN_INITIAL_DOWNLOAD: -10;
+    readonly RPC_CLIENT_NODE_ALREADY_ADDED: -23;
+    readonly RPC_CLIENT_NODE_NOT_ADDED: -24;
+    readonly RPC_WALLET_ERROR: -4;
+    readonly RPC_WALLET_INSUFFICIENT_FUNDS: -6;
+    readonly RPC_WALLET_INVALID_ACCOUNT_NAME: -11;
+    readonly RPC_WALLET_KEYPOOL_RAN_OUT: -12;
+    readonly RPC_WALLET_UNLOCK_NEEDED: -13;
+    readonly RPC_WALLET_PASSPHRASE_INCORRECT: -14;
+    readonly RPC_WALLET_WRONG_ENC_STATE: -15;
+    readonly RPC_WALLET_ENCRYPTION_FAILED: -16;
+    readonly RPC_WALLET_ALREADY_UNLOCKED: -17;
+};
+export type RpcErrorCode = (typeof RpcErrorCode)[keyof typeof RpcErrorCode];
+/** The daemon answered the call with a JSON-RPC error body. */
+export declare class VerusRpcError extends Error {
+    readonly method: string;
+    readonly code: number;
+    constructor(method: string, code: number, message: string);
+}
+/**
+ * A curated (T1) response did not have the shape the mapper expects — the
+ * daemon version drifted or the type curation is wrong. The raw value is
+ * intact on the wire; `client.call()` always works as the escape hatch.
+ */
+export declare class ResponseMappingError extends Error {
+    readonly method: string;
+    readonly field: string;
+    constructor(method: string, field: string, message: string);
+}
+/** An async wallet operation (opid) finished with status "failed" or "cancelled". */
+export declare class OperationFailedError extends Error {
+    readonly opid: string;
+    readonly status: string;
+    readonly code: number | undefined;
+    constructor(opid: string, status: string, code: number | undefined, message: string);
+}
+/** An async wallet operation (opid) did not reach a final state within the polling deadline. */
+export declare class OperationTimeoutError extends Error {
+    readonly opid: string;
+    constructor(opid: string, timeoutMs: number);
+}
+//# sourceMappingURL=errors.d.ts.map