@provex/utils 1.9.2 → 1.10.0-rc.20260912192040.fdbb8fc

package/dist/payment.rails.test.js

@@ -0,0 +1,213 @@
+/**
+ * @fileoverview Rail invariants for payment method configuration.
+ *
+ * `payment.test.ts` covers the behaviour of the individual helpers with named
+ * cases. This file states the rule those helpers exist to enforce, as a sweep
+ * over every provider on every chain, so a newly added provider is covered
+ * without anyone remembering to add a case.
+ *
+ * **The rule.** A payment method on-chain is `keccak256(platform)`, where
+ * `platform` is what the zkTLS attestation names — the `metadata.platform` of
+ * the `@zkp2p/providers` template. `UnifiedPaymentVerifier` requires
+ * `snapshot.paymentMethod == intent.paymentMethod`, so a deposit that attaches
+ * anything else accepts intents no attestation can ever satisfy.
+ *
+ * Zelle is the case that taught this: every bank template (Chase, Bank of
+ * America, Citi, and now Wells Fargo, U.S. Bank, and TD) declares
+ * `platform: "zelle"`. The bank rides in the action type, never the platform.
+ * So bank-level keys are a capture-time detail — which website the extension
+ * opens — and must collapse to the rail everywhere the on-chain method is
+ * computed, while staying distinct everywhere the buyer picks a bank.
+ *
+ * The tests below assert both directions, because collapsing too much is its
+ * own bug: it would leave the buyer unable to say which bank they paid from.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { chainIds } from './chain.js';
+import { providers, subProviders, providerConfigs, subProviderConfigs, isProviderDisabled, providerKeyToContractId, resolveRailProviderKey, getProviderPaymentMethodIds, computeProviderAvailability, findLegacySubProviderAttachments, } from './payment.js';
+/** Every provider config that can be attached to a deposit, on every chain. */
+const attachableConfigs = () => chainIds.flatMap((chainId) => Object.values(providerConfigs(chainId))
+    .filter((config) => config.key !== providers.MANUAL)
+    .map((config) => ({ chainId, config })));
+const railIdFor = (key) => providerKeyToContractId(resolveRailProviderKey(key)).toLowerCase();
+describe('payment rail configuration', () => {
+    describe('the id a write submits', () => {
+        it('produces exactly one payment method id per provider', () => {
+            // Fanning out was the original bug in both directions: the deposit got
+            // three bank methods nothing could fulfil, and the availability gate
+            // then compared against ids the write no longer submits.
+            for (const { chainId, config } of attachableConfigs()) {
+                const ids = getProviderPaymentMethodIds(config);
+                assert.strictEqual(ids.length, 1, `${config.key} on chain ${chainId} produced ${ids.length} ids: ${ids.join(', ')}`);
+            }
+        });
+        it('produces the rail hash, never a sub-provider hash', () => {
+            const bankIds = new Set(Object.values(subProviders).map((key) => providerKeyToContractId(key).toLowerCase()));
+            for (const { chainId, config } of attachableConfigs()) {
+                const [id] = getProviderPaymentMethodIds(config);
+                assert.strictEqual(id, railIdFor(config.key), `${config.key} on chain ${chainId} does not submit its own rail hash`);
+                assert.ok(!bankIds.has(id), `${config.key} on chain ${chainId} submits a bank-level hash — no attestation carries one`);
+            }
+        });
+        it('emits lowercased ids, so callers can compare without normalizing', () => {
+            // `Deposit.attachedPaymentMethodIds` is lowercased. A checksummed id here
+            // would silently never collide, making every method look addable.
+            for (const { config } of attachableConfigs()) {
+                for (const id of getProviderPaymentMethodIds(config)) {
+                    assert.strictEqual(id, id.toLowerCase(), `${config.key} produced a non-lowercased id`);
+                }
+            }
+        });
+    });
+    describe('rail resolution', () => {
+        it('collapses every sub-provider onto a real provider key', () => {
+            const known = new Set(Object.values(providers));
+            for (const key of Object.values(subProviders)) {
+                const rail = resolveRailProviderKey(key);
+                assert.notStrictEqual(rail, key, `${key} did not collapse`);
+                assert.ok(known.has(rail), `${key} collapsed to "${rail}", which is not a provider key`);
+            }
+        });
+        it('leaves rail keys untouched, so it is safe to apply unconditionally', () => {
+            for (const key of Object.values(providers)) {
+                assert.strictEqual(resolveRailProviderKey(key), key);
+            }
+        });
+        it('declares sub-providers only under the rail they collapse to', () => {
+            for (const [railKey, banks] of Object.entries(subProviderConfigs)) {
+                for (const bankKey of Object.keys(banks ?? {})) {
+                    assert.strictEqual(resolveRailProviderKey(bankKey), railKey, `${bankKey} is declared under ${railKey} but collapses elsewhere`);
+                }
+            }
+        });
+    });
+    describe('what must stay per-bank', () => {
+        it('keeps a distinct capture target for every bank', () => {
+            // The mirror of the collapse. On-chain the banks are one method, but the
+            // extension has to open the right bank's website and parse its page, so
+            // the capture-time identity must not be collapsed with it.
+            const platforms = Object.values(subProviderConfigs)
+                .flatMap((banks) => Object.values(banks ?? {}))
+                .map((bank) => bank.extensionPlatform);
+            assert.strictEqual(new Set(platforms).size, platforms.length, `sub-providers share an extension platform: ${platforms.join(', ')}`);
+            for (const platform of platforms) {
+                assert.ok(platform, 'a sub-provider has no extension platform to capture from');
+            }
+        });
+        it('gives every bank its own send link', () => {
+            for (const [railKey, banks] of Object.entries(subProviderConfigs)) {
+                for (const [bankKey, bank] of Object.entries(banks ?? {})) {
+                    assert.strictEqual(typeof bank.sendLink, 'function', `${railKey}/${bankKey} has no send link for the payer to follow`);
+                }
+            }
+        });
+    });
+    describe('availability against an existing deposit', () => {
+        it('marks a provider unavailable once its own rail id is attached', () => {
+            // The contract reverts on re-adding a hash the deposit already holds,
+            // so availability has to be decided against exactly the id the write
+            // submits — not against a related one.
+            for (const chainId of chainIds) {
+                for (const config of Object.values(providerConfigs(chainId))) {
+                    if (config.key === providers.MANUAL)
+                        continue;
+                    if (isProviderDisabled(config.key, config.disabled))
+                        continue;
+                    const attached = new Set(getProviderPaymentMethodIds(config));
+                    const { available, unavailable } = computeProviderAvailability({ chainId, attachedPaymentMethodIds: attached });
+                    assert.ok(unavailable.some((entry) => entry.key === config.key), `${config.key} on chain ${chainId} stayed addable after being attached — re-adding reverts`);
+                    assert.ok(!available.some((entry) => entry.key === config.key), `${config.key} on chain ${chainId} appears in both lists`);
+                }
+            }
+        });
+        it('keeps the rail addable on a deposit holding only legacy bank ids', () => {
+            // This is the repair path. A deposit carrying `zelle-chase` and friends
+            // can be fulfilled by nothing; attaching the rail is how it is fixed, so
+            // the interface must keep offering it.
+            const bankIds = new Set(Object.values(subProviders).map((key) => providerKeyToContractId(key).toLowerCase()));
+            for (const chainId of chainIds) {
+                const { available } = computeProviderAvailability({
+                    chainId,
+                    attachedPaymentMethodIds: bankIds,
+                });
+                assert.ok(available.some((entry) => entry.key === providers.ZELLE), `chain ${chainId} hides Zelle from a deposit that needs it most`);
+            }
+        });
+        it('flags a deposit holding only bank ids as needing the rail', () => {
+            // The state deposits 182 and 7 are in on PulseChain. Such a deposit is
+            // invisible to buyers rather than broken for them, so it produces no
+            // failed orders and no complaints — this predicate is the only thing
+            // that can tell the maker their liquidity is doing nothing.
+            const bankIds = new Set(Object.values(subProviders).map((key) => providerKeyToContractId(key).toLowerCase()));
+            for (const chainId of chainIds) {
+                const found = findLegacySubProviderAttachments({
+                    chainId,
+                    attachedPaymentMethodIds: bankIds,
+                });
+                const zelle = found.find((entry) => entry.rail === providers.ZELLE);
+                assert.ok(zelle, `chain ${chainId} failed to flag a deposit that no buyer can see`);
+                // It must name the rail to attach. Naming a bank would send the maker
+                // back through the very write that stranded the deposit.
+                assert.strictEqual(zelle.rail, providers.ZELLE);
+                assert.deepStrictEqual(zelle.attachedSubProviderKeys, [...Object.values(subProviders)].sort(), 'must report the bank rows it actually holds');
+            }
+        });
+        it('stops flagging once the rail is attached', () => {
+            // The repair is one transaction and the bank rows survive it — they
+            // cannot be removed. If their presence kept the warning up, every
+            // repaired deposit would nag its owner forever with no way to comply.
+            const railAndBanks = new Set([
+                providerKeyToContractId(providers.ZELLE).toLowerCase(),
+                ...Object.values(subProviders).map((key) => providerKeyToContractId(key).toLowerCase()),
+            ]);
+            for (const chainId of chainIds) {
+                const found = findLegacySubProviderAttachments({
+                    chainId,
+                    attachedPaymentMethodIds: railAndBanks,
+                });
+                assert.ok(!found.some((entry) => entry.rail === providers.ZELLE), `chain ${chainId} still warns about a deposit that has already been repaired`);
+            }
+        });
+        it('leaves healthy deposits alone', () => {
+            // A false positive here tells a maker their working deposit is broken.
+            for (const chainId of chainIds) {
+                assert.deepStrictEqual(findLegacySubProviderAttachments({ chainId, attachedPaymentMethodIds: new Set() }), [], `chain ${chainId} flagged a deposit with no payment methods at all`);
+                for (const config of Object.values(providerConfigs(chainId))) {
+                    if (config.key === providers.MANUAL)
+                        continue;
+                    const attached = new Set(getProviderPaymentMethodIds(config));
+                    assert.deepStrictEqual(findLegacySubProviderAttachments({ chainId, attachedPaymentMethodIds: attached }), [], `chain ${chainId} flagged a deposit holding only the rail id for ${config.key}`);
+                }
+            }
+        });
+        it('never names a rail the chain will not accept', () => {
+            // Telling a maker to attach a disabled rail sends them to a write that
+            // cannot succeed, and the modal would not offer it either.
+            const everyKnownId = new Set([...Object.values(providers), ...Object.values(subProviders)].map((key) => providerKeyToContractId(key).toLowerCase()));
+            for (const chainId of chainIds) {
+                // Drop the rails so every sub-provider still looks unrepaired.
+                const attached = new Set(everyKnownId);
+                for (const key of Object.values(providers)) {
+                    attached.delete(providerKeyToContractId(key).toLowerCase());
+                }
+                for (const entry of findLegacySubProviderAttachments({ chainId, attachedPaymentMethodIds: attached })) {
+                    const config = providerConfigs(chainId)[entry.rail];
+                    assert.ok(config, `chain ${chainId} named ${entry.rail}, which it does not support`);
+                    assert.ok(!isProviderDisabled(entry.rail, config.disabled), `chain ${chainId} told a maker to attach disabled rail ${entry.rail}`);
+                }
+            }
+        });
+        it('never reports a provider as both available and unavailable', () => {
+            for (const chainId of chainIds) {
+                const { available, unavailable } = computeProviderAvailability({
+                    chainId,
+                    attachedPaymentMethodIds: new Set(),
+                });
+                const keys = [...available, ...unavailable].map((entry) => entry.key);
+                assert.strictEqual(new Set(keys).size, keys.length, `chain ${chainId} double-listed a provider`);
+                assert.ok(!keys.includes(providers.MANUAL), 'manual is not attachable and must appear in neither list');
+            }
+        });
+    });
+});

package/dist/payment.test.js

@@ -2,7 +2,7 @@ import { describe, it, test } from 'node:test';
 import assert from 'node:assert/strict';
 import { base } from 'viem/chains';
 import { getAddress } from 'viem';
-import { providerConfigs, getCurrenciesForProvider, providers, verifierGetsKey, providerKeyToContractId, resolveApiProviderKey, getProviderPaymentMethodIds, computeProviderAvailability, availableProviderConfigs, subProviders, isDayResolutionRail } from './payment.js';
+import { providerConfigs, getCurrenciesForProvider, providers, verifierGetsKey, providerKeyToContractId, resolveApiProviderKey, resolveRailProviderKey, getProviderPaymentMethodIds, computeProviderAvailability, availableProviderConfigs, subProviders, isDayResolutionRail } from './payment.js';
 import { paymentVerifierToKey, providerByContractId, getProviderByContractId, getProviderNameByContractId, providerKeyToVerifiers, providerKeyToVerifiersMap, getPaymentMethodConfig, getPaymentMethodName, getPaymentMethodMinimum, getPaymentProviderMinimum, calculateEffectiveMinimum, isPaymentMethodKnown, isPaymentMethodIdKnown, isExternalPaymentMethod, getExternalPaymentMethod, externalPaymentMethods, getExtensionPlatform, getParentProviderKey, isSubProviderKey, providerRequiresMetadataIndex, getProviderIconStack, getPaymentIcon, getPlatformRisk, fromPeerTier, tierToPeerTier, tiers, getAllPaymentMethods, verifiablePaymentMethods, } from './payment.js';
 import { getDefaultToken } from './tokens.js';
 import { SUPPORTED_CURRENCIES } from './currencies.js';
@@ -206,6 +206,38 @@ describe('resolveApiProviderKey', () => {
         assert.equal(resolveApiProviderKey('unknown-sub'), 'unknown-sub');
     });
 });
+/**
+ * Tests for resolveRailProviderKey — the same collapse, applied to the
+ * ON-CHAIN payment method. A Zelle attestation is issued for the rail: every
+ * bank template declares `metadata.platform: "zelle"` and the enclave verify
+ * route is `zelle/transfer_zelle_{bank}`, so the bank never reaches the
+ * payment method. Deposits that attached bank-level methods accepted intents
+ * that no attestation could fulfil — they sat until they expired.
+ */
+describe('resolveRailProviderKey', () => {
+    it('collapses every Zelle bank to the rail', () => {
+        // The full set, not a sample: one bank left un-collapsed is one bank whose
+        // deposits silently strand every intent signalled against them.
+        for (const bank of Object.values(subProviders)) {
+            assert.equal(resolveRailProviderKey(bank), providers.ZELLE);
+        }
+    });
+    it('leaves rails that have no banks untouched', () => {
+        assert.equal(resolveRailProviderKey(providers.VENMO), 'venmo');
+        assert.equal(resolveRailProviderKey(providers.CASHAPP), 'cashapp');
+        assert.equal(resolveRailProviderKey(providers.ZELLE), 'zelle');
+    });
+    it('is idempotent, so applying it twice cannot drift', () => {
+        // Call sites apply it at the write boundary; a second application (say a
+        // caller that already normalized) must be a no-op.
+        assert.equal(resolveRailProviderKey(resolveRailProviderKey('zelle-chase')), resolveRailProviderKey('zelle-chase'));
+    });
+    it('maps the rail key to the payment method id registered on-chain', () => {
+        // Pins the migration target: keccak256("zelle"). If this changes, deposits
+        // would be attaching a method the registry does not route.
+        assert.equal(providerKeyToContractId(resolveRailProviderKey('zelle-bofa')), '0xf752c7d19698ecb0bb8988abf9b9a53a4c3657f3bc8850a6fb59fdf3e3ce8cd3');
+    });
+});
 /**
  * Tests for providerConfigs - payment provider configuration
  */
@@ -317,11 +349,11 @@ describe('providerConfigs', () => {
 /**
  * Tests for {@link getProviderPaymentMethodIds}.
  *
- * The contract uniqueness predicate is `paymentMethodId = keccak(providerKey)`,
- * and providers with sub-providers (currently only Zelle) fan out into one
- * row per sub-provider — the parent key itself is NOT submitted on-chain.
- * The helper has to mirror that fan-out exactly or the availability check
- * downstream will be wrong.
+ * The contract uniqueness predicate is `paymentMethodId = keccak(providerKey)`.
+ * This helper must return exactly the ids the write submits — one per rail —
+ * so the availability check downstream asks the same question the contract
+ * will. It used to fan a parent out into one id per sub-provider, matching a
+ * submission that no longer happens.
  */
 describe('getProviderPaymentMethodIds', () => {
     const configs = providerConfigs(base.id);
@@ -331,17 +363,19 @@ describe('getProviderPaymentMethodIds', () => {
         assert.equal(ids.length, 1);
         assert.equal(ids[0], expected);
     });
-    it('returns ONLY sub-provider contractIds for a parent with sub-providers (not the parent itself)', () => {
-        // Zelle's parent key is NOT whitelisted on-chain — only sub-providers
-        // are. Submitting the parent would revert with `PaymentMethodNotWhitelisted`,
-        // so it must not be in the returned list.
+    it('returns ONLY the rail id for a parent with sub-providers, never the banks', () => {
+        // A Zelle attestation is issued for the rail, so `keccak256("zelle")` is
+        // the only method a Zelle payment can satisfy — and the only one
+        // AddPlatformModal / ProveXClient put on the wire. Returning the bank ids
+        // here made the availability gate answer a question the contract never
+        // asks: a deposit already holding `zelle` collided with none of them, so
+        // Zelle kept looking addable and the re-add reverted.
         const ids = getProviderPaymentMethodIds(configs.zelle);
-        const parentId = providerKeyToContractId('zelle').toLowerCase();
-        assert.ok(!ids.includes(parentId), 'zelle parent contractId must NOT be in the fan-out list');
-        const expectedSubIds = Object.values(subProviders).map(k => providerKeyToContractId(k).toLowerCase());
-        assert.equal(ids.length, expectedSubIds.length);
-        for (const subId of expectedSubIds) {
-            assert.ok(ids.includes(subId), `expected sub-provider contractId ${subId} in fan-out list`);
+        const railId = providerKeyToContractId('zelle').toLowerCase();
+        assert.deepEqual(ids, [railId]);
+        for (const subKey of Object.values(subProviders)) {
+            const subId = providerKeyToContractId(subKey).toLowerCase();
+            assert.ok(!ids.includes(subId), `bank contractId ${subId} must NOT be returned`);
         }
     });
     it('returns lowercased hex (downstream comparison is case-sensitive)', () => {
@@ -408,45 +442,33 @@ describe('computeProviderAvailability', () => {
         assert.ok(available.some(c => c.key === 'revolut'), 'revolut still available');
         assert.ok(available.some(c => c.key === 'zelle'), 'zelle still available (no sub collisions)');
     });
-    it('parent is unavailable when ONE sub-provider hash is in the attached set (Bug 2)', () => {
-        // Only zelle-chase is attached. Per the contract semantics — the modal
-        // submits ALL Zelle sub-providers in one batch and the first existing
-        // row makes the whole tx revert — the Zelle parent must be flagged
-        // unavailable.
-        const { available, unavailable } = computeProviderAvailability({
-            chainId,
-            attachedPaymentMethodIds: new Set([zelleChaseId]),
-        });
-        assert.ok(!available.some(c => c.key === 'zelle'), 'zelle parent must NOT be available');
-        assert.ok(unavailable.some(c => c.key === 'zelle'), 'zelle parent must be in unavailable');
-    });
-    it('parent is unavailable when ALL sub-providers are attached', () => {
-        // Every Zelle sub is attached. Parent must be unavailable.
+    it('Zelle is UNAVAILABLE once the rail hash is attached', () => {
+        // `keccak256("zelle")` is what the modal submits, so re-adding it reverts
+        // with `PaymentMethodAlreadyExists`. Missing this is what let a maker who
+        // had already added Zelle pick it again and watch the transaction fail.
         const { available, unavailable } = computeProviderAvailability({
-            chainId,
-            attachedPaymentMethodIds: new Set([zelleChaseId, zelleBofaId, zelleCitiId]),
-        });
-        assert.ok(!available.some(c => c.key === 'zelle'));
-        assert.ok(unavailable.some(c => c.key === 'zelle'));
-    });
-    it('parent is available when only the parent-key hash is in the set but no sub-providers are', () => {
-        // Defensive edge case — a malformed indexer row that stored the parent
-        // keccak hash rather than a sub-provider hash. The contract would also
-        // reject re-adding the parent hash, so we must treat the parent as
-        // unavailable here. This guards against the inverse of Bug 2 too: a
-        // future change that compares the parent's own contractId.
-        const { unavailable } = computeProviderAvailability({
             chainId,
             attachedPaymentMethodIds: new Set([zelleParentId]),
         });
-        // The parent's own contractId is in `getProviderPaymentMethodIds`
-        // ONLY for providers without sub-providers, so for Zelle (which has
-        // sub-providers) this attached id has no effect — Zelle stays
-        // available because the modal would only ever submit sub-provider
-        // hashes. This is the correct behavior: the contract row's
-        // paymentMethodId would never realistically be the parent for a Zelle
-        // deposit since the parent isn't whitelisted.
-        assert.ok(!unavailable.some(c => c.key === 'zelle'), 'zelle remains available — parent hash unused at submit time');
+        assert.ok(!available.some(c => c.key === 'zelle'), 'zelle must NOT be available');
+        assert.ok(unavailable.some(c => c.key === 'zelle'), 'zelle must be in unavailable');
+    });
+    it('Zelle stays AVAILABLE on a deposit carrying only legacy bank hashes', () => {
+        // The migration case, and the reason this must not fan out. A deposit
+        // holding only `zelle-chase` can never have its intents fulfilled — the
+        // attestation names the rail. Attaching `zelle` is the repair, and the
+        // contract permits it (different hash), so the gate must offer it.
+        for (const attached of [
+            new Set([zelleChaseId]),
+            new Set([zelleChaseId, zelleBofaId, zelleCitiId]),
+        ]) {
+            const { available, unavailable } = computeProviderAvailability({
+                chainId,
+                attachedPaymentMethodIds: attached,
+            });
+            assert.ok(available.some(c => c.key === 'zelle'), 'zelle must remain available for migration');
+            assert.ok(!unavailable.some(c => c.key === 'zelle'), 'zelle must NOT be marked unavailable');
+        }
     });
     it('marks a deactivated provider as unavailable when its hash is in the attached set (Bug 1)', () => {
         // The contract's `setPaymentMethodActive(false)` does NOT remove the

package/dist/rateInput.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Parsing, keystroke handling and plausibility checks for
+ * maker-entered conversion rates.
+ *
+ * ## Why this module exists
+ *
+ * A conversion rate is typed as text and stored on chain as an 18-decimal
+ * bigint. Ten production deposits were created with rates inflated by exactly
+ * `10 ** (decimal places typed)` — `1.029` became `1029`, `1.15` became `115`,
+ * `1.2` became `12` — because the deposit-creation form held the rate in
+ * component state as a bigint and re-derived the displayed text from it on
+ * every keystroke. The half-finished string `"1."` parses to the same bigint as
+ * `"1"`, so the formatter rendered it back as `"1"` and the decimal separator
+ * the maker had just typed was erased. Every later digit then landed in the
+ * whole-number part.
+ *
+ * Three deposits are still live on PulseChain priced a thousand times above
+ * market, which no buyer will ever fill.
+ *
+ * ## The rule this module enforces
+ *
+ * The maker's raw text is the single source of truth while editing, and it is
+ * converted to a bigint exactly once, at submit. Nothing re-derives the text
+ * from the number. {@link nextRateInputValue} is the whole of the editing
+ * transition, and it is a pure string-to-string function precisely so that
+ * "type it one character at a time" and "paste it in one go" cannot diverge —
+ * see the fuzz tests in `rateInput.test.ts`, which assert that equivalence over
+ * generated input.
+ *
+ * ## Separator policy
+ *
+ * Digits and a single separator are accepted, and **every separator is a
+ * decimal separator**. A comma is normalised to a period, so a maker on a
+ * locale that writes `0,978` and one that writes `0.978` both get 0.978.
+ * Group separators are deliberately *not* accepted: a rate never needs
+ * grouping to be typed, and accepting it reintroduces the exact ambiguity that
+ * makes `1,029` unreadable — one thousand and twenty-nine, or one point oh two
+ * nine? Rejecting is safe because it is loud; guessing is not.
+ *
+ * @see {@link parseRateInput} for the text-to-bigint conversion
+ * @see {@link nextRateInputValue} for the editing transition
+ */
+/**
+ * Decimal places a conversion rate carries on chain. Rates are always
+ * 18-decimal fixed point regardless of the fiat currency's own precision — the
+ * currency's `decimals` field describes how the rate is *displayed*, never how
+ * it is stored.
+ */
+export declare const RATE_DECIMALS = 18;
+/**
+ * Why a candidate rate could not be turned into a bigint.
+ *
+ * - `empty` — nothing was entered
+ * - `unsupportedCharacter` — something other than a digit or separator
+ * - `multipleDecimalSeparators` — more than one separator, so the intended
+ *   value is ambiguous
+ * - `missingDigits` — a bare separator with no digits either side
+ * - `tooManyDecimalPlaces` — more precision than 18 decimals can carry
+ * - `notPositive` — parsed to zero; a deposit priced at zero cannot trade
+ */
+export type RateParseFailureReason = 'empty' | 'unsupportedCharacter' | 'multipleDecimalSeparators' | 'missingDigits' | 'tooManyDecimalPlaces' | 'notPositive';
+/**
+ * Outcome of converting maker-entered text into an on-chain rate. A
+ * discriminated union so callers cannot read `value` without having checked
+ * that parsing succeeded.
+ */
+export type RateParseResult = {
+    readonly status: 'parsed';
+    /** The rate as an 18-decimal bigint, ready for the escrow call. */
+    readonly value: bigint;
+    /** The same value as unambiguous `whole.fractional` text. */
+    readonly canonicalText: string;
+} | {
+    readonly status: 'failed';
+    readonly reason: RateParseFailureReason;
+};
+/**
+ * Normalise a candidate rate string, or reject it.
+ *
+ * Accepts a partially-typed value — `''`, `'1'`, `'1.'` and `'1.0'` are all
+ * legal states on the way to `'1.02'` — because this runs on every keystroke.
+ * Completeness is checked at submit by {@link parseRateInput}, not here.
+ *
+ * @param candidate - Text the input element now holds
+ * @returns The candidate with any comma rewritten to a period, or `null` if it
+ *   is not a legal partial rate
+ *
+ * @example
+ * ```ts
+ * normalizeRateInput('1,029')  // '1.029'  — comma is a decimal separator
+ * normalizeRateInput('1.')     // '1.'     — legal mid-typing
+ * normalizeRateInput('1.2.3')  // null     — ambiguous
+ * normalizeRateInput('1e3')    // null     — not a digit or separator
+ * ```
+ */
+export declare const normalizeRateInput: (candidate: string) => string | null;
+/**
+ * Next value of the rate field, given the text the input element now holds.
+ *
+ * This is the entire editing transition. It is pure and string-to-string: the
+ * value is never routed through a bigint and back, which is what erased the
+ * decimal separator and inflated ten production deposits. An illegal candidate
+ * leaves the field on its previous value, which is how a keystroke is refused.
+ *
+ * @param options - Current field value and the candidate replacing it
+ * @returns The value the field should now hold
+ *
+ * @example
+ * ```ts
+ * nextRateInputValue({ current: '1', candidate: '1,' })    // '1.'
+ * nextRateInputValue({ current: '1.2', candidate: '1.2.' }) // '1.2' — refused
+ * ```
+ */
+export declare const nextRateInputValue: ({ current, candidate }: {
+    current: string;
+    candidate: string;
+}) => string;
+/**
+ * Convert maker-entered rate text into an 18-decimal bigint.
+ *
+ * Call this once, at submit. Calling it on every keystroke and rendering the
+ * result back into the field is the defect this module exists to prevent.
+ *
+ * @param candidate - Raw text the maker entered
+ * @returns Parsed rate, or the reason it could not be parsed
+ *
+ * @example
+ * ```ts
+ * parseRateInput('0.978')  // { status: 'parsed', value: 978000000000000000n, ... }
+ * parseRateInput('0,978')  // identical — comma is a decimal separator
+ * parseRateInput('978')    // { status: 'parsed', value: 978000000000000000000n, ... }
+ * parseRateInput('')       // { status: 'failed', reason: 'empty' }
+ * ```
+ */
+export declare const parseRateInput: (candidate: string) => RateParseResult;
+/**
+ * Rates at or above this many fiat units per token are held back for the maker
+ * to confirm.
+ *
+ * This is a deliberately crude backstop, not a market check. It exists because
+ * every rate corrupted in production landed far above it (12, 115, 978, 1020,
+ * 1029, 1099) while every legitimate rate observed on chain sat near 1 — the
+ * highest genuine one being roughly 18, for Mexican pesos. A handful of
+ * currencies do trade in the thousands per dollar, so this asks rather than
+ * refuses; the maker can confirm and proceed.
+ */
+export declare const RATE_CONFIRMATION_THRESHOLD: bigint;
+/**
+ * Whether a parsed rate is large enough that the maker should confirm it before
+ * the deposit is created.
+ *
+ * @param options - The parsed rate, as an 18-decimal bigint
+ * @returns `true` when the rate warrants an explicit confirmation
+ *
+ * @example
+ * ```ts
+ * needsRateConfirmation({ value: parseUnits('1.029', 18) })  // false
+ * needsRateConfirmation({ value: parseUnits('1029', 18) })   // true
+ * ```
+ */
+export declare const needsRateConfirmation: ({ value }: {
+    value: bigint;
+}) => boolean;