agentex-creator-sdk 1.0.0

package/dist/packages/contracts/src/token-market.d.ts

@@ -0,0 +1,193 @@
+import { type Hex } from 'viem';
+import { type EvidenceItem, type MarketPolicy, type TokenMarket } from './index.js';
+/**
+ * Token Researcher 0.3.0 market reads (P01): observed DEX pools on listed venues and balances of recent transfer recipients.
+ *
+ * - Pools are found only by factory lookups (`getPair` / `getPool`) on the venues and quote tokens listed below, in ONE Multicall3
+ *   `aggregate3` eth_call at the pinned block. Other venues, other quote tokens, Uniswap V4 and aggregators are never checked.
+ * - Recent recipients come from ONE `alchemy_getAssetTransfers` page (newest first, at or before the pinned block). They are recent
+ *   activity, never a holder list, ranking or distribution.
+ * - Pool token balances, reserves, V3 price and active liquidity, and recipient balances are read in ONE more `aggregate3` eth_call.
+ *
+ * Every factory address and quote token below was checked live (code present, known pair returned, symbol and decimals read) on
+ * 15 September 2026. Pure functions only: the executor, checkpoint scope, publication suite and result contract all derive the
+ * same section from captured receipts, so no value can be asserted without its receipt.
+ */
+export declare const MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";
+export declare const MULTICALL3_DOCUMENTATION = "https://www.multicall3.com/deployments";
+/** Gas for one market aggregate3 eth_call (1,500,000). eth_call gas is not spent on chain; the subcall count is bounded below. */
+export declare const MARKET_CALL_GAS = "0x16e360";
+export declare const MAXIMUM_MARKET_POOLS = 8;
+export declare const MAXIMUM_RECENT_TRANSFERS = 25;
+export declare const MAXIMUM_RECENT_RECIPIENTS = 10;
+export declare const HOLDER_ACTIVITY_METHOD = "alchemy_getAssetTransfers";
+export declare const HOLDER_ACTIVITY_DOCUMENTATION = "https://www.alchemy.com/docs/reference/alchemy-getassettransfers";
+/** Coverage rows (packages/providers coverage.ts) that gate each market read on a chain. */
+export declare const MARKET_COVERAGE_TOOLS: Readonly<{
+    pools: "evm.dex-pool-discovery@0.1.0";
+    holders: "evm.recent-holder-activity@0.1.0";
+}>;
+export type MarketProtocol = 'uniswap-v2' | 'uniswap-v3' | 'aerodrome';
+export interface MarketVenue {
+    id: string;
+    label: string;
+    protocol: MarketProtocol;
+    factory: string;
+    feeTiers: readonly number[] | null;
+    stableFlags: readonly boolean[] | null;
+    documentationUrl: string;
+}
+export interface MarketQuoteToken {
+    address: string;
+    symbol: string;
+    decimals: number;
+}
+export interface MarketVenueSet {
+    chain: 'ethereum' | 'base' | 'robinhood';
+    venues: readonly MarketVenue[];
+    quotes: readonly MarketQuoteToken[];
+}
+/** Keyed by chain id: Robinhood Chain testnet (46630) has no listed venue, so its pool section is unsupported. */
+export declare const MARKET_VENUES: Readonly<Record<number, MarketVenueSet>>;
+export declare const marketVenuesFor: (chainId: number | null | undefined) => MarketVenueSet | null;
+/** Exported for fixtures and verifiers that decode or answer aggregate3 requests. */
+export declare const MULTICALL3_ABI: readonly [{
+    readonly name: "aggregate3";
+    readonly type: "function";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly type: "tuple[]";
+        readonly components: readonly [{
+            readonly type: "address";
+            readonly name: "target";
+        }, {
+            readonly type: "bool";
+            readonly name: "allowFailure";
+        }, {
+            readonly type: "bytes";
+            readonly name: "callData";
+        }];
+        readonly name: "calls";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "tuple[]";
+        readonly components: readonly [{
+            readonly type: "bool";
+            readonly name: "success";
+        }, {
+            readonly type: "bytes";
+            readonly name: "returnData";
+        }];
+        readonly name: "returnData";
+    }];
+}];
+export declare const MARKET_SELECTORS: Readonly<{
+    balanceOf: "0x70a08231";
+    getReserves: "0x0902f1ac";
+    slot0: "0x3850c7bd";
+    liquidity: "0x1a686502";
+}>;
+export declare class MarketDecodeError extends Error {
+    constructor(message: string);
+}
+type VenueFields = {
+    venue: string;
+    protocol: MarketProtocol;
+    factory: string;
+    quoteToken: string;
+    quoteSymbol: string;
+    quoteDecimals: number;
+    feeTier: number | null;
+    stable: boolean | null;
+};
+export interface DiscoveryEntry extends VenueFields {
+    callData: Hex;
+}
+/** Factory lookups for every listed (quote token, venue, fee tier or stable flag), quote tokens first so WETH pools lead. The token itself is never its own quote. */
+export declare function discoveryPlan(set: MarketVenueSet, token: string): DiscoveryEntry[];
+/** Multicall3 aggregate3 with allowFailure on every subcall: one failed lookup is recorded, never hidden, and never fails the others. */
+export declare function encodeAggregate(calls: readonly {
+    target: string;
+    callData: Hex;
+}[]): Hex;
+/** The discovery multicall: each lookup targets its venue's factory. */
+export declare const encodeDiscovery: (plan: readonly DiscoveryEntry[]) => Hex;
+/** The eth_call object for a market multicall. Key order is fixed so checkpoint requests hash identically. */
+export declare const marketCall: (data: Hex) => {
+    to: string;
+    data: `0x${string}`;
+    gas: string;
+};
+export declare function decodeAggregate(result: unknown, expected: number): {
+    success: boolean;
+    returnData: Hex;
+}[];
+export interface CheckedVenue extends VenueFields {
+    lookup: 'pool' | 'no-pool' | 'call-failed';
+    pool: string | null;
+}
+export interface FoundPool extends VenueFields {
+    address: string;
+}
+export declare function poolsFromDiscovery(plan: readonly DiscoveryEntry[], results: readonly {
+    success: boolean;
+    returnData: Hex;
+}[]): {
+    checked: CheckedVenue[];
+    found: FoundPool[];
+};
+/** The exact indexed request: newest ERC-20 transfers of this token at or before the pinned block, zero values excluded. */
+export declare function holderTransferRequest(token: string, snapshotBlock: string): {
+    fromBlock: string;
+    toBlock: string;
+    contractAddresses: string[];
+    category: string[];
+    order: string;
+    maxCount: string;
+    excludeZeroValue: boolean;
+    withMetadata: boolean;
+};
+export interface RecentRecipient {
+    address: string;
+    latestReceiptBlock: string;
+}
+export declare function recipientsFromTransfers(result: unknown, token: string, snapshotBlock: string): {
+    examined: number;
+    truncated: boolean;
+    recipients: RecentRecipient[];
+};
+export interface BalanceEntry {
+    kind: 'pool-token' | 'pool-quote' | 'pool-reserves' | 'pool-slot0' | 'pool-liquidity' | 'recipient';
+    subject: string;
+    target: string;
+    callData: Hex;
+}
+export declare function balancesPlan(token: string, pools: readonly FoundPool[], recipients: readonly RecentRecipient[]): BalanceEntry[];
+type EvidenceLike = Pick<EvidenceItem, 'id' | 'source' | 'request' | 'result' | 'completeness'>;
+/**
+ * Derives the whole market section from captured receipts. The executor and every verifier call this same function, so a report's
+ * market section is valid only when it equals the derivation from its own evidence. `unsupported` carries server-side availability
+ * decisions (coverage or credential), which are not derivable from receipts.
+ */
+export declare function buildMarketSection(args: {
+    policy: MarketPolicy;
+    chainId: number | null;
+    token: string;
+    snapshotBlock: string | null;
+    evidence: readonly EvidenceLike[];
+    unsupported: {
+        pools: string | null;
+        holders: string | null;
+    };
+}): TokenMarket;
+/** True when the balances multicall for a derived plan is still unread (the executor reads it once). */
+export declare const marketBalancesData: (token: string, pools: readonly FoundPool[], recipients: readonly RecentRecipient[]) => {
+    plan: BalanceEntry[];
+    data: `0x${string}`;
+} | null;
+export declare function marketLimitations(chainId: number | null, policy: MarketPolicy): string[];
+/** Checkpoint scope: a market eth_call is exactly the discovery lookup for this token, or a bounded balances/pool-state read. */
+export declare function marketCallInScope(call: unknown, token: string, chainId: number): boolean;
+/** Checkpoint scope for the one indexed transfer page. */
+export declare function marketTransferRequestInScope(request: readonly unknown[], token: string, snapshotBlock: string): boolean;
+export {};

package/dist/packages/contracts/src/token-market.js

@@ -0,0 +1,335 @@
+import { decodeAbiParameters, decodeFunctionData, decodeFunctionResult, encodeFunctionData, getAddress, isAddress, parseAbi } from 'viem';
+import { contentHash } from './index.js';
+/**
+ * Token Researcher 0.3.0 market reads (P01): observed DEX pools on listed venues and balances of recent transfer recipients.
+ *
+ * - Pools are found only by factory lookups (`getPair` / `getPool`) on the venues and quote tokens listed below, in ONE Multicall3
+ *   `aggregate3` eth_call at the pinned block. Other venues, other quote tokens, Uniswap V4 and aggregators are never checked.
+ * - Recent recipients come from ONE `alchemy_getAssetTransfers` page (newest first, at or before the pinned block). They are recent
+ *   activity, never a holder list, ranking or distribution.
+ * - Pool token balances, reserves, V3 price and active liquidity, and recipient balances are read in ONE more `aggregate3` eth_call.
+ *
+ * Every factory address and quote token below was checked live (code present, known pair returned, symbol and decimals read) on
+ * 15 September 2026. Pure functions only: the executor, checkpoint scope, publication suite and result contract all derive the
+ * same section from captured receipts, so no value can be asserted without its receipt.
+ */
+export const MULTICALL3_ADDRESS = '0xcA11bde05977b3631167028862bE2a173976CA11';
+export const MULTICALL3_DOCUMENTATION = 'https://www.multicall3.com/deployments';
+/** Gas for one market aggregate3 eth_call (1,500,000). eth_call gas is not spent on chain; the subcall count is bounded below. */
+export const MARKET_CALL_GAS = '0x16e360';
+export const MAXIMUM_MARKET_POOLS = 8;
+export const MAXIMUM_RECENT_TRANSFERS = 25;
+export const MAXIMUM_RECENT_RECIPIENTS = 10;
+export const HOLDER_ACTIVITY_METHOD = 'alchemy_getAssetTransfers';
+export const HOLDER_ACTIVITY_DOCUMENTATION = 'https://www.alchemy.com/docs/reference/alchemy-getassettransfers';
+/** Coverage rows (packages/providers coverage.ts) that gate each market read on a chain. */
+export const MARKET_COVERAGE_TOOLS = Object.freeze({ pools: 'evm.dex-pool-discovery@0.1.0', holders: 'evm.recent-holder-activity@0.1.0' });
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+const V3_FEES = Object.freeze([100, 500, 3000, 10000]);
+const UNISWAP_V2_DOCS = 'https://developers.uniswap.org/docs/protocols/v2/deployments';
+const UNISWAP_V3_DOCS = 'https://developers.uniswap.org/docs/protocols/v3/deployments';
+const venue = (id, label, protocol, factory, documentationUrl, extra = {}) => Object.freeze({ id, label, protocol, factory: getAddress(factory), feeTiers: extra.feeTiers ?? null, stableFlags: extra.stableFlags ?? null, documentationUrl });
+const quote = (address, symbol, decimals) => Object.freeze({ address: getAddress(address), symbol, decimals });
+/** Keyed by chain id: Robinhood Chain testnet (46630) has no listed venue, so its pool section is unsupported. */
+export const MARKET_VENUES = Object.freeze({
+    1: Object.freeze({ chain: 'ethereum', venues: Object.freeze([
+            venue('uniswap-v2', 'Uniswap V2', 'uniswap-v2', '0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f', UNISWAP_V2_DOCS),
+            venue('sushiswap-v2', 'SushiSwap V2', 'uniswap-v2', '0xC0AEe478e3658e2610c5F7A4A2E1777cE9e4f2Ac', 'https://docs.sushi.com/contracts/cpamm'),
+            venue('uniswap-v3', 'Uniswap V3', 'uniswap-v3', '0x1F98431c8aD98523631AE4a59f267346ea31F984', UNISWAP_V3_DOCS, { feeTiers: V3_FEES }),
+        ]), quotes: Object.freeze([quote('0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', 'WETH', 18), quote('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', 'USDC', 6), quote('0xdAC17F958D2ee523a2206206994597C13D831ec7', 'USDT', 6)]) }),
+    8453: Object.freeze({ chain: 'base', venues: Object.freeze([
+            venue('uniswap-v2', 'Uniswap V2', 'uniswap-v2', '0x8909Dc15e40173Ff4699343b6eB8132c65e18eC6', UNISWAP_V2_DOCS),
+            venue('uniswap-v3', 'Uniswap V3', 'uniswap-v3', '0x33128a8fC17869897dcE68Ed026d694621f6FDfD', UNISWAP_V3_DOCS, { feeTiers: V3_FEES }),
+            venue('aerodrome', 'Aerodrome', 'aerodrome', '0x420DD381b31aEf6683db6B902084cB0FFECe40Da', 'https://github.com/aerodrome-finance/contracts', { stableFlags: Object.freeze([false, true]) }),
+        ]), quotes: Object.freeze([quote('0x4200000000000000000000000000000000000006', 'WETH', 18), quote('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', 'USDC', 6)]) }),
+    4663: Object.freeze({ chain: 'robinhood', venues: Object.freeze([
+            venue('uniswap-v2', 'Uniswap V2', 'uniswap-v2', '0x8bceaa40b9acdfaedf85adf4ff01f5ad6517937f', UNISWAP_V2_DOCS),
+            venue('uniswap-v3', 'Uniswap V3', 'uniswap-v3', '0x1f7d7550b1b028f7571e69a784071f0205fd2efa', UNISWAP_V3_DOCS, { feeTiers: V3_FEES }),
+        ]), quotes: Object.freeze([quote('0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73', 'WETH', 18), quote('0x5fc5360d0400a0fd4f2af552add042d716f1d168', 'USDG', 6)]) }),
+});
+export const marketVenuesFor = (chainId) => (typeof chainId === 'number' ? MARKET_VENUES[chainId] ?? null : null);
+const MULTICALL_ABI = parseAbi(['struct Call3 { address target; bool allowFailure; bytes callData; }', 'struct Result3 { bool success; bytes returnData; }', 'function aggregate3(Call3[] calls) payable returns (Result3[] returnData)']);
+const FACTORY_ABI = parseAbi(['function getPair(address tokenA, address tokenB) view returns (address pair)', 'function getPool(address tokenA, address tokenB, uint24 fee) view returns (address pool)']);
+const AERODROME_ABI = parseAbi(['function getPool(address tokenA, address tokenB, bool stable) view returns (address pool)']);
+const BALANCE_ABI = parseAbi(['function balanceOf(address account) view returns (uint256)']);
+/** Exported for fixtures and verifiers that decode or answer aggregate3 requests. */
+export const MULTICALL3_ABI = MULTICALL_ABI;
+export const MARKET_SELECTORS = Object.freeze({ balanceOf: '0x70a08231', getReserves: '0x0902f1ac', slot0: '0x3850c7bd', liquidity: '0x1a686502' });
+export class MarketDecodeError extends Error {
+    constructor(message) { super(message); this.name = 'MarketDecodeError'; }
+}
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Factory lookups for every listed (quote token, venue, fee tier or stable flag), quote tokens first so WETH pools lead. The token itself is never its own quote. */
+export function discoveryPlan(set, token) {
+    const subject = getAddress(token);
+    const entries = [];
+    for (const q of set.quotes) {
+        if (q.address.toLowerCase() === subject.toLowerCase())
+            continue;
+        const base = { quoteToken: q.address, quoteSymbol: q.symbol, quoteDecimals: q.decimals };
+        for (const v of set.venues) {
+            const fields = { venue: v.id, protocol: v.protocol, factory: v.factory, ...base };
+            if (v.protocol === 'uniswap-v2')
+                entries.push({ ...fields, feeTier: null, stable: null, callData: encodeFunctionData({ abi: FACTORY_ABI, functionName: 'getPair', args: [subject, q.address] }) });
+            else if (v.protocol === 'uniswap-v3')
+                for (const fee of v.feeTiers ?? [])
+                    entries.push({ ...fields, feeTier: fee, stable: null, callData: encodeFunctionData({ abi: FACTORY_ABI, functionName: 'getPool', args: [subject, q.address, fee] }) });
+            else
+                for (const stable of v.stableFlags ?? [])
+                    entries.push({ ...fields, feeTier: null, stable, callData: encodeFunctionData({ abi: AERODROME_ABI, functionName: 'getPool', args: [subject, q.address, stable] }) });
+        }
+    }
+    return entries;
+}
+/** Multicall3 aggregate3 with allowFailure on every subcall: one failed lookup is recorded, never hidden, and never fails the others. */
+export function encodeAggregate(calls) {
+    return encodeFunctionData({ abi: MULTICALL_ABI, functionName: 'aggregate3', args: [calls.map((call) => ({ target: getAddress(call.target), allowFailure: true, callData: call.callData }))] });
+}
+/** The discovery multicall: each lookup targets its venue's factory. */
+export const encodeDiscovery = (plan) => encodeAggregate(plan.map((entry) => ({ target: entry.factory, callData: entry.callData })));
+/** The eth_call object for a market multicall. Key order is fixed so checkpoint requests hash identically. */
+export const marketCall = (data) => ({ to: MULTICALL3_ADDRESS, data, gas: MARKET_CALL_GAS });
+export function decodeAggregate(result, expected) {
+    if (typeof result !== 'string' || !/^0x(?:[0-9a-fA-F]{2})*$/.test(result) || result === '0x')
+        throw new MarketDecodeError('The multicall returned no data.');
+    let decoded;
+    try {
+        decoded = decodeFunctionResult({ abi: MULTICALL_ABI, functionName: 'aggregate3', data: result });
+    }
+    catch {
+        throw new MarketDecodeError('The multicall response is not an aggregate3 result.');
+    }
+    if (!Array.isArray(decoded) || decoded.length !== expected)
+        throw new MarketDecodeError('The multicall response does not match the request.');
+    return decoded.map((item) => ({ success: item.success === true, returnData: item.returnData }));
+}
+const word = (data, index) => data.length >= 2 + 64 * (index + 1) ? `0x${data.slice(2 + 64 * index, 2 + 64 * (index + 1))}` : null;
+const addressWord = (data) => { const first = data.length === 66 ? word(data, 0) : null; return first && /^0x0{24}[0-9a-fA-F]{40}$/.test(first) ? getAddress(`0x${first.slice(26)}`) : null; };
+const uintWord = (data, index = 0) => { const value = word(data, index); return value ? BigInt(value).toString() : null; };
+export function poolsFromDiscovery(plan, results) {
+    const checked = [];
+    const found = [];
+    const seen = new Set();
+    plan.forEach(({ callData: _callData, ...fields }, index) => {
+        const result = results[index];
+        const pool = result.success ? addressWord(result.returnData) : null;
+        const lookup = !result.success || (pool === null && result.returnData !== '0x' && result.returnData.length !== 66) ? 'call-failed' : pool === null || pool === ZERO_ADDRESS ? 'no-pool' : 'pool';
+        checked.push({ ...fields, lookup: result.success && result.returnData === '0x' ? 'call-failed' : lookup, pool: lookup === 'pool' ? pool : null });
+        if (lookup === 'pool' && !seen.has(pool.toLowerCase())) {
+            seen.add(pool.toLowerCase());
+            found.push({ ...fields, address: pool });
+        }
+    });
+    return { checked, found };
+}
+/** The exact indexed request: newest ERC-20 transfers of this token at or before the pinned block, zero values excluded. */
+export function holderTransferRequest(token, snapshotBlock) {
+    return { fromBlock: '0x0', toBlock: `0x${BigInt(snapshotBlock).toString(16)}`, contractAddresses: [token.toLowerCase()], category: ['erc20'], order: 'desc', maxCount: `0x${MAXIMUM_RECENT_TRANSFERS.toString(16)}`, excludeZeroValue: true, withMetadata: false };
+}
+export function recipientsFromTransfers(result, token, snapshotBlock) {
+    if (!object(result) || !Array.isArray(result.transfers) || result.transfers.length > MAXIMUM_RECENT_TRANSFERS)
+        throw new MarketDecodeError('The transfer index response is outside the requested page.');
+    const recipients = [];
+    const seen = new Set();
+    let capped = false;
+    for (const transfer of result.transfers) {
+        if (!object(transfer) || typeof transfer.blockNum !== 'string' || !/^0x[0-9a-fA-F]{1,16}$/.test(transfer.blockNum))
+            throw new MarketDecodeError('A transfer has no block number.');
+        const block = BigInt(transfer.blockNum);
+        if (block > BigInt(snapshotBlock))
+            throw new MarketDecodeError('The index returned a transfer after the pinned block.');
+        const contract = object(transfer.rawContract) ? transfer.rawContract.address : undefined;
+        if (typeof contract !== 'string' || contract.toLowerCase() !== token.toLowerCase())
+            throw new MarketDecodeError('The index returned a transfer of another token.');
+        if (typeof transfer.to !== 'string' || !isAddress(transfer.to, { strict: false }))
+            continue;
+        const to = getAddress(transfer.to);
+        const key = to.toLowerCase();
+        if (to === ZERO_ADDRESS || seen.has(key))
+            continue;
+        seen.add(key);
+        if (recipients.length >= MAXIMUM_RECENT_RECIPIENTS) {
+            capped = true;
+            continue;
+        }
+        recipients.push({ address: to, latestReceiptBlock: block.toString() });
+    }
+    return { examined: result.transfers.length, truncated: capped || (typeof result.pageKey === 'string' && result.pageKey.length > 0), recipients };
+}
+const balanceOf = (account) => encodeFunctionData({ abi: BALANCE_ABI, functionName: 'balanceOf', args: [getAddress(account)] });
+export function balancesPlan(token, pools, recipients) {
+    const entries = [];
+    for (const pool of pools.slice(0, MAXIMUM_MARKET_POOLS)) {
+        entries.push({ kind: 'pool-token', subject: pool.address, target: getAddress(token), callData: balanceOf(pool.address) }, { kind: 'pool-quote', subject: pool.address, target: pool.quoteToken, callData: balanceOf(pool.address) });
+        if (pool.protocol === 'uniswap-v3')
+            entries.push({ kind: 'pool-slot0', subject: pool.address, target: pool.address, callData: MARKET_SELECTORS.slot0 }, { kind: 'pool-liquidity', subject: pool.address, target: pool.address, callData: MARKET_SELECTORS.liquidity });
+        else
+            entries.push({ kind: 'pool-reserves', subject: pool.address, target: pool.address, callData: MARKET_SELECTORS.getReserves });
+    }
+    for (const recipient of recipients.slice(0, MAXIMUM_RECENT_RECIPIENTS))
+        entries.push({ kind: 'recipient', subject: recipient.address, target: getAddress(token), callData: balanceOf(recipient.address) });
+    return entries;
+}
+const REASONS = {
+    poolsSkipped: 'Pool discovery is switched off by this version\'s market policy; pools are not inspected.',
+    holdersSkipped: 'Recent holder activity is switched off by this version\'s market policy.',
+    notRead: 'Not read: the run stopped before this read.',
+    poolsError: 'The pool discovery multicall failed; pool presence on the listed venues is unknown.',
+    holdersError: 'The transfer index request failed; recent recipients are unknown.',
+    noVenues: 'No verified DEX venue is listed for this chain, so pools were not looked up.',
+    poolsNone: 'No pool exists at the pinned block for the listed venue and quote-token pairs. Pools on other venues, with other quote tokens or on Uniswap V4 are not checked, so this is not proof of no liquidity.',
+    poolsObserved: 'Pools found by factory lookup on the listed venues at the pinned block, with token balances held by each pool. This is not every pool, not total liquidity and not a price or depth quote.',
+    holdersNone: 'The index returned no non-zero transfer to a recipient at or before the pinned block.',
+    holdersObserved: 'Current balances (at the pinned block) of accounts that received this token in its most recent indexed transfers. This is recent activity, not a holder list, ranking or distribution; an account can be a pool, exchange or contract.',
+};
+const multicallData = (item) => item.source.method === 'eth_call' && object(item.request[0]) && typeof item.request[0].to === 'string' && item.request[0].to.toLowerCase() === MULTICALL3_ADDRESS.toLowerCase() && typeof item.request[0].data === 'string' ? item.request[0].data : null;
+/**
+ * Derives the whole market section from captured receipts. The executor and every verifier call this same function, so a report's
+ * market section is valid only when it equals the derivation from its own evidence. `unsupported` carries server-side availability
+ * decisions (coverage or credential), which are not derivable from receipts.
+ */
+export function buildMarketSection(args) {
+    const { policy, chainId, token, snapshotBlock, evidence } = args;
+    const set = marketVenuesFor(chainId);
+    const pools = { status: 'skipped', reason: REASONS.poolsSkipped, venuesChecked: [], pools: [], poolsFound: 0, truncated: false, evidenceIds: [] };
+    const holders = { status: 'skipped', reason: REASONS.holdersSkipped, basis: 'recent-transfer-recipients-not-a-holder-list', transfersExamined: 0, truncated: false, accounts: [], evidenceIds: [] };
+    let found = [];
+    let recipients = [];
+    if (policy.discoverPools) {
+        if (args.unsupported.pools)
+            Object.assign(pools, { status: 'unsupported', reason: args.unsupported.pools.slice(0, 1000) });
+        else if (!set)
+            Object.assign(pools, { status: 'unsupported', reason: REASONS.noVenues });
+        else if (snapshotBlock === null)
+            Object.assign(pools, { status: 'not-read', reason: REASONS.notRead });
+        else {
+            const plan = discoveryPlan(set, token);
+            const data = encodeDiscovery(plan);
+            const receipts = evidence.filter((item) => multicallData(item) === data);
+            const ok = receipts.find((item) => item.completeness === 'complete-for-request');
+            if (ok) {
+                try {
+                    const decoded = poolsFromDiscovery(plan, decodeAggregate(ok.result, plan.length));
+                    found = decoded.found;
+                    Object.assign(pools, { status: found.length ? 'observed' : 'none-found', reason: found.length ? REASONS.poolsObserved : REASONS.poolsNone, venuesChecked: decoded.checked, poolsFound: found.length, truncated: found.length > MAXIMUM_MARKET_POOLS, evidenceIds: [ok.id] });
+                }
+                catch {
+                    Object.assign(pools, { status: 'error', reason: REASONS.poolsError, evidenceIds: [ok.id] });
+                    found = [];
+                }
+            }
+            else if (receipts.length)
+                Object.assign(pools, { status: 'error', reason: REASONS.poolsError, evidenceIds: receipts.map((item) => item.id).slice(0, 1) });
+            else
+                Object.assign(pools, { status: 'not-read', reason: REASONS.notRead });
+        }
+    }
+    if (policy.recentHolderActivity) {
+        if (args.unsupported.holders)
+            Object.assign(holders, { status: 'unsupported', reason: args.unsupported.holders.slice(0, 1000) });
+        else if (snapshotBlock === null)
+            Object.assign(holders, { status: 'not-read', reason: REASONS.notRead });
+        else {
+            const request = contentHash(holderTransferRequest(token, snapshotBlock));
+            const receipts = evidence.filter((item) => item.source.method === HOLDER_ACTIVITY_METHOD && item.request.length === 1 && contentHash(item.request[0]) === request);
+            const ok = receipts.find((item) => item.completeness === 'complete-for-request');
+            if (ok) {
+                try {
+                    const page = recipientsFromTransfers(ok.result, token, snapshotBlock);
+                    recipients = page.recipients;
+                    Object.assign(holders, { status: recipients.length ? 'observed' : 'none-found', reason: recipients.length ? REASONS.holdersObserved : REASONS.holdersNone, transfersExamined: page.examined, truncated: page.truncated, evidenceIds: [ok.id] });
+                }
+                catch {
+                    Object.assign(holders, { status: 'error', reason: REASONS.holdersError, evidenceIds: [ok.id] });
+                    recipients = [];
+                }
+            }
+            else if (receipts.length)
+                Object.assign(holders, { status: 'error', reason: REASONS.holdersError, evidenceIds: receipts.map((item) => item.id).slice(0, 1) });
+            else
+                Object.assign(holders, { status: 'not-read', reason: REASONS.notRead });
+        }
+    }
+    const shownPools = found.slice(0, MAXIMUM_MARKET_POOLS);
+    const plan = shownPools.length || recipients.length ? balancesPlan(token, shownPools, recipients) : [];
+    const balanceReceipt = plan.length ? (() => { const data = encodeAggregate(plan); const receipts = evidence.filter((item) => multicallData(item) === data); return receipts.find((item) => item.completeness === 'complete-for-request') ?? receipts[0] ?? null; })() : null;
+    let results = null;
+    if (balanceReceipt?.completeness === 'complete-for-request') {
+        try {
+            results = decodeAggregate(balanceReceipt.result, plan.length);
+        }
+        catch {
+            results = null;
+        }
+    }
+    const value = (kind, subject) => {
+        const index = plan.findIndex((entry) => entry.kind === kind && entry.subject === subject);
+        const result = index >= 0 && results ? results[index] : undefined;
+        return result?.success ? result.returnData : null;
+    };
+    const allFound = new Set(found.map((pool) => pool.address.toLowerCase()));
+    pools.pools = shownPools.map((pool) => {
+        const token0 = pool.quoteToken.toLowerCase() < token.toLowerCase() ? pool.quoteToken : getAddress(token);
+        const reserves = value('pool-reserves', pool.address);
+        const slot0 = value('pool-slot0', pool.address);
+        const liquidity = value('pool-liquidity', pool.address);
+        const tokenBalance = value('pool-token', pool.address);
+        const quoteBalance = value('pool-quote', pool.address);
+        const tickWord = slot0 ? word(slot0, 1) : null;
+        const { address, ...fields } = pool;
+        return { ...fields, address, token0, tokenBalanceAtomic: tokenBalance && tokenBalance.length === 66 ? uintWord(tokenBalance) : null, quoteBalanceAtomic: quoteBalance && quoteBalance.length === 66 ? uintWord(quoteBalance) : null,
+            reserve0Atomic: reserves ? uintWord(reserves, 0) : null, reserve1Atomic: reserves ? uintWord(reserves, 1) : null,
+            sqrtPriceX96: slot0 && word(slot0, 0) ? decodeAbiParameters([{ type: 'uint160' }], word(slot0, 0))[0].toString() : null,
+            tick: tickWord ? Number(decodeAbiParameters([{ type: 'int24' }], tickWord)[0]) : null,
+            activeLiquidity: liquidity && liquidity.length === 66 ? uintWord(liquidity) : null,
+            evidenceIds: [...pools.evidenceIds, ...(balanceReceipt ? [balanceReceipt.id] : [])] };
+    });
+    holders.accounts = recipients.map((recipient) => {
+        const balance = value('recipient', recipient.address);
+        return { address: recipient.address, latestReceiptBlock: recipient.latestReceiptBlock, balanceAtomic: balance && balance.length === 66 ? uintWord(balance) : null, isDiscoveredPool: allFound.has(recipient.address.toLowerCase()),
+            evidenceIds: [...holders.evidenceIds, ...(balanceReceipt ? [balanceReceipt.id] : [])] };
+    });
+    return { pools, recentHolderActivity: holders, limitations: marketLimitations(chainId, policy) };
+}
+/** True when the balances multicall for a derived plan is still unread (the executor reads it once). */
+export const marketBalancesData = (token, pools, recipients) => { const plan = balancesPlan(token, pools, recipients); return plan.length ? { plan, data: encodeAggregate(plan) } : null; };
+export function marketLimitations(chainId, policy) {
+    const set = marketVenuesFor(chainId);
+    const lines = [];
+    if (policy.discoverPools) {
+        lines.push(set ? `Pools are found only by factory lookups on ${set.venues.map((item) => item.label).join(', ')} against ${set.quotes.map((item) => item.symbol).join(', ')} at the pinned block. Other venues, other quote tokens, Uniswap V4 and aggregators are not checked, and no total liquidity is claimed.` : 'No verified DEX venue is listed for this chain; pools are not inspected.');
+        lines.push('Pool token balances are balanceOf values at the pinned block. For concentrated-liquidity pools they include out-of-range liquidity and uncollected fees; they are not executable depth, a price or a valuation.');
+    }
+    if (policy.recentHolderActivity)
+        lines.push('Recent recipients come from one provider index page of the newest transfers at or before the pinned block; completeness is the index\'s claim. They are not a holder list, ranking or distribution, and no concentration figure is computed.');
+    return lines;
+}
+/** Checkpoint scope: a market eth_call is exactly the discovery lookup for this token, or a bounded balances/pool-state read. */
+export function marketCallInScope(call, token, chainId) {
+    if (!object(call) || Object.keys(call).length !== 3 || typeof call.to !== 'string' || call.to.toLowerCase() !== MULTICALL3_ADDRESS.toLowerCase() || call.gas !== MARKET_CALL_GAS || typeof call.data !== 'string')
+        return false;
+    const set = marketVenuesFor(chainId);
+    if (!set)
+        return false;
+    if (call.data === encodeDiscovery(discoveryPlan(set, token)))
+        return true;
+    let calls;
+    try {
+        const decoded = decodeFunctionData({ abi: MULTICALL_ABI, data: call.data });
+        if (decoded.functionName !== 'aggregate3')
+            return false;
+        calls = decoded.args[0];
+    }
+    catch {
+        return false;
+    }
+    if (!calls.length || calls.length > MAXIMUM_MARKET_POOLS * 4 + MAXIMUM_RECENT_RECIPIENTS)
+        return false;
+    const tokens = new Set([token, ...set.quotes.map((item) => item.address)].map((value) => value.toLowerCase()));
+    const poolState = new Set([MARKET_SELECTORS.getReserves, MARKET_SELECTORS.slot0, MARKET_SELECTORS.liquidity]);
+    return calls.every((item) => item.allowFailure === true && ((tokens.has(item.target.toLowerCase()) && item.callData.length === 74 && item.callData.toLowerCase().startsWith(MARKET_SELECTORS.balanceOf)) || poolState.has(item.callData.toLowerCase())));
+}
+/** Checkpoint scope for the one indexed transfer page. */
+export function marketTransferRequestInScope(request, token, snapshotBlock) {
+    return request.length === 1 && contentHash(request[0]) === contentHash(holderTransferRequest(token, snapshotBlock));
+}