@provex/utils 1.6.2 → 1.7.0-rc.20260522201545.020a3eb

package/dist/payment.d.ts

@@ -17,7 +17,7 @@
  * - Low risk (Revolut, Wise, Monzo, MercadoPago): 5x cap multiplier, no cooldown
  * - Medium risk (Zelle): 1.5x cap multiplier, cooldown applies
  * - High risk (Venmo, CashApp): 1x cap multiplier, cooldown applies
- * - Highest risk (PayPal): 0.75x cap multiplier, requires Peer Plus tier
+ * - Highest risk (PayPal): 0.75x cap multiplier, requires Plus tier or higher
  *
  * @see {@link reputation} for tier system
  * @see {@link currencies} for supported currencies per provider
@@ -155,7 +155,15 @@ export type Limits = {
 /** Send link options */
 export type SendLinkOptions = {
     username: string;
-    amount: bigint;
+    /**
+     * Fiat amount, formatted as a decimal string (e.g. `"1.00"`, `"100.50"`),
+     * suitable for inlining directly into a payment-provider URL's `amount`
+     * query parameter. Providers that pre-fill amount fields (Venmo today)
+     * expect a dollar-units number, NOT token base units. The caller is
+     * responsible for converting from on-chain token amounts via
+     * `convertTokenInputToCurrency` + `formatUnits` before passing this in.
+     */
+    amount: string;
     subProvider?: SubProviderKey;
     qrCode?: boolean;
 };
@@ -177,6 +185,8 @@ export type PaymentSubProviderConfig = {
      * e.g., 'zelle-chase' -> 'chase', 'zelle-bofa' -> 'bofa'
      */
     extensionPlatform: ExtensionPlatformKey;
+    /** Whether the extension sends amounts as integer cents. Defaults to false (dollar decimal). */
+    amountInCents?: boolean;
 };
 /** Payment config */
 export type PaymentConfig = {
@@ -431,6 +441,58 @@ export declare const getAllPaymentMethods: (chainId: ChainId, includeSubProvider
  * @returns All verifiable payment methods
  */
 export declare const verifiablePaymentMethods: (chainId: ChainId, includeSubProviders?: boolean) => ProviderKey[];
+/**
+ * Compute every payment-method id (lowercased, 32-byte keccak hex) that
+ * attaching the given parent provider would attempt to register on a deposit.
+ *
+ * For a provider with no sub-providers this is just `[providerKeyToContractId(key)]`.
+ * For a provider with sub-providers (currently only Zelle), the contract does
+ * NOT accept the parent key — the UI fans it out into one row per sub-provider.
+ * The returned list mirrors what {@link providerConfigs}-driven submission
+ * code (e.g. AddPlatformModal) would put on the wire.
+ *
+ * Keys are lowercased so callers can compare directly against
+ * `Deposit.attachedPaymentMethodIds` without per-call normalization.
+ */
+export declare function getProviderPaymentMethodIds(config: PaymentConfig): string[];
+/**
+ * Args for {@link computeProviderAvailability} and {@link availableProviderConfigs}.
+ */
+export interface ProviderAvailabilityArgs {
+    chainId: ChainId;
+    /**
+     * Lowercased hex of every `paymentMethodId` already attached to the deposit
+     * (active OR inactive). Source from {@link Deposit.attachedPaymentMethodIds}.
+     * The contract reverts on re-add of any hash in this set, so even inactive
+     * rows count as unavailable.
+     */
+    attachedPaymentMethodIds: Set<string>;
+}
+/**
+ * Decide, for every non-manual non-disabled provider on `chainId`, whether
+ * it can still be attached to a deposit given the deposit's already-attached
+ * payment method id hashes.
+ *
+ * Important — a parent provider is unavailable if ANY of its candidate hashes
+ * (own contractId plus every sub-provider's contractId) is already attached.
+ * This matches the contract's atomicity: `addPaymentMethods` submits the full
+ * fan-out in one transaction and reverts with `PaymentMethodAlreadyExists`
+ * the moment one row collides. A maker who already has Zelle-Chase attached
+ * cannot re-add the Zelle parent without colliding on the Chase sub-row.
+ *
+ * `manual` is always excluded from both lists.
+ */
+export declare function computeProviderAvailability(args: ProviderAvailabilityArgs): {
+    available: PaymentConfig[];
+    unavailable: PaymentConfig[];
+};
+/**
+ * Convenience wrapper around {@link computeProviderAvailability} that returns
+ * only the available list. Use this on call sites that don't need the
+ * unavailable set (e.g. counting providers remaining to gate an Add Platform
+ * button).
+ */
+export declare function availableProviderConfigs(args: ProviderAvailabilityArgs): PaymentConfig[];
 /**
  * Get supported currencies for a payment provider.
  * Returns only the currencies that are in the provider's supported list.

package/dist/payment.js

@@ -17,7 +17,7 @@
  * - Low risk (Revolut, Wise, Monzo, MercadoPago): 5x cap multiplier, no cooldown
  * - Medium risk (Zelle): 1.5x cap multiplier, cooldown applies
  * - High risk (Venmo, CashApp): 1x cap multiplier, cooldown applies
- * - Highest risk (PayPal): 0.75x cap multiplier, requires Peer Plus tier
+ * - Highest risk (PayPal): 0.75x cap multiplier, requires Plus tier or higher
  *
  * @see {@link reputation} for tier system
  * @see {@link currencies} for supported currencies per provider
@@ -587,8 +587,11 @@ export const providerConfigs = (chainId) => {
                 SUPPORTED_CURRENCIES.EUR.contractId,
             ],
             color: '#088177',
+            // Aligned to peer's medium-risk pattern (1.5x cap multiplier, has
+            // cooldown, no min tier) — matches the `medium` riskLevel label.
+            // Previously sat at 1x, which is peer's high-risk multiplier.
             riskLevel: 'medium',
-            capMultiplier: 1,
+            capMultiplier: 1.5,
             hasCooldown: true,
             minimumTier: null,
             disabled: true,
@@ -645,8 +648,11 @@ export const providerConfigs = (chainId) => {
                 SUPPORTED_CURRENCIES.USD.contractId,
             ],
             color: '#1EC677',
+            // Aligned to peer's medium-risk pattern (1.5x cap multiplier, has
+            // cooldown, no min tier) — matches the `medium` riskLevel label.
+            // Previously sat at 1x, which is peer's high-risk multiplier.
             riskLevel: 'medium',
-            capMultiplier: 1,
+            capMultiplier: 1.5,
             hasCooldown: true,
             minimumTier: null,
             disabled: true,
@@ -668,8 +674,11 @@ export const providerConfigs = (chainId) => {
                 SUPPORTED_CURRENCIES.CAD.contractId,
             ],
             color: '#4A5568',
+            // Aligned to peer's medium-risk pattern (1.5x cap multiplier, has
+            // cooldown, no min tier) — matches the `medium` riskLevel label.
+            // Previously sat at 1x, which is peer's high-risk multiplier.
             riskLevel: 'medium',
-            capMultiplier: 1,
+            capMultiplier: 1.5,
             hasCooldown: true,
             minimumTier: null,
             disabled: true,
@@ -691,8 +700,11 @@ export const providerConfigs = (chainId) => {
                 SUPPORTED_CURRENCIES.INR.contractId,
             ],
             color: '#2D3748',
+            // Aligned to peer's medium-risk pattern (1.5x cap multiplier, has
+            // cooldown, no min tier) — matches the `medium` riskLevel label.
+            // Previously sat at 1x, which is peer's high-risk multiplier.
             riskLevel: 'medium',
-            capMultiplier: 1,
+            capMultiplier: 1.5,
             hasCooldown: true,
             minimumTier: null,
             disabled: true,
@@ -1048,6 +1060,69 @@ export const getAllPaymentMethods = (chainId, includeSubProviders = false) => {
 export const verifiablePaymentMethods = (chainId, includeSubProviders = false) => {
     return getAllPaymentMethods(chainId, includeSubProviders).filter(key => key !== providers.MANUAL);
 };
+/**
+ * Compute every payment-method id (lowercased, 32-byte keccak hex) that
+ * attaching the given parent provider would attempt to register on a deposit.
+ *
+ * For a provider with no sub-providers this is just `[providerKeyToContractId(key)]`.
+ * For a provider with sub-providers (currently only Zelle), the contract does
+ * NOT accept the parent key — the UI fans it out into one row per sub-provider.
+ * The returned list mirrors what {@link providerConfigs}-driven submission
+ * code (e.g. AddPlatformModal) would put on the wire.
+ *
+ * Keys are lowercased so callers can compare directly against
+ * `Deposit.attachedPaymentMethodIds` without per-call normalization.
+ */
+export function getProviderPaymentMethodIds(config) {
+    const subProviders = config.subProviders;
+    if (subProviders && subProviders.size > 0) {
+        return Array.from(subProviders).map(sub => providerKeyToContractId(sub.key).toLowerCase());
+    }
+    return [providerKeyToContractId(config.key).toLowerCase()];
+}
+/**
+ * Decide, for every non-manual non-disabled provider on `chainId`, whether
+ * it can still be attached to a deposit given the deposit's already-attached
+ * payment method id hashes.
+ *
+ * Important — a parent provider is unavailable if ANY of its candidate hashes
+ * (own contractId plus every sub-provider's contractId) is already attached.
+ * This matches the contract's atomicity: `addPaymentMethods` submits the full
+ * fan-out in one transaction and reverts with `PaymentMethodAlreadyExists`
+ * the moment one row collides. A maker who already has Zelle-Chase attached
+ * cannot re-add the Zelle parent without colliding on the Chase sub-row.
+ *
+ * `manual` is always excluded from both lists.
+ */
+export function computeProviderAvailability(args) {
+    const configs = providerConfigs(args.chainId);
+    const available = [];
+    const unavailable = [];
+    for (const config of Object.values(configs)) {
+        if (config.key === providers.MANUAL)
+            continue;
+        if (isProviderDisabled(config.key, config.disabled))
+            continue;
+        const candidateIds = getProviderPaymentMethodIds(config);
+        const collides = candidateIds.some(id => args.attachedPaymentMethodIds.has(id));
+        if (collides) {
+            unavailable.push(config);
+        }
+        else {
+            available.push(config);
+        }
+    }
+    return { available, unavailable };
+}
+/**
+ * Convenience wrapper around {@link computeProviderAvailability} that returns
+ * only the available list. Use this on call sites that don't need the
+ * unavailable set (e.g. counting providers remaining to gate an Add Platform
+ * button).
+ */
+export function availableProviderConfigs(args) {
+    return computeProviderAvailability(args).available;
+}
 /**
  * Get supported currencies for a payment provider.
  * Returns only the currencies that are in the provider's supported list.

package/dist/payment.test.js

@@ -1,7 +1,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { base } from 'viem/chains';
-import { providerConfigs, getCurrenciesForProvider, verifierGetsKey, providerKeyToContractId, resolveApiProviderKey } from './payment.js';
+import { providerConfigs, getCurrenciesForProvider, providers, verifierGetsKey, providerKeyToContractId, resolveApiProviderKey, getProviderPaymentMethodIds, computeProviderAvailability, availableProviderConfigs, subProviders } from './payment.js';
 import { SUPPORTED_CURRENCIES } from './currencies.js';
 describe('getCurrenciesForProvider', () => {
     const configs = providerConfigs(base.id);
@@ -210,33 +210,44 @@ describe('providerConfigs', () => {
     const configs = providerConfigs(base.id);
     describe('sendLink functions', () => {
         it('venmo sendLink generates correct URL without QR code', () => {
-            const result = configs.venmo.sendLink?.({ username: 'testuser', amount: 100n });
+            const result = configs.venmo.sendLink?.({ username: 'testuser', amount: '100.00' });
             assert.ok(result?.includes('account.venmo.com/pay'), 'Should use web URL');
             assert.ok(result?.includes('testuser'), 'Should include username');
-            assert.ok(result?.includes('100'), 'Should include amount');
+            assert.ok(result?.includes('amount=100.00'), 'Should pass through the formatted fiat amount verbatim');
         });
         it('venmo sendLink generates correct URL with QR code', () => {
-            const result = configs.venmo.sendLink?.({ username: 'testuser', amount: 100n, qrCode: true });
+            const result = configs.venmo.sendLink?.({ username: 'testuser', amount: '100.00', qrCode: true });
             assert.ok(result?.startsWith('venmo://'), 'Should use venmo:// protocol');
+            assert.ok(result?.includes('amount=100.00'), 'Should pass through the formatted fiat amount verbatim');
+        });
+        it('venmo sendLink rejects a numeric (bigint base-unit) amount via type system', () => {
+            // Regression: previous signature was `amount: bigint`, and callers
+            // passed `intent.amount` (USDC base units, e.g. 1_000000n for $1).
+            // The URL templated literally as `amount=1000000`, which Venmo
+            // interpreted as $1,000,000. This assertion exists as a sentinel
+            // that the formatted-string path is the supported contract.
+            const result = configs.venmo.sendLink?.({ username: 'testuser', amount: '1.00' });
+            assert.ok(result?.includes('amount=1.00'), 'Fiat string should pass through unchanged');
+            assert.ok(!result?.includes('amount=1000000'), 'Token base units must never appear in the URL');
         });
         it('cashapp sendLink generates correct URL', () => {
-            const result = configs.cashapp.sendLink?.({ username: '$testuser', amount: 100n });
+            const result = configs.cashapp.sendLink?.({ username: '$testuser', amount: '100.00' });
             assert.ok(result?.includes('cash.app'), 'Should use cash.app URL');
         });
         it('cashapp sendLink handles username without $ prefix', () => {
-            const result = configs.cashapp.sendLink?.({ username: 'testuser', amount: 100n });
+            const result = configs.cashapp.sendLink?.({ username: 'testuser', amount: '100.00' });
             assert.ok(result?.includes('$testuser'), 'Should add $ prefix to username');
         });
         it('revolut sendLink generates correct URL', () => {
-            const result = configs.revolut.sendLink?.({ username: 'testuser', amount: 100n });
+            const result = configs.revolut.sendLink?.({ username: 'testuser', amount: '100.00' });
             assert.ok(result?.includes('revolut.me'), 'Should use revolut.me URL');
         });
         it('wise sendLink generates correct URL', () => {
-            const result = configs.wise.sendLink?.({ username: 'testuser', amount: 100n });
+            const result = configs.wise.sendLink?.({ username: 'testuser', amount: '100.00' });
             assert.ok(result?.includes('wise.com/pay/me'), 'Should use wise.com URL');
         });
         it('mercadopago sendLink generates correct URL', () => {
-            const result = configs.mercadopago.sendLink?.({ username: 'testuser', amount: 100n });
+            const result = configs.mercadopago.sendLink?.({ username: 'testuser', amount: '100.00' });
             assert.ok(result?.includes('mercadopago.com'), 'Should use mercadopago URL');
         });
         // PayPal sendLink tests removed — provider disabled
@@ -300,3 +311,195 @@ 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.
+ */
+describe('getProviderPaymentMethodIds', () => {
+    const configs = providerConfigs(base.id);
+    it('returns the parent contractId (lowercased) for a provider with no sub-providers', () => {
+        const ids = getProviderPaymentMethodIds(configs.venmo);
+        const expected = providerKeyToContractId('venmo').toLowerCase();
+        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.
+        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`);
+        }
+    });
+    it('returns lowercased hex (downstream comparison is case-sensitive)', () => {
+        // `Deposit.attachedPaymentMethodIds` is lowercased; the comparator at the
+        // call site does no extra normalization. If this helper ever returns
+        // mixed case we'd silently start treating "already attached" rows as
+        // available — the worst kind of regression.
+        const ids = getProviderPaymentMethodIds(configs.revolut);
+        for (const id of ids) {
+            assert.equal(id, id.toLowerCase(), `id ${id} must be lowercased`);
+        }
+    });
+});
+/**
+ * Tests for {@link computeProviderAvailability} / {@link availableProviderConfigs}.
+ *
+ * These map directly to the bugs the user reported:
+ *
+ *   Bug 1 — "active-only" wrongly counted deactivated providers as
+ *           available. Fix verified by `marks a deactivated provider as
+ *           unavailable when its hash is in the attached set`.
+ *
+ *   Bug 2 — parent provider was wrongly available when only sub-providers
+ *           collided. Fix verified by `parent is unavailable when ANY
+ *           sub-provider hash is in the attached set` + the variants
+ *           below.
+ *
+ *   Bug 3 — UI gate. Verified by the empty-list case
+ *           (`returns empty available list when every supported provider is
+ *           attached`).
+ */
+describe('computeProviderAvailability', () => {
+    const chainId = base.id;
+    const configs = providerConfigs(chainId);
+    const venmoId = providerKeyToContractId('venmo').toLowerCase();
+    const zelleParentId = providerKeyToContractId('zelle').toLowerCase();
+    const zelleChaseId = providerKeyToContractId('zelle-chase').toLowerCase();
+    const zelleBofaId = providerKeyToContractId('zelle-bofa').toLowerCase();
+    const zelleCitiId = providerKeyToContractId('zelle-citi').toLowerCase();
+    const revolutId = providerKeyToContractId('revolut').toLowerCase();
+    it('deposit with no providers attached: every non-disabled provider is available', () => {
+        const { available, unavailable } = computeProviderAvailability({
+            chainId,
+            attachedPaymentMethodIds: new Set(),
+        });
+        assert.equal(unavailable.length, 0);
+        // Every non-manual, non-disabled provider should be available. The
+        // exact count depends on `disabled` flags and env-var overrides; just
+        // check that the parent providers we DO ship come through.
+        const keys = available.map(c => c.key);
+        assert.ok(keys.includes('venmo'), 'venmo should be available');
+        assert.ok(keys.includes('zelle'), 'zelle should be available');
+        assert.ok(keys.includes('revolut'), 'revolut should be available');
+        // manual must NEVER be in the available list.
+        assert.ok(!keys.includes('manual'), 'manual must never be offered');
+    });
+    it('deposit with one parent attached: that parent is unavailable, others remain available', () => {
+        const { available, unavailable } = computeProviderAvailability({
+            chainId,
+            attachedPaymentMethodIds: new Set([venmoId]),
+        });
+        assert.ok(!available.some(c => c.key === 'venmo'), 'venmo must NOT be in available');
+        assert.ok(unavailable.some(c => c.key === 'venmo'), 'venmo must be in unavailable');
+        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.
+        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');
+    });
+    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
+        // depositVerifierAdded row; the paymentMethodId stays attached and
+        // re-adding it reverts. So even an attached set sourced from
+        // inactive-included rows must drive this provider out of `available`.
+        const { available, unavailable } = computeProviderAvailability({
+            chainId,
+            attachedPaymentMethodIds: new Set([revolutId]),
+        });
+        assert.ok(!available.some(c => c.key === 'revolut'));
+        assert.ok(unavailable.some(c => c.key === 'revolut'));
+    });
+    it('returns empty available list when every supported provider is attached (Bug 3 gate)', () => {
+        // Build attached set from EVERY non-disabled provider's payment method
+        // ids (using getProviderPaymentMethodIds so the fan-out is correct for
+        // sub-providered parents).
+        const allAttached = new Set();
+        for (const config of Object.values(configs)) {
+            if (config.key === providers.MANUAL)
+                continue;
+            for (const id of getProviderPaymentMethodIds(config)) {
+                allAttached.add(id);
+            }
+        }
+        const result = computeProviderAvailability({ chainId, attachedPaymentMethodIds: allAttached });
+        assert.equal(result.available.length, 0, `available should be empty, got ${result.available.map(c => c.key).join(',')}`);
+        // unavailable should contain at least the visible non-disabled set
+        assert.ok(result.unavailable.length > 0);
+    });
+    it('availableProviderConfigs is a thin wrapper that returns only the available list', () => {
+        const both = computeProviderAvailability({
+            chainId,
+            attachedPaymentMethodIds: new Set([venmoId]),
+        });
+        const wrapped = availableProviderConfigs({
+            chainId,
+            attachedPaymentMethodIds: new Set([venmoId]),
+        });
+        assert.deepEqual(wrapped.map(c => c.key), both.available.map(c => c.key));
+    });
+    it('excludes the manual provider regardless of attached set', () => {
+        // manual is always excluded — adding it has no meaning in the UX. This
+        // is true for every input.
+        const cases = [
+            new Set(),
+            new Set([venmoId]),
+            new Set([zelleChaseId, revolutId]),
+        ];
+        for (const attached of cases) {
+            const { available, unavailable } = computeProviderAvailability({
+                chainId,
+                attachedPaymentMethodIds: attached,
+            });
+            assert.ok(!available.some(c => c.key === 'manual'), 'manual must not be in available');
+            assert.ok(!unavailable.some(c => c.key === 'manual'), 'manual must not be in unavailable');
+        }
+    });
+});

package/dist/reputation.d.ts

@@ -9,22 +9,27 @@
  * - **Platform risk configs**: Multipliers and cooldown flags from payment.ts
  *
  * @remarks
- * These limits only apply to Base chain deposits using the peer gating service.
- * Pulsechain deposits do not have reputation-based restrictions.
+ * Reputation is now scored from PulseChain volume only — Base data is no
+ * longer aggregated. The taker cap still varies by tier; PulseChain is the
+ * only chain that produces taker-tier-influencing volume.
  *
- * Tier progression (by fulfilled volume in USD):
- * - Peer Peasant: $0+ → $100 cap, 12h cooldown
- * - Peer: $500+ → $250 cap, 6h cooldown
- * - Peer Plus: $2,000+ → $1,000 cap, no cooldown
- * - Peer Pro: $10,000+ → $2,500 cap, no cooldown
- * - Peer Platinum: $25,000+ → $5,000 cap, no cooldown
- * - Peer President: Manually assigned VIP → unlimited cap, no cooldown, bypasses all locks
+ * Tier progression (by CUMULATIVE / lifetime fulfilled volume in USD).
+ * Thresholds mirror peer.xyz's published ladder
+ * (https://docs.peer.xyz/guides/for-buyers/reputation#the-five-tiers).
+ * Volume is NOT windowed — it accumulates over the user's lifetime, so
+ * a user only ever moves UP the ladder, never back down for inactivity:
+ * - Entry:    $0+       → $100 cap,   12h cooldown
+ * - Neutral:  $500+     → $250 cap,   6h cooldown
+ * - Plus:     $2,000+   → $1,000 cap, no cooldown
+ * - Pro:      $10,000+  → $2,500 cap, no cooldown
+ * - Platinum: $25,000+  → $5,000 cap, no cooldown
+ * - VIP:      Manually assigned → unlimited cap, no cooldown, bypasses all locks
  *
  * Platform multipliers modify the base cap:
  * - Low risk (Revolut, Wise, Monzo, MercadoPago): 5x multiplier, no cooldown
  * - Medium risk (Zelle): 1.5x multiplier
  * - High risk (Venmo, CashApp): 1x multiplier
- * - Highest risk (PayPal): 0.75x multiplier, requires Peer Plus tier
+ * - Highest risk (PayPal): 0.75x multiplier, requires Plus tier or higher
  *
  * @see {@link payment} for platform risk configurations
  */
@@ -42,7 +47,7 @@ export interface TierConfig {
     baseCap: number;
     /** Cooldown duration in hours (0 = no cooldown) */
     cooldownHours: number;
-    /** Volume range display text (e.g. "$500 - $2k") */
+    /** Volume range display text (e.g. "$200 - $1k") */
     volumeRangeDisplay: string;
 }
 /**
@@ -50,8 +55,13 @@ export interface TierConfig {
  * Maps universal tier names to their configuration.
  *
  * @remarks
- * Tier names in the codebase use short universal names (peasant, neutral, plus, pro, platinum, president)
- * while the UI displays the peer brand names (Peer Peasant, Peer, Peer Plus, etc.)
+ * Internal tier keys (peasant / neutral / plus / pro / platinum / president)
+ * are stable data identifiers and DO NOT change — the indexer, the contract
+ * gating service, and persisted user state all key on them. The `name` field
+ * below is the user-facing display name; we use a neutral progression ladder
+ * (Entry / Neutral / Plus / Pro / Platinum / VIP) rather than peer.xyz's
+ * brand voice ("Peer Peasant" etc.), which is theirs and reads as gentle
+ * hazing of low-volume users — not the tone Provex wants.
  */
 export declare const TAKER_TIERS: Record<TakerTier, TierConfig>;
 /**
@@ -64,23 +74,52 @@ export declare const TIER_ORDER: TakerTier[];
  * Matches peer.xyz's TR() function behaviour.
  *
  * @example
- * getVolumeRangeDisplay('pro')    // "$10k - $25k"
+ * getVolumeRangeDisplay('pro')    // "$5k - $10k"
  * getVolumeRangeDisplay('president') // "VIP"
  */
 export declare function getVolumeRangeDisplay(tier: TakerTier): string;
 /**
- * Calculate the effective cap for a tier and platform combination.
- * Derives from tier base cap and platform risk multiplier.
+ * Sentinel cap value used in place of `Infinity` (which has no bigint
+ * representation) to signal "no upper limit" — president tier on every
+ * platform. Equal to `2n ** 256n - 1n` (max uint256); no realistic
+ * token amount can exceed it, so the standard `amount > cap` comparison
+ * naturally short-circuits to false for unlimited users.
+ *
+ * Callers that render the cap as a string MUST check for this sentinel
+ * before formatting — `Number(UNLIMITED_CAP_BASE_UNITS)` overflows to
+ * `Infinity` but `.toLocaleString()` on the bigint prints a 78-digit
+ * number that is not useful in a UI.
+ */
+export declare const UNLIMITED_CAP_BASE_UNITS: bigint;
+/**
+ * Calculate the effective cap for a tier and platform combination, in
+ * token base units (scaled by `decimals`). Designed so the caller can
+ * compare directly against a token amount it already holds as a bigint
+ * — no rebasing from USD floats on the consumer side.
+ *
+ * Assumes the token trades 1:1 with USD (USDC, USDT, DAI). When we add
+ * a non-stablecoin token this function needs a price feed or the caller
+ * needs to convert before comparing.
  *
  * @param tier - The user's current tier
  * @param providerKey - The payment platform
- * @returns Effective cap in USD, null if platform is locked for this tier,
- *          or Infinity if the user is president (no cap).
+ * @param decimals - Token decimals (USDC = 6, an 18-decimal stable = 18)
+ * @returns Effective cap in token base units, or:
+ *   - `null` — platform is locked at this tier
+ *   - `UNLIMITED_CAP_BASE_UNITS` — president tier (no cap enforcement)
  */
-export declare function getEffectiveCap({ tier, providerKey, }: {
+export declare function getEffectiveCap({ tier, providerKey, decimals, }: {
     tier: TakerTier;
     providerKey: ProviderKey;
-}): number | null;
+    decimals: number;
+}): bigint | null;
+/**
+ * Companion display helper — converts the base-units cap back into a
+ * USD number for `toLocaleString()`-style formatting. Returns `null`
+ * for locked and `Infinity` for unlimited, mirroring the legacy
+ * `getEffectiveCap` return shape so display code stays simple.
+ */
+export declare function getEffectiveCapDisplayUsd(cap: bigint | null, decimals: number): number | null;
 /**
  * Get the cooldown duration for a tier and platform.
  * Derives from tier cooldown hours and platform hasCooldown flag.