@pushchain/core 6.0.20 → 6.0.21

package/src/lib/orchestrator/internals/pc20/address-codec.d.ts

@@ -0,0 +1,31 @@
+/**
+ * PC20 address codecs.
+ *
+ * UniversalCore stores every external identity as `bytes32`, with VM-specific
+ * encoding:
+ *
+ *   EVM — the 20-byte address left-padded to 32 bytes.
+ *   SVM — the raw 32-byte Solana public key, stored directly.
+ *
+ * The public API always speaks chain-native: checksummed hex for EVM, base58
+ * for Solana. These helpers are the only place the two representations meet.
+ */
+import { type Hex } from 'viem';
+import { CHAIN } from '../../../constants/enums';
+/** 32 zero bytes — the registry's "absent" value, and Solana's default pubkey. */
+export declare const ZERO_BYTES32: "0x0000000000000000000000000000000000000000000000000000000000000000";
+/** True when a `bytes32` registry read came back empty (unset mapping). */
+export declare function isZeroBytes32(value: string): boolean;
+/**
+ * Normalize a chain-native address to the registry's `bytes32` form.
+ *
+ * @throws {InvalidPC20AddressError} on a malformed or zero/default address.
+ */
+export declare function pc20AddressToBytes32(chain: CHAIN, address: string): Hex;
+/**
+ * Convert a registry `bytes32` back to the chain-native representation:
+ * checksummed hex for EVM, base58 for Solana.
+ *
+ * @throws {InvalidPC20AddressError} on a malformed or zero value.
+ */
+export declare function pc20Bytes32ToAddress(chain: CHAIN, value: string): string;

package/src/lib/orchestrator/internals/pc20/address-codec.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * PC20 address codecs.
+ *
+ * UniversalCore stores every external identity as `bytes32`, with VM-specific
+ * encoding:
+ *
+ *   EVM — the 20-byte address left-padded to 32 bytes.
+ *   SVM — the raw 32-byte Solana public key, stored directly.
+ *
+ * The public API always speaks chain-native: checksummed hex for EVM, base58
+ * for Solana. These helpers are the only place the two representations meet.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZERO_BYTES32 = void 0;
+exports.isZeroBytes32 = isZeroBytes32;
+exports.pc20AddressToBytes32 = pc20AddressToBytes32;
+exports.pc20Bytes32ToAddress = pc20Bytes32ToAddress;
+const tslib_1 = require("tslib");
+const viem_1 = require("viem");
+const web3_js_1 = require("@solana/web3.js");
+const bs58_1 = tslib_1.__importDefault(require("bs58"));
+const enums_1 = require("../../../constants/enums");
+const chain_namespace_1 = require("./chain-namespace");
+const errors_1 = require("./errors");
+/** 32 zero bytes — the registry's "absent" value, and Solana's default pubkey. */
+exports.ZERO_BYTES32 = '0x0000000000000000000000000000000000000000000000000000000000000000';
+const ZERO_EVM_ADDRESS = '0x0000000000000000000000000000000000000000';
+/** True when a `bytes32` registry read came back empty (unset mapping). */
+function isZeroBytes32(value) {
+    return /^0x0*$/i.test(value);
+}
+/**
+ * Normalize a chain-native address to the registry's `bytes32` form.
+ *
+ * @throws {InvalidPC20AddressError} on a malformed or zero/default address.
+ */
+function pc20AddressToBytes32(chain, address) {
+    const vm = (0, chain_namespace_1.vmForChain)(chain);
+    return vm === enums_1.VM.SVM
+        ? svmAddressToBytes32(chain, address)
+        : evmAddressToBytes32(chain, address);
+}
+/**
+ * Convert a registry `bytes32` back to the chain-native representation:
+ * checksummed hex for EVM, base58 for Solana.
+ *
+ * @throws {InvalidPC20AddressError} on a malformed or zero value.
+ */
+function pc20Bytes32ToAddress(chain, value) {
+    const vm = (0, chain_namespace_1.vmForChain)(chain);
+    if (!(0, viem_1.isHex)(value) || value.length !== 66) {
+        throw new errors_1.InvalidPC20AddressError('Registry value is not a 32-byte hex string.', {
+            chain,
+            address: value,
+        });
+    }
+    if (isZeroBytes32(value)) {
+        throw new errors_1.InvalidPC20AddressError('Registry value is the zero identity.', {
+            chain,
+            address: value,
+            hint: 'The mapping is unset — check `deployed`/`known` before decoding.',
+        });
+    }
+    return vm === enums_1.VM.SVM ? svmBytes32ToAddress(value) : evmBytes32ToAddress(chain, value);
+}
+// ---------------------------------------------------------------------------
+// EVM
+// ---------------------------------------------------------------------------
+function evmAddressToBytes32(chain, address) {
+    if (!(0, viem_1.isAddress)(address)) {
+        throw new errors_1.InvalidPC20AddressError('Not a valid 20-byte EVM address.', {
+            chain,
+            address,
+        });
+    }
+    if (address.toLowerCase() === ZERO_EVM_ADDRESS) {
+        throw new errors_1.InvalidPC20AddressError('Zero address is not a valid PC20 token.', {
+            chain,
+            address,
+        });
+    }
+    return (0, viem_1.padHex)((0, viem_1.getAddress)(address), { size: 32, dir: 'left' });
+}
+function evmBytes32ToAddress(chain, value) {
+    // An EVM identity occupies the low 20 bytes; anything in the high 12 bytes
+    // means this value was written for a different VM and must not be truncated
+    // into a plausible-looking address.
+    const highBytes = value.slice(2, 26);
+    if (!/^0*$/.test(highBytes)) {
+        throw new errors_1.InvalidPC20AddressError('Registry value has non-zero high bytes and is not a left-padded EVM address.', { chain, address: value, hint: 'This identity may belong to a non-EVM chain.' });
+    }
+    return (0, viem_1.getAddress)(`0x${value.slice(26)}`);
+}
+// ---------------------------------------------------------------------------
+// SVM
+// ---------------------------------------------------------------------------
+function svmAddressToBytes32(chain, address) {
+    let key;
+    try {
+        // Accept both base58 (the normal form) and 32-byte hex, so a value read
+        // back off-chain can be round-tripped without the caller re-encoding it.
+        key = (0, viem_1.isHex)(address)
+            ? new web3_js_1.PublicKey(Buffer.from(address.slice(2), 'hex'))
+            : new web3_js_1.PublicKey(address);
+    }
+    catch {
+        throw new errors_1.InvalidPC20AddressError('Not a valid Solana public key.', {
+            chain,
+            address,
+        });
+    }
+    if (key.equals(web3_js_1.PublicKey.default)) {
+        throw new errors_1.InvalidPC20AddressError('Default public key is not a valid PC20 mint.', {
+            chain,
+            address,
+        });
+    }
+    return `0x${Buffer.from(key.toBytes()).toString('hex')}`;
+}
+function svmBytes32ToAddress(value) {
+    return bs58_1.default.encode(Buffer.from(value.slice(2), 'hex'));
+}
+//# sourceMappingURL=address-codec.js.map

package/src/lib/orchestrator/internals/pc20/chain-namespace.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Chain namespace mapping for PC20 — single source of truth.
+ *
+ * `chainNamespace` is the key for every PC20 registry read on UniversalCore
+ * (`getPC20Wrapper`, `getPC20Source`, `pc20FactoryByChain`,
+ * `getPC20ExportGasAndFees`, `pc20DeploymentGasOverhead`) and appears in the
+ * public PC20 result types.
+ *
+ * The contracts define it as the CAIP-2 chain identifier — see
+ * `push-chain-core-contracts/src/Interfaces/IUniversalCore.sol`:
+ *
+ *     /// @param destChainNamespace  Destination chain (CAIP-2, e.g., "eip155:1")
+ *
+ * ## Why this derives from CHAIN_INFO and not from the CHAIN enum value
+ *
+ * The `CHAIN` enum values look like CAIP-2 strings already, so identity is
+ * tempting. It is wrong. `CHAIN.PUSH_LOCALNET` is `'eip155:9001'` while its
+ * `CHAIN_INFO.chainId` is `'9000'`, and `CHAIN.PUSH_MAINNET`'s chainId is still
+ * the `'TBD'` placeholder. The rest of the SDK (`helpers.getChainNamespace`,
+ * `utils/external-tx-hash.chainFromNamespace`) already derives from
+ * `CHAIN_INFO`, so deriving here keeps one convention instead of introducing a
+ * second that silently disagrees on those two chains.
+ *
+ * The `'TBD'` placeholder is rejected outright. `'eip155:TBD'` is a
+ * syntactically fine string that matches nothing in the registry — exactly the
+ * kind of value that reads back as "not deployed".
+ *
+ * Do NOT confuse this with `VM_NAMESPACE` in `constants/chain.ts`, which is the
+ * CAIP-2 *prefix* only (`'eip155'` / `'solana'`). Passing a bare prefix to the
+ * registry silently misses.
+ *
+ * ## Why these throw
+ *
+ * An unmapped namespace returns `(0x0, known=false)` from the registry, which
+ * is indistinguishable from "this wrapper is not deployed yet". Returning a
+ * negative would surface a mapping bug as an empty receipt field or a spurious
+ * "not registered" error. Throwing keeps the failure legible.
+ */
+import { CHAIN, VM } from '../../../constants/enums';
+/**
+ * Convert a supported `CHAIN` to the namespace string UniversalCore is keyed on.
+ *
+ * @throws {PC20UnknownChainNamespaceError} if the chain is unsupported or its
+ * chainId is still a placeholder.
+ */
+export declare function chainToNamespace(chain: CHAIN): string;
+/**
+ * Convert a namespace string from chain or protobuf data back to a `CHAIN`.
+ *
+ * Used by the outbound tracking fallback, where `destinationChain` arrives as an
+ * untyped string from the node.
+ *
+ * @throws {PC20UnknownChainNamespaceError} if it maps to no supported chain.
+ */
+export declare function namespaceToChain(namespace: string): CHAIN;
+/** Non-throwing variant for callers that legitimately probe an unknown value. */
+export declare function tryNamespaceToChain(namespace: string): CHAIN | undefined;
+/** Non-throwing variant, for building candidate chain lists. */
+export declare function tryChainToNamespace(chain: CHAIN): string | undefined;
+/** VM for a supported chain. Throws rather than defaulting to EVM. */
+export declare function vmForChain(chain: CHAIN): VM;
+/** True for any Push Chain network (never an external chain). */
+export declare function isPushChain(chain: CHAIN): boolean;
+/**
+ * Supported external chains that have a usable namespace — the default target
+ * set for deployment discovery when the caller passes no explicit `chains`.
+ */
+export declare function allExternalChains(): CHAIN[];

package/src/lib/orchestrator/internals/pc20/chain-namespace.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Chain namespace mapping for PC20 — single source of truth.
+ *
+ * `chainNamespace` is the key for every PC20 registry read on UniversalCore
+ * (`getPC20Wrapper`, `getPC20Source`, `pc20FactoryByChain`,
+ * `getPC20ExportGasAndFees`, `pc20DeploymentGasOverhead`) and appears in the
+ * public PC20 result types.
+ *
+ * The contracts define it as the CAIP-2 chain identifier — see
+ * `push-chain-core-contracts/src/Interfaces/IUniversalCore.sol`:
+ *
+ *     /// @param destChainNamespace  Destination chain (CAIP-2, e.g., "eip155:1")
+ *
+ * ## Why this derives from CHAIN_INFO and not from the CHAIN enum value
+ *
+ * The `CHAIN` enum values look like CAIP-2 strings already, so identity is
+ * tempting. It is wrong. `CHAIN.PUSH_LOCALNET` is `'eip155:9001'` while its
+ * `CHAIN_INFO.chainId` is `'9000'`, and `CHAIN.PUSH_MAINNET`'s chainId is still
+ * the `'TBD'` placeholder. The rest of the SDK (`helpers.getChainNamespace`,
+ * `utils/external-tx-hash.chainFromNamespace`) already derives from
+ * `CHAIN_INFO`, so deriving here keeps one convention instead of introducing a
+ * second that silently disagrees on those two chains.
+ *
+ * The `'TBD'` placeholder is rejected outright. `'eip155:TBD'` is a
+ * syntactically fine string that matches nothing in the registry — exactly the
+ * kind of value that reads back as "not deployed".
+ *
+ * Do NOT confuse this with `VM_NAMESPACE` in `constants/chain.ts`, which is the
+ * CAIP-2 *prefix* only (`'eip155'` / `'solana'`). Passing a bare prefix to the
+ * registry silently misses.
+ *
+ * ## Why these throw
+ *
+ * An unmapped namespace returns `(0x0, known=false)` from the registry, which
+ * is indistinguishable from "this wrapper is not deployed yet". Returning a
+ * negative would surface a mapping bug as an empty receipt field or a spurious
+ * "not registered" error. Throwing keeps the failure legible.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chainToNamespace = chainToNamespace;
+exports.namespaceToChain = namespaceToChain;
+exports.tryNamespaceToChain = tryNamespaceToChain;
+exports.tryChainToNamespace = tryChainToNamespace;
+exports.vmForChain = vmForChain;
+exports.isPushChain = isPushChain;
+exports.allExternalChains = allExternalChains;
+const enums_1 = require("../../../constants/enums");
+const chain_1 = require("../../../constants/chain");
+const errors_1 = require("./errors");
+/** All `CHAIN` enum values (PUSH_TESTNET_DONUT aliases PUSH_TESTNET, so this de-dupes). */
+const ALL_CHAINS = Array.from(new Set(Object.values(enums_1.CHAIN)));
+/** chainId values that are placeholders rather than real identifiers. */
+const PLACEHOLDER_CHAIN_IDS = new Set(['TBD', '', 'unknown']);
+function deriveNamespace(chain) {
+    const info = chain_1.CHAIN_INFO[chain];
+    if (!info)
+        return undefined;
+    if (PLACEHOLDER_CHAIN_IDS.has(info.chainId))
+        return undefined;
+    return `${chain_1.VM_NAMESPACE[info.vm]}:${info.chainId}`;
+}
+const CHAIN_TO_NAMESPACE = new Map(ALL_CHAINS.flatMap((chain) => {
+    const ns = deriveNamespace(chain);
+    return ns ? [[chain, ns]] : [];
+}));
+const NAMESPACE_TO_CHAIN = new Map(Array.from(CHAIN_TO_NAMESPACE, ([chain, ns]) => [ns, chain]));
+/**
+ * Convert a supported `CHAIN` to the namespace string UniversalCore is keyed on.
+ *
+ * @throws {PC20UnknownChainNamespaceError} if the chain is unsupported or its
+ * chainId is still a placeholder.
+ */
+function chainToNamespace(chain) {
+    const namespace = CHAIN_TO_NAMESPACE.get(chain);
+    if (!namespace) {
+        throw new errors_1.PC20UnknownChainNamespaceError(String(chain), {
+            chain: String(chain),
+            hint: 'This chain has no usable CAIP-2 chainId in CHAIN_INFO ' +
+                '(unsupported, or still a TBD placeholder).',
+        });
+    }
+    return namespace;
+}
+/**
+ * Convert a namespace string from chain or protobuf data back to a `CHAIN`.
+ *
+ * Used by the outbound tracking fallback, where `destinationChain` arrives as an
+ * untyped string from the node.
+ *
+ * @throws {PC20UnknownChainNamespaceError} if it maps to no supported chain.
+ */
+function namespaceToChain(namespace) {
+    const chain = NAMESPACE_TO_CHAIN.get(namespace);
+    if (!chain) {
+        throw new errors_1.PC20UnknownChainNamespaceError(namespace, {
+            hint: 'Expected a CAIP-2 chain id (e.g. "eip155:11155111"), not a bare ' +
+                'namespace prefix such as "eip155".',
+        });
+    }
+    return chain;
+}
+/** Non-throwing variant for callers that legitimately probe an unknown value. */
+function tryNamespaceToChain(namespace) {
+    return NAMESPACE_TO_CHAIN.get(namespace);
+}
+/** Non-throwing variant, for building candidate chain lists. */
+function tryChainToNamespace(chain) {
+    return CHAIN_TO_NAMESPACE.get(chain);
+}
+/** VM for a supported chain. Throws rather than defaulting to EVM. */
+function vmForChain(chain) {
+    const info = chain_1.CHAIN_INFO[chain];
+    if (!info) {
+        throw new errors_1.PC20UnknownChainNamespaceError(String(chain), {
+            chain: String(chain),
+            hint: 'Chain is not present in CHAIN_INFO.',
+        });
+    }
+    return info.vm;
+}
+/** True for any Push Chain network (never an external chain). */
+function isPushChain(chain) {
+    // PUSH_TESTNET_DONUT is an alias of PUSH_TESTNET, so it is covered here.
+    return (chain === enums_1.CHAIN.PUSH_MAINNET ||
+        chain === enums_1.CHAIN.PUSH_TESTNET ||
+        chain === enums_1.CHAIN.PUSH_LOCALNET);
+}
+/**
+ * Supported external chains that have a usable namespace — the default target
+ * set for deployment discovery when the caller passes no explicit `chains`.
+ */
+function allExternalChains() {
+    return ALL_CHAINS.filter((c) => !isPushChain(c) && CHAIN_TO_NAMESPACE.has(c));
+}
+//# sourceMappingURL=chain-namespace.js.map

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

@@ -0,0 +1,160 @@
+/**
+ * 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.
+ */
+export type PC20ErrorContext = {
+    /** Chain the caller supplied, when relevant. */
+    chain?: string;
+    /** Address the caller supplied, when relevant. */
+    address?: string;
+    /** Chain the SDK expected — signer chain, `from.chain`, or the Push chain. */
+    expectedChain?: string;
+    /** Resolved CAIP-2 namespace used for the registry read. */
+    chainNamespace?: string;
+    /** Short, actionable remediation. */
+    hint?: string;
+};
+/** Base class for all PC20 failures. `instanceof PC20Error` catches the family. */
+export declare class PC20Error extends Error {
+    readonly code: string;
+    readonly chain?: string;
+    readonly address?: string;
+    readonly expectedChain?: string;
+    readonly chainNamespace?: string;
+    readonly hint?: string;
+    constructor(code: string, message: string, ctx?: PC20ErrorContext);
+}
+/** Address is malformed for the supplied chain's VM, or is the zero/default address. */
+export declare class InvalidPC20AddressError extends PC20Error {
+    constructor(message: string, ctx?: PC20ErrorContext);
+}
+/**
+ * `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.
+ */
+export declare class PC20TokenChainMismatchError extends PC20Error {
+    constructor(ctx?: PC20ErrorContext);
+}
+/** UniversalCore has no source mapping for this wrapper on this chain. */
+export declare class PC20WrapperNotRegisteredError extends PC20Error {
+    constructor(ctx?: PC20ErrorContext);
+}
+/**
+ * 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.
+ */
+export declare class PC20RegistryMismatchError extends PC20Error {
+    constructor(ctx?: PC20ErrorContext & {
+        resolvedWrapper?: string;
+    });
+}
+/**
+ * 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.
+ */
+export declare class PC20FactoryMismatchError extends PC20Error {
+    constructor(ctx?: PC20ErrorContext & {
+        gatewayFactory?: string;
+        registryFactory?: string;
+    });
+}
+/** Token does not implement `pc20Metadata()`, or the metadata fails validation. */
+export declare class InvalidPC20MetadataError extends PC20Error {
+    constructor(message: string, ctx?: PC20ErrorContext);
+}
+/**
+ * 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".
+ */
+export declare class PC20ExpectedButPRC20Error extends PC20Error {
+    constructor(ctx?: PC20ErrorContext);
+}
+/** Destination chain has no configured PC20 factory, or is not supported for PC20. */
+export declare class UnsupportedPC20DestinationError extends PC20Error {
+    constructor(ctx?: PC20ErrorContext);
+}
+/** Caller's balance of the wrapper (inbound) or Push source (export) is short. */
+export declare class InsufficientPC20BalanceError extends PC20Error {
+    constructor(ctx?: PC20ErrorContext & {
+        required?: bigint;
+        available?: bigint;
+    });
+}
+/**
+ * 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.
+ */
+export declare class PC20AmbiguousAddressError extends PC20Error {
+    readonly candidates: Array<{
+        chain: string;
+        pushAddress: string;
+    }>;
+    constructor(address: string, candidates: Array<{
+        chain: string;
+        pushAddress: string;
+    }>);
+}
+/**
+ * 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.
+ */
+export declare class PC20UnknownChainNamespaceError extends PC20Error {
+    constructor(namespace: string, ctx?: PC20ErrorContext);
+}
+/**
+ * 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.
+ */
+export declare class PC20WrapperPredictionUnavailableError extends PC20Error {
+    constructor(ctx?: PC20ErrorContext);
+}
+/** A PC20 export reverted after the source token was locked. Carries recovery context. */
+export declare class PC20ExportRevertedError extends PC20Error {
+    readonly outboundTxId?: string;
+    readonly lockedAmount?: bigint;
+    readonly revertRecipient?: string;
+    constructor(ctx?: PC20ErrorContext & {
+        outboundTxId?: string;
+        lockedAmount?: bigint;
+        revertRecipient?: string;
+    });
+}
+/**
+ * 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.
+ */
+export declare class PC20UnsafeEmptyPayloadError extends PC20Error {
+    constructor(ctx?: PC20ErrorContext);
+}