@kynesyslabs/demosdk 2.12.2 → 4.0.0

package/build/websdk/demosclass.d.ts

@@ -8,6 +8,7 @@ import type { NetworkParameters, NetworkUpgradeProposal, ProposalVoteInfo } from
 import { RPCRequest, RPCResponse, RPCResponseWithValidityData } from "../types/communication/rpc";
 import { IKeyPair } from "./types/KeyPair";
 import { UnifiedCrypto } from "../encryption/unifiedCrypto";
+import { type NetworkInfo } from "../denomination/networkInfo";
 import { TweetSimplified } from "../types";
 import { GetDiscordMessageResult } from "../types/web2/discord";
 import type { TLSNotary, TLSNotaryConfig } from "../tlsnotary";
@@ -28,6 +29,18 @@ export declare class Demos {
     private _cachedNetworkParameters;
     private _cachedNetworkParametersAt;
     private _cachedNetworkParametersRpcUrl;
+    private _cachedNetworkInfo;
+    private _cachedNetworkInfoRpcUrl;
+    private _cachedNetworkInfoFailed;
+    private _cachedNetworkInfoFailedAt;
+    private _cachedNetworkInfoWarned;
+    /**
+     * TTL for the failed-detection memo. After this elapses we re-attempt
+     * `getNetworkInfo` so a transient outage doesn't poison the instance
+     * forever. The warn-once flag is sticky across retries — operators
+     * still see the warning exactly once per instance lifetime.
+     */
+    private static readonly _NETWORK_INFO_FAILURE_TTL_MS;
     /** Connection status of the RPC URL */
     connected: boolean;
     dual_sign: boolean;
@@ -95,21 +108,50 @@ export declare class Demos {
     /**
      * Create a signed DEMOS transaction to send native tokens to a given address.
      *
-     * @param to - The reciever
-     * @param amount - The amount in DEM
+     * P4 dual-input:
+     *  - `bigint` (preferred, post-v3): amount in OS (smallest unit;
+     *    1 DEM = 10^9 OS). Use `denomination.demToOs(...)` to convert
+     *    a human-readable DEM input.
+     *  - `number` (deprecated, v2 callers): amount in DEM. Auto-converted
+     *    to OS internally via `OS_PER_DEM`. Will be removed in v4.
      *
+     * Sub-DEM precision is rejected with `SubDemPrecisionError` when
+     * the connected node is pre-fork — its legacy DEM-`number` wire
+     * cannot carry < 1 DEM and silent truncation is unacceptable. The
+     * caller can either round to a whole DEM or upgrade the target
+     * node.
+     *
+     * @example
+     * ```ts
+     * import { denomination } from "@kynesyslabs/demosdk"
+     * await demos.pay("0x...", denomination.demToOs(100))   // 100 DEM
+     * await demos.pay("0x...", 100_000_000_000n)             // raw OS
+     * await demos.pay("0x...", 100)                          // legacy DEM number (deprecated)
+     * ```
+     *
+     * @param to - The receiver address (0x-prefixed hex).
+     * @param amount - DEM `number` (legacy) or OS `bigint` (preferred).
      * @returns The signed transaction.
      */
-    pay(to: string, amount: number): Promise<Transaction>;
+    pay(to: string, amount: number | bigint): Promise<Transaction>;
     /**
      * Create a signed DEMOS transaction to send native tokens to a given address.
      *
-     * @param to - The reciever
-     * @param amount - The amount in DEM
+     * Alias of {@link pay}. Same dual-input semantics — `bigint` is the
+     * preferred OS shape; `number` is the deprecated legacy DEM shape.
+     *
+     * @example
+     * ```ts
+     * import { denomination } from "@kynesyslabs/demosdk"
+     * await demos.transfer("0x...", denomination.demToOs("1.5"))  // 1.5 DEM
+     * await demos.transfer("0x...", 1_500_000_000n)                // raw OS
+     * ```
      *
+     * @param to - The receiver address (0x-prefixed hex).
+     * @param amount - DEM `number` (legacy) or OS `bigint` (preferred).
      * @returns The signed transaction.
      */
-    transfer(to: string, amount: number): Promise<Transaction>;
+    transfer(to: string, amount: number | bigint): Promise<Transaction>;
     /**
      * Create a signed DEMOS transaction to store binary data on the blockchain.
      * Data is stored in the sender's account.
@@ -212,17 +254,40 @@ export declare class Demos {
     /**
      * @private
      * Calculates and applies the gas fee for a transaction (SDK-level fallback).
-     * NOTE: We infer the fee by analyzing the generated GCR (Gas Consumption Record) edits:
-     * - Sum all "balance" edits with operation "remove" for the sender
-     * - Subtract the declared transaction `amount`
-     * The remainder is treated as the network fee. If a fee already exists on the tx, we only raise
-     * `network_fee` if the newly inferred fee is higher (prevents double-charging on re-sign).
-     * This is an interim approach; the preferred design is for the node to return fees explicitly.
+     *
+     * NOTE: We infer the fee by analyzing the generated GCR (Gas Consumption
+     * Record) edits:
+     * - Sum all "balance" edits with operation "remove" for the sender.
+     * - Subtract the declared transaction `amount`.
+     * The remainder is treated as the network fee. If a fee already exists on
+     * the tx, we only raise `network_fee` if the newly inferred fee is higher
+     * (prevents double-charging on re-sign). This is an interim approach; the
+     * preferred design is for the node to return fees explicitly.
+     *
+     * P4: arithmetic uses `bigint` internally so OS-magnitude amounts
+     * (~10^19 OS for whole-network supply) don't overflow JS `number`'s
+     * 2^53 safe-integer ceiling. The function tolerates legacy `number`
+     * (DEM) and post-fork `string` (OS) inputs in any field, normalises
+     * to OS-bigint via `_coerceWireAmountToOs`, then writes the
+     * derived fee back in DEM-`number` (legacy wire) — the
+     * serializerGate (P4 commit 2) re-encodes to OS at hash time when
+     * the connected node is post-fork.
      *
      * @param raw_tx - The transaction for which to calculate the fee.
      * @returns The updated transaction with the fee applied.
      */
     private _calculateAndApplyGasFee;
+    /**
+     * Coerce a wire-format amount/fee value (legacy DEM `number`,
+     * post-fork OS decimal `string`, or in-flight `bigint`) to an OS
+     * `bigint`. Used by `_calculateAndApplyGasFee` and other internal
+     * arithmetic paths to stay in OS-bigint regardless of which wire
+     * shape the caller produced. Mirrors the node's `toOsBigint` helper
+     * in `forks/serializerGate.ts`.
+     *
+     * @internal
+     */
+    static _coerceWireAmountToOs(value: number | string | bigint): bigint;
     /**
      * Single transport wrapper for axios.post against the Demos RPC node.
      *
@@ -324,6 +389,18 @@ export declare class Demos {
     /**
      * Get information about an address.
      *
+     * P4: `balance` is `bigint` in **OS** (smallest unit, 1 DEM = 10^9 OS).
+     * Use `denomination.osToDem(info.balance)` for display.
+     *
+     * @example
+     * ```ts
+     * import { denomination } from "@kynesyslabs/demosdk"
+     * const info = await demos.getAddressInfo("0x...")
+     * if (info) {
+     *     console.log("balance:", denomination.osToDem(info.balance), "DEM")
+     * }
+     * ```
+     *
      * @param address - The address
      */
     getAddressInfo(address: string): Promise<AddressInfo | null>;
@@ -364,6 +441,50 @@ export declare class Demos {
      *   the response shape is invalid.
      */
     private _getNetworkParametersCached;
+    /**
+     * Fetches the connected node's per-fork activation status.
+     *
+     * Mirrors the node's `getNetworkInfo` `nodeCall`
+     * (`libs/network/handlers/forkHandlers.ts`). The response carries
+     * activation height, current chain head, and the `activated` boolean
+     * for every known fork.
+     *
+     * Caches the result on this `Demos` instance for the instance's
+     * lifetime (no TTL). To re-fetch after a node upgrade, construct a
+     * fresh `Demos` instance.
+     *
+     * On RPC failure (404, malformed response, network error), this
+     * method returns `null` and the SDK assumes pre-fork wire format.
+     * A `console.warn` is emitted exactly once per `Demos` instance
+     * recommending the operator upgrade the target node.
+     *
+     * @returns The fork-status payload, or `null` if the RPC failed.
+     */
+    getNetworkInfo(): Promise<NetworkInfo | null>;
+    /**
+     * @internal
+     * Cached fork-status accessor. Returns `osDenomination` activation
+     * status as a boolean. `false` is the safe default (legacy wire
+     * format) when the node is unreachable or pre-P3c.
+     */
+    private _isPostForkCached;
+    /**
+     * @internal
+     * Reset the cached fork status. Intended for tests; production code
+     * should construct a fresh `Demos` instance instead.
+     */
+    _resetForkStatusCacheForTesting(): void;
+    /**
+     * @internal
+     * Sub-DEM precision guard. Run by every public-API entry point that
+     * takes a user-supplied OS amount before tx construction. Throws
+     * `SubDemPrecisionError` when the connected node is pre-fork and
+     * the amount carries sub-DEM precision (would silently truncate on
+     * the legacy DEM-`number` wire).
+     *
+     * @param amountOs - The OS amount the caller is sending.
+     */
+    private _assertAmountAcceptableOnTargetNode;
     /**
      * Lists currently-open proposals (pending tally or activating after
      * approval). Rejected/active historical proposals are not included.
@@ -431,9 +552,12 @@ export declare class Demos {
         /**
          * Get a cost quote for an IPFS operation without submitting a transaction.
          *
-         * Use this to estimate costs and populate custom_charges before signing.
-         * The returned cost should be used as max_cost_dem in the transaction's
-         * custom_charges field.
+         * Use this to estimate costs and populate `custom_charges` before signing.
+         * Pipe the response through `IPFSOperations.quoteToCustomCharges`
+         * (or `createCustomCharges`) to obtain a `max_cost_os` decimal-string
+         * suitable for the transaction's `custom_charges.ipfs.max_cost_os`
+         * field. The helpers handle both pre-fork (`cost_dem`) and
+         * post-fork (`cost_os`) node response shapes.
          *
          * @param fileSizeBytes - Size of file in bytes
          * @param operation - IPFS operation type ('IPFS_ADD', 'IPFS_PIN', or 'IPFS_UNPIN')
@@ -444,7 +568,6 @@ export declare class Demos {
          * ```typescript
          * // Get quote for add operation
          * const quote = await demos.ipfs.quote(content.length, 'IPFS_ADD')
-         * console.log(`Cost: ${quote.cost_dem} DEM`)
          *
          * // Use quote to build transaction with cost control
          * const payload = IPFSOperations.createAddPayload(content, {
@@ -453,7 +576,10 @@ export declare class Demos {
          * ```
          */
         quote: (fileSizeBytes: number, operation?: "IPFS_ADD" | "IPFS_PIN" | "IPFS_UNPIN", durationBlocks?: number) => Promise<{
-            cost_dem: string;
+            /** Pre-fork node: cost in DEM as decimal string. */
+            cost_dem?: string;
+            /** Post-fork node: cost in OS as decimal string. */
+            cost_os?: string;
             file_size_bytes: number;
             is_genesis: boolean;
             breakdown: {
@@ -478,8 +604,9 @@ export declare class Demos {
         sign: (raw_tx: Transaction) => Promise<Transaction>;
         empty: () => Transaction;
         prepare: (data?: any) => Promise<Transaction>;
-        pay(to: string, amount: number, demos: Demos): Promise<Transaction>;
-        transfer(to: string, amount: number, demos: Demos): Promise<Transaction>;
+        pay(to: string, amount: number | bigint, demos: Demos): Promise<Transaction>;
+        _demNumberToOsBigint(amountDem: number): bigint;
+        transfer(to: string, amount: number | bigint, demos: Demos): Promise<Transaction>;
         signWithAlgorithm: (data: string, keypair: IKeyPair, options: {
             algorithm: SigningAlgorithm;
         }) => Promise<{
@@ -515,8 +642,9 @@ export declare class Demos {
     DemosTransactions: {
         empty: () => Transaction;
         prepare: (data?: any) => Promise<Transaction>;
-        pay(to: string, amount: number, demos: Demos): Promise<Transaction>;
-        transfer(to: string, amount: number, demos: Demos): Promise<Transaction>;
+        pay(to: string, amount: number | bigint, demos: Demos): Promise<Transaction>;
+        _demNumberToOsBigint(amountDem: number): bigint;
+        transfer(to: string, amount: number | bigint, demos: Demos): Promise<Transaction>;
         sign: (raw_tx: Transaction, keypair: IKeyPair, options: {
             algorithm: SigningAlgorithm;
         }) => Promise<Transaction>;
@@ -555,8 +683,9 @@ export declare class Demos {
     transactions: {
         empty: () => Transaction;
         prepare: (data?: any) => Promise<Transaction>;
-        pay(to: string, amount: number, demos: Demos): Promise<Transaction>;
-        transfer(to: string, amount: number, demos: Demos): Promise<Transaction>;
+        pay(to: string, amount: number | bigint, demos: Demos): Promise<Transaction>;
+        _demNumberToOsBigint(amountDem: number): bigint;
+        transfer(to: string, amount: number | bigint, demos: Demos): Promise<Transaction>;
         sign: (raw_tx: Transaction, keypair: IKeyPair, options: {
             algorithm: SigningAlgorithm;
         }) => Promise<Transaction>;