@pushchain/core 6.0.20 → 6.0.21

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

@@ -0,0 +1,412 @@
+"use strict";
+/**
+ * Push-to-external PC20 export.
+ *
+ * Three things differ from the PRC20 outbound path, and all three are
+ * load-bearing:
+ *
+ *   1. The payload carries the `PC20` selector plus the destination wrapper's
+ *      metadata. The SDK builds this — unlike inbound, where the external
+ *      gateway prepends the selector.
+ *   2. The gas quote comes from `getPC20ExportGasAndFees`, not
+ *      `getOutboundTxGasAndFees`. Only the former knows about the first-export
+ *      deployment overhead.
+ *   3. The source token IS approved to UGPC. This is the mirror image of
+ *      inbound: an export locks the Push-native token into VaultPC20, so the
+ *      gateway must be able to pull it.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PC20_SYMBOL_BYTES = exports.MAX_PC20_NAME_BYTES = exports.PC20_SELECTOR = void 0;
+exports.buildPC20ExportPayload = buildPC20ExportPayload;
+exports.assertMetadataFitsFactoryLimits = assertMetadataFitsFactoryLimits;
+exports.quotePC20Export = quotePC20Export;
+exports.queryPC20OutboundGasFee = queryPC20OutboundGasFee;
+exports.resolveDestinationWrapper = resolveDestinationWrapper;
+exports.validatePC20Export = validatePC20Export;
+const viem_1 = require("viem");
+const abi_1 = require("../../../constants/abi");
+const chain_1 = require("../../../constants/chain");
+const context_1 = require("../context");
+const chain_namespace_1 = require("./chain-namespace");
+const resolver_1 = require("./resolver");
+const address_codec_1 = require("./address-codec");
+const errors_1 = require("./errors");
+/** `bytes4(ascii("PC20"))`. Must match the chain's PC20 route selector. */
+exports.PC20_SELECTOR = '0x50433230';
+/**
+ * Factory limits on the metadata forwarded to the destination.
+ *
+ * Mirrors `PC20Factory.MAX_NAME_LENGTH` / `MAX_SYMBOL_LENGTH`. Pinned by test
+ * against the reference contract revision — exceeding them reverts on the
+ * destination chain, long after the source token has been locked, so the SDK
+ * fails fast on the Push side instead.
+ */
+exports.MAX_PC20_NAME_BYTES = 64;
+exports.MAX_PC20_SYMBOL_BYTES = 32;
+/**
+ * Build the outbound payload:
+ *
+ *     PC20_SELECTOR
+ *       || abi.encode(destChainNamespace, name, symbol, decimals)
+ *       || rawDestinationUserData
+ *
+ * The user data is appended raw, not ABI-encoded into the tuple — the
+ * destination settlement path strips the fixed-width prefix and forwards the
+ * remainder verbatim.
+ */
+function buildPC20ExportPayload(params) {
+    const namespace = (0, chain_namespace_1.chainToNamespace)(params.destinationChain);
+    assertMetadataFitsFactoryLimits(params.name, params.symbol);
+    const metadata = (0, viem_1.encodeAbiParameters)([
+        { name: 'destChainNamespace', type: 'string' },
+        { name: 'name', type: 'string' },
+        { name: 'symbol', type: 'string' },
+        { name: 'decimals', type: 'uint8' },
+    ], [namespace, params.name, params.symbol, params.decimals]);
+    const userData = params.destinationUserData ?? '0x';
+    return (0, viem_1.encodePacked)(['bytes4', 'bytes', 'bytes'], [exports.PC20_SELECTOR, metadata, userData]);
+}
+/**
+ * Reject metadata the destination factory would refuse.
+ *
+ * Byte length, not character count — a multi-byte symbol can pass a `.length`
+ * check and still revert on chain.
+ */
+function assertMetadataFitsFactoryLimits(name, symbol) {
+    const nameBytes = new TextEncoder().encode(name).length;
+    const symbolBytes = new TextEncoder().encode(symbol).length;
+    if (nameBytes === 0 || symbolBytes === 0) {
+        throw new errors_1.InvalidPC20MetadataError('PC20 name and symbol must be non-empty.');
+    }
+    if (nameBytes > exports.MAX_PC20_NAME_BYTES) {
+        throw new errors_1.InvalidPC20MetadataError(`PC20 name is ${nameBytes} bytes; the destination factory allows ${exports.MAX_PC20_NAME_BYTES}.`);
+    }
+    if (symbolBytes > exports.MAX_PC20_SYMBOL_BYTES) {
+        throw new errors_1.InvalidPC20MetadataError(`PC20 symbol is ${symbolBytes} bytes; the destination factory allows ${exports.MAX_PC20_SYMBOL_BYTES}.`);
+    }
+}
+/**
+ * Quote a PC20 export.
+ *
+ * ## Why the deployment margin is unconditional
+ *
+ * `isFirstExport` is read before the transaction is included, so it is a
+ * time-of-check/time-of-use value. Two things can happen in between:
+ *
+ *   - quoted `true`, another export deploys the wrapper first → the quote
+ *     over-funds. Harmless.
+ *   - quoted `false`, the wrapper turns out to be absent at execution (registry
+ *     rollback, factory reconfiguration, reorg) → the quote under-funds by
+ *     `pc20DeploymentGasOverhead` and the transfer strands on the destination
+ *     with the source token already locked.
+ *
+ * The second is unrecoverable without operator intervention, so the ceiling
+ * always covers a deployment. `maxPCForGas` is a ceiling rather than a charge —
+ * the unspent remainder is not consumed — so the only cost is a higher required
+ * balance. `gasLimitUsed` itself is passed through unchanged.
+ */
+async function quotePC20Export(ctx, pushPC20, destinationChain, gasLimit, opts) {
+    const namespace = (0, chain_namespace_1.chainToNamespace)(destinationChain);
+    const core = await (0, resolver_1.getUniversalCoreAddress)(opts);
+    const result = await ctx.pushClient.readContract({
+        address: core,
+        abi: abi_1.UNIVERSAL_CORE_EVM,
+        functionName: 'getPC20ExportGasAndFees',
+        args: [namespace, gasLimit, pushPC20],
+    });
+    const [gasToken, gasFee, protocolFee, gasPrice, chainNamespace, gasLimitUsed, isFirstExport] = result;
+    const overhead = await ctx.pushClient.readContract({
+        address: core,
+        abi: abi_1.UNIVERSAL_CORE_EVM,
+        functionName: 'pc20DeploymentGasOverhead',
+        args: [namespace],
+    });
+    // Add the overhead even when the quote already included it. Double-counting
+    // raises a ceiling that is never fully spent; under-counting strands funds.
+    const gasLimitCeiling = gasLimitUsed + overhead;
+    (0, context_1.printLog)(ctx, `quotePC20Export — namespace=${chainNamespace}, gasLimitUsed=${gasLimitUsed}, ` +
+        `isFirstExport=${isFirstExport}, overhead=${overhead}, ceiling=${gasLimitCeiling}`);
+    return {
+        gasToken,
+        gasFee,
+        protocolFee,
+        gasPrice,
+        chainNamespace,
+        gasLimitUsed,
+        isFirstExport,
+        gasLimitCeiling,
+    };
+}
+/**
+ * PC20 quote adapted to the shape `queryOutboundGasFee` returns, so the shared
+ * R2 gas-sizing code downstream is untouched.
+ *
+ * `nativeValueForGas` and `sizing` are intentionally absent — the caller's
+ * native-PC swap sizing consumes `gasFee`/`protocolFee`/`gasPrice` the same way
+ * it does for PRC20. What differs is only where the numbers came from.
+ */
+async function queryPC20OutboundGasFee(ctx, pushPC20, gasLimit, destinationChain) {
+    const opts = {
+        network: ctx.pushNetwork,
+        rpcUrls: ctx.rpcUrls,
+    };
+    const quote = await quotePC20Export(ctx, pushPC20, destinationChain, gasLimit, opts);
+    const universalCoreAddress = await (0, resolver_1.getUniversalCoreAddress)(opts);
+    return {
+        gasToken: quote.gasToken,
+        gasFee: quote.gasFee,
+        protocolFee: quote.protocolFee,
+        gasPrice: quote.gasPrice,
+        gasLimitUsed: quote.gasLimitUsed,
+        universalCoreAddress,
+        isFirstExport: quote.isFirstExport,
+        gasLimitCeiling: quote.gasLimitCeiling,
+        nativeValueForGas: BigInt(0),
+    };
+}
+/**
+ * Resolve the wrapper address the destination transfer should target.
+ *
+ * For a repeat export this is the registered wrapper. For a first export the
+ * wrapper does not exist yet, but the destination settlement mints into the CEA
+ * and then executes user data — so the SDK still needs the address in order to
+ * build the transfer that delivers funds to the actual recipient.
+ *
+ * ## Funds-at-risk ordering
+ *
+ * This must run BEFORE the source-token approval. By the time the outbound is
+ * submitted the token is locked in VaultPC20; a wrapper address that turns out
+ * to be wrong then means a transfer to a dead address with no way back except
+ * the revert path. Every failure here therefore throws rather than falling back
+ * to a guess.
+ *
+ * The prediction is read from the live factory's own `computeWrapperAddress`,
+ * which derives from its own `type(PC20Wrapper).creationCode`. That is why the
+ * SDK does not mirror the CREATE2 derivation locally: a mirrored init-code hash
+ * can drift from the deployed bytecode, while asking the factory cannot.
+ *
+ * ## Which factory to ask
+ *
+ * Two contracts hold a `pc20Factory` pointer, and they are not the same slot:
+ *
+ *   - `UniversalCore.pc20FactoryByChain(ns)` on Push — the protocol's registry
+ *     mirror, and the value Tier B cross-checks against.
+ *   - `Vault.pc20Factory()` on the destination chain — the contract that
+ *     actually calls `deployWrapper` at settlement (`Vault.sol:327`).
+ *
+ * The Vault is therefore the authoritative answer to "where will the wrapper
+ * land"; the registry copy can go stale without settlement noticing. The
+ * deployed UniversalCore does not expose `pc20FactoryByChain` — by chain-team
+ * decision the token mappings plus the Vault's own pointer are the supported
+ * surface — so the Vault read is the standing path. The registry attempt is
+ * kept first purely for forward compatibility: if a future upgrade adds the
+ * accessor, the two become cross-checked with no SDK change.
+ */
+async function resolveDestinationWrapper(ctx, pushPC20, destinationChain, opts) {
+    const namespace = (0, chain_namespace_1.chainToNamespace)(destinationChain);
+    const registered = await (0, resolver_1.getRegisteredWrapper)(pushPC20, destinationChain, opts);
+    if (registered) {
+        return { address: registered.address, deployed: true };
+    }
+    if ((0, chain_namespace_1.vmForChain)(destinationChain) !== 'EVM') {
+        // SVM: the wrapper is the deterministic `pc20_mint` PDA — a pure local
+        // derivation, so unlike EVM there is no factory to consult and prediction
+        // cannot drift from deployment (the program derives from the same seeds,
+        // state.rs:13). `deployed` is decided by whether the mint account exists.
+        return resolveSvmDestinationWrapper(pushPC20, destinationChain, opts);
+    }
+    // First export — predict from the live factory.
+    const { factory, source } = await resolveDestinationFactory(ctx, destinationChain, opts);
+    (0, context_1.printLog)(ctx, `resolveDestinationWrapper — factory ${factory} (via ${source})`);
+    let predicted;
+    try {
+        predicted = await readPredictedWrapper(ctx, factory, pushPC20, destinationChain, opts);
+    }
+    catch (err) {
+        throw new errors_1.PC20WrapperPredictionUnavailableError({
+            chain: String(destinationChain),
+            address: factory,
+            chainNamespace: namespace,
+            hint: 'The destination factory could not be reached to compute the wrapper ' +
+                'address. Aborted before approval, so no funds are locked. ' +
+                `(${err instanceof Error ? err.message : String(err)})`,
+        });
+    }
+    return { address: (0, viem_1.getAddress)(predicted), deployed: false };
+}
+/**
+ * SVM destination wrapper: the deterministic `pc20_mint` PDA.
+ *
+ * Derived locally from `[b"pc20_mint", source_asset_20]` under the gateway
+ * program (mirrors `pc20.rs` / validated against the deployed devnet binary,
+ * which contains the same seed strings). Existence of the mint account is what
+ * distinguishes a repeat export from a first one — settlement creates the mint
+ * idempotently either way, so a wrong `deployed` flag here costs gas headroom,
+ * not funds.
+ */
+async function resolveSvmDestinationWrapper(pushPC20, destinationChain, opts) {
+    const { PublicKey, Connection } = await Promise.resolve().then(() => __importStar(require('@solana/web3.js')));
+    const { SVM_GATEWAY_IDL } = await Promise.resolve().then(() => __importStar(require('../../../constants/abi')));
+    const { predictSvmWrapperMint } = await Promise.resolve().then(() => __importStar(require('./svm')));
+    const programId = new PublicKey(SVM_GATEWAY_IDL.address);
+    const mint = predictSvmWrapperMint(programId, pushPC20);
+    const rpc = opts.rpcUrls?.[destinationChain]?.[0] ??
+        chain_1.CHAIN_INFO[destinationChain]?.defaultRPC?.[0];
+    if (!rpc) {
+        throw new errors_1.UnsupportedPC20DestinationError({
+            chain: String(destinationChain),
+            hint: 'No RPC URL configured for this chain.',
+        });
+    }
+    let deployed = false;
+    try {
+        const info = await new Connection(rpc).getAccountInfo(mint);
+        deployed = info !== null;
+    }
+    catch (err) {
+        // The PDA derivation is still valid; only the deployed flag is unknown.
+        // Downstream decisions (gas headroom, whether recipient-ATA delivery is
+        // even possible) hinge on that flag, so guessing is worse than aborting —
+        // and this runs pre-approval, so aborting locks nothing.
+        throw new errors_1.PC20WrapperPredictionUnavailableError({
+            chain: String(destinationChain),
+            address: mint.toBase58(),
+            hint: 'Could not query the Solana RPC to check mint existence. Aborted ' +
+                `before approval, so no funds are locked. (${err instanceof Error ? err.message : String(err)})`,
+        });
+    }
+    return { address: mint.toBase58(), deployed };
+}
+/**
+ * Find the factory that will deploy the destination wrapper.
+ *
+ * Prefers UniversalCore's registry so the value stays cross-checked against the
+ * protocol's own view. Falls back to the destination `Vault.pc20Factory()` —
+ * the contract that actually calls `deployWrapper` — when the registry has no
+ * entry or does not expose the accessor at all.
+ *
+ * The fallback is not a guess. The Vault is strictly closer to the truth for
+ * this question: settlement reads *its* pointer, so a wrapper predicted from it
+ * cannot disagree with where the wrapper is deployed, whereas a stale registry
+ * mirror can.
+ */
+async function resolveDestinationFactory(ctx, destinationChain, opts) {
+    const namespace = (0, chain_namespace_1.chainToNamespace)(destinationChain);
+    const core = await (0, resolver_1.getUniversalCoreAddress)(opts);
+    const factoryRaw = await ctx.pushClient
+        .readContract({
+        address: core,
+        abi: abi_1.UNIVERSAL_CORE_EVM,
+        functionName: 'pc20FactoryByChain',
+        args: [namespace],
+    })
+        .catch(() => undefined);
+    if (factoryRaw && !(0, address_codec_1.isZeroBytes32)(factoryRaw)) {
+        return {
+            factory: (0, viem_1.getAddress)((0, address_codec_1.pc20Bytes32ToAddress)(destinationChain, factoryRaw)),
+            source: 'registry',
+        };
+    }
+    const vault = chain_1.VAULT_ADDRESSES[destinationChain];
+    if (!vault) {
+        throw new errors_1.UnsupportedPC20DestinationError({
+            chain: String(destinationChain),
+            chainNamespace: namespace,
+            hint: 'UniversalCore has no PC20 factory registered for this chain, and no ' +
+                'Vault address is configured to fall back to.',
+        });
+    }
+    const client = destinationClient(destinationChain, opts);
+    const vaultFactory = (await client
+        .readContract({
+        address: (0, viem_1.getAddress)(vault),
+        abi: abi_1.VAULT_PC20_FACTORY_EVM,
+        functionName: 'pc20Factory',
+        args: [],
+    })
+        .catch(() => undefined));
+    if (!vaultFactory || vaultFactory === '0x0000000000000000000000000000000000000000') {
+        throw new errors_1.UnsupportedPC20DestinationError({
+            chain: String(destinationChain),
+            chainNamespace: namespace,
+            hint: 'Neither UniversalCore nor the destination Vault has a PC20 factory set.',
+        });
+    }
+    return { factory: (0, viem_1.getAddress)(vaultFactory), source: 'vault' };
+}
+/** Public client for a destination chain, honouring `rpcUrls` overrides. */
+function destinationClient(chain, opts) {
+    const rpc = opts.rpcUrls?.[chain]?.[0] ?? chain_1.CHAIN_INFO[chain]?.defaultRPC?.[0];
+    if (!rpc) {
+        throw new errors_1.UnsupportedPC20DestinationError({
+            chain: String(chain),
+            hint: 'No RPC URL configured for this chain.',
+        });
+    }
+    return (0, viem_1.createPublicClient)({ transport: (0, viem_1.http)(rpc) });
+}
+async function readPredictedWrapper(ctx, factory, pushPC20, destinationChain, opts) {
+    const { createPublicClient, http } = await Promise.resolve().then(() => __importStar(require('viem')));
+    const rpc = opts.rpcUrls?.[destinationChain]?.[0] ??
+        (await Promise.resolve().then(() => __importStar(require('../../../constants/chain')))).CHAIN_INFO[destinationChain]
+            ?.defaultRPC?.[0];
+    if (!rpc) {
+        throw new Error(`No RPC configured for ${destinationChain}`);
+    }
+    const client = createPublicClient({ transport: http(rpc) });
+    const predicted = (await client.readContract({
+        address: factory,
+        abi: abi_1.PC20_FACTORY_EVM,
+        functionName: 'computeWrapperAddress',
+        args: [pushPC20],
+    }));
+    if (!predicted || predicted === '0x0000000000000000000000000000000000000000') {
+        throw new Error('factory returned the zero address');
+    }
+    (0, context_1.printLog)(ctx, `resolveDestinationWrapper — predicted wrapper ${predicted} via factory ${factory}`);
+    return predicted;
+}
+// ---------------------------------------------------------------------------
+// Validation entry point
+// ---------------------------------------------------------------------------
+/**
+ * Everything that must hold before a PC20 export approves or broadcasts.
+ *
+ * Ordered so the cheapest, most likely failures come first and nothing that
+ * touches funds runs until all of them pass.
+ */
+async function validatePC20Export(ctx, resolved, destinationChain, opts) {
+    const namespace = (0, chain_namespace_1.chainToNamespace)(destinationChain);
+    assertMetadataFitsFactoryLimits(resolved.name, resolved.symbol);
+    // The destination factory is deliberately NOT read here. A repeat export
+    // targets an already-registered wrapper and never needs it, so requiring it
+    // up front would fail exports that are perfectly safe. Only the first-export
+    // prediction path depends on the factory, and `resolveDestinationWrapper`
+    // reads it there — where a failure correctly aborts before approval.
+    const wrapper = await resolveDestinationWrapper(ctx, resolved.pushAddress, destinationChain, opts);
+    return { wrapper, namespace };
+}
+//# sourceMappingURL=export.js.map

package/src/lib/orchestrator/internals/pc20/gate.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The PC20 gate.
+ *
+ * `funds.token` publicly accepts a `MoveableToken` or a `PC20TokenReference`.
+ * Exactly one place decides which branch a transaction takes, and it is here.
+ * Everything downstream types against `LegacyExecuteParams`, whose `funds.token`
+ * is an `InternalFundsToken` and whose `_pc20` descriptor is authoritative for
+ * PC20 behavior. A PC20 reference reaching a builder unresolved is a compile
+ * error, not a runtime `undefined`.
+ *
+ * Resolution happens once, here, before approvals, fee calculation, or any
+ * broadcast — so a chain/address mismatch costs the caller nothing.
+ */
+import type { ExecuteParams, LegacyExecuteParams } from '../../orchestrator.types';
+import type { OrchestratorContext } from '../context';
+import { type ResolvedPC20 } from './resolver';
+type PC20AwareParams = {
+    funds?: {
+        amount: bigint;
+    };
+    _pc20?: ResolvedPC20;
+};
+/** True when this transaction's funds are a PC20 reference. */
+export declare function isPC20Transaction(params: ExecuteParams): boolean;
+/** True only for a resolved, funds-bearing external-wrapper burn. */
+export declare function isPC20ImportWithFunds(params: PC20AwareParams): boolean;
+/**
+ * Fail closed before a wrapper burn can be broadcast without a real user
+ * payload behind the PC20 selector.
+ */
+export declare function assertPC20ImportHasPayload(params: PC20AwareParams, hasPayload: boolean, path: string): void;
+/**
+ * Validate chain ownership and resolve the PC20 against the live registry.
+ *
+ * Returns params shaped for the shared execution path, with `_pc20` carrying
+ * the resolved descriptor. The caller's token object is never mutated.
+ */
+export declare function resolvePC20Funds(ctx: OrchestratorContext, params: ExecuteParams): Promise<LegacyExecuteParams>;
+/**
+ * Narrow `ExecuteParams` to the shared execution shape.
+ *
+ * Synchronous counterpart used where no PC20 resolution is possible or needed.
+ * Throws if a PC20 reference reaches it, which would mean the async gate was
+ * skipped.
+ */
+export declare function assertLegacyFunds(params: ExecuteParams): LegacyExecuteParams;
+/**
+ * Re-verify a prepared PC20 transaction at send time.
+ *
+ * A prepared tx is built now and broadcast later. Between the two, the registry
+ * can change in a way that matters:
+ *
+ *   - a first export lands and creates a wrapper mapping that did not exist,
+ *     turning a predicted destination address into a registered one;
+ *   - a factory is reconfigured, invalidating the identity the payload assumed.
+ *
+ * Only the critical reads are repeated — forward/reverse registry agreement and
+ * the Push source binding. Re-running the whole Tier B sweep on every send of a
+ * prepared tx would cost more than it protects.
+ *
+ * Throws if the resolved Push source has moved. That is not recoverable by
+ * retrying: the signed payload already encodes the old source.
+ */
+export declare function revalidatePreparedPC20(ctx: OrchestratorContext, prepared: LegacyExecuteParams): Promise<void>;
+/** Resolve PC20 funds when present; otherwise pass the legacy shape through. */
+export declare function gateFunds(ctx: OrchestratorContext, params: ExecuteParams): Promise<LegacyExecuteParams>;
+export {};

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

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * The PC20 gate.
+ *
+ * `funds.token` publicly accepts a `MoveableToken` or a `PC20TokenReference`.
+ * Exactly one place decides which branch a transaction takes, and it is here.
+ * Everything downstream types against `LegacyExecuteParams`, whose `funds.token`
+ * is an `InternalFundsToken` and whose `_pc20` descriptor is authoritative for
+ * PC20 behavior. A PC20 reference reaching a builder unresolved is a compile
+ * error, not a runtime `undefined`.
+ *
+ * Resolution happens once, here, before approvals, fee calculation, or any
+ * broadcast — so a chain/address mismatch costs the caller nothing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPC20Transaction = isPC20Transaction;
+exports.isPC20ImportWithFunds = isPC20ImportWithFunds;
+exports.assertPC20ImportHasPayload = assertPC20ImportHasPayload;
+exports.resolvePC20Funds = resolvePC20Funds;
+exports.assertLegacyFunds = assertLegacyFunds;
+exports.revalidatePreparedPC20 = revalidatePreparedPC20;
+exports.gateFunds = gateFunds;
+const orchestrator_types_1 = require("../../orchestrator.types");
+const helpers_1 = require("../helpers");
+const resolver_1 = require("./resolver");
+const chain_namespace_1 = require("./chain-namespace");
+const errors_1 = require("./errors");
+/** True when this transaction's funds are a PC20 reference. */
+function isPC20Transaction(params) {
+    return (0, orchestrator_types_1.isPC20Reference)(params.funds?.token);
+}
+/** True only for a resolved, funds-bearing external-wrapper burn. */
+function isPC20ImportWithFunds(params) {
+    return (params._pc20?.direction === 'import' &&
+        (params.funds?.amount ?? BigInt(0)) > BigInt(0));
+}
+/**
+ * Fail closed before a wrapper burn can be broadcast without a real user
+ * payload behind the PC20 selector.
+ */
+function assertPC20ImportHasPayload(params, hasPayload, path) {
+    if (!isPC20ImportWithFunds(params) || hasPayload)
+        return;
+    const descriptor = params._pc20;
+    if (!descriptor)
+        return;
+    throw new errors_1.PC20UnsafeEmptyPayloadError({
+        chain: String(descriptor.originChain),
+        address: descriptor.originAddress,
+        chainNamespace: descriptor.chainNamespace,
+        hint: `${path} produced an empty return payload. ` +
+            'No transaction was submitted; prepare it again with a fixed SDK.',
+    });
+}
+/**
+ * Where the funds token must live for this transaction.
+ *
+ * `to.chain` is the *destination* and is never the answer — mistaking the two
+ * is the single most likely caller error, which is why it gets its own check
+ * and its own error rather than failing later as "wrapper not registered".
+ */
+function expectedFundsChain(ctx, params) {
+    // Explicit CEA-origin route (Routes 3/4): the funds sit on the `from` chain.
+    const fromChain = params.from?.chain;
+    if (fromChain)
+        return fromChain;
+    // Push-to-external export: the caller named a Push-native token.
+    const token = params.funds?.token;
+    if (token && (0, chain_namespace_1.isPushChain)(token.chain)) {
+        return (0, helpers_1.getPushChainForNetwork)(ctx.pushNetwork);
+    }
+    // Direct external-to-Push: the funds are wherever the signer is.
+    return ctx.universalSigner.account.chain;
+}
+/**
+ * Validate chain ownership and resolve the PC20 against the live registry.
+ *
+ * Returns params shaped for the shared execution path, with `_pc20` carrying
+ * the resolved descriptor. The caller's token object is never mutated.
+ */
+async function resolvePC20Funds(ctx, params) {
+    const token = params.funds?.token;
+    const amount = params.funds?.amount ?? BigInt(0);
+    if (amount <= BigInt(0)) {
+        throw new Error('funds.amount must be greater than zero for a PC20 transfer.');
+    }
+    const expected = expectedFundsChain(ctx, params);
+    if (token.chain !== expected) {
+        throw new errors_1.PC20TokenChainMismatchError({
+            chain: String(token.chain),
+            address: token.address,
+            expectedChain: String(expected),
+        });
+    }
+    const resolved = await (0, resolver_1.resolvePC20Token)(token.chain, token.address, {
+        network: ctx.pushNetwork,
+        rpcUrls: ctx.rpcUrls,
+        // Factory identity is Tier B. Run it on first use of a given
+        // (chain, address) per session; the resolver caches the verdict.
+        tierB: true,
+    });
+    return {
+        ...params,
+        funds: {
+            amount,
+            token: {
+                symbol: resolved.symbol,
+                decimals: resolved.decimals,
+                // The gateway request carries the *external wrapper* address. The
+                // Push-side transfer uses `_pc20.pushAddress` instead.
+                address: resolved.originAddress,
+                mechanism: 'pc20-burn',
+            },
+        },
+        _pc20: resolved,
+    };
+}
+/**
+ * Narrow `ExecuteParams` to the shared execution shape.
+ *
+ * Synchronous counterpart used where no PC20 resolution is possible or needed.
+ * Throws if a PC20 reference reaches it, which would mean the async gate was
+ * skipped.
+ */
+function assertLegacyFunds(params) {
+    if ((0, orchestrator_types_1.isPC20Reference)(params.funds?.token)) {
+        throw new Error('Internal: a PC20 funds reference reached the legacy path without ' +
+            'resolution. resolvePC20Funds() must run first.');
+    }
+    return params;
+}
+/**
+ * Re-verify a prepared PC20 transaction at send time.
+ *
+ * A prepared tx is built now and broadcast later. Between the two, the registry
+ * can change in a way that matters:
+ *
+ *   - a first export lands and creates a wrapper mapping that did not exist,
+ *     turning a predicted destination address into a registered one;
+ *   - a factory is reconfigured, invalidating the identity the payload assumed.
+ *
+ * Only the critical reads are repeated — forward/reverse registry agreement and
+ * the Push source binding. Re-running the whole Tier B sweep on every send of a
+ * prepared tx would cost more than it protects.
+ *
+ * Throws if the resolved Push source has moved. That is not recoverable by
+ * retrying: the signed payload already encodes the old source.
+ */
+async function revalidatePreparedPC20(ctx, prepared) {
+    const descriptor = prepared._pc20;
+    if (!descriptor)
+        return;
+    // An export's identity is the Push token itself, which the payload pins; a
+    // registry change cannot redirect it. Only imports need the recheck.
+    if (descriptor.direction !== 'import')
+        return;
+    const fresh = await (0, resolver_1.resolvePC20Token)(descriptor.originChain, descriptor.originAddress, {
+        network: ctx.pushNetwork,
+        rpcUrls: ctx.rpcUrls,
+        // Tier A only. Tier B already passed at prepare time and its subjects
+        // (factory identity, deployed bytecode) do not change without a redeploy.
+        tierB: false,
+        // Prepared transactions must compare against live registry state rather
+        // than the positive result cached while they were constructed.
+        bypassCache: true,
+    });
+    if (fresh.pushAddress.toLowerCase() !== descriptor.pushAddress.toLowerCase()) {
+        throw new errors_1.PC20RegistryMismatchError({
+            chain: String(descriptor.originChain),
+            address: descriptor.originAddress,
+            chainNamespace: descriptor.chainNamespace,
+            resolvedWrapper: fresh.pushAddress,
+            hint: 'The registry changed after this transaction was prepared. Prepare it ' +
+                'again — the signed payload encodes the previous Push source.',
+        });
+    }
+}
+/** Resolve PC20 funds when present; otherwise pass the legacy shape through. */
+async function gateFunds(ctx, params) {
+    return isPC20Transaction(params)
+        ? resolvePC20Funds(ctx, params)
+        : assertLegacyFunds(params);
+}
+//# sourceMappingURL=gate.js.map