@poa-box/core 0.1.0

package/dist/reads/token.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Participation-token reads — typed wrappers over graph/documents/token.
+ *
+ * Serves the read paths of `pop token balance` (src/commands/token/balance.ts)
+ * and `pop token requests` (src/commands/token/requests.ts), plus the
+ * subgraph half of the token-address resolution in
+ * src/commands/token/helpers.ts.
+ *
+ * NOT ported here (deliberately — see the header of
+ * src/commands/token/helpers.ts): readTokenGates / checkWearsAnyHat /
+ * readTokenRequest. Those are provider-bound revert predictors that MUST stay
+ * on RPC: ParticipationTokenContract.executor/.hatsContract are the zero
+ * address on all live subgraph rows, memberHatIds/approverHatIds are not
+ * indexed at all, and requests(id) is the existence/state gate evaluated
+ * immediately before a write — subgraph lag there means knowingly
+ * broadcasting a doomed transaction.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveParticipationToken = resolveParticipationToken;
+exports.getTokenBalance = getTokenBalance;
+exports.listTokenRequests = listTokenRequests;
+exports.listUserTokenRequests = listUserTokenRequests;
+const token_1 = require("../graph/documents/token");
+const resolve_1 = require("./resolve");
+/**
+ * Resolve an org (name or hex ID) to its ParticipationToken address.
+ * Port of resolveTokenAddress in src/commands/token/helpers.ts — the
+ * subgraph-only half of that file (the hat-gate readers stay in the CLI).
+ */
+async function resolveParticipationToken(client, orgIdOrName, chainId) {
+    const modules = await (0, resolve_1.resolveOrgModules)(client, orgIdOrName, chainId);
+    return {
+        orgId: modules.orgId,
+        tokenAddress: (0, resolve_1.requireModule)(modules, 'participationTokenAddress'),
+    };
+}
+/**
+ * Subgraph read behind `pop token balance` — src/commands/token/balance.ts.
+ * TokenBalance mirrors ERC20 balanceOf exactly (verified live: the sum of a
+ * token's TokenBalance rows equals its indexed totalSupply).
+ */
+async function getTokenBalance(client, tokenAddress, holder, chainId) {
+    const data = await client.query(token_1.FETCH_TOKEN_BALANCE, { token: tokenAddress.toLowerCase(), balanceId: (0, token_1.tokenBalanceId)(tokenAddress, holder) }, chainId);
+    const symbol = data?.participationTokenContract?.symbol
+        ? String(data.participationTokenContract.symbol)
+        : null;
+    const balanceWei = data?.tokenBalance?.balance !== null && data?.tokenBalance?.balance !== undefined
+        ? String(data.tokenBalance.balance)
+        : null;
+    const updatedAt = data?.tokenBalance?.updatedAt !== undefined && data?.tokenBalance?.updatedAt !== null
+        ? String(data.tokenBalance.updatedAt)
+        : null;
+    return { tokenAddress, symbol, balanceWei, updatedAt };
+}
+/**
+ * List token requests for a ParticipationToken.
+ * Subgraph read behind `pop token requests` — src/commands/token/requests.ts
+ * (`status: 'pending'` ⇒ FETCH_PENDING_TOKEN_REQUESTS, `'all'` ⇒
+ * FETCH_ALL_TOKEN_REQUESTS; pending is the CLI default).
+ */
+async function listTokenRequests(client, tokenAddress, opts) {
+    const gqlQuery = opts?.status === 'all' ? token_1.FETCH_ALL_TOKEN_REQUESTS : token_1.FETCH_PENDING_TOKEN_REQUESTS;
+    const result = await client.query(gqlQuery, { tokenAddress }, opts?.chainId);
+    return result.tokenRequests || [];
+}
+/**
+ * One requester's token-request history (newest first, max 50) —
+ * FETCH_USER_TOKEN_REQUESTS from graph/documents/token. Rows omit
+ * `requester` (it is the filter variable).
+ */
+async function listUserTokenRequests(client, tokenAddress, userAddress, chainId) {
+    const result = await client.query(token_1.FETCH_USER_TOKEN_REQUESTS, { tokenAddress, userAddress: userAddress.toLowerCase() }, chainId);
+    return result.tokenRequests || [];
+}

package/dist/reads/treasury.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Treasury reads — typed wrappers over graph/documents/treasury.
+ *
+ * Serves the read paths of `pop treasury view` (src/commands/treasury/view.ts),
+ * `pop treasury distributions` (src/commands/treasury/distributions.ts), the
+ * distribution lookups of `pop treasury claim` / `claim-mine`, and the member
+ * snapshots that `compute-merkle` / `claim-mine` build merkle trees from.
+ *
+ * Read-sourcing policy (inherited from the CLI, comments load-bearing):
+ *   - display reads (view / distributions) are pure subgraph
+ *   - `distribution(id:)` answers null — NOT an error — for an id it has not
+ *     indexed, and a brand-new distribution is exactly the case where someone
+ *     claims early. Callers MUST treat null as "not indexed yet" and fall back
+ *     to PaymentManager.getDistribution, never render it as DistributionNotFound.
+ *   - the write-gating twins (hasClaimed / isOptedOut / getDistribution as a
+ *     revert predictor) stay on RPC in the host. isOptedOut in particular has
+ *     no trustworthy indexed twin: the OptOutToggle table has ZERO rows on all
+ *     nine live Gnosis PaymentManagers (verified 2026-07) because zero
+ *     OptOutToggled events have ever been emitted, so the mapping is
+ *     unexercised and no live row proves it indexes correctly.
+ */
+import { ethers } from 'ethers';
+import type { GraphClient } from '../graph/client';
+import { distributionEntityId } from '../graph/documents/treasury';
+export { distributionEntityId };
+export interface DistributionClaimRow {
+    id: string;
+    claimer: string;
+    claimerUsername: string | null;
+    amount: string;
+    claimedAt: string;
+    transactionHash: string;
+}
+export interface DistributionRow {
+    id: string;
+    distributionId: string;
+    payoutToken: string;
+    totalAmount: string;
+    totalClaimed: string;
+    checkpointBlock: string;
+    createdAtBlock: string | null;
+    merkleRoot: string;
+    /** Enum is exactly Active | Finalized. */
+    status: 'Active' | 'Finalized' | string;
+    createdAt: string | null;
+    finalizedAt: string | null;
+    unclaimedAmount: string | null;
+    claims: DistributionClaimRow[];
+}
+export interface PaymentRow {
+    id: string;
+    payer: string;
+    payerUsername: string | null;
+    amount: string;
+    token: string;
+    receivedAt: string;
+    transactionHash: string;
+}
+export interface TreasuryData {
+    id: string;
+    executorContract: {
+        id: string;
+        isPaused: boolean;
+        owner: string | null;
+        allowedCaller: string | null;
+        sweeps: Array<{
+            id: string;
+            to: string;
+            amount: string;
+            sweptAt: string;
+            transactionHash: string;
+        }>;
+    } | null;
+    participationToken: {
+        id: string;
+        name: string;
+        symbol: string;
+        totalSupply: string;
+    } | null;
+    paymentManager: {
+        id: string;
+        owner: string | null;
+        revenueShareToken: string | null;
+        distributionCounter: string;
+        distributions: DistributionRow[];
+        payments: PaymentRow[];
+    } | null;
+}
+/**
+ * Full treasury overview — subgraph read behind `pop treasury view`
+ * (src/commands/treasury/view.ts) and `pop treasury distributions`
+ * (src/commands/treasury/distributions.ts). Returns the raw organization
+ * entity; null when the org is unknown on this chain.
+ */
+export declare function fetchTreasuryData(client: GraphClient, orgIdOrName: string | undefined, chainId?: number): Promise<TreasuryData | null>;
+/**
+ * Distribution list, optionally filtered by status — the selection behind
+ * `pop treasury distributions --status ...`.
+ */
+export declare function listDistributions(client: GraphClient, orgIdOrName: string | undefined, chainId?: number, status?: 'Active' | 'Finalized'): Promise<DistributionRow[]>;
+export interface IndexedDistribution {
+    id: string;
+    distributionId: string;
+    /** Re-checksummed at the boundary (the subgraph stores addresses lowercased,
+     * while the ABI-decoded getDistribution() path yields EIP-55 — without this
+     * the value silently changes case depending on whether the distribution
+     * happens to be indexed). */
+    payoutToken: string;
+    totalAmount: string;
+    totalClaimed: string;
+    checkpointBlock: string;
+    /** The contract has NO getter for this — subgraph-only field. */
+    createdAtBlock: string | null;
+    merkleRoot: string;
+    status: 'Active' | 'Finalized' | string;
+    /** Derived exactly like `pop treasury claim` does: status === 'Finalized'.
+     * The enum only becomes Finalized once DistributionFinalized is indexed, so
+     * a false positive is impossible; a stale Active is caught at gas estimation. */
+    finalized: boolean;
+}
+/**
+ * One distribution by (paymentManager, distributionId) — the indexed twin of
+ * PaymentManager.getDistribution(), read behind `pop treasury claim`
+ * (src/commands/treasury/claim.ts).
+ *
+ * Returns null when the subgraph has not indexed the id — callers MUST fall
+ * back to getDistribution() on-chain, never treat null as DistributionNotFound.
+ */
+export declare function fetchDistributionById(client: GraphClient, paymentManagerAddress: string, distributionId: number | string, chainId?: number): Promise<IndexedDistribution | null>;
+export interface ActiveDistributionRow {
+    distributionId: string;
+    totalAmount: string;
+    merkleRoot: string;
+    checkpointBlock: string;
+    payoutToken: string;
+    claims: Array<{
+        claimer: string;
+    }>;
+}
+/**
+ * Every still-claimable distribution with its claim log — the read behind
+ * `pop treasury claim-mine` (src/commands/treasury/claim-mine.ts).
+ */
+export declare function fetchActiveDistributions(client: GraphClient, orgIdOrName: string | undefined, chainId?: number): Promise<ActiveDistributionRow[]>;
+/**
+ * Members + PT balances at the CURRENT head — the builder snapshot used by
+ * `pop treasury compute-merkle` (src/commands/treasury/compute-merkle.ts).
+ * Ordered by PT balance desc: the dust-to-largest-holder rule depends on
+ * allocations[0] being the largest holder.
+ */
+export declare const FETCH_MEMBERS_PT = "\n  query FetchMembersPT($orgId: Bytes!) {\n    organization(id: $orgId) {\n      users(\n        orderBy: participationTokenBalance,\n        orderDirection: desc,\n        first: 1000\n      ) {\n        address\n        participationTokenBalance\n        membershipStatus\n        account {\n          username\n        }\n      }\n      participationToken {\n        totalSupply\n      }\n    }\n  }\n";
+/**
+ * Members AND opt-out state as of a distribution's checkpoint block — the
+ * reconstruction snapshot used by `pop treasury claim-mine`
+ * (src/commands/treasury/claim-mine.ts).
+ *
+ * Both halves are block-scoped on purpose. `pop treasury compute-merkle`
+ * excludes opted-out members when it BUILDS the tree (the only place opt-out
+ * is enforced since audit L-19), so reconstructing that tree has to reproduce
+ * the opt-out set as it was AT BUILD TIME. Using current opt-out state instead
+ * would rebuild a different tree the moment anyone toggles after a
+ * distribution is created, and every member would get "Root mismatch" for a
+ * valid distribution. compute-merkle sets checkpointBlock to the build block,
+ * so this is that state.
+ *
+ * optOutToggles is a TOP-LEVEL entity, so it MUST be scoped to this org's
+ * PaymentManager. Unfiltered it returns toggles from every PaymentManager the
+ * subgraph indexes (nine on Gnosis today), and any address that opted out of a
+ * DIFFERENT org would be dropped from this org's tree — producing a spurious
+ * "Root mismatch" that tells every member they cannot claim.
+ */
+export declare const FETCH_MEMBERS_AT_BLOCK = "\n  query FetchMembersAtBlock($orgId: Bytes!, $block: Int!, $paymentManager: String!) {\n    organization(id: $orgId, block: { number: $block }) {\n      participationToken { totalSupply }\n      users(orderBy: participationTokenBalance, orderDirection: desc, first: 1000) {\n        address\n        participationTokenBalance\n        membershipStatus\n      }\n    }\n    optOutToggles(\n      block: { number: $block }\n      where: { paymentManager: $paymentManager }\n      first: 1000\n      orderBy: toggledAtBlock\n      orderDirection: asc\n    ) {\n      user\n      optedOut\n      toggledAtBlock\n    }\n  }\n";
+export interface MemberPtRow {
+    address: string;
+    participationTokenBalance: string;
+    membershipStatus: string;
+    account?: {
+        username: string | null;
+    } | null;
+}
+export interface OptOutToggleRow {
+    user: string;
+    optedOut: boolean;
+    toggledAtBlock: string;
+}
+/** Current-head member snapshot (compute-merkle builder input). */
+export declare function fetchMembersPT(client: GraphClient, orgId: string, chainId?: number): Promise<{
+    users: MemberPtRow[];
+    totalSupply: string;
+} | null>;
+/** Block-pinned member + opt-out snapshot (claim-mine reconstruction input). */
+export declare function fetchMembersAtBlock(client: GraphClient, orgId: string, block: number, paymentManagerAddress: string, chainId?: number): Promise<{
+    users: MemberPtRow[];
+    totalSupply: string;
+    optOutToggles: OptOutToggleRow[];
+} | null>;
+/**
+ * Latest toggle per user wins — the log is ascending, so the last write for an
+ * address is its state at the pinned block. Pure port of the fold in
+ * `pop treasury claim-mine`.
+ */
+export declare function optedOutSetFromToggles(toggles: OptOutToggleRow[]): Set<string>;
+export interface PayoutTokenInfo {
+    address: string;
+    symbol: string;
+    decimals: number;
+    isNative: boolean;
+}
+/**
+ * Resolve a distribution payout token to human units — port of
+ * resolvePayoutTokenInfo in src/commands/treasury/helpers.ts (shared by claim,
+ * claim-mine, propose-distribution and propose-finalize so amounts render
+ * identically).
+ *
+ * PaymentManager uses address(0) for the chain's native token (verified:
+ * claimDistribution transfers raw value when payoutToken == address(0));
+ * ERC20s are resolved via a live decimals()/symbol() read with the known-token
+ * table then an 18-decimals default as fallbacks. RPC on purpose: the subgraph
+ * does not index arbitrary ERC20s. When no provider is supplied the live read
+ * is skipped and the table/default fallback applies directly.
+ */
+export declare function resolvePayoutTokenInfo(provider: ethers.providers.Provider | undefined, tokenAddress: string, chainId?: number): Promise<PayoutTokenInfo>;

package/dist/reads/treasury.js

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * Treasury reads — typed wrappers over graph/documents/treasury.
+ *
+ * Serves the read paths of `pop treasury view` (src/commands/treasury/view.ts),
+ * `pop treasury distributions` (src/commands/treasury/distributions.ts), the
+ * distribution lookups of `pop treasury claim` / `claim-mine`, and the member
+ * snapshots that `compute-merkle` / `claim-mine` build merkle trees from.
+ *
+ * Read-sourcing policy (inherited from the CLI, comments load-bearing):
+ *   - display reads (view / distributions) are pure subgraph
+ *   - `distribution(id:)` answers null — NOT an error — for an id it has not
+ *     indexed, and a brand-new distribution is exactly the case where someone
+ *     claims early. Callers MUST treat null as "not indexed yet" and fall back
+ *     to PaymentManager.getDistribution, never render it as DistributionNotFound.
+ *   - the write-gating twins (hasClaimed / isOptedOut / getDistribution as a
+ *     revert predictor) stay on RPC in the host. isOptedOut in particular has
+ *     no trustworthy indexed twin: the OptOutToggle table has ZERO rows on all
+ *     nine live Gnosis PaymentManagers (verified 2026-07) because zero
+ *     OptOutToggled events have ever been emitted, so the mapping is
+ *     unexercised and no live row proves it indexes correctly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FETCH_MEMBERS_AT_BLOCK = exports.FETCH_MEMBERS_PT = exports.distributionEntityId = void 0;
+exports.fetchTreasuryData = fetchTreasuryData;
+exports.listDistributions = listDistributions;
+exports.fetchDistributionById = fetchDistributionById;
+exports.fetchActiveDistributions = fetchActiveDistributions;
+exports.fetchMembersPT = fetchMembersPT;
+exports.fetchMembersAtBlock = fetchMembersAtBlock;
+exports.optedOutSetFromToggles = optedOutSetFromToggles;
+exports.resolvePayoutTokenInfo = resolvePayoutTokenInfo;
+const ethers_1 = require("ethers");
+const treasury_1 = require("../graph/documents/treasury");
+Object.defineProperty(exports, "distributionEntityId", { enumerable: true, get: function () { return treasury_1.distributionEntityId; } });
+const resolve_1 = require("./resolve");
+const contracts_1 = require("../contracts");
+const chains_1 = require("../chains");
+/**
+ * Full treasury overview — subgraph read behind `pop treasury view`
+ * (src/commands/treasury/view.ts) and `pop treasury distributions`
+ * (src/commands/treasury/distributions.ts). Returns the raw organization
+ * entity; null when the org is unknown on this chain.
+ */
+async function fetchTreasuryData(client, orgIdOrName, chainId) {
+    const orgId = await (0, resolve_1.resolveOrgId)(client, orgIdOrName, chainId);
+    const result = await client.query(treasury_1.FETCH_TREASURY_DATA, { orgId }, chainId);
+    return result.organization ?? null;
+}
+/**
+ * Distribution list, optionally filtered by status — the selection behind
+ * `pop treasury distributions --status ...`.
+ */
+async function listDistributions(client, orgIdOrName, chainId, status) {
+    const org = await fetchTreasuryData(client, orgIdOrName, chainId);
+    let distributions = org?.paymentManager?.distributions ?? [];
+    if (status)
+        distributions = distributions.filter((d) => d.status === status);
+    return distributions;
+}
+/**
+ * One distribution by (paymentManager, distributionId) — the indexed twin of
+ * PaymentManager.getDistribution(), read behind `pop treasury claim`
+ * (src/commands/treasury/claim.ts).
+ *
+ * Returns null when the subgraph has not indexed the id — callers MUST fall
+ * back to getDistribution() on-chain, never treat null as DistributionNotFound.
+ */
+async function fetchDistributionById(client, paymentManagerAddress, distributionId, chainId) {
+    const result = await client
+        .query(treasury_1.FETCH_DISTRIBUTION_BY_ID, { id: (0, treasury_1.distributionEntityId)(paymentManagerAddress, distributionId) }, chainId)
+        .catch(() => ({ distribution: null }));
+    const indexed = result.distribution;
+    if (!indexed)
+        return null;
+    return {
+        ...indexed,
+        payoutToken: ethers_1.ethers.utils.getAddress(indexed.payoutToken),
+        finalized: indexed.status === 'Finalized',
+    };
+}
+/**
+ * Every still-claimable distribution with its claim log — the read behind
+ * `pop treasury claim-mine` (src/commands/treasury/claim-mine.ts).
+ */
+async function fetchActiveDistributions(client, orgIdOrName, chainId) {
+    const orgId = await (0, resolve_1.resolveOrgId)(client, orgIdOrName, chainId);
+    const result = await client.query(treasury_1.FETCH_ACTIVE_DISTRIBUTIONS, { orgId }, chainId);
+    return result.organization?.paymentManager?.distributions ?? [];
+}
+// ---------------------------------------------------------------------------
+// Member snapshots for merkle building / reconstruction
+// ---------------------------------------------------------------------------
+/**
+ * Members + PT balances at the CURRENT head — the builder snapshot used by
+ * `pop treasury compute-merkle` (src/commands/treasury/compute-merkle.ts).
+ * Ordered by PT balance desc: the dust-to-largest-holder rule depends on
+ * allocations[0] being the largest holder.
+ */
+exports.FETCH_MEMBERS_PT = `
+  query FetchMembersPT($orgId: Bytes!) {
+    organization(id: $orgId) {
+      users(
+        orderBy: participationTokenBalance,
+        orderDirection: desc,
+        first: 1000
+      ) {
+        address
+        participationTokenBalance
+        membershipStatus
+        account {
+          username
+        }
+      }
+      participationToken {
+        totalSupply
+      }
+    }
+  }
+`;
+/**
+ * Members AND opt-out state as of a distribution's checkpoint block — the
+ * reconstruction snapshot used by `pop treasury claim-mine`
+ * (src/commands/treasury/claim-mine.ts).
+ *
+ * Both halves are block-scoped on purpose. `pop treasury compute-merkle`
+ * excludes opted-out members when it BUILDS the tree (the only place opt-out
+ * is enforced since audit L-19), so reconstructing that tree has to reproduce
+ * the opt-out set as it was AT BUILD TIME. Using current opt-out state instead
+ * would rebuild a different tree the moment anyone toggles after a
+ * distribution is created, and every member would get "Root mismatch" for a
+ * valid distribution. compute-merkle sets checkpointBlock to the build block,
+ * so this is that state.
+ *
+ * optOutToggles is a TOP-LEVEL entity, so it MUST be scoped to this org's
+ * PaymentManager. Unfiltered it returns toggles from every PaymentManager the
+ * subgraph indexes (nine on Gnosis today), and any address that opted out of a
+ * DIFFERENT org would be dropped from this org's tree — producing a spurious
+ * "Root mismatch" that tells every member they cannot claim.
+ */
+exports.FETCH_MEMBERS_AT_BLOCK = `
+  query FetchMembersAtBlock($orgId: Bytes!, $block: Int!, $paymentManager: String!) {
+    organization(id: $orgId, block: { number: $block }) {
+      participationToken { totalSupply }
+      users(orderBy: participationTokenBalance, orderDirection: desc, first: 1000) {
+        address
+        participationTokenBalance
+        membershipStatus
+      }
+    }
+    optOutToggles(
+      block: { number: $block }
+      where: { paymentManager: $paymentManager }
+      first: 1000
+      orderBy: toggledAtBlock
+      orderDirection: asc
+    ) {
+      user
+      optedOut
+      toggledAtBlock
+    }
+  }
+`;
+/** Current-head member snapshot (compute-merkle builder input). */
+async function fetchMembersPT(client, orgId, chainId) {
+    const result = await client.query(exports.FETCH_MEMBERS_PT, { orgId }, chainId);
+    const org = result.organization;
+    if (!org)
+        return null;
+    return { users: org.users ?? [], totalSupply: org.participationToken?.totalSupply ?? '0' };
+}
+/** Block-pinned member + opt-out snapshot (claim-mine reconstruction input). */
+async function fetchMembersAtBlock(client, orgId, block, paymentManagerAddress, chainId) {
+    const result = await client.query(exports.FETCH_MEMBERS_AT_BLOCK, { orgId, block, paymentManager: paymentManagerAddress.toLowerCase() }, chainId);
+    const org = result.organization;
+    if (!org)
+        return null;
+    return {
+        users: org.users ?? [],
+        totalSupply: org.participationToken?.totalSupply ?? '0',
+        optOutToggles: result.optOutToggles ?? [],
+    };
+}
+/**
+ * Latest toggle per user wins — the log is ascending, so the last write for an
+ * address is its state at the pinned block. Pure port of the fold in
+ * `pop treasury claim-mine`.
+ */
+function optedOutSetFromToggles(toggles) {
+    const optedOut = new Set();
+    for (const t of toggles ?? []) {
+        const addr = String(t.user).toLowerCase();
+        if (t.optedOut)
+            optedOut.add(addr);
+        else
+            optedOut.delete(addr);
+    }
+    return optedOut;
+}
+/**
+ * Resolve a distribution payout token to human units — port of
+ * resolvePayoutTokenInfo in src/commands/treasury/helpers.ts (shared by claim,
+ * claim-mine, propose-distribution and propose-finalize so amounts render
+ * identically).
+ *
+ * PaymentManager uses address(0) for the chain's native token (verified:
+ * claimDistribution transfers raw value when payoutToken == address(0));
+ * ERC20s are resolved via a live decimals()/symbol() read with the known-token
+ * table then an 18-decimals default as fallbacks. RPC on purpose: the subgraph
+ * does not index arbitrary ERC20s. When no provider is supplied the live read
+ * is skipped and the table/default fallback applies directly.
+ */
+async function resolvePayoutTokenInfo(provider, tokenAddress, chainId) {
+    if (!tokenAddress || tokenAddress === ethers_1.ethers.constants.AddressZero) {
+        const native = (0, chains_1.getNetworkByChainId)(chainId ?? 0)?.nativeCurrency?.symbol ?? 'native';
+        return { address: ethers_1.ethers.constants.AddressZero, symbol: native, decimals: 18, isNative: true };
+    }
+    const known = (0, chains_1.getTokenByAddress)(tokenAddress);
+    let decimals = known?.decimals;
+    let symbol = known?.symbol;
+    if (provider) {
+        try {
+            const erc20 = (0, contracts_1.createReadContract)(tokenAddress, 'ERC20', provider);
+            const [liveDecimals, liveSymbol] = await Promise.all([
+                erc20.decimals(),
+                erc20.symbol().catch(() => undefined),
+            ]);
+            decimals = Number(liveDecimals);
+            symbol = liveSymbol ?? symbol;
+        }
+        catch {
+            // Live read failed — fall back to the known-token table / 18.
+        }
+    }
+    return {
+        address: tokenAddress,
+        symbol: symbol ?? 'tokens',
+        decimals: decimals ?? 18,
+        isNative: false,
+    };
+}