@provex/utils 1.7.0 → 1.8.0-rc.20260607065921.1177ada

package/dist/input.js

@@ -48,7 +48,16 @@ export const adjustLowestDecimal = (inputVal, direction) => {
     // Convert back to string, pad with zeros if needed
     let valueStr = value.toString().padStart(whole.length + 18, '0');
     let newWhole = BigInt(valueStr.slice(0, valueStr.length - 18) || '0').toString();
-    let newDecimal = valueStr.slice(-18, -18 + originalDecimals);
+    // Take the last 18 chars (the decimal portion of the padded value),
+    // then trim back down to the original precision.
+    //
+    // Two-step slice instead of `valueStr.slice(-18, -18 + originalDecimals)`
+    // — that single slice returns an empty string when
+    // originalDecimals === 18 because end (0) ≤ begin (-18 wraps to a
+    // positive index), which silently drops every decimal digit at the
+    // 18-decimal cap. The two-step path is correct for every
+    // originalDecimals in [1, 18].
+    let newDecimal = valueStr.slice(-18).slice(0, originalDecimals);
     // If originalDecimals was 0, don't add a decimal point
     return originalDecimals > 0 ? `${newWhole}.${newDecimal}` : newWhole;
 };

package/dist/input.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/input.test.js

@@ -0,0 +1,94 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { adjustLowestDecimal } from './input.js';
+describe('adjustLowestDecimal', () => {
+    describe('whole numbers (no decimal point)', () => {
+        it('increments by 1', () => {
+            assert.equal(adjustLowestDecimal('100', 1), '101');
+            assert.equal(adjustLowestDecimal('0', 1), '1');
+            assert.equal(adjustLowestDecimal('9', 1), '10');
+        });
+        it('decrements by 1', () => {
+            assert.equal(adjustLowestDecimal('100', -1), '99');
+            assert.equal(adjustLowestDecimal('10', -1), '9');
+            assert.equal(adjustLowestDecimal('1', -1), '0');
+        });
+        it('does not produce a decimal point on a whole-number input', () => {
+            const result = adjustLowestDecimal('100', 1);
+            assert.ok(!result.includes('.'), `expected no decimal point, got "${result}"`);
+        });
+    });
+    describe('two decimal places', () => {
+        it('increments the hundredths place and preserves precision', () => {
+            assert.equal(adjustLowestDecimal('1.50', 1), '1.51');
+            assert.equal(adjustLowestDecimal('0.00', 1), '0.01');
+        });
+        it('decrements the hundredths place and preserves precision', () => {
+            assert.equal(adjustLowestDecimal('1.50', -1), '1.49');
+            assert.equal(adjustLowestDecimal('1.00', -1), '0.99');
+        });
+        it('keeps trailing zeros (precision is sticky)', () => {
+            // 1.50 - 1 step at the hundredths → 1.49 (NOT "1.5"), because
+            // the original input declared 2 decimals of precision.
+            assert.equal(adjustLowestDecimal('1.50', -1), '1.49');
+            // 1.00 + 1 step → 1.01 (NOT "1.01" collapsed to "1.01")
+            assert.equal(adjustLowestDecimal('1.00', 1), '1.01');
+        });
+    });
+    describe('three+ decimal places', () => {
+        it('operates at the deepest entered precision', () => {
+            assert.equal(adjustLowestDecimal('0.001', 1), '0.002');
+            assert.equal(adjustLowestDecimal('0.001', -1), '0.000');
+            assert.equal(adjustLowestDecimal('0.0001', 1), '0.0002');
+        });
+        it('preserves precision when crossing decimal carry', () => {
+            assert.equal(adjustLowestDecimal('0.009', 1), '0.010');
+            assert.equal(adjustLowestDecimal('0.099', 1), '0.100');
+        });
+    });
+    describe('cannot decrement below zero', () => {
+        // The function's contract (line 44-47) is: "if direction is -1
+        // and value < delta, do nothing." This protects against negative
+        // outputs in numeric input controls.
+        it('clamps at zero for whole numbers', () => {
+            assert.equal(adjustLowestDecimal('0', -1), '0');
+        });
+        it('clamps at zero for decimals', () => {
+            assert.equal(adjustLowestDecimal('0.00', -1), '0.00');
+            assert.equal(adjustLowestDecimal('0.001', -1), '0.000');
+        });
+    });
+    describe('decimal precision cap (18 places)', () => {
+        // Internally the function pads to 18 decimals for the bigint math.
+        // The boundary case (input AT 18 decimals) used to drop every
+        // decimal digit because the final single-slice math hit
+        // `slice(-18, 0)` and returned empty. Fixed by switching to a
+        // two-step `slice(-18).slice(0, originalDecimals)` — pin that
+        // here so a regression to the single-slice path would surface.
+        it('preserves precision at 17 decimals after adjust', () => {
+            const result = adjustLowestDecimal('0.12345678901234567', 1);
+            const [, decimal = ''] = result.split('.');
+            assert.equal(decimal.length, 17, `expected 17 decimal places, got ${decimal.length}`);
+        });
+        it('preserves precision at exactly 18 decimals after adjust', () => {
+            const result = adjustLowestDecimal('0.123456789012345678', 1);
+            // Adjusting at the 18th decimal place (idx 17) by +1 flips the
+            // last digit: ...678 → ...679. Result must still be 18-decimal.
+            assert.equal(result, '0.123456789012345679');
+        });
+        it('truncates inputs beyond 18 decimals before adjusting', () => {
+            // Input with 30 decimal characters gets truncated to 18 at
+            // parse time, then incremented at the 18th decimal place.
+            const result = adjustLowestDecimal('0.123456789012345678901234567890', 1);
+            assert.equal(result, '0.123456789012345679');
+        });
+    });
+    describe('large whole-number values', () => {
+        it('handles values larger than Number.MAX_SAFE_INTEGER via bigint', () => {
+            // 2^53 = 9007199254740992 — anything above this loses precision
+            // in plain JS numbers. The function uses bigint internally so
+            // the result must be exact.
+            assert.equal(adjustLowestDecimal('9007199254740992', 1), '9007199254740993');
+        });
+    });
+});

package/dist/json.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/json.test.js

@@ -0,0 +1,103 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { jsonSerializer, mapBigIntFields } from './json.js';
+describe('jsonSerializer.stringify', () => {
+    it('serializes a plain object without bigints (matches JSON.stringify)', () => {
+        const obj = { name: 'test', count: 42, active: true };
+        assert.equal(jsonSerializer.stringify(obj), JSON.stringify(obj));
+    });
+    it('converts a top-level bigint to a string', () => {
+        const json = jsonSerializer.stringify({ amount: 100000000n });
+        assert.equal(json, '{"amount":"100000000"}');
+    });
+    it('converts nested bigints to strings', () => {
+        const json = jsonSerializer.stringify({
+            outer: { inner: 999n, deeper: { evenDeeper: 1n } },
+        });
+        assert.equal(json, '{"outer":{"inner":"999","deeper":{"evenDeeper":"1"}}}');
+    });
+    it('handles arrays of bigints', () => {
+        const json = jsonSerializer.stringify([1n, 2n, 3n]);
+        assert.equal(json, '["1","2","3"]');
+    });
+    it('handles mixed arrays', () => {
+        const json = jsonSerializer.stringify([1n, 'two', 3]);
+        assert.equal(json, '["1","two",3]');
+    });
+    it('handles a negative bigint', () => {
+        const json = jsonSerializer.stringify({ delta: -123n });
+        assert.equal(json, '{"delta":"-123"}');
+    });
+    it('handles zero bigint', () => {
+        const json = jsonSerializer.stringify({ zero: 0n });
+        assert.equal(json, '{"zero":"0"}');
+    });
+});
+describe('jsonSerializer.parse', () => {
+    it('is JSON.parse by reference', () => {
+        // Documented behavior — parse does NOT convert string-shaped numbers
+        // back to bigints. That's mapBigIntFields' job.
+        assert.equal(jsonSerializer.parse, JSON.parse);
+    });
+    it('returns parsed values as plain objects (no auto-bigint)', () => {
+        const parsed = jsonSerializer.parse('{"amount":"100000000"}');
+        assert.deepEqual(parsed, { amount: '100000000' });
+        assert.equal(typeof parsed.amount, 'string');
+    });
+});
+describe('mapBigIntFields', () => {
+    it('converts a named field to bigint at the top level', () => {
+        const result = mapBigIntFields({ amount: '100', name: 'x' }, ['amount']);
+        assert.equal(result.amount, 100n);
+        assert.equal(result.name, 'x');
+    });
+    it('leaves fields not in the list untouched', () => {
+        const result = mapBigIntFields({ amount: '100', count: '50' }, ['amount']);
+        assert.equal(result.amount, 100n);
+        assert.equal(result.count, '50'); // string, not bigint
+    });
+    it('recurses into nested objects', () => {
+        const result = mapBigIntFields({ outer: { inner: '50', label: 'x' } }, ['inner']);
+        assert.equal(result.outer.inner, 50n);
+        assert.equal(result.outer.label, 'x');
+    });
+    it('recurses into arrays', () => {
+        const result = mapBigIntFields([{ amount: '10' }, { amount: '20' }], ['amount']);
+        assert.equal(result[0].amount, 10n);
+        assert.equal(result[1].amount, 20n);
+    });
+    it('handles array-of-array nesting', () => {
+        const result = mapBigIntFields([[{ amount: '1' }], [{ amount: '2' }]], ['amount']);
+        assert.equal(result[0][0].amount, 1n);
+        assert.equal(result[1][0].amount, 2n);
+    });
+    it('only converts strings that match the digit regex', () => {
+        // The implementation requires /^-?\d+$/ to coerce — strings with
+        // non-digit characters stay as strings to avoid BigInt() throws.
+        const result = mapBigIntFields({ amount: 'not-a-number', count: '42abc' }, ['amount', 'count']);
+        assert.equal(result.amount, 'not-a-number');
+        assert.equal(result.count, '42abc');
+    });
+    it('handles negative number strings', () => {
+        const result = mapBigIntFields({ delta: '-100' }, ['delta']);
+        assert.equal(result.delta, -100n);
+    });
+    it('leaves non-string values in matched fields alone', () => {
+        // The implementation gates on `typeof value === 'string'`, so a
+        // number or bigint at a matched key stays as-is.
+        const result = mapBigIntFields({ amount: 42 }, ['amount']);
+        assert.equal(result.amount, 42);
+    });
+    it('handles a roundtrip: stringify → parse → mapBigIntFields', () => {
+        const original = { amount: 100000000n, name: 'test', nested: { value: 50n } };
+        const json = jsonSerializer.stringify(original);
+        const parsed = jsonSerializer.parse(json);
+        const restored = mapBigIntFields(parsed, ['amount', 'value']);
+        assert.deepEqual(restored, original);
+    });
+    it('returns primitives unchanged', () => {
+        assert.equal(mapBigIntFields(42, ['amount']), 42);
+        assert.equal(mapBigIntFields('hello', ['amount']), 'hello');
+        assert.equal(mapBigIntFields(null, ['amount']), null);
+    });
+});

package/dist/participants.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/participants.test.js

@@ -0,0 +1,56 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { generateParticipantId } from './participants.js';
+const DEAD_ADDRESS = '0xdead000000000000000000000000000000000000';
+const BEEF_ADDRESS = '0xbeef000000000000000000000000000000000000';
+describe('generateParticipantId', () => {
+    it('returns a 0x-prefixed 66-character hex string (32 bytes)', () => {
+        const id = generateParticipantId(1, DEAD_ADDRESS);
+        assert.match(id, /^0x[0-9a-f]{64}$/);
+    });
+    it('is deterministic for the same inputs', () => {
+        const a = generateParticipantId(8453, DEAD_ADDRESS);
+        const b = generateParticipantId(8453, DEAD_ADDRESS);
+        assert.equal(a, b);
+    });
+    it('produces different IDs for different chains with the same address', () => {
+        // The whole point of this fn: cross-chain uniqueness. The same
+        // address on chain 1 and chain 8453 must hash to different ids,
+        // otherwise indexer counterparty tracking collapses across chains.
+        const onMainnet = generateParticipantId(1, DEAD_ADDRESS);
+        const onBase = generateParticipantId(8453, DEAD_ADDRESS);
+        assert.notEqual(onMainnet, onBase);
+    });
+    it('produces different IDs for different addresses on the same chain', () => {
+        const dead = generateParticipantId(8453, DEAD_ADDRESS);
+        const beef = generateParticipantId(8453, BEEF_ADDRESS);
+        assert.notEqual(dead, beef);
+    });
+    it('accepts bigint chainId equivalent to numeric', () => {
+        // Documented signature is `number | bigint`. Confirm the two
+        // shapes produce the same hash (otherwise an indexer that uses
+        // bigint and a UI that uses number would silently disagree).
+        const fromNumber = generateParticipantId(8453, DEAD_ADDRESS);
+        const fromBigint = generateParticipantId(8453n, DEAD_ADDRESS);
+        assert.equal(fromNumber, fromBigint);
+    });
+    it('handles a large chainId (PulseChain = 369)', () => {
+        const id = generateParticipantId(369, DEAD_ADDRESS);
+        assert.match(id, /^0x[0-9a-f]{64}$/);
+    });
+    it('handles chainId 0 (zero is valid as a numeric chain identifier)', () => {
+        // Zero is a meaningful sentinel chainId in some test/dev contexts;
+        // the function should still produce a valid hash, not throw.
+        const id = generateParticipantId(0, DEAD_ADDRESS);
+        assert.match(id, /^0x[0-9a-f]{64}$/);
+    });
+    it('produces an ID independent of address case', () => {
+        // viem's keccak256 should treat the hex content equivalently
+        // regardless of input case (concatHex normalizes). Documenting
+        // this so an upstream change to viem's case handling would surface
+        // here, not silently in production.
+        const lower = generateParticipantId(8453, '0xdead000000000000000000000000000000000000');
+        const upper = generateParticipantId(8453, '0xDEAD000000000000000000000000000000000000');
+        assert.equal(lower, upper);
+    });
+});

package/dist/payment.d.ts

@@ -86,6 +86,22 @@ export declare const subProviders: {
 };
 /** Sub-provider key (providers within providers) */
 export type SubProviderKey = typeof subProviders[keyof typeof subProviders];
+/**
+ * Rails whose zkTLS proof carries only a calendar DATE (no time of day), so the
+ * gate applies the day-resolution window (latestPlausiblePaymentMs) and the buy
+ * UI must disclose the wider timing window.
+ *
+ * - `providers.ZELLE` — parent key used by deposit rate cards (covers all Zelle).
+ * - `subProviders.CHASE` — confirmed via real proof: timestamp is 8-digit YYYYMMDD.
+ *
+ * Other Zelle sub-banks (BofA, Citi) use `dateStringUtcParameter` in the gate
+ * until real proofs confirm their timestamp format. Add them here once confirmed
+ * and the gate is updated to `dayParameterYyyymmdd`. Keep in sync with
+ * `payment-extraction.ts` — every key here must use `dayParameterYyyymmdd` there.
+ */
+export declare const DAY_RESOLUTION_PROVIDER_KEYS: ReadonlySet<ProviderKey | SubProviderKey>;
+/** True if a provider's proof only resolves payment time to the calendar date. */
+export declare function isDayResolutionRail(key: ProviderKey | SubProviderKey): boolean;
 /**
  * Extension platform keys - the platform identifiers used by the PeerAuth extension.
  * For Zelle sub-providers, these are the bank names without the 'zelle-' prefix.

package/dist/payment.js

@@ -133,6 +133,27 @@ export const subProviders = {
     BANK_OF_AMERICA: 'zelle-bofa',
     CITI: 'zelle-citi',
 };
+/**
+ * Rails whose zkTLS proof carries only a calendar DATE (no time of day), so the
+ * gate applies the day-resolution window (latestPlausiblePaymentMs) and the buy
+ * UI must disclose the wider timing window.
+ *
+ * - `providers.ZELLE` — parent key used by deposit rate cards (covers all Zelle).
+ * - `subProviders.CHASE` — confirmed via real proof: timestamp is 8-digit YYYYMMDD.
+ *
+ * Other Zelle sub-banks (BofA, Citi) use `dateStringUtcParameter` in the gate
+ * until real proofs confirm their timestamp format. Add them here once confirmed
+ * and the gate is updated to `dayParameterYyyymmdd`. Keep in sync with
+ * `payment-extraction.ts` — every key here must use `dayParameterYyyymmdd` there.
+ */
+export const DAY_RESOLUTION_PROVIDER_KEYS = new Set([
+    providers.ZELLE,
+    subProviders.CHASE,
+]);
+/** True if a provider's proof only resolves payment time to the calendar date. */
+export function isDayResolutionRail(key) {
+    return DAY_RESOLUTION_PROVIDER_KEYS.has(key);
+}
 /**
  * Extension platform keys - the platform identifiers used by the PeerAuth extension.
  * For Zelle sub-providers, these are the bank names without the 'zelle-' prefix.

package/dist/payment.test.js

@@ -1,7 +1,7 @@
-import { describe, it } from 'node:test';
+import { describe, it, test } from 'node:test';
 import assert from 'node:assert/strict';
 import { base } from 'viem/chains';
-import { providerConfigs, getCurrenciesForProvider, providers, verifierGetsKey, providerKeyToContractId, resolveApiProviderKey, getProviderPaymentMethodIds, computeProviderAvailability, availableProviderConfigs, subProviders } from './payment.js';
+import { providerConfigs, getCurrenciesForProvider, providers, verifierGetsKey, providerKeyToContractId, resolveApiProviderKey, getProviderPaymentMethodIds, computeProviderAvailability, availableProviderConfigs, subProviders, isDayResolutionRail } from './payment.js';
 import { SUPPORTED_CURRENCIES } from './currencies.js';
 describe('getCurrenciesForProvider', () => {
     const configs = providerConfigs(base.id);
@@ -474,6 +474,18 @@ describe('computeProviderAvailability', () => {
         // unavailable should contain at least the visible non-disabled set
         assert.ok(result.unavailable.length > 0);
     });
+    test('isDayResolutionRail flags Zelle rails (date-only proof timestamp), not millisecond rails', () => {
+        // Chase proof (parity-seed.json) confirmed: timestamp is 8-digit YYYYMMDD.
+        // Parent 'zelle' key covers deposit rate cards that show all Zelle sub-banks.
+        assert.equal(isDayResolutionRail(providers.ZELLE), true);
+        assert.equal(isDayResolutionRail(subProviders.CHASE), true);
+        // BofA and Citi use dateStringUtcParameter until real proofs confirm date-only
+        // format — must NOT be flagged until the gate is updated to dayParameterYyyymmdd.
+        assert.equal(isDayResolutionRail(subProviders.BANK_OF_AMERICA), false);
+        assert.equal(isDayResolutionRail(subProviders.CITI), false);
+        // Millisecond-resolution rails must never be flagged.
+        assert.equal(isDayResolutionRail(providers.REVOLUT), false);
+    });
     it('availableProviderConfigs is a thin wrapper that returns only the available list', () => {
         const both = computeProviderAvailability({
             chainId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provex/utils",
-  "version": "1.7.0",
+  "version": "1.8.0-rc.20260607065921.1177ada",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -130,7 +130,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@zkp2p/providers": "^7.8.0"
+    "@zkp2p/providers": "github:zkp2p/providers#7751475b73b533b342d8518628578b33ea191a19"
   },
   "peerDependencies": {
     "viem": "^2.0.0"