@pushchain/core 6.0.19 → 6.0.21

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

@@ -0,0 +1,189 @@
+/**
+ * Solana PC20 support.
+ *
+ * Derived directly from the program source at
+ * `push-chain-gateway-contracts@pc20-3rd-iteration`:
+ *   `contracts/svm-gateway/programs/universal-gateway/src/state.rs`
+ *   `contracts/svm-gateway/programs/universal-gateway/src/instructions/pc20.rs`
+ *
+ * No built IDL artifact exists in that repo yet, so the PDA seeds and the
+ * `Pc20State` layout are mirrored here rather than read from an IDL. Both are
+ * pinned by unit test against the constants below; if the program changes them,
+ * the tests must be updated deliberately rather than silently drifting.
+ *
+ * Relevant program facts, and why each matters to the SDK:
+ *
+ *   - `pc20_mint = PDA([b"pc20_mint", source_asset_20], program_id)` where
+ *     `source_asset` is the **20-byte** Push-native address, not a 32-byte
+ *     padded one. Getting this wrong yields a valid-looking but wrong mint.
+ *   - `pc20_state = PDA([b"pc20_state", pc20_mint], program_id)`.
+ *   - An inbound burn passes `remaining_accounts = [pc20_state, pc20_mint]`, in
+ *     that order (`pc20.rs:244-245` reads index 0 then 1).
+ *   - An inbound burn passes NO gateway token vault — the wrapper is burned,
+ *     not escrowed.
+ */
+import { PublicKey } from '@solana/web3.js';
+import { Buffer } from 'buffer';
+/** `state.rs:13` — `pub const PC20_MINT_SEED: &[u8] = b"pc20_mint";` */
+export declare const PC20_MINT_SEED: Buffer;
+/** `state.rs:14` — `pub const PC20_STATE_SEED: &[u8] = b"pc20_state";` */
+export declare const PC20_STATE_SEED: Buffer;
+/** `state.rs:15` — `pub const PC20_SELECTOR: [u8; 4] = *b"PC20";` */
+export declare const PC20_SELECTOR_BYTES: Buffer;
+/**
+ * `Pc20State` account layout (`state.rs:125-134`):
+ *
+ *     discriminator [8]
+ *     source_asset  [20]   // Push-native EVM address, unpadded
+ *     wrapped_mint  [32]
+ *     decimals      [1]
+ *     bump          [1]
+ */
+export declare const PC20_STATE_LEN: number;
+export type Pc20State = {
+    /** Push-native PC20 address, checksummed. */
+    sourceAsset: `0x${string}`;
+    wrappedMint: PublicKey;
+    decimals: number;
+    bump: number;
+};
+/**
+ * Derive the wrapper mint for a Push-native PC20.
+ *
+ * The seed is the raw 20 bytes of the EVM address. A 32-byte left-padded form —
+ * the shape UniversalCore stores for EVM identities — would derive a different,
+ * entirely valid-looking PDA that no wrapper is ever minted to.
+ */
+export declare function derivePC20Mint(programId: PublicKey, pushPC20Address: string): {
+    mint: PublicKey;
+    bump: number;
+};
+/** Derive the `Pc20State` PDA for a wrapper mint. */
+export declare function derivePC20State(programId: PublicKey, mint: PublicKey): {
+    state: PublicKey;
+    bump: number;
+};
+/** Decode a `Pc20State` account. */
+export declare function decodePc20State(data: Uint8Array): Pc20State;
+/**
+ * Validate a supplied Solana PC20 mint against the program's own derivation and
+ * stored state.
+ *
+ * Three independent checks, all required — any one alone can be satisfied by a
+ * mint that is not the canonical wrapper:
+ *   1. the state PDA derives from the supplied mint;
+ *   2. the state's `wrapped_mint` equals the supplied mint;
+ *   3. re-deriving the mint from the state's `source_asset` reproduces it.
+ *
+ * Together they mean the mint, its state, and the Push source are mutually
+ * consistent — which is exactly what stops a mint copied from another
+ * deployment from passing.
+ */
+export declare function validatePC20Mint(params: {
+    programId: PublicKey;
+    mint: PublicKey;
+    state: Pc20State;
+    statePda: PublicKey;
+    /** Push source UniversalCore returned for this wrapper. */
+    expectedSource: `0x${string}`;
+}): void;
+/**
+ * Accounts a Solana PC20 burn adds to the generic `send_universal_tx`
+ * instruction.
+ *
+ * Order is load-bearing: the program reads `remaining_accounts[0]` as the state
+ * and `[1]` as the mint (`pc20.rs:244-245`).
+ *
+ * `gatewayTokenAccount` is deliberately `null`. A PC20 inbound burns the
+ * wrapper via the mint authority rather than escrowing it in a gateway vault,
+ * so passing a vault here would be both unused and misleading.
+ */
+export declare function buildPC20BurnAccounts(params: {
+    programId: PublicKey;
+    mint: PublicKey;
+}): {
+    remainingAccounts: Array<{
+        pubkey: PublicKey;
+        isSigner: boolean;
+        isWritable: boolean;
+    }>;
+    gatewayTokenAccount: null;
+};
+/**
+ * Predicted destination mint for a first Push-to-Solana export.
+ *
+ * The SVM counterpart of the EVM `computeWrapperAddress` call. Unlike EVM,
+ * where the factory computes the address on chain, the mint is a pure PDA — so
+ * deriving it locally cannot drift, provided the seeds above stay in sync with
+ * the program.
+ */
+export declare function predictSvmWrapperMint(programId: PublicKey, pushPC20Address: string): PublicKey;
+/**
+ * Delivery instruction for a repeat export: SPL `TransferChecked` moving the
+ * freshly minted wrapper from the CEA ATA to the recipient's ATA.
+ *
+ * Settlement (`pc20.rs` id=5) mints into the CEA ATA and then CPIs exactly one
+ * instruction from the userData, signed by the CEA PDA — so delivery IS this
+ * one transfer. The signer flag is not encoded: `invoke_signed_gateway_instruction`
+ * marks whichever account equals the CEA authority as the signer.
+ *
+ * Only valid when the recipient ATA already exists — SPL transfers do not
+ * create destination accounts, and a failed CPI fails the whole settlement
+ * with the source already locked. Callers must verify existence first; on a
+ * first export the ATA cannot exist (its mint doesn't yet), so this is
+ * strictly a repeat-export tool.
+ */
+export declare function buildPC20SvmDeliveryFields(params: {
+    mint: PublicKey;
+    ceaAta: PublicKey;
+    recipientAta: PublicKey;
+    ceaAuthority: PublicKey;
+    amount: bigint;
+    decimals: number;
+}): {
+    targetProgram: `0x${string}`;
+    accounts: Array<{
+        pubkey: `0x${string}`;
+        isWritable: boolean;
+    }>;
+    ixData: Uint8Array;
+    instructionId: 2;
+};
+/** SPL Token program. */
+export declare const SPL_TOKEN_PROGRAM_ID: PublicKey;
+/**
+ * R3 (CEA → Push) burn payload: the outbound's execute-payload making the CEA
+ * self-call `send_universal_tx` to burn wrapper tokens it holds.
+ *
+ * The finalize dispatcher detects this shape (`execute.rs:511`:
+ * target == gateway && `is_pc20_burn_ix`) and routes to
+ * `route_pc20_burn_from_finalize_cea`, which enforces:
+ *   - ix_data = discriminator("global:send_universal_tx") || Borsh
+ *     `SendUniversalTxIxArgs { req, native_amount }` with native_amount == 0;
+ *   - `req.recipient == push_account` — the unlocked token goes to the CEA's
+ *     bound UEA on Push, nowhere else (forwarding happens via `req.payload`);
+ *   - payload accounts exactly `[pc20_state ro, pc20_mint w, cea_ata w,
+ *     token_program ro]` (`parse_pc20_cea_burn_accounts`).
+ *
+ * The revert recipient is the CEA PDA: a failed inbound re-mints the wrapper
+ * back to the CEA (`revert.rs` PC20 branch), restoring the pre-burn state.
+ */
+export declare function buildPC20SvmCeaBurnPayload(params: {
+    gatewayProgram: PublicKey;
+    mint: PublicKey;
+    ceaAuthority: PublicKey;
+    ceaAta: PublicKey;
+    /** 20-byte UEA (the CEA's push_account) — program-enforced recipient. */
+    ueaAddress: `0x${string}`;
+    amount: bigint;
+    /** Push-side UniversalPayload bytes executed after the unlock (may be empty). */
+    pushPayload: Uint8Array;
+}): {
+    targetProgram: `0x${string}`;
+    accounts: Array<{
+        pubkey: `0x${string}`;
+        isWritable: boolean;
+    }>;
+    ixData: Uint8Array;
+    instructionId: 2;
+};

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

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * Solana PC20 support.
+ *
+ * Derived directly from the program source at
+ * `push-chain-gateway-contracts@pc20-3rd-iteration`:
+ *   `contracts/svm-gateway/programs/universal-gateway/src/state.rs`
+ *   `contracts/svm-gateway/programs/universal-gateway/src/instructions/pc20.rs`
+ *
+ * No built IDL artifact exists in that repo yet, so the PDA seeds and the
+ * `Pc20State` layout are mirrored here rather than read from an IDL. Both are
+ * pinned by unit test against the constants below; if the program changes them,
+ * the tests must be updated deliberately rather than silently drifting.
+ *
+ * Relevant program facts, and why each matters to the SDK:
+ *
+ *   - `pc20_mint = PDA([b"pc20_mint", source_asset_20], program_id)` where
+ *     `source_asset` is the **20-byte** Push-native address, not a 32-byte
+ *     padded one. Getting this wrong yields a valid-looking but wrong mint.
+ *   - `pc20_state = PDA([b"pc20_state", pc20_mint], program_id)`.
+ *   - An inbound burn passes `remaining_accounts = [pc20_state, pc20_mint]`, in
+ *     that order (`pc20.rs:244-245` reads index 0 then 1).
+ *   - An inbound burn passes NO gateway token vault — the wrapper is burned,
+ *     not escrowed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPL_TOKEN_PROGRAM_ID = exports.PC20_STATE_LEN = exports.PC20_SELECTOR_BYTES = exports.PC20_STATE_SEED = exports.PC20_MINT_SEED = void 0;
+exports.derivePC20Mint = derivePC20Mint;
+exports.derivePC20State = derivePC20State;
+exports.decodePc20State = decodePc20State;
+exports.validatePC20Mint = validatePC20Mint;
+exports.buildPC20BurnAccounts = buildPC20BurnAccounts;
+exports.predictSvmWrapperMint = predictSvmWrapperMint;
+exports.buildPC20SvmDeliveryFields = buildPC20SvmDeliveryFields;
+exports.buildPC20SvmCeaBurnPayload = buildPC20SvmCeaBurnPayload;
+const web3_js_1 = require("@solana/web3.js");
+const viem_1 = require("viem");
+const buffer_1 = require("buffer");
+const enums_1 = require("../../../constants/enums");
+const errors_1 = require("./errors");
+/** `state.rs:13` — `pub const PC20_MINT_SEED: &[u8] = b"pc20_mint";` */
+exports.PC20_MINT_SEED = buffer_1.Buffer.from('pc20_mint');
+/** `state.rs:14` — `pub const PC20_STATE_SEED: &[u8] = b"pc20_state";` */
+exports.PC20_STATE_SEED = buffer_1.Buffer.from('pc20_state');
+/** `state.rs:15` — `pub const PC20_SELECTOR: [u8; 4] = *b"PC20";` */
+exports.PC20_SELECTOR_BYTES = buffer_1.Buffer.from('PC20');
+/**
+ * `Pc20State` account layout (`state.rs:125-134`):
+ *
+ *     discriminator [8]
+ *     source_asset  [20]   // Push-native EVM address, unpadded
+ *     wrapped_mint  [32]
+ *     decimals      [1]
+ *     bump          [1]
+ */
+exports.PC20_STATE_LEN = 8 + 20 + 32 + 1 + 1;
+/**
+ * Derive the wrapper mint for a Push-native PC20.
+ *
+ * The seed is the raw 20 bytes of the EVM address. A 32-byte left-padded form —
+ * the shape UniversalCore stores for EVM identities — would derive a different,
+ * entirely valid-looking PDA that no wrapper is ever minted to.
+ */
+function derivePC20Mint(programId, pushPC20Address) {
+    const sourceAsset = toSourceAssetBytes(pushPC20Address);
+    const [mint, bump] = web3_js_1.PublicKey.findProgramAddressSync([exports.PC20_MINT_SEED, sourceAsset], programId);
+    return { mint, bump };
+}
+/** Derive the `Pc20State` PDA for a wrapper mint. */
+function derivePC20State(programId, mint) {
+    const [state, bump] = web3_js_1.PublicKey.findProgramAddressSync([exports.PC20_STATE_SEED, mint.toBuffer()], programId);
+    return { state, bump };
+}
+/** Decode a `Pc20State` account. */
+function decodePc20State(data) {
+    if (data.length < exports.PC20_STATE_LEN) {
+        throw new errors_1.InvalidPC20AddressError(`Pc20State account is ${data.length} bytes; expected at least ${exports.PC20_STATE_LEN}.`, { chain: String(enums_1.CHAIN.SOLANA_DEVNET) });
+    }
+    const buf = buffer_1.Buffer.from(data);
+    const sourceAsset = `0x${buf.subarray(8, 28).toString('hex')}`;
+    const wrappedMint = new web3_js_1.PublicKey(buf.subarray(28, 60));
+    return {
+        sourceAsset: (0, viem_1.getAddress)(sourceAsset),
+        wrappedMint,
+        decimals: buf[60],
+        bump: buf[61],
+    };
+}
+/**
+ * Validate a supplied Solana PC20 mint against the program's own derivation and
+ * stored state.
+ *
+ * Three independent checks, all required — any one alone can be satisfied by a
+ * mint that is not the canonical wrapper:
+ *   1. the state PDA derives from the supplied mint;
+ *   2. the state's `wrapped_mint` equals the supplied mint;
+ *   3. re-deriving the mint from the state's `source_asset` reproduces it.
+ *
+ * Together they mean the mint, its state, and the Push source are mutually
+ * consistent — which is exactly what stops a mint copied from another
+ * deployment from passing.
+ */
+function validatePC20Mint(params) {
+    const { programId, mint, state, statePda, expectedSource } = params;
+    const { state: derivedState } = derivePC20State(programId, mint);
+    if (!derivedState.equals(statePda)) {
+        throw new errors_1.PC20RegistryMismatchError({
+            address: mint.toBase58(),
+            hint: `pc20_state PDA does not derive from this mint (expected ${derivedState.toBase58()}).`,
+        });
+    }
+    if (!state.wrappedMint.equals(mint)) {
+        throw new errors_1.PC20RegistryMismatchError({
+            address: mint.toBase58(),
+            hint: `Pc20State.wrapped_mint is ${state.wrappedMint.toBase58()}, not the supplied mint.`,
+        });
+    }
+    const { mint: derivedMint } = derivePC20Mint(programId, state.sourceAsset);
+    if (!derivedMint.equals(mint)) {
+        throw new errors_1.PC20RegistryMismatchError({
+            address: mint.toBase58(),
+            hint: `Re-deriving from Pc20State.source_asset yields ${derivedMint.toBase58()}.`,
+        });
+    }
+    if ((0, viem_1.getAddress)(state.sourceAsset) !== (0, viem_1.getAddress)(expectedSource)) {
+        throw new errors_1.PC20RegistryMismatchError({
+            address: mint.toBase58(),
+            hint: `Pc20State.source_asset (${state.sourceAsset}) does not match the Push ` +
+                `source UniversalCore returned (${expectedSource}).`,
+        });
+    }
+}
+/**
+ * Accounts a Solana PC20 burn adds to the generic `send_universal_tx`
+ * instruction.
+ *
+ * Order is load-bearing: the program reads `remaining_accounts[0]` as the state
+ * and `[1]` as the mint (`pc20.rs:244-245`).
+ *
+ * `gatewayTokenAccount` is deliberately `null`. A PC20 inbound burns the
+ * wrapper via the mint authority rather than escrowing it in a gateway vault,
+ * so passing a vault here would be both unused and misleading.
+ */
+function buildPC20BurnAccounts(params) {
+    const { state } = derivePC20State(params.programId, params.mint);
+    return {
+        // Flags per route_pc20_universal_tx (deposit.rs): the state is read-only,
+        // the mint must be writable (it is burned against), and neither may sign —
+        // the program rejects any deviation, so these are load-bearing.
+        remainingAccounts: [
+            { pubkey: state, isSigner: false, isWritable: false },
+            { pubkey: params.mint, isSigner: false, isWritable: true },
+        ],
+        gatewayTokenAccount: null,
+    };
+}
+/**
+ * Predicted destination mint for a first Push-to-Solana export.
+ *
+ * The SVM counterpart of the EVM `computeWrapperAddress` call. Unlike EVM,
+ * where the factory computes the address on chain, the mint is a pure PDA — so
+ * deriving it locally cannot drift, provided the seeds above stay in sync with
+ * the program.
+ */
+function predictSvmWrapperMint(programId, pushPC20Address) {
+    return derivePC20Mint(programId, pushPC20Address).mint;
+}
+/**
+ * Delivery instruction for a repeat export: SPL `TransferChecked` moving the
+ * freshly minted wrapper from the CEA ATA to the recipient's ATA.
+ *
+ * Settlement (`pc20.rs` id=5) mints into the CEA ATA and then CPIs exactly one
+ * instruction from the userData, signed by the CEA PDA — so delivery IS this
+ * one transfer. The signer flag is not encoded: `invoke_signed_gateway_instruction`
+ * marks whichever account equals the CEA authority as the signer.
+ *
+ * Only valid when the recipient ATA already exists — SPL transfers do not
+ * create destination accounts, and a failed CPI fails the whole settlement
+ * with the source already locked. Callers must verify existence first; on a
+ * first export the ATA cannot exist (its mint doesn't yet), so this is
+ * strictly a repeat-export tool.
+ */
+function buildPC20SvmDeliveryFields(params) {
+    // SPL Token TransferChecked: index 12, data = u8 || u64 LE amount || u8 decimals.
+    const ixData = new Uint8Array(10);
+    ixData[0] = 12;
+    new DataView(ixData.buffer).setBigUint64(1, params.amount, true);
+    ixData[9] = params.decimals;
+    const hex = (k) => `0x${buffer_1.Buffer.from(k.toBytes()).toString('hex')}`;
+    return {
+        targetProgram: hex(exports.SPL_TOKEN_PROGRAM_ID),
+        accounts: [
+            { pubkey: hex(params.ceaAta), isWritable: true }, // source
+            { pubkey: hex(params.mint), isWritable: false }, // mint (checked)
+            { pubkey: hex(params.recipientAta), isWritable: true }, // destination
+            { pubkey: hex(params.ceaAuthority), isWritable: false }, // owner → CPI signer
+        ],
+        ixData,
+        instructionId: 2,
+    };
+}
+/** SPL Token program. */
+exports.SPL_TOKEN_PROGRAM_ID = new web3_js_1.PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
+/**
+ * R3 (CEA → Push) burn payload: the outbound's execute-payload making the CEA
+ * self-call `send_universal_tx` to burn wrapper tokens it holds.
+ *
+ * The finalize dispatcher detects this shape (`execute.rs:511`:
+ * target == gateway && `is_pc20_burn_ix`) and routes to
+ * `route_pc20_burn_from_finalize_cea`, which enforces:
+ *   - ix_data = discriminator("global:send_universal_tx") || Borsh
+ *     `SendUniversalTxIxArgs { req, native_amount }` with native_amount == 0;
+ *   - `req.recipient == push_account` — the unlocked token goes to the CEA's
+ *     bound UEA on Push, nowhere else (forwarding happens via `req.payload`);
+ *   - payload accounts exactly `[pc20_state ro, pc20_mint w, cea_ata w,
+ *     token_program ro]` (`parse_pc20_cea_burn_accounts`).
+ *
+ * The revert recipient is the CEA PDA: a failed inbound re-mints the wrapper
+ * back to the CEA (`revert.rs` PC20 branch), restoring the pre-burn state.
+ */
+function buildPC20SvmCeaBurnPayload(params) {
+    const { state } = derivePC20State(params.gatewayProgram, params.mint);
+    // Anchor discriminator: first 8 bytes of SHA-256("global:send_universal_tx").
+    const discriminator = sha256(new TextEncoder().encode('global:send_universal_tx')).subarray(0, 8);
+    const recipient = buffer_1.Buffer.from(params.ueaAddress.slice(2), 'hex');
+    if (recipient.length !== 20) {
+        throw new errors_1.InvalidPC20AddressError('UEA must be a 20-byte address.', {
+            address: params.ueaAddress,
+        });
+    }
+    // Borsh SendUniversalTxIxArgs { req: UniversalTxRequest, native_amount: u64 }
+    // req: recipient [u8;20] || token [32] || amount u64 LE || payload Vec<u8>
+    //      || revert_recipient [32] || signature_data Vec<u8>   (state.rs:67)
+    const payloadLen = params.pushPayload.length;
+    const ixData = new Uint8Array(8 + 20 + 32 + 8 + 4 + payloadLen + 32 + 4 + 8);
+    const view = new DataView(ixData.buffer);
+    let o = 0;
+    ixData.set(discriminator, o);
+    o += 8;
+    ixData.set(recipient, o);
+    o += 20;
+    ixData.set(params.mint.toBytes(), o);
+    o += 32;
+    view.setBigUint64(o, params.amount, true);
+    o += 8;
+    view.setUint32(o, payloadLen, true);
+    o += 4; // Borsh Vec<u8>: u32 LE length
+    ixData.set(params.pushPayload, o);
+    o += payloadLen;
+    // Revert re-mints to the CEA, restoring pre-burn state.
+    ixData.set(params.ceaAuthority.toBytes(), o);
+    o += 32;
+    view.setUint32(o, 0, true);
+    o += 4; // signature_data: empty Vec<u8>
+    view.setBigUint64(o, BigInt(0), true); // native_amount: must be 0
+    const hex = (k) => `0x${buffer_1.Buffer.from(k.toBytes()).toString('hex')}`;
+    return {
+        targetProgram: hex(params.gatewayProgram),
+        accounts: [
+            { pubkey: hex(state), isWritable: false },
+            { pubkey: hex(params.mint), isWritable: true },
+            { pubkey: hex(params.ceaAta), isWritable: true },
+            { pubkey: hex(exports.SPL_TOKEN_PROGRAM_ID), isWritable: false },
+        ],
+        ixData,
+        instructionId: 2,
+    };
+}
+/** Minimal sha256 over bytes, returned as bytes. */
+function sha256(data) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { createHash } = require('crypto');
+    return createHash('sha256').update(data).digest();
+}
+/** Normalize a Push-native EVM address into the 20 raw bytes used as a seed. */
+function toSourceAssetBytes(address) {
+    let checksummed;
+    try {
+        checksummed = (0, viem_1.getAddress)(address);
+    }
+    catch {
+        throw new errors_1.InvalidPC20AddressError('Push-native PC20 address is not a valid 20-byte EVM address.', { address });
+    }
+    return buffer_1.Buffer.from(checksummed.slice(2), 'hex');
+}
+//# sourceMappingURL=svm.js.map

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

@@ -0,0 +1,46 @@
+/**
+ * PC20 outbound tracking.
+ *
+ * `externalAssetAddr` alone is not a reliable source for the destination
+ * wrapper address on a PC20 export:
+ *
+ *   - it is empty when the outbound is first created;
+ *   - it is normally backfilled once the destination wrapper is *observed*,
+ *     which only happens when a wrapper is newly deployed;
+ *   - a repeat export deploys nothing, so nothing is observed and the field can
+ *     stay empty indefinitely.
+ *
+ * The wrapper is therefore resolved from UniversalCore whenever the observation
+ * did not supply one. `pc20ContractAddress` (the locked Push-native source) is
+ * the stable identifier that makes the lookup possible.
+ */
+import type { OutboundTxV2 } from '../../../generated/uexecutor/v2/types';
+import type { OrchestratorContext } from '../context';
+import { CHAIN } from '../../../constants/enums';
+import { type PC20ResolverOptions } from './resolver';
+/** Shape of the fields this module needs, so callers can pass partial fixtures. */
+export type PC20OutboundView = Pick<OutboundTxV2, 'isPc20' | 'pc20ContractAddress' | 'externalAssetAddr' | 'destinationChain'> & {
+    observedTx?: {
+        pc20WrapperAddress?: string;
+    } | undefined;
+};
+/**
+ * Best available destination wrapper address for a PC20 outbound, in
+ * chain-native form (checksummed hex on EVM, base58 on Solana).
+ *
+ * Resolution order, cheapest first:
+ *   1. the settlement observation, when a wrapper was newly deployed;
+ *   2. `externalAssetAddr`, once backfilled;
+ *   3. UniversalCore, keyed by the Push-native source.
+ *
+ * Returns `undefined` rather than throwing when nothing resolves — a receipt
+ * for an in-flight outbound legitimately has no wrapper yet, and failing
+ * tracking over a cosmetic field would be worse than omitting it.
+ */
+export declare function resolvePC20WrapperForReceipt(ctx: OrchestratorContext, outbound: PC20OutboundView, opts: PC20ResolverOptions): Promise<string | undefined>;
+/**
+ * Strict namespace resolution for callers that must not silently degrade.
+ *
+ * @throws {PC20UnknownChainNamespaceError} when the namespace maps to no chain.
+ */
+export declare function requireDestinationChain(namespace: string): CHAIN;

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

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * PC20 outbound tracking.
+ *
+ * `externalAssetAddr` alone is not a reliable source for the destination
+ * wrapper address on a PC20 export:
+ *
+ *   - it is empty when the outbound is first created;
+ *   - it is normally backfilled once the destination wrapper is *observed*,
+ *     which only happens when a wrapper is newly deployed;
+ *   - a repeat export deploys nothing, so nothing is observed and the field can
+ *     stay empty indefinitely.
+ *
+ * The wrapper is therefore resolved from UniversalCore whenever the observation
+ * did not supply one. `pc20ContractAddress` (the locked Push-native source) is
+ * the stable identifier that makes the lookup possible.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePC20WrapperForReceipt = resolvePC20WrapperForReceipt;
+exports.requireDestinationChain = requireDestinationChain;
+const context_1 = require("../context");
+const chain_namespace_1 = require("./chain-namespace");
+const resolver_1 = require("./resolver");
+const errors_1 = require("./errors");
+/**
+ * Best available destination wrapper address for a PC20 outbound, in
+ * chain-native form (checksummed hex on EVM, base58 on Solana).
+ *
+ * Resolution order, cheapest first:
+ *   1. the settlement observation, when a wrapper was newly deployed;
+ *   2. `externalAssetAddr`, once backfilled;
+ *   3. UniversalCore, keyed by the Push-native source.
+ *
+ * Returns `undefined` rather than throwing when nothing resolves — a receipt
+ * for an in-flight outbound legitimately has no wrapper yet, and failing
+ * tracking over a cosmetic field would be worse than omitting it.
+ */
+async function resolvePC20WrapperForReceipt(ctx, outbound, opts) {
+    if (!outbound.isPc20)
+        return undefined;
+    const observed = outbound.observedTx?.pc20WrapperAddress;
+    if (observed)
+        return normalizeForChain(outbound.destinationChain, observed);
+    if (outbound.externalAssetAddr) {
+        return normalizeForChain(outbound.destinationChain, outbound.externalAssetAddr);
+    }
+    if (!outbound.pc20ContractAddress) {
+        (0, context_1.printLog)(ctx, '[pc20] outbound is flagged isPc20 but carries no pc20ContractAddress; ' +
+            'cannot resolve the destination wrapper');
+        return undefined;
+    }
+    // `destinationChain` arrives as an untyped string. It must go through the
+    // namespace mapping — passing it to the registry verbatim would return a zero
+    // wrapper, indistinguishable from "not deployed yet".
+    const chain = (0, chain_namespace_1.tryNamespaceToChain)(outbound.destinationChain);
+    if (!chain) {
+        (0, context_1.printLog)(ctx, `[pc20] unmappable destination namespace "${outbound.destinationChain}"; ` +
+            'skipping wrapper resolution');
+        return undefined;
+    }
+    try {
+        const registered = await (0, resolver_1.getRegisteredWrapper)(outbound.pc20ContractAddress, chain, opts);
+        return registered?.address;
+    }
+    catch (err) {
+        (0, context_1.printLog)(ctx, `[pc20] wrapper resolution failed for ${outbound.pc20ContractAddress} on ` +
+            `${chain}: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
+/**
+ * Strict namespace resolution for callers that must not silently degrade.
+ *
+ * @throws {PC20UnknownChainNamespaceError} when the namespace maps to no chain.
+ */
+function requireDestinationChain(namespace) {
+    const chain = (0, chain_namespace_1.tryNamespaceToChain)(namespace);
+    if (!chain) {
+        throw new errors_1.PC20UnknownChainNamespaceError(namespace, {
+            hint: 'Destination chain on the outbound record is not a supported CAIP-2 id.',
+        });
+    }
+    return chain;
+}
+/**
+ * Present an address in the destination chain's native form.
+ *
+ * SVM identities travel as `0x`-prefixed hex internally (that is how the
+ * Cosmos keeper indexes them) but users expect base58.
+ */
+function normalizeForChain(namespace, address) {
+    const chain = (0, chain_namespace_1.tryNamespaceToChain)(namespace);
+    if (!chain)
+        return address;
+    try {
+        if ((0, chain_namespace_1.vmForChain)(chain) === 'SVM' && address.startsWith('0x')) {
+            // Reuse the codec so hex→base58 has exactly one implementation.
+            const { pc20Bytes32ToAddress } = require('./address-codec');
+            return pc20Bytes32ToAddress(chain, address);
+        }
+        const { getAddress } = require('viem');
+        return getAddress(address);
+    }
+    catch {
+        // A malformed address from the node is not worth failing a receipt over.
+        return address;
+    }
+}
+//# sourceMappingURL=tracking.js.map

package/src/lib/orchestrator/internals/preflight.js

@@ -54,7 +54,7 @@ function runPreflight(opts) {
     // 1. PRC-20 burn-balance check (skipped when burnAmount = 0 — R3 paths
     //    structurally hold zero of the source-chain native PRC-20; see plan §9 #4).
     if (burnAmount && burnAmount > BigInt(0) && burnToken) {
-        const onHand = prc20Balance !== null && prc20Balance !== void 0 ? prc20Balance : BigInt(0);
+        const onHand = prc20Balance ?? BigInt(0);
         const sufficient = onHand >= burnAmount;
         const shortfall = sufficient ? BigInt(0) : burnAmount - onHand;
         (0, context_1.fireProgressHook)(ctx, HOOK_PRE_INFO, burnAmount, onHand, sufficient, ueaAddress, pathTag, {

package/src/lib/orchestrator/internals/progress-route-hooks.js

@@ -21,7 +21,7 @@ function pickWaitHooks(route) {
             polling: (chain, elapsed, pushTxHash) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_209_02](chain, elapsed, pushTxHash),
             success: (details) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_01](details),
             timeout: (chain, elapsed, pushTxHash) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_03](chain, elapsed, pushTxHash),
-            failed: (chain, msg, metadata) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02](chain, msg, undefined, metadata === null || metadata === void 0 ? void 0 : metadata.pushTxHash, metadata === null || metadata === void 0 ? void 0 : metadata.txHash),
+            failed: (chain, msg, metadata) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_299_02](chain, msg, undefined, metadata?.pushTxHash, metadata?.txHash),
         };
     }
     if (route === route_detector_1.TransactionRoute.CEA_TO_PUSH) {
@@ -36,7 +36,7 @@ function pickWaitHooks(route) {
             // R3 inbound; pass phase='outbound' so the title reflects the source
             // chain instead of "Push Chain Inbound …".
             timeout: (chain, elapsed, pushTxHash) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_03](chain, elapsed, 'outbound', pushTxHash),
-            failed: (chain, msg, metadata) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](msg, 'outbound', chain, undefined, metadata === null || metadata === void 0 ? void 0 : metadata.pushTxHash, metadata === null || metadata === void 0 ? void 0 : metadata.txHash),
+            failed: (chain, msg, metadata) => progress_hook_1.default[progress_hook_types_1.PROGRESS_HOOK.SEND_TX_399_02](msg, 'outbound', chain, undefined, metadata?.pushTxHash, metadata?.txHash),
         };
     }
     // Route 4 (CEA_TO_CEA) has no spec'd ID range yet; cascade hops and