@pushchain/core 6.0.20 → 6.0.21

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

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * Typed PC20 errors.
+ *
+ * Every error carries a stable `code` discriminator so callers classify by
+ * `instanceof` or `err.code` rather than by parsing messages, and structured
+ * context fields (supplied chain, supplied address, expected chain, resolved
+ * namespace) plus a concise remediation hint.
+ *
+ * Two rules these must not break:
+ *  - Never classify a token by symbol. PC20 identity is address-and-chain only.
+ *  - Never embed raw RPC payloads in the message. Context fields are curated.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PC20UnsafeEmptyPayloadError = exports.PC20ExportRevertedError = exports.PC20WrapperPredictionUnavailableError = exports.PC20UnknownChainNamespaceError = exports.PC20AmbiguousAddressError = exports.InsufficientPC20BalanceError = exports.UnsupportedPC20DestinationError = exports.PC20ExpectedButPRC20Error = exports.InvalidPC20MetadataError = exports.PC20FactoryMismatchError = exports.PC20RegistryMismatchError = exports.PC20WrapperNotRegisteredError = exports.PC20TokenChainMismatchError = exports.InvalidPC20AddressError = exports.PC20Error = void 0;
+/** Base class for all PC20 failures. `instanceof PC20Error` catches the family. */
+class PC20Error extends Error {
+    code;
+    chain;
+    address;
+    expectedChain;
+    chainNamespace;
+    hint;
+    constructor(code, message, ctx = {}) {
+        const parts = [message];
+        if (ctx.chain)
+            parts.push(`chain=${ctx.chain}`);
+        if (ctx.address)
+            parts.push(`address=${ctx.address}`);
+        if (ctx.expectedChain)
+            parts.push(`expectedChain=${ctx.expectedChain}`);
+        if (ctx.chainNamespace)
+            parts.push(`namespace=${ctx.chainNamespace}`);
+        if (ctx.hint)
+            parts.push(`— ${ctx.hint}`);
+        super(parts.join(' '));
+        this.name = new.target.name;
+        this.code = code;
+        this.chain = ctx.chain;
+        this.address = ctx.address;
+        this.expectedChain = ctx.expectedChain;
+        this.chainNamespace = ctx.chainNamespace;
+        this.hint = ctx.hint;
+    }
+}
+exports.PC20Error = PC20Error;
+/** Address is malformed for the supplied chain's VM, or is the zero/default address. */
+class InvalidPC20AddressError extends PC20Error {
+    constructor(message, ctx = {}) {
+        super('PC20_INVALID_ADDRESS', message, ctx);
+    }
+}
+exports.InvalidPC20AddressError = InvalidPC20AddressError;
+/**
+ * `funds.token.chain` does not match where the funds actually are — the signer's
+ * chain for a direct external route, `params.from.chain` for a CEA-origin route,
+ * or the Push chain for an export.
+ *
+ * This is the check that stops a wrapper address copied onto the wrong chain.
+ */
+class PC20TokenChainMismatchError extends PC20Error {
+    constructor(ctx = {}) {
+        super('PC20_TOKEN_CHAIN_MISMATCH', 'PC20 token chain does not match the chain the funds are on.', {
+            hint: 'funds.token.chain must be where the token lives, not the ' +
+                'destination. `to.chain` is the destination.',
+            ...ctx,
+        });
+    }
+}
+exports.PC20TokenChainMismatchError = PC20TokenChainMismatchError;
+/** UniversalCore has no source mapping for this wrapper on this chain. */
+class PC20WrapperNotRegisteredError extends PC20Error {
+    constructor(ctx = {}) {
+        super('PC20_WRAPPER_NOT_REGISTERED', 'No PC20 wrapper is registered at this address on this chain.', {
+            hint: 'Confirm the wrapper has been deployed by an export to this chain, ' +
+                'and that the address belongs to this chain.',
+            ...ctx,
+        });
+    }
+}
+exports.PC20WrapperNotRegisteredError = PC20WrapperNotRegisteredError;
+/**
+ * Forward and reverse registry lookups disagree: `getPC20Source(wrapper)`
+ * resolved a source whose `getPC20Wrapper(source)` is a different address.
+ *
+ * A stale or partially-written registry entry. Never proceed — the burn would
+ * unlock the wrong Push token.
+ */
+class PC20RegistryMismatchError extends PC20Error {
+    constructor(ctx = {}) {
+        super('PC20_REGISTRY_MISMATCH', `PC20 registry forward/reverse mismatch${ctx.resolvedWrapper ? ` (reverse resolved to ${ctx.resolvedWrapper})` : ''}.`, { hint: 'This is a registry inconsistency; do not retry blindly.', ...ctx });
+    }
+}
+exports.PC20RegistryMismatchError = PC20RegistryMismatchError;
+/**
+ * The live external gateway's configured `pc20Factory` differs from the
+ * reference factory (the destination Vault's, or UniversalCore's registry if
+ * exposed), or the factory does not recognize the wrapper.
+ *
+ * Proceeding risks the gateway taking the non-PC20 path for this token.
+ */
+class PC20FactoryMismatchError extends PC20Error {
+    constructor(ctx = {}) {
+        super('PC20_FACTORY_MISMATCH', 'PC20 factory identity mismatch between the live gateway and UniversalCore.', {
+            hint: 'The deployment is misconfigured; report it rather than retrying.',
+            ...ctx,
+        });
+    }
+}
+exports.PC20FactoryMismatchError = PC20FactoryMismatchError;
+/** Token does not implement `pc20Metadata()`, or the metadata fails validation. */
+class InvalidPC20MetadataError extends PC20Error {
+    constructor(message, ctx = {}) {
+        super('PC20_INVALID_METADATA', message, ctx);
+    }
+}
+exports.InvalidPC20MetadataError = InvalidPC20MetadataError;
+/**
+ * A synthetic PRC20 address was supplied where a Push-native PC20 was expected.
+ *
+ * Distinct from {@link InvalidPC20MetadataError}: a PRC20 is a legitimate token
+ * on the wrong API, not a broken one. Kept separate so the message can point at
+ * the right call instead of reading as "your token is invalid".
+ */
+class PC20ExpectedButPRC20Error extends PC20Error {
+    constructor(ctx = {}) {
+        super('PC20_EXPECTED_BUT_PRC20', 'This address is a synthetic PRC20, not a Push-native PC20.', {
+            hint: 'Move PRC20 tokens with the MoveableToken API ' +
+                '(pushChainClient.moveable.token.*), not a { chain, address } PC20 reference.',
+            ...ctx,
+        });
+    }
+}
+exports.PC20ExpectedButPRC20Error = PC20ExpectedButPRC20Error;
+/** Destination chain has no configured PC20 factory, or is not supported for PC20. */
+class UnsupportedPC20DestinationError extends PC20Error {
+    constructor(ctx = {}) {
+        super('PC20_UNSUPPORTED_DESTINATION', 'PC20 export is not configured for this destination chain.', { hint: 'No PC20 factory is registered for this chain namespace.', ...ctx });
+    }
+}
+exports.UnsupportedPC20DestinationError = UnsupportedPC20DestinationError;
+/** Caller's balance of the wrapper (inbound) or Push source (export) is short. */
+class InsufficientPC20BalanceError extends PC20Error {
+    constructor(ctx = {}) {
+        super('PC20_INSUFFICIENT_BALANCE', `Insufficient PC20 balance${ctx.required !== undefined && ctx.available !== undefined
+            ? ` (required ${ctx.required}, available ${ctx.available})`
+            : ''}.`, ctx);
+    }
+}
+exports.InsufficientPC20BalanceError = InsufficientPC20BalanceError;
+/**
+ * The same address is registered on more than one chain, resolving to
+ * different Push sources, and no `chain` was supplied to disambiguate.
+ *
+ * Only reachable from the lookup utility's optional-chain path. Picking the
+ * first match would be the one way that convenience could actively mislead —
+ * the caller would get a confident answer about the wrong token.
+ */
+class PC20AmbiguousAddressError extends PC20Error {
+    candidates;
+    constructor(address, candidates) {
+        super('PC20_AMBIGUOUS_ADDRESS', `Address is registered on ${candidates.length} chains with different Push sources ` +
+            `(${candidates.map((c) => `${c.chain}→${c.pushAddress}`).join(', ')}).`, {
+            address,
+            hint: 'Pass `chain` in the options to disambiguate.',
+        });
+        this.candidates = candidates;
+    }
+}
+exports.PC20AmbiguousAddressError = PC20AmbiguousAddressError;
+/**
+ * A chain namespace could not be mapped in either direction.
+ *
+ * Thrown rather than returning a negative result: an unmapped namespace reads
+ * from the registry as "not deployed", hiding the actual bug.
+ */
+class PC20UnknownChainNamespaceError extends PC20Error {
+    constructor(namespace, ctx = {}) {
+        super('PC20_UNKNOWN_CHAIN_NAMESPACE', 'Unknown PC20 chain namespace.', {
+            chainNamespace: namespace,
+            ...ctx,
+        });
+    }
+}
+exports.PC20UnknownChainNamespaceError = PC20UnknownChainNamespaceError;
+/**
+ * The destination wrapper address for a first export could not be predicted.
+ *
+ * Thrown strictly BEFORE approval. A first export commits the source token into
+ * VaultPC20 before the destination transfer is built, so an unverifiable
+ * prediction must abort rather than fall back to a guess.
+ */
+class PC20WrapperPredictionUnavailableError extends PC20Error {
+    constructor(ctx = {}) {
+        super('PC20_WRAPPER_PREDICTION_UNAVAILABLE', 'Could not determine the destination PC20 wrapper address for a first export.', {
+            hint: 'Aborted before approval so no funds are locked. Retry once the ' +
+                'destination factory is reachable.',
+            ...ctx,
+        });
+    }
+}
+exports.PC20WrapperPredictionUnavailableError = PC20WrapperPredictionUnavailableError;
+/** A PC20 export reverted after the source token was locked. Carries recovery context. */
+class PC20ExportRevertedError extends PC20Error {
+    outboundTxId;
+    lockedAmount;
+    revertRecipient;
+    constructor(ctx = {}) {
+        super('PC20_EXPORT_REVERTED', 'PC20 export reverted after the source token was locked.', {
+            hint: 'Funds return to the revert recipient on Push Chain.',
+            ...ctx,
+        });
+        this.outboundTxId = ctx.outboundTxId;
+        this.lockedAmount = ctx.lockedAmount;
+        this.revertRecipient = ctx.revertRecipient;
+    }
+}
+exports.PC20ExportRevertedError = PC20ExportRevertedError;
+/**
+ * A wrapper burn was about to be submitted without any Push-side payload.
+ *
+ * Until every supported Push Chain version treats selector-only PC20 payloads
+ * as an empty payload, broadcasting this shape can burn the wrapper and leave
+ * the canonical token permanently locked. The SDK therefore fails closed.
+ */
+class PC20UnsafeEmptyPayloadError extends PC20Error {
+    constructor(ctx = {}) {
+        super('PC20_UNSAFE_EMPTY_PAYLOAD', 'Refusing to submit a PC20 burn without a Push-side forwarding payload.', {
+            hint: 'Prepare the transaction again with an SDK version that always ' +
+                'attaches the PC20 transfer payload.',
+            ...ctx,
+        });
+    }
+}
+exports.PC20UnsafeEmptyPayloadError = PC20UnsafeEmptyPayloadError;
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1,172 @@
+/**
+ * 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.
+ */
+import { type Hex } from 'viem';
+import { CHAIN } from '../../../constants/enums';
+import type { OrchestratorContext } from '../context';
+import { type PC20ResolverOptions, type ResolvedPC20 } from './resolver';
+/** `bytes4(ascii("PC20"))`. Must match the chain's PC20 route selector. */
+export declare const 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.
+ */
+export declare const MAX_PC20_NAME_BYTES = 64;
+export declare const 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.
+ */
+export declare function buildPC20ExportPayload(params: {
+    destinationChain: CHAIN;
+    name: string;
+    symbol: string;
+    decimals: number;
+    destinationUserData?: Hex;
+}): Hex;
+/**
+ * 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.
+ */
+export declare function assertMetadataFitsFactoryLimits(name: string, symbol: string): void;
+export type PC20GasQuote = {
+    gasToken: `0x${string}`;
+    gasFee: bigint;
+    protocolFee: bigint;
+    gasPrice: bigint;
+    chainNamespace: string;
+    gasLimitUsed: bigint;
+    isFirstExport: boolean;
+    /**
+     * `gasLimitUsed` plus a deployment-overhead margin — see
+     * {@link quotePC20Export} for why the margin is unconditional.
+     */
+    gasLimitCeiling: bigint;
+};
+/**
+ * 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.
+ */
+export declare function quotePC20Export(ctx: OrchestratorContext, pushPC20: `0x${string}`, destinationChain: CHAIN, gasLimit: bigint, opts: PC20ResolverOptions): Promise<PC20GasQuote>;
+/**
+ * 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.
+ */
+export declare function queryPC20OutboundGasFee(ctx: OrchestratorContext, pushPC20: `0x${string}`, gasLimit: bigint, destinationChain: CHAIN): Promise<{
+    gasToken: `0x${string}`;
+    gasFee: bigint;
+    protocolFee: bigint;
+    gasPrice: bigint;
+    gasLimitUsed: bigint;
+    universalCoreAddress: `0x${string}`;
+    isFirstExport: boolean;
+    gasLimitCeiling: bigint;
+    /**
+     * Always zero. Present only for shape-compatibility with
+     * `queryOutboundGasFee` — both the EVM and SVM callers size the actual
+     * native value themselves (estimateNativeValueForSwap) from gasFee, and
+     * never consume this field from the quote.
+     */
+    nativeValueForGas: bigint;
+}>;
+export type DestinationWrapper = {
+    /** Chain-native address of the wrapper on the destination chain. */
+    address: string;
+    /** False when this address is a prediction for a not-yet-deployed wrapper. */
+    deployed: boolean;
+};
+/**
+ * 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.
+ */
+export declare function resolveDestinationWrapper(ctx: OrchestratorContext, pushPC20: `0x${string}`, destinationChain: CHAIN, opts: PC20ResolverOptions): Promise<DestinationWrapper>;
+/**
+ * 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.
+ */
+export declare function validatePC20Export(ctx: OrchestratorContext, resolved: ResolvedPC20, destinationChain: CHAIN, opts: PC20ResolverOptions): Promise<{
+    wrapper: DestinationWrapper;
+    namespace: string;
+}>;