@pushchain/core 6.0.27-alpha.2 → 6.0.27-alpha.4

package/src/lib/agentic/constants.d.ts

@@ -1,6 +1,41 @@
-/** Public section-7 discovery constants; deployment wiring stays internal. */
+/** Public vocabulary. JOB.ADDRESS is the explicit per-chain job integration surface. */
 export declare const AGENTIC: Readonly<{
     WALLET: "agentic:wallet";
+    PRINCIPAL: "agentic:principal";
+    JOB: Readonly<{
+        ADDRESS: Readonly<{
+            'eip155:42101': Readonly<{
+                KERNEL: "0x977cf1AC973E9eC4332791d531507575006157Ed";
+                HOOK: "0xDe7A94e510b6C571DE7880d441349689F73A32b3";
+                EVALUATOR: "0x1afC81396f1bb36F91f74506284952b81e4bd47c";
+            }>;
+        }>;
+        EVALUATION: Readonly<{
+            readonly BOOLEAN: "BOOLEAN";
+            readonly COMPARE: "COMPARE";
+            readonly NUMBER: "NUMBER";
+            readonly PERCENTAGE: "PERCENTAGE";
+        }>;
+        OPERATION: Readonly<{
+            readonly EQUAL: "EQUAL";
+            readonly NOT_EQUAL: "NOT_EQUAL";
+            readonly GREATER_THAN: "GREATER_THAN";
+            readonly GREATER_OR_EQUAL: "GREATER_OR_EQUAL";
+            readonly LESS_THAN: "LESS_THAN";
+            readonly LESS_OR_EQUAL: "LESS_OR_EQUAL";
+        }>;
+        LOGIC: Readonly<{
+            readonly ALL: "ALL";
+            readonly ANY: "ANY";
+            readonly AT_LEAST: "AT_LEAST";
+        }>;
+        ALLOWED_MUTABILITY: Readonly<{
+            readonly NONE: "NONE";
+            readonly CLIENT: "CLIENT";
+            readonly PROVIDER: "PROVIDER";
+            readonly BOTH: "BOTH";
+        }>;
+    }>;
     PRESETS: Readonly<{
         CATEGORY: Readonly<{
             DEXES: "DEXES";

package/src/lib/agentic/constants.js

@@ -1,9 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AGENTIC = void 0;
-/** Public section-7 discovery constants; deployment wiring stays internal. */
+const constants_1 = require("../job-spec/constants");
+const deployment_1 = require("../market/deployment");
+/** Public vocabulary. JOB.ADDRESS is the explicit per-chain job integration surface. */
 exports.AGENTIC = Object.freeze({
     WALLET: 'agentic:wallet',
+    PRINCIPAL: constants_1.PRINCIPAL,
+    JOB: Object.freeze({
+        ...constants_1.JOB_VOCABULARY,
+        ADDRESS: Object.freeze({
+            'eip155:42101': Object.freeze({
+                KERNEL: deployment_1.DONUT_MARKETPLACE.kernel,
+                HOOK: deployment_1.DONUT_MARKETPLACE.hook,
+                EVALUATOR: deployment_1.DONUT_MARKETPLACE.evaluator,
+            }),
+        }),
+    }),
     PRESETS: Object.freeze({
         CATEGORY: Object.freeze({
             DEXES: 'DEXES',

package/src/lib/agentic/contracts/prc20-metadata.d.ts

@@ -22,5 +22,5 @@ export declare const PRC20_SOURCE_ABI: readonly [{
 export declare function readSvmSourceToken(snap: Snapshot, token: Address, chain: string, network?: PUSH_NETWORK): Promise<Hex>;
 export declare const CORE_ADDRESS: Address;
 export declare function readGasPrc20(snap: Snapshot, chain: string): Promise<Address>;
-/** Donut native precompile returns a zero word; ERC20 metadata is a dynamic string. */
+/** Solidity PRC20s return a string; Donut precompiles can return an address word. */
 export declare function readOriginToken(snap: Snapshot, token: Address, chain: string): Promise<Address>;

package/src/lib/agentic/contracts/prc20-metadata.js

@@ -64,19 +64,25 @@ exports.CORE_ADDRESS = '0x00000000000000000000000000000000000000C0';
 async function readGasPrc20(snap, chain) {
     return (0, viem_1.getAddress)(await snap.read(exports.CORE_ADDRESS, prc20_evm_1.UNIVERSAL_CORE_EVM, 'gasTokenPRC20ByChainNamespace', [chain]));
 }
-/** Donut native precompile returns a zero word; ERC20 metadata is a dynamic string. */
+/** Solidity PRC20s return a string; Donut precompiles can return an address word. */
 async function readOriginToken(snap, token, chain) {
     let source;
     try {
         source = await snap.read(token, exports.PRC20_SOURCE_ABI, 'SOURCE_TOKEN_ADDRESS');
     }
     catch (cause) {
-        if ((await readGasPrc20(snap, chain)) !== (0, viem_1.getAddress)(token))
+        let sourceWord;
+        try {
+            sourceWord = (0, viem_1.getAddress)(await snap.read(token, NATIVE_SOURCE_ABI, 'SOURCE_TOKEN_ADDRESS'));
+        }
+        catch {
             throw cause;
-        const native = await snap.read(token, NATIVE_SOURCE_ABI, 'SOURCE_TOKEN_ADDRESS');
-        if ((0, viem_1.getAddress)(native) === viem_1.zeroAddress)
+        }
+        if (sourceWord !== viem_1.zeroAddress)
+            return sourceWord;
+        if ((await readGasPrc20(snap, chain)) === (0, viem_1.getAddress)(token))
             return viem_1.zeroAddress;
-        throw cause;
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED, `non-native PRC20 ${token} has an empty source token address`);
     }
     if ((0, viem_1.isAddress)(source, { strict: false }))
         return (0, viem_1.getAddress)(source);

package/src/lib/agentic/contracts/reader.d.ts

@@ -13,6 +13,12 @@ export interface ChainReader {
         blockNumber?: bigint;
     }): Promise<unknown>;
     getBlockNumber(): Promise<bigint>;
+    getBlock?(args: {
+        blockNumber: bigint;
+    }): Promise<{
+        timestamp: bigint;
+        hash?: Hex | null;
+    }>;
     getCode(args: {
         address: Address;
         blockNumber?: bigint;
@@ -31,5 +37,20 @@ export interface ChainReader {
     getTransactionReceipt(args: {
         hash: Hex;
     }): Promise<TransactionReceipt>;
+    getTransaction?(args: {
+        hash: Hex;
+    }): Promise<{
+        input: Hex;
+        blockNumber: bigint | null;
+    }>;
+    /** Raw eth_call, used to verify complete signed marketplace requests before broadcast. */
+    call?(args: {
+        to: Address;
+        data: Hex;
+        account?: Address;
+        blockNumber?: bigint;
+    }): Promise<{
+        data?: Hex;
+    }>;
 }
 export declare function chainReaderFromPublicClient(client: PublicClient): ChainReader;

package/src/lib/agentic/contracts/reader.js

@@ -7,10 +7,13 @@ function chainReaderFromPublicClient(client) {
     return {
         readContract: (args) => client.readContract(args),
         getBlockNumber: () => client.getBlockNumber({ cacheTime: 0 }),
+        getBlock: (args) => client.getBlock(args),
         getCode: (args) => client.getCode(args),
         getBalance: (args) => client.getBalance(args),
         getLogs: (args) => client.getLogs(args),
         getTransactionReceipt: (args) => client.getTransactionReceipt(args),
+        getTransaction: (args) => client.getTransaction(args),
+        call: (args) => client.call(args),
     };
 }
 //# sourceMappingURL=reader.js.map

package/src/lib/agentic/error-messages.d.ts

@@ -0,0 +1,3 @@
+import type { AgenticErrorCode } from './errors';
+export declare function agenticUserMessage(code: AgenticErrorCode, diagnostic: string, details?: Readonly<Record<string, unknown>>): string;
+export declare function agenticRevertUserMessage(name?: string): string;

package/src/lib/agentic/error-messages.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agenticUserMessage = agenticUserMessage;
+exports.agenticRevertUserMessage = agenticRevertUserMessage;
+/** UI copy only. Codes, original messages, hints and causes remain diagnostic data. */
+const MESSAGES = {
+    DUPLICATE_RULE: 'Keep one rule per agent and network. Edit the existing rule or remove the duplicate.',
+    AGENT_IS_OWNER: 'Choose an agent address different from the wallet owner.',
+    AMBIGUOUS_RULE: 'More than one rule matches this agent and network. Keep one active matching rule before sending.',
+    TARGET_NOT_ON_RULE_CHAIN: 'Choose an app on the network selected for this rule.',
+    ASSET_CHAIN_MISMATCH: 'The selected token belongs to a different network. Choose a token on this rule’s network.',
+    TOKEN_ROUTE_UNAVAILABLE: 'This token cannot currently be transferred from Push to the selected network. Choose a token with a supported Push route.',
+    REQUEST_REJECTED: 'The wallet request was cancelled. Check wallet activity before trying again.',
+    NOT_OWNER_OR_AGENT: 'Connect the wallet owner or an agent authorized by its rules.',
+    WALLET_NOT_DEPLOYED: 'This agentic wallet has not been created yet.',
+    NOT_AGENTIC_WALLET: 'This address is not a supported agentic wallet.',
+    DELETE_NEEDS_TARGET: 'Choose which rules to remove.',
+    NO_RULES_FOR_CHAIN: 'This agent has no active rule for the selected network.',
+    FROM_NOT_ALLOWED: 'The agentic wallet is the sender. Remove the custom sender selection.',
+    NOT_ALLOWED_IN_AGENTIC_MODE: 'This action is unavailable while using an agentic wallet.',
+    INVALID_RULE: 'Some rule settings are invalid. Review the rule and try again.',
+    CAPABILITY_UNAVAILABLE: 'This feature is not available for this wallet or network yet.',
+    READ_ONLY: 'Connect a signing wallet to continue.',
+    NOT_WALLET_OWNER: 'Connect the owner wallet to change these permissions.',
+    RULE_NOT_FOUND: 'This rule could not be found. Refresh the wallet’s rules and try again.',
+    RULE_READ_FAILED: 'The wallet’s current state could not be loaded. Refresh and try again.',
+    INCONSISTENT_READ: 'The wallet changed while it was being checked. Refresh before trying again.',
+    INDEX_RACE: 'The expected wallet address changed. Refresh wallet information before trying again.',
+    RECEIPT_MISMATCH: 'The transaction result needs verification. Check its status before retrying.',
+    RECEIPT_UNAVAILABLE: 'The transaction was submitted, but its status could not be confirmed. Check its status before trying again.',
+    AGENT_GAS_INSUFFICIENT: 'The agent needs more Push coins to pay transaction fees.',
+    WALLET_BALANCE_INSUFFICIENT: 'The agentic wallet does not have enough funds for this action.',
+};
+function agenticUserMessage(code, diagnostic, details) {
+    if (code === 'CAPABILITY_UNAVAILABLE') {
+        if (details?.['capability'] === 'nativeActions')
+            return 'A Push rule can allow at most eight functions. Select fewer functions.';
+        if (details?.['capability'] === 'presetCalls')
+            return 'Choose a preset configuration with 1 to 32 allowed functions.';
+        if (details?.['capability'] === 'presetChain' ||
+            details?.['capability'] === 'presetCatalog')
+            return 'This preset is unavailable for the selected network.';
+    }
+    if (code !== 'INVALID_RULE')
+        return MESSAGES[code];
+    if (/validUntil|expiry|expired|future.*timestamp/i.test(diagnostic))
+        return 'Choose an expiry date in the future.';
+    if (/label.*(64|length|most)/i.test(diagnostic))
+        return 'The wallet name is too long. Shorten it and try again.';
+    if (/label/i.test(diagnostic))
+        return 'Enter a valid wallet name.';
+    if (/maxGasPerCall.*positive/i.test(diagnostic))
+        return 'Set a gas budget greater than zero for this rule.';
+    if (/allowedCalls.*(1\.\.32|contain|array)/i.test(diagnostic))
+        return 'Select between 1 and 32 allowed functions for this rule.';
+    if (/rules.*(eight|8)|eight initial rules/i.test(diagnostic))
+        return 'A wallet can be created with at most eight rules. Remove some rules before creating it.';
+    if (/assets.*(eight|8)/i.test(diagnostic))
+        return 'A rule can include at most eight tokens. Select fewer tokens.';
+    if (/duplicate.*pin|pin.*duplicate/i.test(diagnostic))
+        return 'The same function input has more than one condition. Keep one condition for each input.';
+    if (/pins.*(eight|8)/i.test(diagnostic))
+        return 'A function can have at most eight conditions. Choose a simpler function configuration.';
+    if (/pins.*32|32.*pins/i.test(diagnostic))
+        return 'This rule has too many conditions. Select fewer tokens or allowed functions.';
+    if (/selector|function signature/i.test(diagnostic))
+        return 'The selected function format is invalid. Select the function again or check its signature.';
+    if (/dynamic|static|offset|argument.*range|tuple/i.test(diagnostic))
+        return 'This function input cannot be constrained in that format. Choose a supported input or function.';
+    if (/uint256|bigint|non-negative/i.test(diagnostic))
+        return 'One of the spending limits is invalid. Review the amounts and try again.';
+    if (/chainNamespace|unsupported.*chain/i.test(diagnostic))
+        return 'Choose a supported network for this rule.';
+    if (/address/i.test(diagnostic))
+        return 'Enter a valid wallet, token or app address for this rule.';
+    return MESSAGES.INVALID_RULE;
+}
+function agenticRevertUserMessage(name) {
+    if (!name)
+        return 'The transaction could not be completed. Check wallet activity before trying again.';
+    if (/TooManyAllowedCallPins/.test(name))
+        return 'This rule has more than 32 conditions. Select fewer tokens or allowed functions.';
+    if (/TooMany.*Pins|PinRuleOutOfRange/.test(name))
+        return 'This function has too many conditions. Choose a simpler rule configuration.';
+    if (/TooManyActions|TooManyInitialRules|BatchSizeOutOfRange/.test(name))
+        return 'Too many rules or functions are selected. Reduce the selection and try again.';
+    if (/LabelTooLong/.test(name))
+        return 'The wallet name is too long. Shorten it and try again.';
+    if (/DuplicateAction|DuplicateAsset|DuplicateSvmPin/.test(name))
+        return 'This rule contains duplicate functions, tokens or conditions. Remove the duplicate selection.';
+    if (/SpentMismatch|SpentLengthMismatch|AssetSpentMismatch|IndexMismatch|InvalidNonce|IntentGrantNonceMismatch|IntentWalletMismatch/.test(name))
+        return 'The wallet changed while this action was being prepared. Refresh its state before trying again.';
+    if (/EnforcedPause/.test(name))
+        return 'This operation is temporarily paused. Try again later.';
+    if (/OwnerSigExpired|SignatureExpired/.test(name))
+        return 'The wallet approval has expired. Review and sign a new request.';
+    if (/OutsideTimeWindow/.test(name))
+        return 'This request is outside its valid time window. Refresh and approve a new request.';
+    if (/InvalidExpiry/.test(name))
+        return 'Choose a valid future expiry for this rule.';
+    if (/Allowance|Approval/.test(name))
+        return 'The token spending approval is missing or too small. Review the token approvals.';
+    if (/RuleWithoutPin|CeaAccountsMissExpectedCEA|CeaAccountAtUnpinnedIndex/.test(name))
+        return 'The rule is missing a required wallet-recipient restriction. Review its recipient settings.';
+    if (/Unsupported|WrongVmForCall|WrongModeForCall/.test(name))
+        return 'This action is not supported on the selected network or wallet version.';
+    if (/InvalidOwnerSignature|InvalidEnableSignature|InvalidSessionKeySignature|SignerNotFound/.test(name))
+        return 'The signature could not be verified. Reconnect the authorized wallet and try again.';
+    if (/PCValueExceedsCap|Gas.*Cap/.test(name ?? ''))
+        return 'The required gas exceeds this rule’s gas budget. Review the budget before trying again.';
+    if (/ArgPinAboveMax|AmountExceedsCap|TotalSpendCapExceeded|Value.*Cap|MaxCalls|CallLimitReached|TotalNativeAmountExceeded|TotalValueExceeded/.test(name ?? ''))
+        return 'This action exceeds a rule’s spending or usage limit. Reduce the amount or ask the owner to update the rule.';
+    if (/Expired|Expiry/.test(name ?? ''))
+        return 'This rule has expired. Ask the owner to renew it.';
+    if (/ArgPinMismatch|Beneficiary|NotAllowed|NotEnabled|Permission|RuleNot|RulesNot|RecipientTargetMismatch|TargetMismatch|SelectorMismatch|SvmAccountPinMismatch|SvmDataPinMismatch/.test(name ?? ''))
+        return 'This action does not match the wallet’s permissions. Check the token, recipient and allowed function.';
+    if (/CallerIsNotOwner|UnauthorizedOwner|OwnerLaneRequired/.test(name ?? ''))
+        return 'Connect the owner wallet to make this change.';
+    if (/CallerIsNotAgent/.test(name ?? ''))
+        return 'Connect the agent authorized by this rule.';
+    if (/Insufficient|Balance/.test(name ?? ''))
+        return 'There are not enough funds for this action. Check the wallet balance and fees.';
+    return 'The wallet contract rejected this transaction. Review the permissions and transaction details before trying again.';
+}
+//# sourceMappingURL=error-messages.js.map

package/src/lib/agentic/errors.d.ts

@@ -10,6 +10,8 @@ export declare const AGENTIC_ERROR_CODE: {
     readonly AMBIGUOUS_RULE: "AMBIGUOUS_RULE";
     readonly TARGET_NOT_ON_RULE_CHAIN: "TARGET_NOT_ON_RULE_CHAIN";
     readonly ASSET_CHAIN_MISMATCH: "ASSET_CHAIN_MISMATCH";
+    readonly TOKEN_ROUTE_UNAVAILABLE: "TOKEN_ROUTE_UNAVAILABLE";
+    readonly REQUEST_REJECTED: "REQUEST_REJECTED";
     readonly NOT_OWNER_OR_AGENT: "NOT_OWNER_OR_AGENT";
     readonly WALLET_NOT_DEPLOYED: "WALLET_NOT_DEPLOYED";
     readonly NOT_AGENTIC_WALLET: "NOT_AGENTIC_WALLET";
@@ -36,15 +38,18 @@ export type AgenticErrorCode = (typeof AGENTIC_ERROR_CODE)[keyof typeof AGENTIC_
  * eligibility or a read that cannot be trusted. Nothing was signed or sent
  * except receipt errors, which retain the submitted transaction hash.
  */
-export declare class AgenticError extends Error {
-    readonly code: AgenticErrorCode;
+export declare class AgenticError<Code extends string = AgenticErrorCode> extends Error {
+    readonly code: Code;
+    /** Safe end-user copy; message/cause retain technical diagnostics. */
+    readonly userMessage: string;
     readonly hint?: string;
     readonly details?: Readonly<Record<string, unknown>>;
     readonly cause?: unknown;
-    constructor(code: AgenticErrorCode, message: string, opts?: {
+    constructor(code: Code, message: string, opts?: {
         hint?: string;
         details?: Record<string, unknown>;
         cause?: unknown;
+        userMessage?: string;
     });
 }
 /**
@@ -55,6 +60,7 @@ export declare class AgenticError extends Error {
  */
 export declare class AgenticRevertError extends PushChainExecutionError {
     readonly agenticCode?: string;
+    readonly userMessage: string;
     constructor(message: string, opts?: {
         decodedError?: DecodedErrorPayload;
         gatewayTxHash?: string;
@@ -62,4 +68,7 @@ export declare class AgenticRevertError extends PushChainExecutionError {
         cause?: unknown;
     });
 }
+export declare function ruleConstraintLimit(actual: number, callCount: number, chainNamespace?: string): AgenticError;
+export declare function ruleErrorContext(error: unknown, ruleIndex: number, chainNamespace?: string): unknown;
+export declare function tokenRouteUnavailable(cause: unknown, token: string, chainNamespace: string, assetIndex: number): AgenticError;
 export declare function capabilityUnavailable(capability: string, dependency: string, hint?: string): AgenticError;

package/src/lib/agentic/errors.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgenticRevertError = exports.AgenticError = exports.AGENTIC_ERROR_CODE = void 0;
+exports.ruleConstraintLimit = ruleConstraintLimit;
+exports.ruleErrorContext = ruleErrorContext;
+exports.tokenRouteUnavailable = tokenRouteUnavailable;
 exports.capabilityUnavailable = capabilityUnavailable;
 const errors_1 = require("../orchestrator/internals/errors");
+const error_messages_1 = require("./error-messages");
 /**
  * Stable AGW error codes. The first groups are specified by the AGW SDK page
  * (section 3.f); the remainder are SDK-owned codes that keep unsupported or
@@ -15,6 +19,8 @@ exports.AGENTIC_ERROR_CODE = {
     AMBIGUOUS_RULE: 'AMBIGUOUS_RULE',
     TARGET_NOT_ON_RULE_CHAIN: 'TARGET_NOT_ON_RULE_CHAIN',
     ASSET_CHAIN_MISMATCH: 'ASSET_CHAIN_MISMATCH',
+    TOKEN_ROUTE_UNAVAILABLE: 'TOKEN_ROUTE_UNAVAILABLE',
+    REQUEST_REJECTED: 'REQUEST_REJECTED',
     // initialize with agenticWallet (spec 3.f)
     NOT_OWNER_OR_AGENT: 'NOT_OWNER_OR_AGENT',
     WALLET_NOT_DEPLOYED: 'WALLET_NOT_DEPLOYED',
@@ -46,6 +52,8 @@ exports.AGENTIC_ERROR_CODE = {
  */
 class AgenticError extends Error {
     code;
+    /** Safe end-user copy; message/cause retain technical diagnostics. */
+    userMessage;
     hint;
     details;
     cause;
@@ -53,6 +61,11 @@ class AgenticError extends Error {
         super(message);
         this.name = 'AgenticError';
         this.code = code;
+        this.userMessage =
+            opts.userMessage ??
+                (Object.prototype.hasOwnProperty.call(exports.AGENTIC_ERROR_CODE, code)
+                    ? (0, error_messages_1.agenticUserMessage)(code, message, opts.details)
+                    : message);
         this.hint = opts.hint;
         this.details = opts.details;
         this.cause = opts.cause;
@@ -67,6 +80,7 @@ exports.AgenticError = AgenticError;
  */
 class AgenticRevertError extends errors_1.PushChainExecutionError {
     agenticCode;
+    userMessage;
     constructor(message, opts = {}) {
         super(message, {
             decodedError: opts.decodedError,
@@ -75,9 +89,71 @@ class AgenticRevertError extends errors_1.PushChainExecutionError {
         });
         this.name = 'AgenticRevertError';
         this.agenticCode = opts.agenticCode;
+        this.userMessage = (0, error_messages_1.agenticRevertUserMessage)(opts.decodedError?.name ?? opts.agenticCode);
     }
 }
 exports.AgenticRevertError = AgenticRevertError;
+function ruleConstraintLimit(actual, callCount, chainNamespace) {
+    const message = `This rule has ${actual} conditions. The maximum is 32. Remove duplicate functions or select fewer tokens or functions.`;
+    return new AgenticError(exports.AGENTIC_ERROR_CODE.INVALID_RULE, message, {
+        userMessage: message,
+        hint: 'Regenerate the preset after changing selections. Do not drop individual conditions or bypass the contract limit.',
+        details: {
+            reason: 'RULE_CONSTRAINT_LIMIT',
+            field: 'allowedCalls',
+            actual,
+            limit: 32,
+            callCount,
+            chainNamespace,
+        },
+    });
+}
+function ruleErrorContext(error, ruleIndex, chainNamespace) {
+    if (!(error instanceof AgenticError))
+        return error;
+    if (error.details?.['ruleIndex'] !== undefined)
+        return error;
+    return new AgenticError(error.code, error.message, {
+        hint: error.hint,
+        userMessage: `Rule ${ruleIndex + 1}: ${error.userMessage}`,
+        cause: error.cause ?? error,
+        details: {
+            ...error.details,
+            ruleIndex,
+            ...(chainNamespace ? { chainNamespace } : {}),
+        },
+    });
+}
+function tokenRouteUnavailable(cause, token, chainNamespace, assetIndex) {
+    if (cause instanceof AgenticError)
+        return cause;
+    const names = {
+        'eip155:1': 'Ethereum',
+        'eip155:11155111': 'Ethereum Sepolia',
+        'eip155:8453': 'Base',
+        'eip155:84532': 'Base Sepolia',
+        'eip155:42161': 'Arbitrum',
+        'eip155:421614': 'Arbitrum Sepolia',
+        'eip155:56': 'BNB Chain',
+        'eip155:97': 'BNB Testnet',
+    };
+    const network = names[chainNamespace] ??
+        (chainNamespace.startsWith('solana:')
+            ? 'the selected Solana network'
+            : 'the selected network');
+    const message = `This token cannot be sent from Push to ${network}. Choose a token with a supported Push route.`;
+    return new AgenticError(exports.AGENTIC_ERROR_CODE.TOKEN_ROUTE_UNAVAILABLE, message, {
+        userMessage: message,
+        hint: 'Choose a supported token on this network, or wait for a verified PRC20 route for this exact token address. Token symbols alone do not identify a route.',
+        details: {
+            token,
+            chainNamespace,
+            assetIndex,
+            field: `assets[${assetIndex}].token`,
+        },
+        cause,
+    });
+}
 function capabilityUnavailable(capability, dependency, hint) {
     return new AgenticError(exports.AGENTIC_ERROR_CODE.CAPABILITY_UNAVAILABLE, `AGW capability "${capability}" is not available: ${dependency}`, { hint, details: { capability, dependency } });
 }

package/src/lib/agentic/management/common.js

@@ -102,6 +102,12 @@ function wrapSendError(err) {
             cause: err,
         });
     }
+    if (err &&
+        typeof err === 'object' &&
+        (('code' in err && err.code === 4001) ||
+            ('name' in err && err.name === 'UserRejectedRequestError'))) {
+        return new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.REQUEST_REJECTED, 'The wallet request was cancelled.', { cause: err });
+    }
     if (decoded || err instanceof errors_1.PushChainExecutionError) {
         const e = err;
         return new errors_2.AgenticRevertError(e?.message ?? decoded?.name ?? 'AGW revert', {

package/src/lib/agentic/management/destination.d.ts

@@ -0,0 +1,5 @@
+import { type Address } from 'viem';
+import type { CHAIN } from '../../constants/enums';
+import type { AgenticRuntime } from '../runtime';
+/** Preserve read failures as read failures; never report them as bad token routes. */
+export declare function resolveRuleDestination(runtime: AgenticRuntime, wallet: Address, chain: CHAIN): Promise<Address>;

package/src/lib/agentic/management/destination.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRuleDestination = resolveRuleDestination;
+const viem_1 = require("viem");
+const errors_1 = require("../errors");
+/** Preserve read failures as read failures; never report them as bad token routes. */
+async function resolveRuleDestination(runtime, wallet, chain) {
+    try {
+        return (0, viem_1.getAddress)((await runtime.resolveCEA(wallet, chain)).cea);
+    }
+    catch (cause) {
+        if (cause instanceof errors_1.AgenticError)
+            throw cause;
+        const unavailable = cause instanceof Error &&
+            cause.message.includes('CEAFactory not available on chain');
+        const message = unavailable
+            ? 'Agentic wallets are not available on this destination network yet. Choose a supported network.'
+            : 'The wallet’s destination account could not be loaded. Try again shortly.';
+        throw new errors_1.AgenticError(unavailable
+            ? errors_1.AGENTIC_ERROR_CODE.CAPABILITY_UNAVAILABLE
+            : errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED, message, {
+            userMessage: message,
+            cause,
+            details: {
+                chainNamespace: chain,
+                field: 'chainNamespace',
+                stage: 'destinationAccount',
+            },
+        });
+    }
+}
+//# sourceMappingURL=destination.js.map