@pushchain/core 6.0.20 → 6.0.22

package/src/lib/orchestrator/internals/pc20/resolver.js

@@ -0,0 +1,649 @@
+"use strict";
+/**
+ * PC20 registry resolver — the one module that reads PC20 state.
+ *
+ * Used by `sendTransaction`, `prepareTransaction`, cascade construction,
+ * `getPC20Address`, and the outbound tracking fallback.
+ * Nothing else may read the registry directly; a second reader is how the
+ * validation tiers and the cache policy drift apart.
+ *
+ * ## Read budget
+ *
+ * Validation is tiered so a send does not pay for the full identity sweep:
+ *
+ *   Tier A (every send)  — `getPC20Source` then `getPC20Wrapper`. Forward and
+ *                          reverse agreement proves the address is registered
+ *                          for that exact namespace, which is what defeats a
+ *                          wrapper address copied onto the wrong chain.
+ *   Tier B (prepare-time, first use per session, or strict mode) — live gateway
+ *                          factory identity, `isPC20Wrapper`, `wrapperToSource`,
+ *                          `SOURCE_ASSET`, deployed bytecode. Largely redundant
+ *                          once Tier A holds, but it is what catches a
+ *                          misconfigured deployment where the gateway would not
+ *                          take the PC20 burn path at all.
+ *
+ * Each tier is one multicall against one chain. Budget: at most 2 sequential
+ * round trips warm, 4 cold. `__readCount` exists so tests can assert that.
+ *
+ * ## Cache policy
+ *
+ * Positive results are cached for the client's lifetime, keyed by
+ * `(pushNetwork, chain, address)`. Registered mappings are immutable in
+ * practice — a factory reconfiguration is a redeploy-level event.
+ *
+ * Negative results are NEVER cached. The first successful export creates a
+ * mapping that did not previously exist, and a cached "not registered" would
+ * make the SDK permanently wrong about a token that now works.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__readCount = void 0;
+exports.getUniversalCoreAddress = getUniversalCoreAddress;
+exports.__clearPC20Caches = __clearPC20Caches;
+exports.resolveWrapperToSource = resolveWrapperToSource;
+exports.verifyEvmWrapperIdentity = verifyEvmWrapperIdentity;
+exports.readPushPC20Metadata = readPushPC20Metadata;
+exports.listPC20Deployments = listPC20Deployments;
+exports.getRegisteredWrapper = getRegisteredWrapper;
+exports.discoverPC20Chain = discoverPC20Chain;
+exports.resolvePC20Token = resolvePC20Token;
+const viem_1 = require("viem");
+const enums_1 = require("../../../constants/enums");
+const chain_1 = require("../../../constants/chain");
+const abi_1 = require("../../../constants/abi");
+const helpers_1 = require("../helpers");
+const chain_namespace_1 = require("./chain-namespace");
+const address_codec_1 = require("./address-codec");
+const errors_1 = require("./errors");
+// ---------------------------------------------------------------------------
+// Client plumbing
+// ---------------------------------------------------------------------------
+/**
+ * Instrumentation for the round-trip budget assertion. Incremented once per
+ * network round trip (a batch counts as one, which is the whole point).
+ */
+exports.__readCount = { n: 0 };
+const clientCache = new Map();
+/**
+ * Why JSON-RPC batching rather than Multicall3.
+ *
+ * Every PC20 registry read targets UniversalCore on Push Chain, so batching is
+ * what keeps `getPC20Address` at one round trip instead of one per chain. The
+ * obvious tool is `client.multicall()` — but **Multicall3 is not deployed on
+ * Push Chain**, so that path fails outright with "multicallAddress is
+ * required". Verified against Donut: no code at
+ * `0xcA11bde05977b3631167028862bE2a173976CA11`.
+ *
+ * viem's transport-level `batch` option achieves the same thing a layer lower:
+ * concurrent `eth_call`s issued in the same tick are coalesced into a single
+ * JSON-RPC batch request over one HTTP round trip. No contract required, and it
+ * works identically on chains that do have Multicall3.
+ */
+const BATCH_TRANSPORT_OPTS = { batch: { wait: 0 } };
+function rpcFor(chain, opts) {
+    const override = opts.rpcUrls?.[chain]?.[0];
+    const fallback = chain_1.CHAIN_INFO[chain]?.defaultRPC?.[0];
+    const url = override ?? fallback;
+    if (!url) {
+        throw new errors_1.UnsupportedPC20DestinationError({
+            chain: String(chain),
+            hint: 'No RPC URL configured for this chain. Pass one via `rpcUrls`.',
+        });
+    }
+    return url;
+}
+function clientFor(chain, opts) {
+    const url = rpcFor(chain, opts);
+    const key = `${chain}:${url}`;
+    let client = clientCache.get(key);
+    if (!client) {
+        client = (0, viem_1.createPublicClient)({
+            transport: (0, viem_1.http)(url, BATCH_TRANSPORT_OPTS),
+        });
+        clientCache.set(key, client);
+    }
+    return client;
+}
+/**
+ * Read several contract calls in one network round trip.
+ *
+ * Individual `readContract` calls issued together in the same tick are coalesced
+ * by the batching transport (see {@link BATCH_TRANSPORT_OPTS}). `Promise.all`
+ * dispatches them synchronously, which is what puts them in the same batch
+ * window — awaiting them one at a time would silently become N round trips.
+ *
+ * Failures are captured per call rather than thrown, because optional identity
+ * probes such as `CHAIN_NAMESPACE()` are expected to revert on ordinary ERC-20s.
+ * Callers interpret each result individually via {@link unwrap}.
+ */
+async function batchRead(client, contracts) {
+    exports.__readCount.n += 1;
+    return Promise.all(contracts.map((c) => client
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        .readContract(c)
+        .then((result) => ({ status: 'success', result }))
+        .catch((error) => ({ status: 'failure', error }))));
+}
+function unwrap(entry) {
+    return entry?.status === 'success' ? entry.result : undefined;
+}
+// ---------------------------------------------------------------------------
+// UniversalCore address
+// ---------------------------------------------------------------------------
+const universalCoreCache = new Map();
+/**
+ * Resolve UniversalCore through the UGPC precompile, matching how
+ * `gas-calculator.queryOutboundGasFee` does it. Cached per network — the
+ * precompile's `universalCore` pointer does not move within a session.
+ */
+async function getUniversalCoreAddress(opts) {
+    const cached = universalCoreCache.get(opts.network);
+    if (cached)
+        return cached;
+    const pushChain = (0, helpers_1.getPushChainForNetwork)(opts.network);
+    const client = clientFor(pushChain, opts);
+    exports.__readCount.n += 1;
+    const address = (await client.readContract({
+        address: (0, helpers_1.getUniversalGatewayPCAddress)(),
+        abi: abi_1.UNIVERSAL_GATEWAY_PC,
+        functionName: 'universalCore',
+        args: [],
+    }));
+    universalCoreCache.set(opts.network, address);
+    return address;
+}
+// ---------------------------------------------------------------------------
+// Positive-only caches
+// ---------------------------------------------------------------------------
+/** wrapper → Push source. Positive entries only; see the cache policy above. */
+const wrapperToSourceCache = new Map();
+/** Push token → validated metadata. Positive entries only. */
+const metadataCache = new Map();
+/** `(network, chain, address)` pairs that have passed Tier B this session. */
+const tierBVerified = new Set();
+const cacheKey = (network, chain, address) => `${network}:${chain}:${address.toLowerCase()}`;
+/** Test seam. Never call from product code — it would drop verified Tier B state. */
+function __clearPC20Caches() {
+    wrapperToSourceCache.clear();
+    metadataCache.clear();
+    tierBVerified.clear();
+    universalCoreCache.clear();
+    clientCache.clear();
+    exports.__readCount.n = 0;
+}
+// ---------------------------------------------------------------------------
+// Tier A — registry forward/reverse agreement
+// ---------------------------------------------------------------------------
+/**
+ * Resolve an external wrapper to its canonical Push-native source.
+ *
+ * One multicall: `getPC20Source(wrapper, ns)` and, in the same batch, the
+ * reverse `getPC20Wrapper` cannot be issued because it depends on the source.
+ * The reverse read is therefore a second round trip — this is the "2 sequential
+ * round trips" in the budget, and it is not collapsible: the registry has no
+ * combined accessor.
+ *
+ * @throws {PC20WrapperNotRegisteredError} when the wrapper is unknown.
+ * @throws {PC20RegistryMismatchError} when forward and reverse disagree.
+ */
+async function resolveWrapperToSource(chain, address, opts) {
+    const namespace = (0, chain_namespace_1.chainToNamespace)(chain);
+    const rawWrapper = (0, address_codec_1.pc20AddressToBytes32)(chain, address);
+    const key = cacheKey(opts.network, chain, address);
+    const cached = wrapperToSourceCache.get(key);
+    if (cached && !opts.bypassCache) {
+        return { pushAddress: cached, chainNamespace: namespace, rawWrapper };
+    }
+    const core = await getUniversalCoreAddress(opts);
+    const pushClient = clientFor((0, helpers_1.getPushChainForNetwork)(opts.network), opts);
+    const [sourceEntry] = await batchRead(pushClient, [
+        {
+            address: core,
+            abi: abi_1.UNIVERSAL_CORE_EVM,
+            functionName: 'getPC20Source',
+            args: [rawWrapper, namespace],
+        },
+    ]);
+    const source = unwrap(sourceEntry);
+    if (!source || !source[1] || source[0] === '0x0000000000000000000000000000000000000000') {
+        throw new errors_1.PC20WrapperNotRegisteredError({
+            chain: String(chain),
+            address,
+            chainNamespace: namespace,
+        });
+    }
+    const pushAddress = (0, viem_1.getAddress)(source[0]);
+    // Reverse check. A stale or half-written entry would otherwise unlock the
+    // wrong Push token on burn.
+    const [wrapperEntry] = await batchRead(pushClient, [
+        {
+            address: core,
+            abi: abi_1.UNIVERSAL_CORE_EVM,
+            functionName: 'getPC20Wrapper',
+            args: [pushAddress, namespace],
+        },
+    ]);
+    const reverse = unwrap(wrapperEntry);
+    if (!reverse || (0, address_codec_1.isZeroBytes32)(reverse[0]) || reverse[0].toLowerCase() !== rawWrapper.toLowerCase()) {
+        throw new errors_1.PC20RegistryMismatchError({
+            chain: String(chain),
+            address,
+            chainNamespace: namespace,
+            resolvedWrapper: reverse && !(0, address_codec_1.isZeroBytes32)(reverse[0])
+                ? (0, address_codec_1.pc20Bytes32ToAddress)(chain, reverse[0])
+                : undefined,
+        });
+    }
+    wrapperToSourceCache.set(key, pushAddress);
+    return { pushAddress, chainNamespace: namespace, rawWrapper };
+}
+// ---------------------------------------------------------------------------
+// Tier B — live factory identity (EVM)
+// ---------------------------------------------------------------------------
+/**
+ * Verify the live external gateway will actually take the PC20 burn path for
+ * this wrapper, and that its factory is the one UniversalCore knows about.
+ *
+ * Two multicalls: the gateway's factory pointer must be read before the
+ * factory-scoped calls can be addressed.
+ *
+ * @throws {PC20FactoryMismatchError} on any identity disagreement.
+ */
+async function verifyEvmWrapperIdentity(chain, address, pushAddress, opts) {
+    const key = cacheKey(opts.network, chain, address);
+    if (!opts.strict && tierBVerified.has(key))
+        return;
+    const namespace = (0, chain_namespace_1.chainToNamespace)(chain);
+    const gateway = chain_1.UNIVERSAL_GATEWAY_ADDRESSES[chain];
+    if (!gateway) {
+        throw new errors_1.UnsupportedPC20DestinationError({
+            chain: String(chain),
+            chainNamespace: namespace,
+            hint: 'No universal gateway address is configured for this chain.',
+        });
+    }
+    const core = await getUniversalCoreAddress(opts);
+    const pushClient = clientFor((0, helpers_1.getPushChainForNetwork)(opts.network), opts);
+    const extClient = clientFor(chain, opts);
+    // Reference factory to compare the gateway against. The deployed
+    // UniversalCore does not expose `pc20FactoryByChain` (chain-team decision:
+    // the token mappings are the supported registry surface), so the standing
+    // reference is the destination Vault's own pointer — the Vault is what
+    // deploys and mints wrappers (`Vault.sol:327`), so gateway-vs-Vault
+    // agreement is the identity that actually matters at settlement. The
+    // registry read stays first, failure-tolerant, for forward compatibility
+    // should a future upgrade add the accessor.
+    const [registryFactoryEntry] = await batchRead(pushClient, [
+        {
+            address: core,
+            abi: abi_1.UNIVERSAL_CORE_EVM,
+            functionName: 'pc20FactoryByChain',
+            args: [namespace],
+        },
+    ]);
+    const registryFactoryRaw = unwrap(registryFactoryEntry);
+    let referenceFactory = registryFactoryRaw && !(0, address_codec_1.isZeroBytes32)(registryFactoryRaw)
+        ? (0, address_codec_1.pc20Bytes32ToAddress)(chain, registryFactoryRaw)
+        : undefined;
+    if (!referenceFactory) {
+        const vault = chain_1.VAULT_ADDRESSES[chain];
+        if (vault) {
+            const [vaultFactoryEntry] = await batchRead(extClient, [
+                {
+                    address: (0, viem_1.getAddress)(vault),
+                    abi: abi_1.VAULT_PC20_FACTORY_EVM,
+                    functionName: 'pc20Factory',
+                    args: [],
+                },
+            ]);
+            const vaultFactory = unwrap(vaultFactoryEntry);
+            if (vaultFactory && vaultFactory !== '0x0000000000000000000000000000000000000000') {
+                referenceFactory = (0, viem_1.getAddress)(vaultFactory);
+            }
+        }
+    }
+    if (!referenceFactory) {
+        throw new errors_1.UnsupportedPC20DestinationError({
+            chain: String(chain),
+            chainNamespace: namespace,
+            hint: 'Neither UniversalCore nor the destination Vault has a PC20 factory ' +
+                'registered for this chain.',
+        });
+    }
+    const [gatewayFactoryEntry, codeEntry] = await Promise.all([
+        batchRead(extClient, [
+            { address: gateway, abi: abi_1.EXTERNAL_GATEWAY_PC20_EVM, functionName: 'pc20Factory', args: [] },
+        ]).then((r) => r[0]),
+        (async () => {
+            exports.__readCount.n += 1;
+            const code = await extClient.getCode({ address: (0, viem_1.getAddress)(address) });
+            return { status: 'success', result: code };
+        })(),
+    ]);
+    const gatewayFactory = unwrap(gatewayFactoryEntry);
+    if (!gatewayFactory || (0, viem_1.getAddress)(gatewayFactory) !== (0, viem_1.getAddress)(referenceFactory)) {
+        throw new errors_1.PC20FactoryMismatchError({
+            chain: String(chain),
+            address,
+            chainNamespace: namespace,
+            gatewayFactory,
+            registryFactory: referenceFactory,
+        });
+    }
+    const code = unwrap(codeEntry);
+    if (!code || code === '0x') {
+        throw new errors_1.PC20FactoryMismatchError({
+            chain: String(chain),
+            address,
+            chainNamespace: namespace,
+            hint: 'No contract is deployed at this wrapper address.',
+        });
+    }
+    // Factory-scoped identity, batched into one round trip.
+    const factory = (0, viem_1.getAddress)(gatewayFactory);
+    const wrapper = (0, viem_1.getAddress)(address);
+    const [isWrapperEntry, wrapperSourceEntry, sourceAssetEntry] = await batchRead(extClient, [
+        { address: factory, abi: abi_1.PC20_FACTORY_EVM, functionName: 'isPC20Wrapper', args: [wrapper] },
+        { address: factory, abi: abi_1.PC20_FACTORY_EVM, functionName: 'wrapperToSource', args: [wrapper] },
+        { address: wrapper, abi: abi_1.PC20_WRAPPER_EVM, functionName: 'SOURCE_ASSET', args: [] },
+    ]);
+    if (unwrap(isWrapperEntry) !== true) {
+        throw new errors_1.PC20FactoryMismatchError({
+            chain: String(chain),
+            address,
+            chainNamespace: namespace,
+            hint: 'The live factory does not recognize this address as a PC20 wrapper.',
+        });
+    }
+    const factorySource = unwrap(wrapperSourceEntry);
+    const immutableSource = unwrap(sourceAssetEntry);
+    for (const [label, value] of [
+        ['factory.wrapperToSource', factorySource],
+        ['wrapper.SOURCE_ASSET', immutableSource],
+    ]) {
+        if (!value || (0, viem_1.getAddress)(value) !== (0, viem_1.getAddress)(pushAddress)) {
+            throw new errors_1.PC20FactoryMismatchError({
+                chain: String(chain),
+                address,
+                chainNamespace: namespace,
+                hint: `${label} does not match the Push source UniversalCore returned.`,
+            });
+        }
+    }
+    tierBVerified.add(key);
+}
+// ---------------------------------------------------------------------------
+// Push-native metadata
+// ---------------------------------------------------------------------------
+/**
+ * Read and validate standard ERC-20 metadata on a Push-native token.
+ *
+ * Every metadata-compatible ERC-20 born on Push Chain is eligible for PC20
+ * export. Synthetic PRC20s expose `CHAIN_NAMESPACE()` and are rejected even
+ * though they also implement the standard metadata functions.
+ */
+async function readPushPC20Metadata(pushAddress, opts) {
+    const pushChain = (0, helpers_1.getPushChainForNetwork)(opts.network);
+    const key = cacheKey(opts.network, pushChain, pushAddress);
+    const cached = metadataCache.get(key);
+    if (cached)
+        return cached;
+    const client = clientFor(pushChain, opts);
+    const [metadataEntries, codeEntry] = await Promise.all([
+        batchRead(client, [
+            { address: pushAddress, abi: abi_1.ERC20_EVM, functionName: 'name', args: [] },
+            { address: pushAddress, abi: abi_1.ERC20_EVM, functionName: 'symbol', args: [] },
+            { address: pushAddress, abi: abi_1.ERC20_EVM, functionName: 'decimals', args: [] },
+            {
+                address: pushAddress,
+                abi: [
+                    {
+                        type: 'function',
+                        name: 'CHAIN_NAMESPACE',
+                        inputs: [],
+                        outputs: [{ name: '', type: 'string' }],
+                        stateMutability: 'view',
+                    },
+                ],
+                functionName: 'CHAIN_NAMESPACE',
+                args: [],
+            },
+        ]),
+        (async () => {
+            exports.__readCount.n += 1;
+            return { status: 'success', result: await client.getCode({ address: pushAddress }) };
+        })(),
+    ]);
+    const code = unwrap(codeEntry);
+    if (!code || code === '0x') {
+        throw new errors_1.InvalidPC20MetadataError('No contract is deployed at this address.', {
+            chain: String(pushChain),
+            address: pushAddress,
+        });
+    }
+    const prc20Namespace = unwrap(metadataEntries[3]);
+    if (typeof prc20Namespace === 'string') {
+        throw new errors_1.PC20ExpectedButPRC20Error({
+            chain: String(pushChain),
+            address: pushAddress,
+            chainNamespace: prc20Namespace,
+        });
+    }
+    const name = unwrap(metadataEntries[0]);
+    const symbol = unwrap(metadataEntries[1]);
+    const decimals = unwrap(metadataEntries[2]);
+    if (name === undefined || symbol === undefined || decimals === undefined) {
+        throw new errors_1.InvalidPC20MetadataError('Token must implement the ERC-20 metadata functions name(), symbol(), and decimals().', { chain: String(pushChain), address: pushAddress });
+    }
+    if (!name || !symbol) {
+        throw new errors_1.InvalidPC20MetadataError('PC20 name and symbol must be non-empty.', {
+            chain: String(pushChain),
+            address: pushAddress,
+        });
+    }
+    const normalizedDecimals = Number(decimals);
+    if (!Number.isInteger(normalizedDecimals) || normalizedDecimals < 0 || normalizedDecimals > 255) {
+        throw new errors_1.InvalidPC20MetadataError('PC20 decimals must be a valid uint8 value.', {
+            chain: String(pushChain),
+            address: pushAddress,
+        });
+    }
+    const validated = {
+        name,
+        symbol,
+        decimals: normalizedDecimals,
+    };
+    metadataCache.set(key, validated);
+    return validated;
+}
+// ---------------------------------------------------------------------------
+// Destination-side lookups
+// ---------------------------------------------------------------------------
+/**
+ * Confirmed wrapper deployments for a Push-native PC20.
+ *
+ * One multicall regardless of chain count — every `getPC20Wrapper` read targets
+ * UniversalCore on Push Chain, so fanning out per chain would be N round trips
+ * to the same endpoint for no reason.
+ *
+ * Returns confirmed deployments only. A predicted first-export address is the
+ * outbound builder's concern, not discovery's.
+ */
+async function listPC20Deployments(pushAddress, opts) {
+    const targets = (opts.chains ?? (0, chain_namespace_1.allExternalChains)()).filter((c) => !(0, chain_namespace_1.isPushChain)(c));
+    if (targets.length === 0)
+        return [];
+    const core = await getUniversalCoreAddress(opts);
+    const client = clientFor((0, helpers_1.getPushChainForNetwork)(opts.network), opts);
+    const namespaces = targets.map((chain) => (0, chain_namespace_1.chainToNamespace)(chain));
+    const results = await batchRead(client, targets.map((_, i) => ({
+        address: core,
+        abi: abi_1.UNIVERSAL_CORE_EVM,
+        functionName: 'getPC20Wrapper',
+        args: [pushAddress, namespaces[i]],
+    })));
+    const deployments = [];
+    targets.forEach((chain, i) => {
+        const value = unwrap(results[i]);
+        if (!value)
+            return;
+        const [rawAddress, deployed] = value;
+        if (!deployed || (0, address_codec_1.isZeroBytes32)(rawAddress))
+            return;
+        deployments.push({
+            chain,
+            chainNamespace: namespaces[i],
+            vm: (0, chain_namespace_1.vmForChain)(chain),
+            address: (0, address_codec_1.pc20Bytes32ToAddress)(chain, rawAddress),
+            rawAddress,
+        });
+    });
+    return deployments;
+}
+/**
+ * Registered wrapper for a Push PC20 on one destination chain.
+ *
+ * `undefined` means not yet deployed — a legitimate state before a first
+ * export, not an error. Callers that need an address for a first export must go
+ * through the prediction path, which verifies against the live factory.
+ */
+async function getRegisteredWrapper(pushAddress, destinationChain, opts) {
+    const [found] = await listPC20Deployments(pushAddress, {
+        ...opts,
+        chains: [destinationChain],
+    });
+    return found;
+}
+// ---------------------------------------------------------------------------
+// Chain discovery (lookup utility only)
+// ---------------------------------------------------------------------------
+/**
+ * Work out which chain an address belongs to, when the caller did not say.
+ *
+ * Used ONLY by the read-only `getPC20Address` utility. The transaction path
+ * never calls this — `funds.token` requires an explicit `chain`, and
+ * `gate.ts` rejects one that disagrees with where the funds actually are. A
+ * wrapper address copied from the wrong chain still fails on send; it merely
+ * resolves informationally on lookup.
+ *
+ * Order is cheapest-first:
+ *   1. narrow candidates by address format (local, free);
+ *   2. try Push-native, which short-circuits with no registry read at all;
+ *   3. probe every remaining namespace in one multicall.
+ *
+ * @throws {PC20AmbiguousAddressError} when several chains claim the address
+ * with different Push sources.
+ */
+async function discoverPC20Chain(address, opts) {
+    const pushChain = (0, helpers_1.getPushChainForNetwork)(opts.network);
+    const looksEvm = /^0x[0-9a-fA-F]{40}$/.test(address);
+    // 2. Push-native short-circuit. Only an EVM-shaped address can be one.
+    if (looksEvm) {
+        try {
+            const pushAddress = (0, viem_1.getAddress)(address);
+            await readPushPC20Metadata(pushAddress, opts);
+            return { chain: pushChain, pushAddress };
+        }
+        catch {
+            // Not a Push-native PC20 — fall through to the external probe.
+        }
+    }
+    // 1. Format narrowing. A hex address cannot be a Solana mint and vice versa,
+    // so probing the other VM's namespaces would be pure waste.
+    const candidates = (0, chain_namespace_1.allExternalChains)().filter((chain) => looksEvm ? (0, chain_namespace_1.vmForChain)(chain) === enums_1.VM.EVM : (0, chain_namespace_1.vmForChain)(chain) === enums_1.VM.SVM);
+    if (candidates.length === 0)
+        return null;
+    // 3. One multicall across every candidate namespace — all these reads hit
+    // UniversalCore on Push, so chain count costs nothing.
+    const core = await getUniversalCoreAddress(opts);
+    const client = clientFor(pushChain, opts);
+    const probes = candidates.flatMap((chain) => {
+        try {
+            return [
+                {
+                    chain,
+                    namespace: (0, chain_namespace_1.chainToNamespace)(chain),
+                    raw: (0, address_codec_1.pc20AddressToBytes32)(chain, address),
+                },
+            ];
+        }
+        catch {
+            // Address is malformed for this chain's VM — not a candidate.
+            return [];
+        }
+    });
+    if (probes.length === 0)
+        return null;
+    const results = await batchRead(client, probes.map((p) => ({
+        address: core,
+        abi: abi_1.UNIVERSAL_CORE_EVM,
+        functionName: 'getPC20Source',
+        args: [p.raw, p.namespace],
+    })));
+    const matches = [];
+    probes.forEach((p, i) => {
+        const value = unwrap(results[i]);
+        if (!value)
+            return;
+        const [source, known] = value;
+        if (!known || source === '0x0000000000000000000000000000000000000000')
+            return;
+        matches.push({ chain: p.chain, pushAddress: (0, viem_1.getAddress)(source) });
+    });
+    if (matches.length === 0)
+        return null;
+    // Several chains can legitimately hold the same wrapper address only if they
+    // resolve to the same token. Different sources means we cannot answer.
+    const distinct = new Set(matches.map((m) => m.pushAddress.toLowerCase()));
+    if (distinct.size > 1) {
+        throw new errors_1.PC20AmbiguousAddressError(address, matches.map((m) => ({ chain: String(m.chain), pushAddress: m.pushAddress })));
+    }
+    return matches[0];
+}
+// ---------------------------------------------------------------------------
+// Top-level resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a `{ chain, address }` PC20 reference into everything the execution
+ * path needs, exactly once per transaction.
+ *
+ * `expectedChain` is where the funds actually are — the signer's chain for a
+ * direct external route, `params.from.chain` for a CEA-origin route, the Push
+ * chain for an export. Chain-ownership validation is the caller's job because
+ * only the caller knows which of those applies; this function assumes it has
+ * already passed.
+ */
+async function resolvePC20Token(chain, address, opts) {
+    const pushChain = (0, helpers_1.getPushChainForNetwork)(opts.network);
+    // Export: the caller named a Push-native token.
+    if ((0, chain_namespace_1.isPushChain)(chain)) {
+        const pushAddress = (0, viem_1.getAddress)(address);
+        const meta = await readPushPC20Metadata(pushAddress, opts);
+        return {
+            direction: 'export',
+            originChain: pushChain,
+            originAddress: pushAddress,
+            pushAddress,
+            name: meta.name,
+            symbol: meta.symbol,
+            decimals: meta.decimals,
+        };
+    }
+    // Import: the caller named an external wrapper.
+    const { pushAddress, chainNamespace } = await resolveWrapperToSource(chain, address, opts);
+    if ((0, chain_namespace_1.vmForChain)(chain) === enums_1.VM.EVM && (opts.tierB || opts.strict)) {
+        await verifyEvmWrapperIdentity(chain, address, pushAddress, opts);
+    }
+    const meta = await readPushPC20Metadata(pushAddress, opts);
+    return {
+        direction: 'import',
+        originChain: chain,
+        originAddress: (0, chain_namespace_1.vmForChain)(chain) === enums_1.VM.EVM ? (0, viem_1.getAddress)(address) : address,
+        pushAddress,
+        name: meta.name,
+        symbol: meta.symbol,
+        decimals: meta.decimals,
+        wrapperAddress: (0, chain_namespace_1.vmForChain)(chain) === enums_1.VM.EVM ? (0, viem_1.getAddress)(address) : address,
+        chainNamespace,
+    };
+}
+//# sourceMappingURL=resolver.js.map