@pushchain/core 6.0.19 → 6.0.21

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

@@ -0,0 +1,187 @@
+/**
+ * PC20 registry resolver — the one module that reads PC20 state.
+ *
+ * Used by `sendTransaction`, `prepareTransaction`, cascade construction,
+ * `getPC20Address`, and the outbound tracking fallback.
+ * Nothing else may read the registry directly; a second reader is how the
+ * validation tiers and the cache policy drift apart.
+ *
+ * ## Read budget
+ *
+ * Validation is tiered so a send does not pay for the full identity sweep:
+ *
+ *   Tier A (every send)  — `getPC20Source` then `getPC20Wrapper`. Forward and
+ *                          reverse agreement proves the address is registered
+ *                          for that exact namespace, which is what defeats a
+ *                          wrapper address copied onto the wrong chain.
+ *   Tier B (prepare-time, first use per session, or strict mode) — live gateway
+ *                          factory identity, `isPC20Wrapper`, `wrapperToSource`,
+ *                          `SOURCE_ASSET`, deployed bytecode. Largely redundant
+ *                          once Tier A holds, but it is what catches a
+ *                          misconfigured deployment where the gateway would not
+ *                          take the PC20 burn path at all.
+ *
+ * Each tier is one multicall against one chain. Budget: at most 2 sequential
+ * round trips warm, 4 cold. `__readCount` exists so tests can assert that.
+ *
+ * ## Cache policy
+ *
+ * Positive results are cached for the client's lifetime, keyed by
+ * `(pushNetwork, chain, address)`. Registered mappings are immutable in
+ * practice — a factory reconfiguration is a redeploy-level event.
+ *
+ * Negative results are NEVER cached. The first successful export creates a
+ * mapping that did not previously exist, and a cached "not registered" would
+ * make the SDK permanently wrong about a token that now works.
+ */
+import { type Hex } from 'viem';
+import { CHAIN, PUSH_NETWORK, VM } from '../../../constants/enums';
+/** Metadata read off a Push-native PC20 via `pc20Metadata()`. */
+export type PC20Metadata = {
+    name: string;
+    symbol: string;
+    decimals: number;
+    originAddress: `0x${string}`;
+};
+/** A confirmed wrapper deployment on one external chain. */
+export type PC20DeploymentInfo = {
+    chain: CHAIN;
+    chainNamespace: string;
+    vm: VM;
+    /** Chain-native form: checksummed hex (EVM) or base58 (SVM). */
+    address: string;
+    /** Registry form, as stored in UniversalCore. */
+    rawAddress: Hex;
+};
+/** Everything the execution path needs about a resolved funds token. */
+export type ResolvedPC20 = {
+    direction: 'import' | 'export';
+    /** Chain the token the caller named lives on. */
+    originChain: CHAIN;
+    /** Chain-native address of the token the caller named. */
+    originAddress: string;
+    /** Canonical Push-native PC20. */
+    pushAddress: `0x${string}`;
+    name: string;
+    symbol: string;
+    decimals: number;
+    /** External wrapper, when one is registered. Absent before a first export. */
+    wrapperAddress?: string;
+    /** Namespace of the external side (origin for import, destination for export). */
+    chainNamespace?: string;
+};
+export type PC20ResolverOptions = {
+    network: PUSH_NETWORK;
+    /** Per-chain RPC overrides. Falls back to `CHAIN_INFO[chain].defaultRPC`. */
+    rpcUrls?: Partial<Record<CHAIN, string[]>>;
+    /** Run Tier B factory-identity checks even on a warm path. */
+    strict?: boolean;
+    /** Re-read the wrapper/source registry even when a positive cache entry exists. */
+    bypassCache?: boolean;
+};
+/**
+ * Instrumentation for the round-trip budget assertion. Incremented once per
+ * network round trip (a batch counts as one, which is the whole point).
+ */
+export declare const __readCount: {
+    n: number;
+};
+/**
+ * Resolve UniversalCore through the UGPC precompile, matching how
+ * `gas-calculator.queryOutboundGasFee` does it. Cached per network — the
+ * precompile's `universalCore` pointer does not move within a session.
+ */
+export declare function getUniversalCoreAddress(opts: PC20ResolverOptions): Promise<`0x${string}`>;
+/** Test seam. Never call from product code — it would drop verified Tier B state. */
+export declare function __clearPC20Caches(): void;
+/**
+ * Resolve an external wrapper to its canonical Push-native source.
+ *
+ * One multicall: `getPC20Source(wrapper, ns)` and, in the same batch, the
+ * reverse `getPC20Wrapper` cannot be issued because it depends on the source.
+ * The reverse read is therefore a second round trip — this is the "2 sequential
+ * round trips" in the budget, and it is not collapsible: the registry has no
+ * combined accessor.
+ *
+ * @throws {PC20WrapperNotRegisteredError} when the wrapper is unknown.
+ * @throws {PC20RegistryMismatchError} when forward and reverse disagree.
+ */
+export declare function resolveWrapperToSource(chain: CHAIN, address: string, opts: PC20ResolverOptions): Promise<{
+    pushAddress: `0x${string}`;
+    chainNamespace: string;
+    rawWrapper: Hex;
+}>;
+/**
+ * Verify the live external gateway will actually take the PC20 burn path for
+ * this wrapper, and that its factory is the one UniversalCore knows about.
+ *
+ * Two multicalls: the gateway's factory pointer must be read before the
+ * factory-scoped calls can be addressed.
+ *
+ * @throws {PC20FactoryMismatchError} on any identity disagreement.
+ */
+export declare function verifyEvmWrapperIdentity(chain: CHAIN, address: string, pushAddress: `0x${string}`, opts: PC20ResolverOptions): Promise<void>;
+/**
+ * Read and validate `pc20Metadata()` on a Push-native token.
+ *
+ * The absence of `pc20Metadata` is the discriminator between a PC20 and any
+ * other ERC20 — never the symbol. A synthetic PRC20 is detected separately so
+ * it gets an error that points at the right API rather than reading as
+ * "your token is broken".
+ */
+export declare function readPushPC20Metadata(pushAddress: `0x${string}`, opts: PC20ResolverOptions): Promise<PC20Metadata>;
+/**
+ * Confirmed wrapper deployments for a Push-native PC20.
+ *
+ * One multicall regardless of chain count — every `getPC20Wrapper` read targets
+ * UniversalCore on Push Chain, so fanning out per chain would be N round trips
+ * to the same endpoint for no reason.
+ *
+ * Returns confirmed deployments only. A predicted first-export address is the
+ * outbound builder's concern, not discovery's.
+ */
+export declare function listPC20Deployments(pushAddress: `0x${string}`, opts: PC20ResolverOptions & {
+    chains?: CHAIN[];
+}): Promise<PC20DeploymentInfo[]>;
+/**
+ * Registered wrapper for a Push PC20 on one destination chain.
+ *
+ * `undefined` means not yet deployed — a legitimate state before a first
+ * export, not an error. Callers that need an address for a first export must go
+ * through the prediction path, which verifies against the live factory.
+ */
+export declare function getRegisteredWrapper(pushAddress: `0x${string}`, destinationChain: CHAIN, opts: PC20ResolverOptions): Promise<PC20DeploymentInfo | undefined>;
+/**
+ * Work out which chain an address belongs to, when the caller did not say.
+ *
+ * Used ONLY by the read-only `getPC20Address` utility. The transaction path
+ * never calls this — `funds.token` requires an explicit `chain`, and
+ * `gate.ts` rejects one that disagrees with where the funds actually are. A
+ * wrapper address copied from the wrong chain still fails on send; it merely
+ * resolves informationally on lookup.
+ *
+ * Order is cheapest-first:
+ *   1. narrow candidates by address format (local, free);
+ *   2. try Push-native, which short-circuits with no registry read at all;
+ *   3. probe every remaining namespace in one multicall.
+ *
+ * @throws {PC20AmbiguousAddressError} when several chains claim the address
+ * with different Push sources.
+ */
+export declare function discoverPC20Chain(address: string, opts: PC20ResolverOptions): Promise<{
+    chain: CHAIN;
+    pushAddress: `0x${string}`;
+} | null>;
+/**
+ * Resolve a `{ chain, address }` PC20 reference into everything the execution
+ * path needs, exactly once per transaction.
+ *
+ * `expectedChain` is where the funds actually are — the signer's chain for a
+ * direct external route, `params.from.chain` for a CEA-origin route, the Push
+ * chain for an export. Chain-ownership validation is the caller's job because
+ * only the caller knows which of those applies; this function assumes it has
+ * already passed.
+ */
+export declare function resolvePC20Token(chain: CHAIN, address: string, opts: PC20ResolverOptions & {
+    tierB?: boolean;
+}): Promise<ResolvedPC20>;