@routedock/nulth-sdk 0.2.0 → 0.2.2

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   paymentContextFromManifest: () => paymentContextFromManifest,
   setNulthPaymentContext: () => setNulthPaymentContext,
   sha256Hex: () => sha256Hex,
+  stroopsToUsdc: () => stroopsToUsdc,
   usdcToStroops: () => usdcToStroops
 });
 module.exports = __toCommonJS(index_exports);
@@ -78,6 +79,16 @@ function usdcToStroops(amount) {
   }
   return units;
 }
+function stroopsToUsdc(units) {
+  if (units < 0n) {
+    throw new RangeError(`Invalid USDC stroops: "${units.toString()}" is negative`);
+  }
+  const whole = units / USDC_SCALE;
+  const frac = units % USDC_SCALE;
+  if (frac === 0n) return whole.toString();
+  const fracStr = frac.toString().padStart(USDC_DECIMALS, "0").replace(/0+$/, "");
+  return `${whole.toString()}.${fracStr}`;
+}
 
 // src/proof.ts
 function sha256Hex(data) {
@@ -262,6 +273,12 @@ var NulthClient = class {
     return encodeAuthSignature(proof);
   }
   enforcePolicy(context) {
+    if (context.amountStroops < 0n) {
+      throw new RangeError(`Invalid amountStroops: ${context.amountStroops}`);
+    }
+    if (!Number.isSafeInteger(context.ledgerSequence) || context.ledgerSequence < 0) {
+      throw new RangeError(`Invalid ledgerSequence: ${context.ledgerSequence}`);
+    }
     if (this.policy.expiryLedger !== void 0 && context.ledgerSequence > this.policy.expiryLedger) {
       throw new NulthPolicyError("session_expired", "Nulth session expired");
     }
@@ -314,7 +331,7 @@ function paymentContextFromManifest(manifest, mode, ledgerSequence) {
     throw new Error(`manifest.pricing.${mode} missing`);
   }
   return {
-    payee: manifest.payee,
+    payee: pricing.payee ?? manifest.payee,
     amountStroops: usdcToStroops(pricing.amount),
     assetContract: manifest.asset_contract,
     ledgerSequence
@@ -353,5 +370,6 @@ function createPolicyState(input) {
   paymentContextFromManifest,
   setNulthPaymentContext,
   sha256Hex,
+  stroopsToUsdc,
   usdcToStroops
 });

package/dist/index.d.cts

@@ -92,6 +92,18 @@ declare const USDC_DECIMALS = 7;
  * {@link USDC_DECIMALS} decimals, or values too large to represent exactly.
  */
 declare function usdcToStroops(amount: string): bigint;
+/**
+ * Inverse of {@link usdcToStroops}: format exact stroops (10^-7 USDC) as a
+ * canonical decimal USDC string, with no trailing zeros.
+ *
+ * `stroopsToUsdc(usdcToStroops(x)) === x` holds for canonical inputs (the form
+ * this function outputs). Used to report the amount actually signed by a
+ * payment client, which may be less than the manifest price.
+ *
+ * Throws RangeError on negative units (there is no such thing as a negative
+ * transfer amount).
+ */
+declare function stroopsToUsdc(units: bigint): string;
 
 /** SHA-256 hex digest */
 declare function sha256Hex(data: Buffer | string): string;
@@ -176,9 +188,11 @@ declare function paymentContextFromManifest(manifest: {
     pricing: {
         x402?: {
             amount: string;
+            payee?: string;
         };
         'mpp-charge'?: {
             amount: string;
+            payee?: string;
         };
     };
 }, mode: 'x402' | 'mpp-charge', ledgerSequence: number): Omit<PaymentAuthContext, 'authEntry'>;
@@ -191,4 +205,4 @@ declare function createPolicyState(input: {
     ledgerSequence?: number;
 }): NulthPolicyState;
 
-export { DEFAULT_PROVER, type NulthAuthSignature, NulthClient, type NulthClientConfig, NulthPolicyError, type NulthPolicyState, type NulthProof, type NulthSignerConfig, type NulthStellarSigner, type PaymentAuthContext, type ProverBackend, USDC_DECIMALS, assertAuthEntryMatchesContext, authDigestFromEntry, commitAllowlist, commitDailyCap, createNulthSigner, createPolicyState, dayBucket, decodeAuthSignature, encodeAuthSignature, hashPayee, insecureMockProof, paymentContextFromManifest, setNulthPaymentContext, sha256Hex, usdcToStroops };
+export { DEFAULT_PROVER, type NulthAuthSignature, NulthClient, type NulthClientConfig, NulthPolicyError, type NulthPolicyState, type NulthProof, type NulthSignerConfig, type NulthStellarSigner, type PaymentAuthContext, type ProverBackend, USDC_DECIMALS, assertAuthEntryMatchesContext, authDigestFromEntry, commitAllowlist, commitDailyCap, createNulthSigner, createPolicyState, dayBucket, decodeAuthSignature, encodeAuthSignature, hashPayee, insecureMockProof, paymentContextFromManifest, setNulthPaymentContext, sha256Hex, stroopsToUsdc, usdcToStroops };

package/dist/index.d.ts

@@ -92,6 +92,18 @@ declare const USDC_DECIMALS = 7;
  * {@link USDC_DECIMALS} decimals, or values too large to represent exactly.
  */
 declare function usdcToStroops(amount: string): bigint;
+/**
+ * Inverse of {@link usdcToStroops}: format exact stroops (10^-7 USDC) as a
+ * canonical decimal USDC string, with no trailing zeros.
+ *
+ * `stroopsToUsdc(usdcToStroops(x)) === x` holds for canonical inputs (the form
+ * this function outputs). Used to report the amount actually signed by a
+ * payment client, which may be less than the manifest price.
+ *
+ * Throws RangeError on negative units (there is no such thing as a negative
+ * transfer amount).
+ */
+declare function stroopsToUsdc(units: bigint): string;
 
 /** SHA-256 hex digest */
 declare function sha256Hex(data: Buffer | string): string;
@@ -176,9 +188,11 @@ declare function paymentContextFromManifest(manifest: {
     pricing: {
         x402?: {
             amount: string;
+            payee?: string;
         };
         'mpp-charge'?: {
             amount: string;
+            payee?: string;
         };
     };
 }, mode: 'x402' | 'mpp-charge', ledgerSequence: number): Omit<PaymentAuthContext, 'authEntry'>;
@@ -191,4 +205,4 @@ declare function createPolicyState(input: {
     ledgerSequence?: number;
 }): NulthPolicyState;
 
-export { DEFAULT_PROVER, type NulthAuthSignature, NulthClient, type NulthClientConfig, NulthPolicyError, type NulthPolicyState, type NulthProof, type NulthSignerConfig, type NulthStellarSigner, type PaymentAuthContext, type ProverBackend, USDC_DECIMALS, assertAuthEntryMatchesContext, authDigestFromEntry, commitAllowlist, commitDailyCap, createNulthSigner, createPolicyState, dayBucket, decodeAuthSignature, encodeAuthSignature, hashPayee, insecureMockProof, paymentContextFromManifest, setNulthPaymentContext, sha256Hex, usdcToStroops };
+export { DEFAULT_PROVER, type NulthAuthSignature, NulthClient, type NulthClientConfig, NulthPolicyError, type NulthPolicyState, type NulthProof, type NulthSignerConfig, type NulthStellarSigner, type PaymentAuthContext, type ProverBackend, USDC_DECIMALS, assertAuthEntryMatchesContext, authDigestFromEntry, commitAllowlist, commitDailyCap, createNulthSigner, createPolicyState, dayBucket, decodeAuthSignature, encodeAuthSignature, hashPayee, insecureMockProof, paymentContextFromManifest, setNulthPaymentContext, sha256Hex, stroopsToUsdc, usdcToStroops };

package/dist/index.js

@@ -34,6 +34,16 @@ function usdcToStroops(amount) {
   }
   return units;
 }
+function stroopsToUsdc(units) {
+  if (units < 0n) {
+    throw new RangeError(`Invalid USDC stroops: "${units.toString()}" is negative`);
+  }
+  const whole = units / USDC_SCALE;
+  const frac = units % USDC_SCALE;
+  if (frac === 0n) return whole.toString();
+  const fracStr = frac.toString().padStart(USDC_DECIMALS, "0").replace(/0+$/, "");
+  return `${whole.toString()}.${fracStr}`;
+}
 
 // src/proof.ts
 function sha256Hex(data) {
@@ -218,6 +228,12 @@ var NulthClient = class {
     return encodeAuthSignature(proof);
   }
   enforcePolicy(context) {
+    if (context.amountStroops < 0n) {
+      throw new RangeError(`Invalid amountStroops: ${context.amountStroops}`);
+    }
+    if (!Number.isSafeInteger(context.ledgerSequence) || context.ledgerSequence < 0) {
+      throw new RangeError(`Invalid ledgerSequence: ${context.ledgerSequence}`);
+    }
     if (this.policy.expiryLedger !== void 0 && context.ledgerSequence > this.policy.expiryLedger) {
       throw new NulthPolicyError("session_expired", "Nulth session expired");
     }
@@ -270,7 +286,7 @@ function paymentContextFromManifest(manifest, mode, ledgerSequence) {
     throw new Error(`manifest.pricing.${mode} missing`);
   }
   return {
-    payee: manifest.payee,
+    payee: pricing.payee ?? manifest.payee,
     amountStroops: usdcToStroops(pricing.amount),
     assetContract: manifest.asset_contract,
     ledgerSequence
@@ -308,5 +324,6 @@ export {
   paymentContextFromManifest,
   setNulthPaymentContext,
   sha256Hex,
+  stroopsToUsdc,
   usdcToStroops
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routedock/nulth-sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Off-chain ZK proof builder for Nulth smart accounts on Stellar",
   "license": "MIT",
   "type": "module",