@rhinestone/shared-configs 2.11.0 → 2.12.0

package/dist/scripts/generate.js

@@ -110,6 +110,20 @@ function renderChains(chainRegistry, mainnets, testnets) {
         "   *  the on-chain address (non-EVM chains). */",
         "  nearAssetId?: string;",
         "  unpriced?: boolean;",
+        "  /** Whether this token may collateralise an unsponsored gas refund. */",
+        "  gasRefund?: boolean;",
+        "  /** Whether this token may carry an app-fee carve. */",
+        "  appFee?: boolean;",
+        "}",
+        "",
+        "/** A token accepted as payment that is not in the routing catalog. */",
+        "interface PaymentToken {",
+        "  symbol: string;",
+        "  address: string;",
+        "  decimals: number;",
+        "  priceSymbol?: string;",
+        "  appFee?: boolean;",
+        "  gasRefund?: boolean;",
         "}",
         "",
         "interface NativeToken {",
@@ -156,6 +170,8 @@ function renderChains(chainRegistry, mainnets, testnets) {
         "  nativeToken: NativeToken;",
         "  wrappedNativeToken: NativeToken;",
         "  tokens: Token[];",
+        "  /** Tokens accepted as payment that are not in `tokens`. */",
+        "  paymentTokens?: PaymentToken[];",
         "  settlementLayers: SettlementLayer[];",
         "  /** Per-vendor addressing for the enabled layers that need it (Rhino chain",
         "   *  name, CCTP domain, NEAR prefix, OFT adapter). Third-party addresses —",

package/dist/scripts/validation.js

@@ -291,6 +291,46 @@ function structuralProblems(registryChainId, chain) {
         if (!isNonNegativeInt(token.decimals))
             problems.push(`${field}.decimals is not a non-negative integer`);
     }
+    if (chain.paymentTokens !== undefined) {
+        if (!Array.isArray(chain.paymentTokens)) {
+            problems.push('paymentTokens is not an array');
+        }
+        else {
+            const catalog = new Set((Array.isArray(chain.tokens) ? chain.tokens : [])
+                .map((t) => (isObject(t) && typeof t.address === 'string' ? t.address.toLowerCase() : ''))
+                .filter(Boolean));
+            chain.paymentTokens.forEach((token, i) => {
+                const at = `paymentTokens[${i}]`;
+                if (!isObject(token)) {
+                    problems.push(`${at} is not an object`);
+                    return;
+                }
+                if (typeof token.address !== 'string')
+                    problems.push(`${at}.address is not a string`);
+                if (!isNonEmptyString(token.symbol))
+                    problems.push(`${at}.symbol is not a non-empty string`);
+                if (!isNonNegativeInt(token.decimals))
+                    problems.push(`${at}.decimals is not a non-negative integer`);
+                if (!isAbsentOr(token.priceSymbol, isNonEmptyString))
+                    problems.push(`${at}.priceSymbol is not a string`);
+                if (!isAbsentOr(token.appFee, (v) => typeof v === 'boolean'))
+                    problems.push(`${at}.appFee is not a boolean`);
+                if (!isAbsentOr(token.gasRefund, (v) => typeof v === 'boolean'))
+                    problems.push(`${at}.gasRefund is not a boolean`);
+                if (token.appFee !== true && token.gasRefund !== true) {
+                    problems.push(`${at} declares no payment purpose; drop it or set appFee/gasRefund`);
+                }
+                // A duplicate would make the same token reachable through two lists
+                // with different flags, and nothing downstream defines which wins.
+                if (typeof token.address === 'string' && catalog.has(token.address.toLowerCase())) {
+                    problems.push(`${at}.address is already in tokens; declare the flags there instead`);
+                }
+                if (chain.vmType !== 'evm') {
+                    problems.push(`${at} is only valid on an EVM chain — both payment paths are EVM calls`);
+                }
+            });
+        }
+    }
     if (!Array.isArray(chain.tokens)) {
         problems.push('tokens is not an array');
     }
@@ -321,6 +361,10 @@ function structuralProblems(registryChainId, chain) {
                 problems.push(`${at}.nearAssetId is not a string`);
             if (!isAbsentOr(token.unpriced, (v) => typeof v === 'boolean'))
                 problems.push(`${at}.unpriced is not a boolean`);
+            if (!isAbsentOr(token.gasRefund, (v) => typeof v === 'boolean'))
+                problems.push(`${at}.gasRefund is not a boolean`);
+            if (!isAbsentOr(token.appFee, (v) => typeof v === 'boolean'))
+                problems.push(`${at}.appFee is not a boolean`);
             if (!isAbsentOr(token.pegGroup, (v) => PEG_GROUPS.has(v))) {
                 problems.push(`${at}.pegGroup ${JSON.stringify(token.pegGroup)} is not a known peg group`);
             }

package/dist/src/__tests__/paymentTokens.test.d.ts

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

package/dist/src/__tests__/paymentTokens.test.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const bun_test_1 = require("bun:test");
+const index_1 = require("../index");
+const entries = Object.entries(index_1.chainRegistry);
+/**
+ * `<chainId>:<symbol>` for a catalog token we have DECIDED not to accept as
+ * payment. Empty today — every real EVM catalog token is accepted. An entry
+ * here records a decision; it is not a backlog.
+ */
+const NOT_ACCEPTED_AS_PAYMENT = new Set();
+(0, bun_test_1.describe)("payment-token eligibility", () => {
+    (0, bun_test_1.it)("is only ever present as `true`", () => {
+        // `false` and absent mean the same thing, so writing `false` would imply a
+        // distinction the consumer cannot act on.
+        for (const [chainId, chain] of entries) {
+            for (const token of chain.tokens) {
+                if ("gasRefund" in token) {
+                    (0, bun_test_1.expect)(`${chainId}:${token.symbol}=${token.gasRefund}`).toBe(`${chainId}:${token.symbol}=true`);
+                }
+            }
+        }
+    });
+    (0, bun_test_1.it)("forces a decision on every real EVM catalog token", () => {
+        // The flags are opt-in, so a token added without one is silently refused as
+        // payment rather than loudly rejected — which is how Plasma USDC nearly
+        // shipped ineligible. Failing here makes the next author choose.
+        //
+        // Virtual chains are exempt: their token rows are not what the payment
+        // paths consult, which resolve to the settlement chain first. Non-EVM is
+        // exempt by the test below.
+        const undecided = entries
+            .filter(([, chain]) => chain.vmType === "evm" && chain.virtual !== true)
+            .flatMap(([chainId, chain]) => chain.tokens
+            .filter((token) => token.address.toLowerCase() !==
+            chain.nativeToken.address.toLowerCase())
+            .filter((token) => !token.gasRefund || !token.appFee)
+            .map((token) => `${chainId}:${token.symbol}`))
+            .filter((key) => !NOT_ACCEPTED_AS_PAYMENT.has(key));
+        (0, bun_test_1.expect)(undecided).toEqual([]);
+    });
+    (0, bun_test_1.it)("is never set on a non-EVM chain", () => {
+        // The refund settles as an EVM `transferFrom` through the Paymaster, so an
+        // SPL mint or a Stellar SAC marked eligible would be uncollectable.
+        const offenders = entries
+            .filter(([, chain]) => chain.vmType !== "evm")
+            .flatMap(([chainId, chain]) => chain.tokens
+            .filter((token) => token.gasRefund)
+            .map((token) => `${chainId}:${token.symbol}`));
+        (0, bun_test_1.expect)(offenders).toEqual([]);
+    });
+    (0, bun_test_1.it)("is not set on a native token entry", () => {
+        // A chain's native token is eligible by construction — the Paymaster
+        // settles it from a deposit, not a transfer — so declaring it here would
+        // let a chain look ineligible for its own gas token.
+        const offenders = entries
+            .flatMap(([chainId, chain]) => chain.tokens
+            .filter((token) => token.gasRefund &&
+            token.address.toLowerCase() ===
+                chain.nativeToken.address.toLowerCase())
+            .map((token) => `${chainId}:${token.symbol}`));
+        (0, bun_test_1.expect)(offenders).toEqual([]);
+    });
+});
+(0, bun_test_1.describe)("chain.paymentTokens", () => {
+    (0, bun_test_1.it)("never repeats an address already in the routing catalog", () => {
+        // The same token reachable through both lists could carry different flags,
+        // and nothing downstream defines which wins.
+        for (const [chainId, chain] of entries) {
+            const catalog = new Set(chain.tokens.map((token) => token.address.toLowerCase()));
+            for (const token of chain.paymentTokens ?? []) {
+                (0, bun_test_1.expect)(`${chainId}:${token.symbol}:${catalog.has(token.address.toLowerCase())}`).toBe(`${chainId}:${token.symbol}:false`);
+            }
+        }
+    });
+    (0, bun_test_1.it)("declares at least one payment purpose per entry", () => {
+        const purposeless = entries.flatMap(([chainId, chain]) => (chain.paymentTokens ?? [])
+            .filter((token) => !token.appFee && !token.gasRefund)
+            .map((token) => `${chainId}:${token.symbol}`));
+        (0, bun_test_1.expect)(purposeless).toEqual([]);
+    });
+    (0, bun_test_1.it)("is never set on a non-EVM chain", () => {
+        const offenders = entries
+            .filter(([, chain]) => chain.vmType !== "evm")
+            .filter(([, chain]) => (chain.paymentTokens ?? []).length > 0)
+            .map(([chainId]) => chainId);
+        (0, bun_test_1.expect)(offenders).toEqual([]);
+    });
+});

package/dist/src/chains.d.ts

@@ -18,6 +18,19 @@ interface Token {
      *  the on-chain address (non-EVM chains). */
     nearAssetId?: string;
     unpriced?: boolean;
+    /** Whether this token may collateralise an unsponsored gas refund. */
+    gasRefund?: boolean;
+    /** Whether this token may carry an app-fee carve. */
+    appFee?: boolean;
+}
+/** A token accepted as payment that is not in the routing catalog. */
+interface PaymentToken {
+    symbol: string;
+    address: string;
+    decimals: number;
+    priceSymbol?: string;
+    appFee?: boolean;
+    gasRefund?: boolean;
 }
 interface NativeToken {
     /** EVM: zero address placeholder. SVM: wSOL mint. TVM: zero address placeholder. */
@@ -64,6 +77,8 @@ interface Chain {
     nativeToken: NativeToken;
     wrappedNativeToken: NativeToken;
     tokens: Token[];
+    /** Tokens accepted as payment that are not in `tokens`. */
+    paymentTokens?: PaymentToken[];
     settlementLayers: SettlementLayer[];
     /** Per-vendor addressing for the enabled layers that need it (Rhino chain
      *  name, CCTP domain, NEAR prefix, OFT adapter). Third-party addresses —