@kynesyslabs/demosdk 2.12.2 → 3.1.0

package/build/types/blockchain/CustomCharges.d.ts

@@ -5,33 +5,40 @@
  * before execution. Used in the confirm/execute two-step transaction flow
  * to provide cost transparency.
  *
- * @fileoverview Custom charges type definitions for cost estimation
+ * @fileoverview Custom charges type definitions for cost estimation.
+ *
+ * P4 denomination migration:
+ *   All cost fields are bigint-as-decimal-`string` in **OS** (smallest
+ *   unit, 1 DEM = 10^9 OS). Field names changed from `*_dem` to `*_os` to
+ *   reflect the new denomination. Pre-fork-compatible bridges should
+ *   serialise these via the SDK's `serializerGate`, which converts to
+ *   the legacy DEM-`number` shape for pre-fork nodes.
  */
 /**
  * Cost breakdown for IPFS operations
  *
  * Provides detailed cost calculation components so users can understand
- * what they're paying for.
+ * what they're paying for. All values are decimal-string OS amounts.
  */
 export interface IPFSCostBreakdown {
-    /** Base cost for the operation in DEM wei */
+    /** Base cost for the operation, decimal-string OS. */
     base_cost: string;
-    /** Cost based on file size in DEM wei */
+    /** Cost based on file size, decimal-string OS. */
     size_cost: string;
-    /** Cost based on storage duration in DEM wei (optional for indefinite pins) */
+    /** Cost based on storage duration, decimal-string OS (optional for indefinite pins). */
     duration_cost?: string;
-    /** Any additional costs (network fees, etc.) */
+    /** Any additional costs (network fees, etc.) — decimal-string OS values. */
     additional_costs?: Record<string, string>;
 }
 /**
  * IPFS custom charges configuration
  *
  * Included in transaction content to specify maximum cost user agrees to pay.
- * Node will validate that actual cost does not exceed max_cost_dem.
+ * Node will validate that actual cost does not exceed `max_cost_os`.
  */
 export interface IPFSCustomCharges {
-    /** Maximum cost user is willing to pay (in DEM wei as string for BigInt safety) */
-    max_cost_dem: string;
+    /** Maximum cost user is willing to pay, decimal-string OS (BigInt-safe). */
+    max_cost_os: string;
     /** File size in bytes - used for cost calculation validation */
     file_size_bytes: number;
     /** IPFS operation type */
@@ -54,7 +61,7 @@ export interface IPFSCustomCharges {
  *     // ... other fields
  *     custom_charges: {
  *         ipfs: {
- *             max_cost_dem: "1000000000000000000",
+ *             max_cost_os: "1000000000",  // 1 DEM in OS
  *             file_size_bytes: 1024,
  *             operation: "IPFS_ADD"
  *         }
@@ -70,14 +77,16 @@ export interface CustomCharges {
  *
  * Returned by confirmTx to show actual costs vs maximum user agreed to pay.
  * Allows user to review and abort if actual cost is higher than expected.
+ *
+ * All cost fields are decimal-string OS.
  */
 export interface ValidityDataCustomCharges {
     /** Charge type identifier */
     type: "ipfs_storage" | "ipfs_bandwidth" | "compute" | string;
-    /** What user signed as maximum (from TX custom_charges) */
-    max_cost_dem: string;
-    /** What node will actually charge (must be <= max_cost_dem) */
-    actual_cost_dem: string;
+    /** What user signed as maximum (from TX `custom_charges`), decimal-string OS. */
+    max_cost_os: string;
+    /** What node will actually charge (must be `<= max_cost_os`), decimal-string OS. */
+    actual_cost_os: string;
     /** Detailed breakdown of actual costs */
     breakdown: IPFSCostBreakdown;
 }
@@ -88,6 +97,9 @@ export declare function hasIPFSCustomCharges(charges: CustomCharges | undefined)
     ipfs: IPFSCustomCharges;
 };
 /**
- * Validate that actual cost does not exceed maximum
+ * Validate that actual cost does not exceed maximum.
+ *
+ * Inputs are decimal-string OS amounts; both must parse cleanly as
+ * non-negative bigints.
  */
-export declare function isValidCharge(maxCostDem: string, actualCostDem: string): boolean;
+export declare function isValidCharge(maxCostOs: string, actualCostOs: string): boolean;

package/build/types/blockchain/CustomCharges.js

@@ -5,7 +5,14 @@
  * before execution. Used in the confirm/execute two-step transaction flow
  * to provide cost transparency.
  *
- * @fileoverview Custom charges type definitions for cost estimation
+ * @fileoverview Custom charges type definitions for cost estimation.
+ *
+ * P4 denomination migration:
+ *   All cost fields are bigint-as-decimal-`string` in **OS** (smallest
+ *   unit, 1 DEM = 10^9 OS). Field names changed from `*_dem` to `*_os` to
+ *   reflect the new denomination. Pre-fork-compatible bridges should
+ *   serialise these via the SDK's `serializerGate`, which converts to
+ *   the legacy DEM-`number` shape for pre-fork nodes.
  */
 // ============================================================================
 // Type Guards
@@ -17,12 +24,15 @@ export function hasIPFSCustomCharges(charges) {
     return charges?.ipfs !== undefined;
 }
 /**
- * Validate that actual cost does not exceed maximum
+ * Validate that actual cost does not exceed maximum.
+ *
+ * Inputs are decimal-string OS amounts; both must parse cleanly as
+ * non-negative bigints.
  */
-export function isValidCharge(maxCostDem, actualCostDem) {
+export function isValidCharge(maxCostOs, actualCostOs) {
     try {
-        const max = BigInt(maxCostDem);
-        const actual = BigInt(actualCostDem);
+        const max = BigInt(maxCostOs);
+        const actual = BigInt(actualCostOs);
         return actual <= max;
     }
     catch {

package/build/types/blockchain/CustomCharges.js.map

@@ -1 +1 @@
-{"version":3,"file":"CustomCharges.js","sourceRoot":"","sources":["../../../../src/types/blockchain/CustomCharges.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA2GH,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAChC,OAAkC;IAElC,OAAO,OAAO,EAAE,IAAI,KAAK,SAAS,CAAA;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CACzB,UAAkB,EAClB,aAAqB;IAErB,IAAI,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,CAAA;QAC9B,MAAM,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC,CAAA;QACpC,OAAO,MAAM,IAAI,GAAG,CAAA;IACxB,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,KAAK,CAAA;IAChB,CAAC;AACL,CAAC"}
+{"version":3,"file":"CustomCharges.js","sourceRoot":"","sources":["../../../../src/types/blockchain/CustomCharges.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA6GH,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAChC,OAAkC;IAElC,OAAO,OAAO,EAAE,IAAI,KAAK,SAAS,CAAA;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CACzB,SAAiB,EACjB,YAAoB;IAEpB,IAAI,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,CAAA;QAC7B,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,CAAA;QACnC,OAAO,MAAM,IAAI,GAAG,CAAA;IACxB,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,KAAK,CAAA;IAChB,CAAC;AACL,CAAC"}

package/build/types/blockchain/GCREdit.d.ts

@@ -1,13 +1,32 @@
 import { IdentityAttestationPayload, IdentityCommitmentPayload, PqcIdentityRemovePayload, UDIdentityPayload, XMCoreTargetIdentityPayload, NomisWalletIdentity, HumanPassportIdentityData, EthosWalletIdentity, TLSNIdentityContext, TLSNProofRanges } from "../abstraction";
 import { SigningAlgorithm } from "../cryptography";
+/**
+ * Balance-mutation GCR edit — adds to or subtracts from a sender/receiver
+ * balance, or burns a fee.
+ *
+ * Wire-format compatibility (P4): `amount` may be either a JS `number`
+ * (pre-fork node, DEM) or a decimal `string` in OS (post-fork node). The
+ * SDK's `GCRGeneration` populates the field with whichever shape matches
+ * the connected node's fork status.
+ *
+ * Important: the node's post-fork serializer (`forks/serializerGate.ts`)
+ * does **not** re-encode `gcr_edits[].amount`. Whatever the SDK puts here
+ * **is** the wire format and contributes directly to the transaction
+ * hash. Construction-site correctness is the contract.
+ */
 export interface GCREditBalance {
     type: "balance";
     isRollback: boolean;
     operation: "add" | "remove";
     account: string;
-    amount: number;
+    amount: number | string;
     txhash: string;
 }
+/**
+ * Nonce-increment GCR edit. `amount` is a counter delta, not a token
+ * amount — always `1` in current code. Kept as `number` because the fork
+ * does not change its encoding. Do **not** confuse with `GCREditBalance.amount`.
+ */
 export interface GCREditNonce {
     type: "nonce";
     isRollback: boolean;
@@ -137,7 +156,12 @@ export interface GCREditEscrow {
         sender?: string;
         platform?: "twitter" | "github" | "telegram";
         username?: string;
-        amount?: number;
+        /**
+         * Escrow deposit amount. Wire format follows the same pre-fork /
+         * post-fork rule as `GCREditBalance.amount`: `number` DEM
+         * pre-fork, decimal `string` OS post-fork.
+         */
+        amount?: number | string;
         expiryDays?: number;
         message?: string;
         claimant?: string;

package/build/types/blockchain/Transaction.d.ts

@@ -30,7 +30,20 @@ export interface TransactionContent {
     from: string;
     from_ed25519_address: string;
     to: string;
-    amount: number;
+    /**
+     * Native DEM amount transferred by this transaction.
+     *
+     * Wire-format compatibility:
+     * - Pre-fork node: encoded as JS `number` in DEM.
+     * - Post-fork node: encoded as a decimal `string` in OS (1 DEM = 10^9 OS).
+     *
+     * Both shapes are accepted on input; the SDK's `serializerGate`
+     * (P4 commit 2) normalises to the right wire shape per fork status
+     * before signing. SDK-internal arithmetic always uses `bigint` OS via
+     * `denomination` utilities — never raw `number`, which loses precision
+     * above 2^53 OS (~9 million DEM).
+     */
+    amount: number | string;
     data: TransactionContentData;
     gcr_edits: GCREdit[];
     nonce: number;

package/build/types/blockchain/Transaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"Transaction.js","sourceRoot":"","sources":["../../../../src/types/blockchain/Transaction.ts"],"names":[],"mappings":"AA2HA,uCAAuC;AACvC,cAAc,uBAAuB,CAAA"}
+{"version":3,"file":"Transaction.js","sourceRoot":"","sources":["../../../../src/types/blockchain/Transaction.ts"],"names":[],"mappings":"AAwIA,uCAAuC;AACvC,cAAc,uBAAuB,CAAA"}

package/build/types/blockchain/TransactionSubtypes/D402PaymentTransaction.d.ts

@@ -1,13 +1,18 @@
 import { Transaction, TransactionContent } from "../Transaction";
 /**
  * D402 Payment Payload
- * Represents a gasless payment transaction in the D402 protocol
+ * Represents a gasless payment transaction in the D402 protocol.
+ *
+ * Wire-format compatibility (P4): `amount` may be either a JS `number`
+ * (pre-fork DEM, legacy) or a decimal `string` in OS (post-fork). The
+ * SDK's serializerGate normalises at the wire boundary based on the
+ * connected node's fork status.
  */
 export interface D402PaymentPayload {
     /** Recipient's Demos address */
     to: string;
-    /** Payment amount in smallest unit */
-    amount: number;
+    /** Payment amount: pre-fork `number` (DEM) or post-fork `string` (OS). */
+    amount: number | string;
     /** Optional memo/description for the payment */
     memo?: string;
 }

package/build/types/blockchain/TransactionSubtypes/StorageProgramTransaction.d.ts

@@ -1,14 +1,15 @@
 import { Transaction, TransactionContent } from "../Transaction";
-/**
- * Storage Program constants for validation and pricing
- */
 export declare const STORAGE_PROGRAM_CONSTANTS: {
     /** Maximum storage size in bytes (1MB) */
     readonly MAX_SIZE_BYTES: 1048576;
     /** Size chunk for pricing in bytes (10KB) */
     readonly PRICING_CHUNK_BYTES: 10240;
-    /** Fee per chunk in DEM */
-    readonly FEE_PER_CHUNK: 1n;
+    /**
+     * Fee per chunk, expressed in OS (= 1 DEM = 10^9 OS).
+     * Use bigint arithmetic at every call site; the SDK never widens
+     * back to JS `number`, which loses precision above 2^53.
+     */
+    readonly FEE_PER_CHUNK: bigint;
     /** Maximum nesting depth for JSON encoding */
     readonly MAX_JSON_NESTING_DEPTH: 64;
 };

package/build/types/blockchain/TransactionSubtypes/StorageProgramTransaction.js

@@ -3,15 +3,27 @@
 // Constants
 // ============================================================================
 /**
- * Storage Program constants for validation and pricing
+ * Storage Program constants for validation and pricing.
+ *
+ * P4 fix: prior to this revision `FEE_PER_CHUNK` was hard-coded as `1n`,
+ * which represented "1 OS" (the smallest unit) — off by `10^9` from the
+ * intended "1 DEM per chunk" pricing. Now expressed as `OS_PER_DEM` to
+ * make the unit explicit and the pricing correct on the SDK side. (Note:
+ * the node's matching constant must be aligned by P5 to avoid SDK/node
+ * fee-schedule drift — flagged for follow-up.)
  */
+import { OS_PER_DEM } from "../../../denomination/index.js";
 export const STORAGE_PROGRAM_CONSTANTS = {
     /** Maximum storage size in bytes (1MB) */
     MAX_SIZE_BYTES: 1048576,
     /** Size chunk for pricing in bytes (10KB) */
     PRICING_CHUNK_BYTES: 10240,
-    /** Fee per chunk in DEM */
-    FEE_PER_CHUNK: 1n,
+    /**
+     * Fee per chunk, expressed in OS (= 1 DEM = 10^9 OS).
+     * Use bigint arithmetic at every call site; the SDK never widens
+     * back to JS `number`, which loses precision above 2^53.
+     */
+    FEE_PER_CHUNK: OS_PER_DEM,
     /** Maximum nesting depth for JSON encoding */
     MAX_JSON_NESTING_DEPTH: 64,
 };

package/build/types/blockchain/TransactionSubtypes/StorageProgramTransaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"StorageProgramTransaction.js","sourceRoot":"","sources":["../../../../../src/types/blockchain/TransactionSubtypes/StorageProgramTransaction.ts"],"names":[],"mappings":"AAEA,qFAAqF;AAErF,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACrC,0CAA0C;IAC1C,cAAc,EAAE,OAAO;IAEvB,6CAA6C;IAC7C,mBAAmB,EAAE,KAAK;IAE1B,2BAA2B;IAC3B,aAAa,EAAE,EAAE;IAEjB,8CAA8C;IAC9C,sBAAsB,EAAE,EAAE;CACpB,CAAA;AA0OV,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAgB;IACpD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IACzD,MAAM,CAAC,GAAG,OAAkC,CAAA;IAC5C,MAAM,eAAe,GAAG;QACpB,wBAAwB;QACxB,eAAe;QACf,cAAc;QACd,uBAAuB;QACvB,wBAAwB;QACxB,sBAAsB;QACtB,WAAW;QACX,UAAU;QACV,aAAa;QACb,cAAc;QACd,aAAa;KAChB,CAAA;IACD,OAAO,CACH,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;QAC/B,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ;QACpC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAmB,CAAC,CAClD,CAAA;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,QAAiB;IAC7C,OAAO,QAAQ,KAAK,MAAM,IAAI,QAAQ,KAAK,QAAQ,CAAA;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAiB;IACpD,OAAO,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,MAAM,CAAA;AACxD,CAAC"}
+{"version":3,"file":"StorageProgramTransaction.js","sourceRoot":"","sources":["../../../../../src/types/blockchain/TransactionSubtypes/StorageProgramTransaction.ts"],"names":[],"mappings":"AAEA,qFAAqF;AAErF,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAElD,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACrC,0CAA0C;IAC1C,cAAc,EAAE,OAAO;IAEvB,6CAA6C;IAC7C,mBAAmB,EAAE,KAAK;IAE1B;;;;OAIG;IACH,aAAa,EAAE,UAAU;IAEzB,8CAA8C;IAC9C,sBAAsB,EAAE,EAAE;CACpB,CAAA;AA0OV,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAgB;IACpD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IACzD,MAAM,CAAC,GAAG,OAAkC,CAAA;IAC5C,MAAM,eAAe,GAAG;QACpB,wBAAwB;QACxB,eAAe;QACf,cAAc;QACd,uBAAuB;QACvB,wBAAwB;QACxB,sBAAsB;QACtB,WAAW;QACX,UAAU;QACV,aAAa;QACb,cAAc;QACd,aAAa;KAChB,CAAA;IACD,OAAO,CACH,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;QAC/B,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ;QACpC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAmB,CAAC,CAClD,CAAA;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,QAAiB;IAC7C,OAAO,QAAQ,KAAK,MAAM,IAAI,QAAQ,KAAK,QAAQ,CAAA;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAiB;IACpD,OAAO,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,MAAM,CAAA;AACxD,CAAC"}

package/build/types/blockchain/TxFee.d.ts

@@ -1,5 +1,18 @@
+/**
+ * Transaction fee container.
+ *
+ * Wire-format compatibility note: pre-fork wire encodes each field as a JS
+ * `number` in DEM. Post-fork wire encodes them as decimal strings in OS
+ * (smallest unit, 1 DEM = 10^9 OS). Both shapes are accepted on input; the
+ * SDK's `serializerGate` (P4 commit 2) is the wire boundary that picks the
+ * correct on-the-wire shape per the connected node's fork status.
+ *
+ * Internally, fee math is performed in `bigint` OS via `denomination`
+ * conversion utilities — never as `number` (which loses precision above
+ * 2^53 OS, ~9 million DEM).
+ */
 export interface TxFee {
-    network_fee: number;
-    rpc_fee: number;
-    additional_fee: number;
+    network_fee: number | string;
+    rpc_fee: number | string;
+    additional_fee: number | string;
 }

package/build/types/blockchain/address.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Snapshot of an address's on-chain state.
+ *
+ * P4: `balance` is `bigint`. The magnitude depends on the connected
+ * node's fork status:
+ *
+ * - **Post-fork**: the node returns balance in **OS** (smallest unit,
+ *   1 DEM = 10^9 OS). The SDK passes this through unchanged.
+ * - **Pre-fork**: the node returns balance in **DEM**. The SDK passes
+ *   this through unchanged — it does **not** auto-convert client-side.
+ *
+ * Consumers that need to do arithmetic in OS regardless of node version
+ * should branch on `demos.getNetworkInfo()` (or the internal
+ * `_isPostForkCached`) and call `denomination.demToOs(balance)` only
+ * on the pre-fork branch. For display, use `denomination.osToDem(balance)`
+ * post-fork or treat the value as DEM directly pre-fork.
+ *
+ * (Earlier drafts of this doc claimed the SDK multiplied pre-fork
+ * balances client-side via `osToDem`; that was inaccurate on both
+ * counts — `osToDem` divides, and the SDK does not multiply at all.
+ * Fixed in PR-86 review.)
+ */
 export interface AddressInfo {
     pubkey: string;
     assignedTxs: string[];
@@ -6,5 +28,6 @@ export interface AddressInfo {
         web2: Map<string, string[]>;
     };
     nonce: number;
+    /** Address balance, `bigint` in OS (smallest unit). */
     balance: bigint;
 }

package/build/types/blockchain/rawTransaction.d.ts

@@ -1,4 +1,13 @@
 import { TransactionContent } from "./Transaction";
+/**
+ * Raw transaction row as it surfaces from the node's storage layer.
+ *
+ * Wire-format compatibility note (P4): `amount`, `networkFee`, `rpcFee`, and
+ * `additionalFee` may arrive as either JS `number` (pre-fork node, DEM) or
+ * decimal `string` (post-fork node, OS). Consumers must coerce via
+ * `denomination.parseOsString` / `BigInt(...)` before doing arithmetic;
+ * never call raw `Number(...)` once OS-magnitude values are possible.
+ */
 export interface RawTransaction {
     id: number;
     blockNumber: number;
@@ -9,12 +18,12 @@ export interface RawTransaction {
     type: TransactionContent["type"];
     from: any;
     to: any;
-    amount: number;
+    amount: number | string;
     nonce: number;
     timestamp: number;
-    networkFee: number;
-    rpcFee: number;
-    additionalFee: number;
+    networkFee: number | string;
+    rpcFee: number | string;
+    additionalFee: number | string;
     ed25519_signature: string;
     from_ed25519_address: string;
 }

package/build/types/blockchain/statusNative.d.ts

@@ -1,6 +1,14 @@
+/**
+ * Native chain status snapshot for an address.
+ *
+ * Wire-format compatibility (P4): `balance` may arrive as a JS `number`
+ * (pre-fork node, DEM) or a decimal `string` (post-fork node, OS).
+ * Consumers should normalise via `BigInt(...)` to OS internally before
+ * arithmetic. Direct `Number(balance)` truncates above 2^53.
+ */
 export interface StatusNative {
     address: string;
-    balance: number;
+    balance: number | string;
     nonce: number;
     tx_list: string;
 }

package/build/types/bridge/bridgeTradePayload.d.ts

@@ -1,7 +1,7 @@
 export interface BridgeTradePayload {
     fromToken: "NATIVE" | "USDC" | "USDT";
     toToken: "NATIVE" | "USDC" | "USDT";
-    amount: number;
+    amount: number | string;
     fromChainId: number;
     toChainId: number;
 }

package/build/types/gls/StateChange.d.ts

@@ -1,17 +1,43 @@
 import forge from "node-forge";
+/**
+ * Indexer-style state change record. Wire-format compatibility (P4):
+ * `nativeAmount`, `TokenTransfer.amount`, and `NFTTransfer.amount` may
+ * arrive as JS `number` (pre-fork DEM) or decimal `string` (post-fork OS).
+ *
+ * Consumers should normalise via the denomination helpers, **not**
+ * `BigInt(...)`, because:
+ *
+ * - `BigInt(numberWithFractional)` throws `RangeError`.
+ * - `BigInt("non-numeric")` throws `SyntaxError`.
+ * - `BigInt(...)` does not validate decimal-string OS canonicality —
+ *   indexer responses can arrive with whitespace, leading zeros, or
+ *   signed-integer notation.
+ *
+ * Recommended:
+ *
+ * - `denomination.parseOsString(value)` for OS decimal-string inputs
+ *   (post-fork wire). Strips noise and validates the integer shape.
+ * - `denomination.demToOs(value)` for DEM `number` inputs (pre-fork
+ *   wire). Validates and converts to OS bigint.
+ *
+ * Branch on the source's known fork status (e.g. via
+ * `demos.getNetworkInfo()`), not on `typeof value` — the literal `"5"`
+ * could be either a pre-fork DEM string or a post-fork OS string,
+ * which differ by a factor of 10^9.
+ */
 interface TokenTransfer {
     address: string;
-    amount: number;
+    amount: number | string;
 }
 interface NFTTransfer {
     address: string;
     tokenId: string;
-    amount: number;
+    amount: number | string;
 }
 export interface StateChange {
     sender: forge.pki.ed25519.BinaryBuffer;
     receiver: forge.pki.ed25519.BinaryBuffer;
-    nativeAmount: number;
+    nativeAmount: number | string;
     tx_hash: string;
     token: TokenTransfer;
     nft: NFTTransfer;

package/build/types/native/INativePayload.d.ts

@@ -1,6 +1,11 @@
 interface INativeSend {
     nativeOperation: "send";
-    args: [string, number];
+    /**
+     * `[to, amount]`. P4 dual-shape: `amount` may be a JS `number` (pre-fork
+     * DEM) or decimal `string` (post-fork OS). Internal arithmetic uses
+     * `bigint` OS via `denomination` utilities.
+     */
+    args: [string, number | string];
 }
 interface INativeTlsnRequest {
     nativeOperation: "tlsn_request";

package/build/wallet/Wallet.d.ts

@@ -21,7 +21,33 @@ export default class Wallet {
     load(filename: string): Promise<void>;
     save(filename: string): Promise<void>;
     getBalance(): Promise<void>;
-    transfer(to: Address, amount: number, demos: websdk.Demos): Promise<RPCResponseWithValidityData>;
+    /**
+     * Transfer native DEM tokens to a recipient address.
+     *
+     * P4 dual-input:
+     *  - `bigint` (preferred, post-v3): OS amount. 1 DEM = 10^9 OS.
+     *  - `number` (deprecated, v2 callers): DEM amount, auto-converted.
+     *
+     * Internal carrier is OS bigint; the serializerGate (run from
+     * `demos.sign`) chooses pre-fork vs post-fork wire encoding from
+     * the cached `getNetworkInfo` fork status. Sub-DEM precision
+     * against a pre-fork node throws `SubDemPrecisionError` from
+     * `demos.pay` before any tx construction happens — we delegate to
+     * `demos.pay` which carries the guard.
+     *
+     * @example
+     * ```ts
+     * import { denomination, websdk, wallet } from "@kynesyslabs/demosdk"
+     * const w = wallet.default.getInstance("alice")
+     * await w.transfer("0x...", denomination.demToOs(100), demos)
+     * await w.transfer("0x...", 100_000_000_000n, demos)  // raw OS
+     * ```
+     *
+     * @param to - Recipient address (0x-prefixed hex).
+     * @param amount - DEM `number` (legacy) or OS `bigint`.
+     * @param demos - Demos client used to sign and submit.
+     */
+    transfer(to: Address, amount: number | bigint, demos: websdk.Demos): Promise<RPCResponseWithValidityData>;
     broadcast(validityData: RPCResponseWithValidityData, demos: websdk.Demos): Promise<any>;
     generatePasskey(): Promise<string>;
 }

package/build/wallet/Wallet.js

@@ -1,6 +1,5 @@
 // TODO & REVIEW See if the fs methods are useful in this context or nah (also the public ip)
 import * as websdk from "../websdk/index.js";
-import { DemosTransactions } from "../websdk/index.js";
 import { PasskeyGenerator } from "./passkeys/passkeys.js";
 import { Cryptography } from "../encryption/Cryptography.js";
 class Wallet {
@@ -49,23 +48,37 @@ class Wallet {
     }
     /* SECTION Basic writes */
     // NOTE All the writes return a validity object that needs to be confirmed and broadcasted
+    /**
+     * Transfer native DEM tokens to a recipient address.
+     *
+     * P4 dual-input:
+     *  - `bigint` (preferred, post-v3): OS amount. 1 DEM = 10^9 OS.
+     *  - `number` (deprecated, v2 callers): DEM amount, auto-converted.
+     *
+     * Internal carrier is OS bigint; the serializerGate (run from
+     * `demos.sign`) chooses pre-fork vs post-fork wire encoding from
+     * the cached `getNetworkInfo` fork status. Sub-DEM precision
+     * against a pre-fork node throws `SubDemPrecisionError` from
+     * `demos.pay` before any tx construction happens — we delegate to
+     * `demos.pay` which carries the guard.
+     *
+     * @example
+     * ```ts
+     * import { denomination, websdk, wallet } from "@kynesyslabs/demosdk"
+     * const w = wallet.default.getInstance("alice")
+     * await w.transfer("0x...", denomination.demToOs(100), demos)
+     * await w.transfer("0x...", 100_000_000_000n, demos)  // raw OS
+     * ```
+     *
+     * @param to - Recipient address (0x-prefixed hex).
+     * @param amount - DEM `number` (legacy) or OS `bigint`.
+     * @param demos - Demos client used to sign and submit.
+     */
     async transfer(to, amount, demos) {
-        let tx = DemosTransactions.empty();
-        // Putting the right data in the transaction
-        // tx.content.from = keypair.publicKey.toString("hex")
-        tx.content.from = demos.keypair.publicKey.toString("hex");
-        // tx.content.to = to
-        tx.content.type = "native";
-        tx.content.data = [
-            "native",
-            {
-                nativeOperation: "send",
-                args: [to, amount],
-            },
-        ];
-        // tx.content.amount = amount
-        tx = await demos.sign(tx);
-        // Sending the transaction and getting the validity data
+        // Delegate to demos.pay so we get the sub-DEM guard, the
+        // serializerGate, and the canonical native-send tx shape (with
+        // nonce, timestamp, gcr_edits, fee derivation) for free.
+        const tx = await demos.pay(to, amount);
         return await demos.confirm(tx);
     }
     // TODO Implement other methods too

package/build/wallet/Wallet.js.map

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

package/build/websdk/DemosTransactions.d.ts

@@ -9,23 +9,49 @@ export declare const DemosTransactions: {
     /**
      * Create a signed DEMOS transaction to send native tokens to a given address.
      *
+     * P4 dual-input:
+     *  - `bigint`: OS amount (preferred — 1 DEM = 10^9 OS).
+     *  - `number`: DEM amount (legacy, deprecated). Auto-converted to OS.
+     *
+     * Internal carrier in `tx.content.amount` is bigint OS; the
+     * serializerGate (run from `demos.sign`) emits the right wire shape
+     * per the connected node's fork status.
+     *
      * @param to - The reciever
-     * @param amount - The amount in DEM
+     * @param amount - DEM `number` (legacy) or OS `bigint`.
      * @param demos - The demos instance (for getting the address nonce)
      *
      * @returns The signed transaction.
      */
-    pay(to: string, amount: number, demos: Demos): Promise<Transaction>;
+    pay(to: string, amount: number | bigint, demos: Demos): Promise<Transaction>;
+    /**
+     * Convert a legacy DEM `number` input to an OS `bigint` for internal
+     * carrying. Only whole-DEM `number` inputs are accepted on this
+     * legacy path — fractional DEM is rejected with a clear error
+     * directing callers to the bigint OS path (`denomination.demToOs`).
+     *
+     * Rationale: silently flooring (the previous behaviour) discarded up
+     * to ~10^9 OS per call without warning. The migration period
+     * tolerates legacy `number` callers, but only at exact DEM
+     * granularity — anything sub-DEM must come in as `bigint` so the
+     * caller has explicitly opted into OS arithmetic.
+     *
+     * @internal
+     */
+    _demNumberToOsBigint(amountDem: number): bigint;
     /**
      * Create a signed DEMOS transaction to send native tokens to a given address.
      *
+     * Alias of {@link pay}. Same dual-input semantics — `bigint` OS
+     * preferred, `number` DEM accepted as the deprecated path.
+     *
      * @param to - The reciever
-     * @param amount - The amount in DEM
+     * @param amount - DEM `number` (legacy) or OS `bigint`.
      * @param demos - The demos instance (for getting the address nonce)
      *
      * @returns The signed transaction.
      */
-    transfer(to: string, amount: number, demos: Demos): Promise<Transaction>;
+    transfer(to: string, amount: number | bigint, demos: Demos): Promise<Transaction>;
     /**
      * Signs a transaction after hashing its content.
      *