@pushchain/core 6.0.26 → 6.0.27-alpha.1

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

@@ -0,0 +1,414 @@
+import type { ArgPinWire } from './codec/pins';
+/** Public section-6 rules and internal adapters for the deployed v6 wire format.
+ * Source snapshot: October 12, 2026. Internal normalized types are not package exports.
+ */
+import type { Idl } from '@coral-xyz/anchor';
+import type { SvmTermsWire } from './codec/svm-terms';
+import type { MoveableToken } from '../constants/tokens';
+import type { UniversalTxResponse } from '../orchestrator/orchestrator.types';
+import type { ProgressEvent } from '../progress-hook/progress-hook.types';
+export type AgenticAddress = `0x${string}`;
+export type AgenticHex = `0x${string}`;
+export type ForeignChainNamespace = `eip155:${string}` | `solana:${string}`;
+export type AgenticProgressHook = (event: ProgressEvent) => void;
+/** '0x617ba037' or 'supply(address,uint256,address,uint16)'. */
+export type Selector = AgenticHex | `${string}(${string})`;
+/** One Push function a native rule allows, with its own limits and counters. */
+export interface NativeAction {
+    wirePins?: ArgPinWire[];
+    target: AgenticAddress;
+    selector: Selector | 'value-only';
+    /** Default 0: no native PC value allowance. */
+    maxValuePerCall?: bigint;
+    /** Default 0: no native PC value allowance. */
+    maxValueTotal?: bigint;
+    /** Default 0 (unlimited calls until expiry). */
+    maxCalls?: number;
+    pins?: ArgPin[];
+    /** `maxTotal` default uint256 max (unlimited total). */
+    amount?: AmountLimit;
+    /**
+     * Overrides the rule's `validUntil` for this action. Decoded rules set it
+     * only when stored actions expire at different times.
+     */
+    validUntil?: number;
+}
+interface NativeRuleCommon {
+    /** Push address: an EOA, or the UEA of an external key. Never the owner. */
+    agent: AgenticAddress;
+    /** Omitted = the connected Push chain. */
+    chainNamespace?: never;
+    /** Unix seconds. */
+    validUntil: number;
+}
+/** A native rule allowing one function (shorthand for a one-entry `actions`). */
+export interface NativeSingleRule extends NativeRuleCommon, Omit<NativeAction, 'validUntil'> {
+    actions?: never;
+}
+/**
+ * A native rule allowing 1..8 functions under ONE rule ID. Each action keeps
+ * its own limits and counters on-chain; (target, selector) pairs must be
+ * unique. One rule per agent on Push keeps send-time selection unambiguous.
+ * Internal normalized representation; public callers use Rule.allowedCalls.
+ */
+export interface NativeMultiRule extends NativeRuleCommon {
+    actions: NativeAction[];
+    target?: never;
+    selector?: never;
+    maxValuePerCall?: never;
+    maxValueTotal?: never;
+    maxCalls?: never;
+    pins?: never;
+    amount?: never;
+}
+export type NativeRule = NativeSingleRule | NativeMultiRule;
+/**
+ * Where a pin or amount sits in the calldata. `arg` is the argument index in
+ * the selector signature (requires the signature form of `selector`).
+ * `offset` is the raw calldata byte offset, selector included — the form the
+ * contracts store; decoded rules (rules.get/list, decodeRules) always use it
+ * because stored terms carry no ABI. Advanced input form; ABI argument indexes are preferred for authoring.
+ */
+export type ArgPin = {
+    arg: number;
+    offset?: never;
+    expected: AgenticHex | AgenticAddress | bigint;
+} | {
+    offset: number;
+    arg?: never;
+    expected: AgenticHex;
+};
+export type AmountLimit = ({
+    arg: number;
+    offset?: never;
+} | {
+    offset: number;
+    arg?: never;
+}) & {
+    maxPerCall: bigint;
+    maxTotal?: bigint;
+};
+export interface AssetCap {
+    /** The destination chain's token (MOVEABLE constant) or native marker. */
+    token: MoveableToken | AgenticAddress;
+    maxPerCall: bigint;
+    /** Omitted = zero. Explicit zero forbids movement. */
+    maxTotal?: bigint;
+}
+export interface AllowedCall {
+    pins?: ArgPinWire[];
+    target: AgenticAddress;
+    selector: Selector;
+    /** Argument index whose address must be the wallet's destination account. */
+    beneficiary?: number;
+    /** Exact stored calldata offset for lossless decoded rules; mutually exclusive with beneficiary. Approved advanced input form. */
+    beneficiaryOffset?: number;
+    /** Default 0. */
+    maxValue?: bigint;
+}
+export interface UniversalRule {
+    agent: AgenticAddress;
+    chainNamespace: `eip155:${string}`;
+    assets: AssetCap[];
+    /** PC (wei) per outbound for the destination leg. */
+    maxGasPerCall: bigint;
+    validUntil: number;
+    /** 1..32, all on chainNamespace. */
+    allowedCalls: AllowedCall[];
+}
+/** An address may be base58 or a 32-byte hex Solana public key. */
+export type SvmAccountRef = {
+    kind: 'walletCEA';
+} | {
+    kind: 'walletATA';
+    token: string;
+} | {
+    kind: 'address';
+    address: string;
+};
+export type SvmFieldConstraint = {
+    name: string;
+    equals: AgenticHex | bigint | boolean;
+} | {
+    name: string;
+    min: bigint;
+} | {
+    name: string;
+    max: bigint;
+} | {
+    numerator: string;
+    denominator: string;
+    minRatio: {
+        num: bigint;
+        den: bigint;
+    };
+};
+export interface SvmInstructionRule {
+    /** Internal wire override: 0 means no exact account-count constraint. */
+    maxAccounts?: number;
+    program: string;
+    instruction: {
+        idl: Idl;
+        name: string;
+    };
+    /** Top-level account names from a supported Anchor IDL; optional/nested accounts are rejected. */
+    accounts: {
+        name: string;
+        expected: SvmAccountRef;
+    }[];
+    /** Fixed-width fields only; unsupported/variable layouts fail before signing. */
+    fields?: SvmFieldConstraint[];
+}
+export interface SolanaRule {
+    agent: AgenticAddress;
+    chainNamespace: `solana:${string}`;
+    validUntil: number;
+    assets: {
+        token: MoveableToken | string;
+        maxPerCall: bigint;
+        maxTotal?: bigint;
+    }[];
+    maxGasPerCall: bigint;
+    /** Additional output mints whose wallet ATAs must be protected. */
+    outputTokens?: string[];
+    allowedInstructions: SvmInstructionRule[];
+}
+/** Lossless stored Solana layout, accepted by update without an invented IDL. */
+export interface DecodedSolanaRule extends Omit<SvmTermsWire, 'assets'> {
+    format: 'decoded';
+    agent: AgenticAddress;
+    chainNamespace: `solana:${string}`;
+    assets: {
+        token: string;
+        maxPerCall: bigint;
+        maxTotal: bigint;
+    }[];
+}
+export type InternalRule = NativeRule | UniversalRule | SolanaRule;
+export interface InternalRulesRecord {
+    rulesId: AgenticHex;
+    enabled: boolean;
+    chainNamespace: string;
+    agent: AgenticAddress;
+    validUntil: number;
+    rule: InternalRule | DecodedSolanaRule;
+}
+/** Current SDK section 6 public rule shape; contract wire types above are internal. */
+export type WalletMarker = 'agentic:wallet';
+/** Top-level ABI argument, or a path through static tuple/fixed-array fields. */
+export type ArgumentPath = number | readonly number[];
+export type Pin = {
+    arg: ArgumentPath;
+    expected: AgenticHex | AgenticAddress | bigint | WalletMarker;
+    max?: never;
+    account?: never;
+} | {
+    arg: ArgumentPath;
+    max: bigint;
+    expected?: never;
+    account?: never;
+} | {
+    account: number;
+    expected: string | WalletMarker;
+    token?: MoveableToken | string;
+    arg?: never;
+    max?: never;
+};
+export interface RuleCall {
+    target: string;
+    selector: Selector | 'value-only';
+    pins?: Pin[];
+    maxValue?: bigint;
+    app?: string;
+    label?: string;
+}
+export interface RuleAsset {
+    token: MoveableToken | string;
+    maxPerCall: bigint;
+    maxTotal?: bigint;
+}
+export interface Rule {
+    agent: AgenticAddress;
+    chainNamespace?: ForeignChainNamespace;
+    validUntil: number;
+    assets?: RuleAsset[];
+    maxGasPerCall?: bigint;
+    allowedCalls: RuleCall[];
+}
+export type RuleInput = Rule | DecodedSolanaRule;
+export type Spent = {
+    kind: 'native';
+    valueSpent: bigint;
+    amountSpent: bigint;
+    callsUsed: number;
+} | {
+    kind: 'native';
+    actions: {
+        target: AgenticAddress;
+        selector: Selector | 'value-only';
+        valueSpent: bigint;
+        amountSpent: bigint;
+        callsUsed: number;
+    }[];
+} | {
+    kind: 'universal';
+    assets: {
+        token: string;
+        spent: bigint;
+    }[];
+};
+export interface RulesRecord extends Omit<InternalRulesRecord, 'rule'> {
+    rule: RuleInput;
+    spent: Spent;
+}
+export interface InternalCreateOptions {
+    rules: InternalRule[];
+    progressHook?: AgenticProgressHook;
+}
+export interface CreateOptions {
+    rules: RuleInput[];
+    progressHook?: AgenticProgressHook;
+}
+export interface CreateResult {
+    wallet: AgenticAddress;
+    index: number;
+    rulesIds: AgenticHex[];
+    tx: UniversalTxResponse;
+}
+export interface WalletSummary {
+    address: AgenticAddress;
+    index: number;
+    label: string;
+    deployed: boolean;
+    rulesCount: number;
+}
+export interface WalletInfo {
+    address: AgenticAddress;
+    label: string;
+    index: number;
+    owner: AgenticAddress;
+    deployed: boolean;
+    rulesCount: number;
+}
+export type CheckpointKind = 'OWNER_ACTION' | 'RULES_GRANTED' | 'RULES_REVOKED';
+export interface Checkpoint {
+    seq: number;
+    kind: CheckpointKind;
+    ref: AgenticHex;
+    blockNumber: bigint;
+    txHash: AgenticHex;
+}
+export interface AgenticWallet {
+    address: AgenticAddress;
+    info(): Promise<WalletInfo>;
+    owner(): Promise<{
+        owner: AgenticAddress;
+    }>;
+    /** Owner-only rename, at most 64 UTF-8 bytes. Empty resets the default label. */
+    setLabel(label: string, opts?: {
+        progressHook?: AgenticProgressHook;
+    }): Promise<UniversalTxResponse>;
+    checkpoints(opts?: {
+        sinceBlock?: bigint;
+    }): Promise<{
+        checkpoints: Checkpoint[];
+    }>;
+    rules: {
+        /** Enabled rules only; expired-but-enabled rules remain visible. Includes policy spend counters. */
+        list(): Promise<{
+            rules: RulesRecord[];
+        }>;
+        /** Unknown and revoked IDs both return RULE_NOT_FOUND; v1 has no historical records. */
+        get(rulesId: AgenticHex): Promise<RulesRecord>;
+        add(rules: RuleInput[], opts?: {
+            progressHook?: AgenticProgressHook;
+        }): Promise<{
+            rulesIds: AgenticHex[];
+            tx: UniversalTxResponse;
+        }>;
+        update(params: {
+            rules: {
+                rulesId: AgenticHex;
+                rule: RuleInput;
+            }[];
+            progressHook?: AgenticProgressHook;
+        }): Promise<{
+            rules: {
+                rulesId: AgenticHex;
+                replaced: AgenticHex;
+            }[];
+            tx: UniversalTxResponse;
+        }>;
+        delete(rulesIds: AgenticHex[], opts?: {
+            progressHook?: AgenticProgressHook;
+        }): Promise<UniversalTxResponse>;
+        delete(params: {
+            all: true;
+            progressHook?: AgenticProgressHook;
+        }): Promise<UniversalTxResponse>;
+    };
+}
+export interface AgenticNamespace {
+    derive(opts?: {
+        index?: number;
+    }): Promise<{
+        address: AgenticAddress;
+        index: number;
+        deployed: boolean;
+    }>;
+    create(label: string, options: CreateOptions): Promise<CreateResult>;
+    list(): Promise<{
+        wallets: WalletSummary[];
+    }>;
+    wallet(address: AgenticAddress): AgenticWallet;
+}
+/** Door the client uses in agenticWallet mode. */
+export type AgenticDoor = 'owner' | 'agent';
+/** AGW metadata attached to responses produced by an agentic client. */
+export interface AgenticTxMetadata {
+    wallet: AgenticAddress;
+    door: AgenticDoor;
+    /** Rule selected for an agent-door send. */
+    rulesId?: AgenticHex;
+    /** Destination CAIP-2 chain for the selected rule / outbound. */
+    chainNamespace?: string;
+    /** The wallet's destination account (CEA) for an outbound. */
+    destinationAccount?: AgenticAddress;
+    /**
+     * Ordered calls encoded for the destination CEA. Outbound response
+     * to/data/value summarize the first call, including an SDK-generated token
+     * transfer. Replay uses the same representation; it cannot recover which
+     * calls were supplied explicitly versus generated from funds.
+     */
+    destinationCalls?: readonly {
+        to: AgenticAddress;
+        data: AgenticHex;
+        value: bigint;
+    }[];
+    /** SVM instruction executed by the wallet's destination CEA. */
+    destinationInstruction?: {
+        program: AgenticHex;
+        data: AgenticHex;
+        accounts: readonly {
+            pubkey: AgenticHex;
+            isWritable: boolean;
+        }[];
+    };
+    /** Funds-only Solana transfer. token is the burned PRC20 on Push. */
+    destinationTransfer?: {
+        recipient: AgenticHex;
+        token: AgenticAddress;
+        amount: bigint;
+    };
+    /** Ordered actions in a native agent batch; to/data/value summarize its first action. */
+    nativeCalls?: readonly {
+        to: AgenticAddress;
+        data: AgenticHex;
+        value: bigint;
+    }[];
+    /** Account the signer's transaction actually called (wallet or outer sender account). */
+    rawTo: string;
+    /** Calldata the signer's transaction actually carried. */
+    rawData: string;
+}
+export {};

package/src/lib/agentic/agentic.types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=agentic.types.js.map

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

@@ -0,0 +1,37 @@
+/**
+ * Internal capability flags for an AGW contract generation. A method whose
+ * capability is absent fails before any signature. Each unresolved target
+ * feature identifies the contract or product capability that must be verified
+ * before it can be advertised.
+ */
+export declare enum AgenticCapability {
+    /** Factory derive/list/deploy and wallet owner/info reads. */
+    WALLET_READS = "walletReads",
+    /** Active (enabled) rule enumeration and native-rule decoding. */
+    ACTIVE_RULE_READS = "activeRuleReads",
+    /** Owner door: execute(mode, executionCalldata). */
+    OWNER_EXECUTE = "ownerExecute",
+    /** Agent door: executeAsAgent(rulesId, mode, executionCalldata). */
+    AGENT_EXECUTE = "agentExecute",
+    /** Native (Push-chain) rule grants with NativeTerms encoding. */
+    NATIVE_RULES = "nativeRules",
+    /** Exact-equality native spend assertion used by rules.update. */
+    ASSERT_SPENT_NATIVE = "assertSpentNative",
+    /** checkpointCount + Checkpointed events. */
+    CHECKPOINTS = "checkpoints",
+    /** Agent-door EVM outbound composition against v6 per-token caps. */
+    UNIVERSAL_EVM_OUTBOUND = "universalEvmOutbound",
+    /** Target UniversalRule (assets[] / maxGasPerCall) encode/decode. A05/A07. */
+    UNIVERSAL_EVM_RULES = "universalEvmRules",
+    /** Per-token expected-spend assertion for universal replacement. A05. */
+    ASSERT_SPENT_UNIVERSAL_MULTI = "assertSpentUniversalMulti",
+    /** Numeric-pin Solana authoring, exact decoded reads and instruction execution. */
+    UNIVERSAL_SVM_RULES = "universalSvmRules",
+    /** Editable wallet label (setLabel / LabelSet). A07. */
+    SET_LABEL = "setLabel"
+}
+/** Why each target capability is unavailable when a generation lacks it. */
+export declare const CAPABILITY_DEPENDENCY: Record<AgenticCapability, string>;
+export declare function hasCapability(capabilities: ReadonlySet<AgenticCapability>, capability: AgenticCapability): boolean;
+/** Throws CAPABILITY_UNAVAILABLE (before signing) when the flag is absent. */
+export declare function requireCapability(capabilities: ReadonlySet<AgenticCapability> | undefined, capability: AgenticCapability): void;

package/src/lib/agentic/capabilities.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAPABILITY_DEPENDENCY = exports.AgenticCapability = void 0;
+exports.hasCapability = hasCapability;
+exports.requireCapability = requireCapability;
+const errors_1 = require("./errors");
+/**
+ * Internal capability flags for an AGW contract generation. A method whose
+ * capability is absent fails before any signature. Each unresolved target
+ * feature identifies the contract or product capability that must be verified
+ * before it can be advertised.
+ */
+var AgenticCapability;
+(function (AgenticCapability) {
+    /** Factory derive/list/deploy and wallet owner/info reads. */
+    AgenticCapability["WALLET_READS"] = "walletReads";
+    /** Active (enabled) rule enumeration and native-rule decoding. */
+    AgenticCapability["ACTIVE_RULE_READS"] = "activeRuleReads";
+    /** Owner door: execute(mode, executionCalldata). */
+    AgenticCapability["OWNER_EXECUTE"] = "ownerExecute";
+    /** Agent door: executeAsAgent(rulesId, mode, executionCalldata). */
+    AgenticCapability["AGENT_EXECUTE"] = "agentExecute";
+    /** Native (Push-chain) rule grants with NativeTerms encoding. */
+    AgenticCapability["NATIVE_RULES"] = "nativeRules";
+    /** Exact-equality native spend assertion used by rules.update. */
+    AgenticCapability["ASSERT_SPENT_NATIVE"] = "assertSpentNative";
+    /** checkpointCount + Checkpointed events. */
+    AgenticCapability["CHECKPOINTS"] = "checkpoints";
+    /** Agent-door EVM outbound composition against v6 per-token caps. */
+    AgenticCapability["UNIVERSAL_EVM_OUTBOUND"] = "universalEvmOutbound";
+    /** Target UniversalRule (assets[] / maxGasPerCall) encode/decode. A05/A07. */
+    AgenticCapability["UNIVERSAL_EVM_RULES"] = "universalEvmRules";
+    /** Per-token expected-spend assertion for universal replacement. A05. */
+    AgenticCapability["ASSERT_SPENT_UNIVERSAL_MULTI"] = "assertSpentUniversalMulti";
+    /** Numeric-pin Solana authoring, exact decoded reads and instruction execution. */
+    AgenticCapability["UNIVERSAL_SVM_RULES"] = "universalSvmRules";
+    /** Editable wallet label (setLabel / LabelSet). A07. */
+    AgenticCapability["SET_LABEL"] = "setLabel";
+})(AgenticCapability || (exports.AgenticCapability = AgenticCapability = {}));
+/** Why each target capability is unavailable when a generation lacks it. */
+exports.CAPABILITY_DEPENDENCY = {
+    [AgenticCapability.WALLET_READS]: 'no verified AGW deployment for this network (A07)',
+    [AgenticCapability.ACTIVE_RULE_READS]: 'no verified AGW deployment for this network (A07)',
+    [AgenticCapability.OWNER_EXECUTE]: 'no verified AGW deployment for this network (A07)',
+    [AgenticCapability.AGENT_EXECUTE]: 'no verified AGW deployment for this network (A07)',
+    [AgenticCapability.NATIVE_RULES]: 'no verified AGW deployment for this network (A07)',
+    [AgenticCapability.ASSERT_SPENT_NATIVE]: 'no verified AGW deployment for this network (A07)',
+    [AgenticCapability.CHECKPOINTS]: 'no verified AGW deployment for this network (A07)',
+    [AgenticCapability.UNIVERSAL_EVM_OUTBOUND]: 'the selected generation has no verified multi-asset outbound token resolution (A05/A07)',
+    [AgenticCapability.UNIVERSAL_EVM_RULES]: 'EVM universal rules are unavailable for the selected SDK configuration',
+    [AgenticCapability.ASSERT_SPENT_UNIVERSAL_MULTI]: 'universal expected-spend assertions are unavailable for this configuration',
+    [AgenticCapability.UNIVERSAL_SVM_RULES]: 'SVM rules are unavailable for this generation',
+    [AgenticCapability.SET_LABEL]: 'the selected generation has no editable label (A07; labels are deploy-time only)',
+};
+function hasCapability(capabilities, capability) {
+    return capabilities.has(capability);
+}
+/** Throws CAPABILITY_UNAVAILABLE (before signing) when the flag is absent. */
+function requireCapability(capabilities, capability) {
+    if (!capabilities || !capabilities.has(capability)) {
+        throw (0, errors_1.capabilityUnavailable)(capability, exports.CAPABILITY_DEPENDENCY[capability]);
+    }
+}
+//# sourceMappingURL=capabilities.js.map

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

@@ -0,0 +1,3 @@
+import { PUSH_NETWORK } from '../constants/enums';
+/** 'eip155:<id>' of the Push chain for a network — the native rule chain. */
+export declare function pushChainNamespaceFor(network: PUSH_NETWORK): string;

package/src/lib/agentic/chain.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pushChainNamespaceFor = pushChainNamespaceFor;
+const chain_1 = require("../constants/chain");
+const enums_1 = require("../constants/enums");
+/** 'eip155:<id>' of the Push chain for a network — the native rule chain. */
+function pushChainNamespaceFor(network) {
+    const chain = network === enums_1.PUSH_NETWORK.MAINNET
+        ? enums_1.CHAIN.PUSH_MAINNET
+        : network === enums_1.PUSH_NETWORK.TESTNET_DONUT || network === enums_1.PUSH_NETWORK.TESTNET
+            ? enums_1.CHAIN.PUSH_TESTNET_DONUT
+            : enums_1.CHAIN.PUSH_LOCALNET;
+    return `eip155:${chain_1.CHAIN_INFO[chain].chainId}`;
+}
+//# sourceMappingURL=chain.js.map

package/src/lib/agentic/codec/abi-layout.d.ts

@@ -0,0 +1,20 @@
+import { type AbiParameter } from 'viem';
+import type { AgenticHex } from '../agentic.types';
+export declare function isDynamic(p: AbiParameter): boolean;
+/** Bytes this parameter occupies in the head of an encoding. */
+export declare function headSize(p: AbiParameter): number;
+export declare function isSingleWordStatic(p: AbiParameter): boolean;
+/**
+ * Absolute calldata byte offset (selector included) of argument `arg`.
+ * Rejects out-of-range indexes and any argument that is not one static word.
+ */
+export declare function argumentOffset(inputs: readonly AbiParameter[] | undefined, arg: number, what: string): number;
+/** Encode a pin's expected value as the exact 32-byte calldata word. */
+export declare function encodeArgWord(param: AbiParameter, expected: AgenticHex | bigint | string | boolean, what: string): AgenticHex;
+/** Validate a raw calldata offset given directly (offset form). */
+export declare function rawOffset(offset: number, what: string): number;
+/** Absolute location of a scalar reached through static tuple/fixed-array indexes. */
+export declare function argumentLocation(inputs: readonly AbiParameter[] | undefined, arg: number | readonly number[], what: string): {
+    offset: number;
+    param: AbiParameter;
+};