@pushchain/core 6.0.25 → 6.0.27-alpha.0

package/src/lib/read-state/read-tracker.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.trackRead = trackRead;
 exports.toRequestIdHex = toRequestIdHex;
+exports.deriveReadOutcome = deriveReadOutcome;
 exports.inferResultShape = inferResultShape;
 exports.statusName = statusName;
 exports.defaultWaitTimeoutMs = defaultWaitTimeoutMs;
@@ -61,16 +62,23 @@ async function fetchRecords(deps, ref) {
 /** A request is indexed when its block is processed — briefly retry a miss. */
 async function lookupWithRetry(deps, ref, opts) {
     const now = deps.now ?? Date.now;
+    const emit = deps.emit ?? (() => undefined);
     const interval = pollInterval(opts);
     const start = now();
+    const hookRef = 'txHash' in ref ? { txHash: ref.txHash } : { requestId: toRequestIdHex(ref.requestId) };
+    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_03, hookRef);
     for (;;) {
         const records = await fetchRecords(deps, ref);
-        if (records.length > 0)
+        if (records.length > 0) {
+            for (const r of records)
+                emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_04, toRequestIdHex(r.id), statusName(r.status));
             return records;
+        }
         if (now() - start + interval > read_state_1.READ_TRACK_LOOKUP_TIMEOUT_MS)
             break;
         await sleep(interval);
     }
+    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_05, hookRef, now() - start);
     const label = 'txHash' in ref ? ref.txHash : toRequestIdHex(ref.requestId);
     throw new errors_1.ReadNotFoundError(label, 'txHash' in ref ? { txHash: ref.txHash } : { requestId: label });
 }
@@ -144,6 +152,8 @@ async function buildResponse(deps, record, opts) {
     }
     const txHash = req.requestedTxHash.toLowerCase();
     const response = {
+        requestIdUint: BigInt(requestId),
+        outcome: deriveReadOutcome(status, raw?.status, callbackDelivered, decodeError),
         requestId,
         txHash,
         destination,
@@ -174,23 +184,51 @@ async function buildResponse(deps, record, opts) {
     };
     return response;
 }
+/**
+ * One answer to "did it work". Order matters: a source error is delivered to the
+ * callback as an ERROR result, so it is reported before any callback outcome.
+ */
+function deriveReadOutcome(status, rawStatus, callbackDelivered, decodeError) {
+    switch (status) {
+        case read_state_types_1.UNIVERSAL_READ_STATUS.EXPIRED: return read_state_types_1.READ_OUTCOME.EXPIRED;
+        case read_state_types_1.UNIVERSAL_READ_STATUS.FAILED: return read_state_types_1.READ_OUTCOME.FAILED;
+        case read_state_types_1.UNIVERSAL_READ_STATUS.ABORTED: return read_state_types_1.READ_OUTCOME.ABORTED;
+        case read_state_types_1.UNIVERSAL_READ_STATUS.FULFILLED:
+            if (rawStatus !== undefined && rawStatus !== read_state_types_1.READ_STATUS.SUCCESS)
+                return read_state_types_1.READ_OUTCOME.SOURCE_ERROR;
+            if (callbackDelivered === false)
+                return read_state_types_1.READ_OUTCOME.CALLBACK_FAILED;
+            if (callbackDelivered !== true)
+                return read_state_types_1.READ_OUTCOME.UNKNOWN;
+            if (decodeError !== undefined)
+                return read_state_types_1.READ_OUTCOME.DECODE_FAILED;
+            return rawStatus === read_state_types_1.READ_STATUS.SUCCESS ? read_state_types_1.READ_OUTCOME.SUCCESS : read_state_types_1.READ_OUTCOME.UNKNOWN;
+        default:
+            return read_state_types_1.READ_OUTCOME.PENDING;
+    }
+}
 /** Parse every pc_tx receipt (fulfil, settle) into one merged outcome. Missing receipts are skipped. */
 async function collectOutcome(deps, record, requestId) {
     const uc = chain_1.UNIVERSAL_CALLBACK_ADDRESSES[deps.pushNetwork];
     const merged = {};
-    for (const t of record.pcTx) {
+    // Fetch in parallel, merge in pc_tx order (settle facts overwrite fulfil facts as before).
+    const outcomes = await Promise.all(record.pcTx.map(async (t) => {
         if (!t.txHash)
-            continue;
+            return undefined;
         try {
             const receipt = await deps.pushClient.getTransactionReceiptWithArchiveFallback(t.txHash);
-            const o = (0, read_events_1.parseFulfilOutcome)(receipt, uc, requestId);
-            for (const [k, v] of Object.entries(o)) {
-                if (v !== undefined)
-                    merged[k] = v;
-            }
+            return (0, read_events_1.parseFulfilOutcome)(receipt, uc, requestId);
         }
         catch {
-            // pruned or not yet available — leave those fields undefined rather than guess
+            return undefined; // pruned or not yet available — leave those fields undefined rather than guess
+        }
+    }));
+    for (const o of outcomes) {
+        if (!o)
+            continue;
+        for (const [k, v] of Object.entries(o)) {
+            if (v !== undefined)
+                merged[k] = v;
         }
     }
     return merged;
@@ -271,13 +309,13 @@ function inferResultShape(namespace, query) {
     }
 }
 function chainFromCaip2(caip2) {
-    if (caip2 === enums_1.CHAIN.WEB2)
-        return enums_1.CHAIN.WEB2;
+    if ((0, read_state_1.isWeb2ReadChain)(caip2))
+        return read_state_1.WEB2_READ_CHAIN;
     return Object.values(enums_1.CHAIN).includes(caip2) ? caip2 : undefined;
 }
 function explorerTxUrl(network, txHash) {
     const chain = network === enums_1.PUSH_NETWORK.MAINNET ? enums_1.CHAIN.PUSH_MAINNET : network === enums_1.PUSH_NETWORK.LOCALNET ? enums_1.CHAIN.PUSH_LOCALNET : enums_1.CHAIN.PUSH_TESTNET_DONUT;
-    const base = chain_1.PUSH_CHAIN_INFO[chain].explorerUrl ?? 'https://explorer.donut.push.org';
+    const base = chain_1.PUSH_CHAIN_INFO[chain].explorerUrl ?? 'https://donut.push.network';
     return `${base}/tx/${txHash}`;
 }
 // ---------------------------------------------------------------------------
@@ -312,6 +350,8 @@ async function waitForRead(deps, initial, opts) {
     const interval = pollInterval(opts);
     const start = now();
     let timeoutMs = opts.timeoutMs ?? read_state_1.READ_TRACK_MAX_TIMEOUT_MS;
+    // Push head at a known time; later heights are estimated from the block time (no extra RPC per poll).
+    let head;
     // Resolve a fresh head for each wait/resume, only when a default is needed.
     // Bound this RPC too: a stalled height lookup must not hang the promise forever.
     if (opts.timeoutMs === undefined && !initial.isTerminal) {
@@ -327,6 +367,7 @@ async function waitForRead(deps, initial, opts) {
                     }, read_state_1.READ_TRACK_MAX_TIMEOUT_MS);
                 }),
             ]);
+            head = { height, at: now() };
             timeoutMs = Math.min(read_state_1.READ_TRACK_MAX_TIMEOUT_MS, now() - start + defaultWaitTimeoutMs(height, initial.request.spec.expiryPushChainHeight));
         }
         finally {
@@ -334,6 +375,23 @@ async function waitForRead(deps, initial, opts) {
                 clearTimeout(timer);
         }
     }
+    else if (!initial.isTerminal) {
+        // Explicit timeout: the head only feeds the expiry warning, so never block on it.
+        deps.pushClient.publicClient.getBlockNumber({ cacheTime: 0 })
+            .then((height) => { head = { height, at: now() }; })
+            .catch(() => undefined);
+    }
+    let expiryWarned = false;
+    const warnNearExpiry = (r) => {
+        if (expiryWarned || !head)
+            return;
+        const estimated = head.height + BigInt(Math.floor((now() - head.at) / read_state_1.PUSH_BLOCK_TIME_MS));
+        const left = r.request.spec.expiryPushChainHeight - estimated;
+        if (left > read_state_1.READ_EXPIRY_WARNING_BLOCKS)
+            return;
+        expiryWarned = true;
+        emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_04, r.requestId, left > 0n ? left : 0n);
+    };
     emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_104_02, initial.txHash, initial.requestId, initial.request.logIndex);
     // Every snapshot taken from here on is built with the wait() options, so a
     // resultShape given to wait() decodes even a record that is already terminal.
@@ -388,6 +446,7 @@ async function waitForRead(deps, initial, opts) {
             else if (current.status === read_state_types_1.UNIVERSAL_READ_STATUS.VOTING)
                 emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_105_02, current.requestId);
         }
+        warnNearExpiry(current);
         const elapsed = now() - start;
         if (elapsed >= timeoutMs)
             timeout();
@@ -403,13 +462,20 @@ function emitTerminal(emit, r) {
             emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_03, r.requestId, r.callbackFailReason);
         if (r.fees.burned !== undefined)
             emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_04, r.requestId, r.fees.burned, r.fees.refunded ?? 0n);
-        if (r.fees.refundFailed === true)
-            emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_06, r.requestId, r.fees.refunded, r.request.refundTo);
-        else if (r.fees.refunded !== undefined)
-            emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_05, r.requestId, r.fees.refunded, r.request.refundTo);
+    }
+    // Refund facts exist for FULFILLED/FAILED (settle logs) and EXPIRED (EndBlock logs).
+    if (r.fees.refundFailed === true)
+        emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_06, r.requestId, r.fees.refunded, r.request.refundTo);
+    else if (r.fees.refunded !== undefined)
+        emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_106_05, r.requestId, r.fees.refunded, r.request.refundTo);
+    // 199-01 means it worked. A FULFILLED read that did not (source error, callback
+    // failure, undecodable, unconfirmed delivery) ends on 199-02 named by its outcome.
+    if (r.outcome === read_state_types_1.READ_OUTCOME.SUCCESS) {
         emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_01, r.requestId, r.value, r.raw?.resultData ?? '0x', r.callbackDelivered);
         return;
     }
-    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_02, r.requestId, statusName(r.status), r.raw?.errorCode, r.errorMsg, r.fees.refunded);
+    const ended = r.status === read_state_types_1.UNIVERSAL_READ_STATUS.FULFILLED ? r.outcome : statusName(r.status);
+    const detail = r.errorMsg || r.decodeError || '';
+    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_199_02, r.requestId, ended, r.raw?.errorCode, detail, r.fees.refunded);
 }
 //# sourceMappingURL=read-tracker.js.map

package/src/lib/read-state/registry.js

@@ -28,9 +28,8 @@ function resolveReadCallback(callback, network, queryKey) {
     if (callback && 'request' in callback)
         throw new errors_1.InvalidReadQueryError('callback.request was removed; use callback.abi, functionName and args');
     if (callback?.target !== undefined) {
-        if (callback.gasLimit === undefined)
-            throw new errors_1.InvalidReadQueryError('callback.gasLimit is required for a custom target');
-        return { ...callback, gasLimit: callback.gasLimit };
+        // Same default as the registry: unused callback budget is refunded.
+        return { ...callback, gasLimit: callback.gasLimit ?? read_state_1.REGISTRY_CALLBACK_GAS };
     }
     if (callback?.abi !== undefined || callback?.functionName !== undefined || callback?.args !== undefined) {
         throw new errors_1.InvalidReadQueryError('callback abi, functionName and args require callback.target');

package/src/lib/read-state/result-decoder.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.decodeReadResult = decodeReadResult;
 const viem_1 = require("viem");
 const errors_1 = require("./errors");
+const buffer_1 = require("buffer");
+const svm_account_1 = require("./svm-account");
 const WEB2_ABI_TYPE = {
     uint256: 'uint256',
     int256: 'int256',
@@ -29,6 +31,10 @@ function decodeReadResult(resultData, shape) {
     const len = (0, viem_1.size)(resultData);
     try {
         switch (shape.kind) {
+            case 'svmAccount': {
+                const { accountName, value } = (0, svm_account_1.decodeIdlAccount)(shape.idl, buffer_1.Buffer.from(resultData.slice(2), 'hex'), shape.accountName);
+                return { kind: 'svmAccount', value, accountName };
+            }
             case 'uint256': {
                 if (len !== 32)
                     throw new errors_1.ReadDecodeError(`expected 32 bytes for uint256, got ${len}`);

package/src/lib/read-state/spec-builder.js

@@ -106,7 +106,7 @@ function buildReadSpecFromPreflight(preflight, params, defaults = {}) {
     return {
         callback: params.callback,
         queryKey: (0, registry_1.computeReadQueryKey)(params.destination, params.query),
-        chain: dest.caip2,
+        chain: (isWeb2 ? read_state_1.WEB2_READ_CHAIN : dest.caip2),
         spec,
         specTuple: toTuple(spec),
         encodedSpec: encodeSpec(spec),
@@ -185,7 +185,7 @@ function toCallData(prepared, target) {
  */
 async function simulateRead(deps, prepared, opts) {
     const age = Date.now() - prepared.preflight.fetchedAt;
-    if (age > (opts.staleAfterMs ?? 60_000)) {
+    if (age > (opts.staleAfterMs ?? read_state_1.READ_PREFLIGHT_STALE_MS)) {
         prepared.warnings.push(`preflight is ${Math.round(age / 1000)} s old — pushBlockNumber moves every block; rebuild before sending`);
     }
     try {

package/src/lib/read-state/svm-account.d.ts

@@ -0,0 +1,20 @@
+import { type Idl } from '@coral-xyz/anchor';
+import { PublicKey } from '@solana/web3.js';
+import type { CHAIN } from '../constants/enums';
+/** snake_case, camelCase and PascalCase spellings of one name share a key. */
+export declare function idlNameKey(name: string): string;
+/** Structural checks the coder does not make, so a bad IDL fails at prepare time. */
+export declare function validateIdl(idl: Idl): void;
+/** The IDL's own spelling of an account layout name given in any case style. */
+export declare function resolveAccountName(idl: Idl, name: string): string;
+/**
+ * Decode account bytes with the IDL. With `accountName`, the data's discriminator
+ * must match that layout; without it, the layout is the one whose discriminator
+ * prefixes the data.
+ */
+export declare function decodeIdlAccount(idl: Idl, data: Uint8Array, accountName?: string): {
+    accountName: string;
+    value: unknown;
+};
+/** Inspect the mint owner; the chain alone cannot distinguish SPL Token and Token-2022. */
+export declare function detectTokenProgram(mint: string, chain: CHAIN, rpcUrls?: string[]): Promise<PublicKey>;

package/src/lib/read-state/svm-account.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.idlNameKey = idlNameKey;
+exports.validateIdl = validateIdl;
+exports.resolveAccountName = resolveAccountName;
+exports.decodeIdlAccount = decodeIdlAccount;
+exports.detectTokenProgram = detectTokenProgram;
+const anchor_1 = require("@coral-xyz/anchor");
+const web3_js_1 = require("@solana/web3.js");
+const chain_1 = require("../constants/chain");
+const buffer_1 = require("buffer");
+const errors_1 = require("./errors");
+const svm_1 = require("./envelopes/svm");
+/** snake_case, camelCase and PascalCase spellings of one name share a key. */
+function idlNameKey(name) {
+    return name.replace(/_/g, '').toLowerCase();
+}
+/** Structural checks the coder does not make, so a bad IDL fails at prepare time. */
+function validateIdl(idl) {
+    try {
+        if (!idl || typeof idl !== 'object')
+            throw new Error('idl must be an Anchor IDL object');
+        new web3_js_1.PublicKey(idl.address);
+        if (!idl.accounts?.length)
+            throw new Error('the IDL declares no accounts');
+        for (const a of idl.accounts) {
+            const d = a.discriminator;
+            if (!Array.isArray(d) || d.length === 0 || d.some(b => !Number.isInteger(b) || b < 0 || b > 255)) {
+                throw new Error(`account ${a.name}: discriminator must be a non-empty byte array`);
+            }
+        }
+        new anchor_1.BorshAccountsCoder(idl);
+    }
+    catch (error) {
+        throw new errors_1.InvalidReadQueryError(`invalid Solana account IDL: ${error.message}`);
+    }
+}
+/** The IDL's own spelling of an account layout name given in any case style. */
+function resolveAccountName(idl, name) {
+    const accounts = idl.accounts ?? [];
+    const exact = accounts.find(a => a.name === name);
+    if (exact)
+        return exact.name;
+    const key = idlNameKey(name);
+    const matches = accounts.filter(a => idlNameKey(a.name) === key);
+    if (matches.length === 1)
+        return matches[0].name;
+    const known = accounts.map(a => a.name).join(', ') || 'none';
+    throw new errors_1.InvalidReadQueryError(matches.length > 1 ? `functionName ${name} is ambiguous in the IDL (${matches.map(a => a.name).join(', ')})` : `functionName ${name} is not an account in the IDL (accounts: ${known})`);
+}
+function hasDiscriminator(a, data) {
+    return data.length >= a.discriminator.length && a.discriminator.every((b, i) => data[i] === b);
+}
+/**
+ * Decode account bytes with the IDL. With `accountName`, the data's discriminator
+ * must match that layout; without it, the layout is the one whose discriminator
+ * prefixes the data.
+ */
+function decodeIdlAccount(idl, data, accountName) {
+    const accounts = idl.accounts ?? [];
+    let def;
+    if (accountName !== undefined) {
+        def = accounts.find(a => a.name === resolveAccountName(idl, accountName));
+        if (def && !hasDiscriminator(def, data)) {
+            throw new errors_1.ReadDecodeError(`account data discriminator does not match ${def.name}`);
+        }
+    }
+    else {
+        const found = accounts.filter(a => hasDiscriminator(a, data));
+        // Longest match wins if one discriminator prefixes another.
+        def = found.sort((x, y) => y.discriminator.length - x.discriminator.length)[0];
+        if (!def) {
+            const head = buffer_1.Buffer.from(data.subarray(0, 8)).toString('hex');
+            throw new errors_1.ReadDecodeError(`no IDL account discriminator matches the account data (0x${head})`);
+        }
+    }
+    if (!def)
+        throw new errors_1.ReadDecodeError('account not found in the IDL');
+    return { accountName: def.name, value: new anchor_1.BorshAccountsCoder(idl).decode(def.name, buffer_1.Buffer.from(data)) };
+}
+/** Inspect the mint owner; the chain alone cannot distinguish SPL Token and Token-2022. */
+async function detectTokenProgram(mint, chain, rpcUrls) {
+    const address = new web3_js_1.PublicKey(mint);
+    const urls = rpcUrls ?? chain_1.CHAIN_INFO[chain]?.defaultRPC;
+    if (!urls?.length)
+        throw new errors_1.InvalidReadQueryError(`no Solana RPC configured for ${chain}`);
+    let lastError;
+    for (const url of urls) {
+        let info;
+        try {
+            info = await new web3_js_1.Connection(url, 'finalized').getAccountInfo(address, 'finalized');
+        }
+        catch (error) {
+            lastError = error;
+            continue;
+        }
+        if (!info)
+            throw new errors_1.InvalidReadQueryError(`token mint does not exist: ${mint}`);
+        if (!info.owner.equals(svm_1.TOKEN_PROGRAM_ID) && !info.owner.equals(svm_1.TOKEN_2022_PROGRAM_ID)) {
+            throw new errors_1.InvalidReadQueryError('mint is not owned by SPL Token or Token-2022');
+        }
+        // Mint base layout: 82 bytes, initialized flag at byte 45. Token-2022
+        // extensions pad to 165 bytes and carry AccountType.Mint (1) at byte 165.
+        if (info.executable || info.data.length < 82 || info.data[45] !== 1 ||
+            (info.owner.equals(svm_1.TOKEN_PROGRAM_ID) && info.data.length !== 82) ||
+            (info.owner.equals(svm_1.TOKEN_2022_PROGRAM_ID) && info.data.length !== 82 &&
+                (info.data.length < 166 || info.data[165] !== 1))) {
+            throw new errors_1.InvalidReadQueryError('token address is not an initialized mint');
+        }
+        return info.owner;
+    }
+    throw lastError;
+}
+//# sourceMappingURL=svm-account.js.map

package/src/lib/read-state/svm-pda.d.ts

@@ -0,0 +1,13 @@
+/**
+ * PDA derivation for `read(programId, { idl, functionName, args })`.
+ *
+ * The seed layout comes from the IDL, never from a guessed encoding: Anchor
+ * records each PDA's seeds on the instruction accounts that use it. `args` fill
+ * the non-constant seeds in order, encoded as the IDL declares them.
+ */
+import type { Idl } from '@coral-xyz/anchor';
+import { PublicKey } from '@solana/web3.js';
+/** Derive the PDA of account layout `functionName` from its IDL seed template and positional `args`. */
+export declare function deriveIdlPda(idl: Idl, functionName: string, args?: readonly unknown[]): PublicKey;
+/** Whether `subject` is the IDL's program id (base58 or 0x-hex). */
+export declare function isProgramSubject(idl: Idl, subject: string): boolean;

package/src/lib/read-state/svm-pda.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveIdlPda = deriveIdlPda;
+exports.isProgramSubject = isProgramSubject;
+const web3_js_1 = require("@solana/web3.js");
+const buffer_1 = require("buffer");
+const normalize_address_1 = require("../orchestrator/svm-idl/normalize-address");
+const errors_1 = require("./errors");
+const svm_account_1 = require("./svm-account");
+/** Every instruction account named like `name` that carries PDA seeds. */
+function findSeedTemplates(idl, name) {
+    const key = (0, svm_account_1.idlNameKey)(name);
+    const out = [];
+    const visit = (instruction, accounts) => {
+        for (const a of accounts) {
+            if (a.accounts)
+                visit(instruction, a.accounts); // composite account groups
+            else if (a.pda && (0, svm_account_1.idlNameKey)(a.name) === key)
+                out.push({ pda: a.pda, instruction });
+        }
+    };
+    for (const ix of idl.instructions ?? [])
+        visit(ix, ix.accounts);
+    return out;
+}
+function toPublicKey(value, what) {
+    if (value instanceof web3_js_1.PublicKey)
+        return value;
+    try {
+        return new web3_js_1.PublicKey(buffer_1.Buffer.from((0, normalize_address_1.toSvmHexAddress)(value).slice(2), 'hex'));
+    }
+    catch (e) {
+        throw new errors_1.InvalidReadQueryError(`${what} must be a Solana pubkey (base58, 0x 32-byte hex, or PublicKey): ${e.message}`);
+    }
+}
+const INT_WIDTH = {
+    u8: [1, false], i8: [1, true], u16: [2, false], i16: [2, true], u32: [4, false], i32: [4, true],
+    u64: [8, false], i64: [8, true], u128: [16, false], i128: [16, true],
+};
+function encodeInt(value, type, what) {
+    const [bytes, signed] = INT_WIDTH[type];
+    let n;
+    try {
+        n = typeof value === 'bigint' ? value : BigInt(value);
+    }
+    catch {
+        throw new errors_1.InvalidReadQueryError(`${what} must be an integer for ${type}`);
+    }
+    const bits = BigInt(bytes * 8);
+    const min = signed ? -(1n << (bits - 1n)) : 0n;
+    const max = signed ? (1n << (bits - 1n)) - 1n : (1n << bits) - 1n;
+    if (n < min || n > max)
+        throw new errors_1.InvalidReadQueryError(`${what} out of ${type} range: ${n}`);
+    let u = n < 0n ? (1n << bits) + n : n;
+    const out = buffer_1.Buffer.alloc(bytes);
+    for (let i = 0; i < bytes; i++) {
+        out[i] = Number(u & 0xffn);
+        u >>= 8n;
+    }
+    return out;
+}
+function encodeSeed(value, type, what) {
+    if (type === 'pubkey')
+        return toPublicKey(value, what).toBuffer();
+    if (typeof type === 'string' && type in INT_WIDTH)
+        return encodeInt(value, type, what);
+    if (type === 'bool') {
+        if (typeof value !== 'boolean')
+            throw new errors_1.InvalidReadQueryError(`${what} must be a boolean`);
+        return buffer_1.Buffer.from([value ? 1 : 0]);
+    }
+    if (type === 'string') {
+        if (typeof value !== 'string')
+            throw new errors_1.InvalidReadQueryError(`${what} must be a string`);
+        return buffer_1.Buffer.from(value, 'utf8');
+    }
+    const isBytes = type === 'bytes' || (typeof type === 'object' && type !== null && 'array' in type && type.array[0] === 'u8');
+    if (isBytes) {
+        if (value instanceof Uint8Array)
+            return buffer_1.Buffer.from(value);
+        if (typeof value === 'string' && /^0x([0-9a-fA-F]{2})*$/.test(value))
+            return buffer_1.Buffer.from(value.slice(2), 'hex');
+        throw new errors_1.InvalidReadQueryError(`${what} must be bytes (Uint8Array or 0x-hex)`);
+    }
+    throw new errors_1.InvalidReadQueryError(`${what}: seed type ${JSON.stringify(type)} is not supported`);
+}
+function argType(ix, path) {
+    if (path.includes('.'))
+        throw new errors_1.InvalidReadQueryError(`seed arg path ${path} reads a struct field; only top-level instruction args are supported`);
+    const arg = ix.args.find(a => a.name === path) ?? ix.args.find(a => (0, svm_account_1.idlNameKey)(a.name) === (0, svm_account_1.idlNameKey)(path));
+    if (!arg)
+        throw new errors_1.InvalidReadQueryError(`seed arg ${path} is not an argument of ${ix.name}`);
+    return arg.type;
+}
+function describeSeeds(t) {
+    return t.pda.seeds.map(s => (s.kind === 'const' ? `"${buffer_1.Buffer.from(s.value).toString('utf8')}"` : `${s.kind}:${s.path}`)).join(', ');
+}
+/** Same seeds, same order: two instructions describing one PDA agree. */
+function sameLayout(a, b) {
+    return JSON.stringify([a.pda.seeds, a.pda.program]) === JSON.stringify([b.pda.seeds, b.pda.program]);
+}
+/** Derive the PDA of account layout `functionName` from its IDL seed template and positional `args`. */
+function deriveIdlPda(idl, functionName, args = []) {
+    const templates = findSeedTemplates(idl, functionName);
+    if (templates.length === 0) {
+        throw new errors_1.InvalidReadQueryError(`the IDL has no PDA seeds for ${functionName}; pass the account address as the subject instead of the program id`);
+    }
+    const [template] = templates;
+    if (templates.some(t => !sameLayout(t, template))) {
+        throw new errors_1.InvalidReadQueryError(`the IDL describes ${functionName} with different seeds in different instructions; pass the account address as the subject`);
+    }
+    const dynamic = template.pda.seeds.filter(s => s.kind !== 'const');
+    if (args.length !== dynamic.length) {
+        throw new errors_1.InvalidReadQueryError(`${functionName} is derived from seeds [${describeSeeds(template)}]: expected ${dynamic.length} args, got ${args.length}`);
+    }
+    let i = 0;
+    const seeds = template.pda.seeds.map((seed) => {
+        if (seed.kind === 'const')
+            return buffer_1.Buffer.from(seed.value);
+        const what = `args[${i}] (${seed.kind}:${seed.path})`;
+        const value = args[i++];
+        if (seed.kind === 'account') {
+            if (seed.path.includes('.'))
+                throw new errors_1.InvalidReadQueryError(`seed ${seed.path} reads another account's field; pass the account address as the subject`);
+            return encodeSeed(value, 'pubkey', what);
+        }
+        return encodeSeed(value, argType(template.instruction, seed.path), what);
+    });
+    let programId = new web3_js_1.PublicKey(idl.address);
+    const program = template.pda.program;
+    if (program) {
+        if (program.kind !== 'const')
+            throw new errors_1.InvalidReadQueryError(`${functionName} is derived under a non-constant program; pass the account address as the subject`);
+        programId = new web3_js_1.PublicKey(buffer_1.Buffer.from(program.value));
+    }
+    return web3_js_1.PublicKey.findProgramAddressSync(seeds, programId)[0];
+}
+/** Whether `subject` is the IDL's program id (base58 or 0x-hex). */
+function isProgramSubject(idl, subject) {
+    try {
+        return (0, normalize_address_1.toSvmHexAddress)(subject) === (0, normalize_address_1.toSvmHexAddress)(idl.address);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=svm-pda.js.map

package/src/lib/universal/prc20-address.d.ts

@@ -0,0 +1,15 @@
+import { CHAIN, PUSH_NETWORK } from '../constants/enums';
+import { type MoveableToken } from '../constants/tokens';
+/** Shared pure origin-to-PRC20 mapping; no signer or network reads. */
+export declare function getPRC20Address(token: MoveableToken | {
+    chain: string;
+    address: string;
+}, options?: {
+    network?: PUSH_NETWORK;
+}): {
+    address: `0x${string}`;
+    chain: CHAIN;
+    symbol: string;
+    decimals: number;
+    network: PUSH_NETWORK;
+};