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

package/AGW.md

@@ -1,6 +1,6 @@
 # Agentic wallets on Push Chain
 
-This branch implements the SDK-only October 12 feedback against the deployed Donut v5 contracts. Contract-dependent changes remain explicit below.
+This branch implements the SDK-only October 12 feedback against the deployed Donut v6 contracts. The runtime targets v6 only; existing v5 wallets are not silently adapted.
 
 ## Connect
 
@@ -83,15 +83,15 @@ async function manage(owner: PushChain, address: Address, id: Hex) {
 
 `create` and `rules.add` reject a duplicate agent/chain pair with `DUPLICATE_RULE`. Put several permitted calls in the same rule. Existing overlapping grants can still cause `AMBIGUOUS_RULE` when sending; the owner must resolve the overlap. The contract validates every actual agent call.
 
-On deployed v5, native rules allow at most **eight** calls, eight equality pins and one maximum pin per call. Public native lifetime budgets, `maxCalls`, `amount`, single-call shorthand and `actions[]` are retired. Native counters still accumulate for reporting and atomic update assertions.
+On deployed v6, native rules allow at most **eight** calls, eight equality/maximum pins per call. Public native lifetime budgets, `maxCalls`, `amount`, single-call shorthand and `actions[]` are retired. Native value and call counters accumulate for reporting and atomic updates. A v6 MAX pin only bounds an individual call and does not increment amountSpent; that counter belongs to the separate internal amount meter.
 
 ## Pins and zero defaults
 
-An equality pin fixes an argument; a maximum pin bounds it. For EVM signatures, `arg` is a zero-based static argument position. With a raw four-byte selector, it is a 32-byte ABI head-word position. Reads return a raw selector and these word positions. Unsupported dynamic/compound layouts fail explicitly; no guessed tuple-field indexes are produced.
+An equality pin fixes an argument; a maximum pin bounds it. For EVM signatures, `arg` is a zero-based static argument position. With a raw four-byte selector, it is a 32-byte ABI head-word position. Reads return a raw selector and these word positions. For full signatures, a path such as `arg: [0, 3]` selects a field within a static tuple or fixed array. Dynamic layouts fail explicitly. Reads retain exact word positions rather than guessing missing ABI metadata.
 
 `PushChain.CONSTANTS.AGENTIC.WALLET` resolves to the AGW on Push, its CEA on an EVM destination, or its CEA/selected token ATA on Solana. Deployment addresses and encoding helpers are internal.
 
-Omitted `maxValue`, `assets[].maxTotal`, and `maxGasPerCall` default to **zero**, which permits no corresponding movement. Specify positive caps for sends that need value, tokens or destination gas. Native value is limited per call; there is no public native lifetime-total cap.
+Omitted `maxValue`, `assets[].maxTotal`, and `maxGasPerCall` default to **zero**. Asset totals meter tokens sent from Push; they do not meter trading or lending using capital already in the destination CEA. Specify positive caps for sends that need value, tokens or destination gas. Native value is limited per call; there is no public native lifetime-total cap.
 
 ## EVM destinations
 
@@ -112,7 +112,7 @@ function evmRule(agent: Address, target: Address): Rule {
 }
 ```
 
-The deployed policy supports one `WALLET` equality pin per EVM destination call. General destination equality/maximum pins need the new contract deployment and currently fail with `CAPABILITY_UNAVAILABLE` before signing.
+The deployed v6 policy supports up to eight EQ/MAX pins per EVM destination call and 32 across the rule. Multiple entries for the same target/function are alternatives; every constraint in one entry must pass. The SDK rejects a bare alternative beside a pinned one because it would bypass the pins.
 
 When the caller omits destination `gasLimit`, a fresh EVM CEA gets a 2,000,000 gas default to cover first-use deployment. An existing CEA uses the normal quote default. An explicit caller value is preserved. The rule's gas/value caps still apply.
 
@@ -153,19 +153,26 @@ Connect with `PushChain.initialize(signer, { agenticWallet: address })` to send
 
 Updates assert existing spend, delete the old rule and grant its replacement atomically. Native updates assert each action separately: a rule with N native actions records N+4 checkpoints on current v5. Agent execution records no owner checkpoint. Direct `setLabel` records none.
 
-## Deployment-dependent behavior
+## V6 deployment and creation
 
-The October 12 contract feedback is not deployed. Until it is verified:
+The runtime uses factory `0xFBBEB6a365178fAaA81A9789a5f64b300c37e5bc` and URP `0xBA32e7A1500cb34311a31127bcD40CA52C8CFd36`, from source `ffd567d`. URP still reports 3.1.0; verified deployment wiring and the v6 ABI identify the supported generation.
 
-- Outbound sends on both doors require a separately owner-set gateway allowance; the SDK never silently creates or restores one. Insufficient allowance fails before signing.
-- Creation uses the existing index-bound deploy/grant flow. If a signer cannot execute it atomically, `CREATE_PARTIAL` preserves committed receipts and recovery details. Do not blindly retry creation.
-- General EVM destination pins and the new atomic factory `createWallet` are unavailable.
+`create` uses one index-bound `createWalletWithSig` call from the owner's Push identity, with the contract's owner-caller empty-signature path. The wallet and up to eight initial rules are committed atomically. A concurrent slot change returns INDEX_RACE; a receipt-read failure retains the submitted hash for recovery. CREATE_PARTIAL is removed. No sequential creation fallback exists.
 
-`rules.delete` is the public name; on-chain `revokeRules` names/events remain unchanged. Unsupported capabilities use `CAPABILITY_UNAVAILABLE`. On-chain errors retain revert details through `AgenticRevertError`/`PushChainExecutionError`.
+For outbound sends on either door, the wallet approves the gateway inside the transaction after policy authorization, executes the outbound, and clears remaining allowance. No separate approval or SDK allowance check is needed; GATEWAY_ALLOWANCE_INSUFFICIENT is removed. Approval/cleanup uses the contract's best-effort token calls. To stop an agent, delete its rules; clearing the gateway allowance does not disable an otherwise valid rule.
+
+The wire encoder uses uint32 maximum for unlimited native calls and 255 for unspecified Solana account count. Neither uses the retired zero sentinel. The envelope remains version 1. Existing v5 wallets and addresses do not become v6 wallets.
+
+`rules.delete` is the public name; on-chain `revokeRules` names/events remain unchanged. Revert errors retain decoded details and cause. Core transaction response fields used by other SDK routes are not globally removed.
 
 ## Preset discovery and templates (section 7)
 
-`PushChain.utils.agentic` contains only `presets.list/get`. The enumerable categories are `AGENTIC.PRESETS.CATEGORY.DEXES`, `LENDING` and `PREDICTION`. All three currently have empty `chains` lists because the app/address catalog is not approved yet; hide them in a UI. No production DEX/lending addresses ship in this framework.
+`PushChain.utils.agentic` contains `presets.list/get`. The categories are `AGENTIC.PRESETS.CATEGORY.DEXES`, `LENDING`, `STAKING` and `PREDICTION`. The catalog includes mainnet and testnet templates. Discovery is network-independent: pass `chainNamespace` to select the intended chain. A mainnet template does not imply that the connected Push network supports execution to it:
+
+- DEXES: Uniswap V3 on Ethereum, Base and Arbitrum (mainnet and their Sepolia testnets); PancakeSwap V3 on BNB mainnet and BSC testnet.
+- LENDING: Aave on Ethereum, Base, Arbitrum and BNB mainnets, plus Sepolia/Base Sepolia/Arbitrum Sepolia; Moonwell on Base mainnet/testnet and Venus on BNB mainnet/testnet.
+- STAKING: EigenLayer deposits on Ethereum mainnet and Sepolia; Lido stake and wrap/unwrap on Ethereum mainnet. Withdrawal requests with dynamic amounts, claims with position-derived amounts and EigenLayer withdrawals are excluded from these bounded presets. A selected native asset supplies the Lido `submit` value cap; omitted caps remain zero.
+- PREDICTION: no entries yet. Hide categories with empty `chains` lists.
 
 ```ts
 const { presets } = PushChain.utils.agentic.presets.list({ type: 'CATEGORY' });
@@ -173,22 +180,100 @@ const availablePresets = presets.filter(preset => preset.chains.length > 0);
 const { rules: reviewTemplates } = PushChain.utils.agentic.presets.get(
   PushChain.CONSTANTS.AGENTIC.PRESETS.CATEGORY.DEXES,
 );
-// Currently [], since there is no approved catalog. Never treat an empty result as an active preset.
+// Choose tokens in the review UI, then call get again as below.
 
-function filledPreset(agent: Address) {
+function filledPreset(agent: Address, tokenIn: Address, tokenOut: Address) {
   return PushChain.utils.agentic.presets.get(
     PushChain.CONSTANTS.AGENTIC.PRESETS.CATEGORY.DEXES,
-    { agent, validUntil: Math.floor(Date.now() / 1000) + 3600 },
-  ).rules;
+    {
+      chainNamespace: 'eip155:11155111',
+      agent,
+      validUntil: Math.floor(Date.now() / 1000) + 3600,
+      maxGasPerCall: BigInt(10) ** BigInt(18),
+      assets: [
+        { token: tokenIn, maxPerCall: BigInt(100), maxTotal: BigInt(1000) },
+        { token: tokenOut, maxPerCall: BigInt(100), maxTotal: BigInt(1000) },
+      ],
+    },
+  );
 }
 ```
 
-With catalog entries, `get` groups calls into one rule per chain. With agent and expiry supplied, its return type is `Rule[]`; otherwise it is `PresetRuleTemplate[]`, requiring those fields before `create`. Assets must name their chain unless a single chain filter is supplied. Missing `maxPerCall` or `maxTotal` defaults to zero (user decision, October 12), so missing caps do not grant token movement.
+The example caps are illustrative raw units; choose caps for the actual token decimals and gas requirements. `get` groups calls into one rule per chain. The result is `{ rules, readiness }`. With agent and expiry supplied, `rules` is typed as `Rule[]`; otherwise it is `PresetRuleTemplate[]`. This type distinction alone does not establish readiness. Assets must name their chain unless a single chain filter is supplied. Omitted asset caps and `maxGasPerCall` default to zero.
+
+DEX discovery works without options, with an empty asset list, or with assets for only some chains. A chain with fewer than two tokens returns full-signature review calls with wallet-recipient pins and an explicit zero input-amount maximum. A single supplied token is also pinned as the input. These calls cannot spend swap input tokens, even if asset budgets are filled later. Call `get` again after selecting both tokens to replace the review calls with the complete token-pinned rules; merely assigning `rule.assets` is insufficient.
+
+With two ERC20 tokens, `get` expands ordered pairs into exact-input and exact-output calls with token, wallet-recipient and input-amount pins. Native markers and expansions exceeding the policy's 32-pin limit are rejected. Two tokens fit the shipped router template; three do not. Static tuple fields use paths such as `[0, 3]`.
+
+Reviewed EVM spenders generate approvals pinned to that spender and bounded by the asset's per-call cap. Money-market approvals are restricted to the market's underlying token. Distinct spenders become separate pinned alternatives under v6. These destination approvals are ordinary ERC20 allowances; the wallet's automatic Push-side gateway approval is separate.
 
-Reviewed EVM catalog spenders generate approvals pinned to that spender and bounded by the asset's per-call cap. Native assets need no approval. Conflicting spenders for the same token are rejected until the policy representation is reviewed; the framework never replaces them with an unrestricted approval. General EVM approval pins still require the pending contract upgrade, and normal `create/add` validation enforces that boundary. Presets do not sign, fetch app ABIs or modify wallets.
+Templates describe permissions, not available liquidity or guaranteed execution. Verify destination token balances, supported reserves and source PRC20 routes before use: protocol testnet mock tokens may differ from MOVEABLE tokens. Presets do not sign, fetch app ABIs or modify wallets. Dynamic-path swaps, Solana protocol templates and unconfirmed deployments are excluded. Mainnet addresses were checked read-only; no mainnet transactions were executed. Other mainnet protocols in the proposal remain excluded until their deployment and permission constraints are verified. Local policy tests do not execute the destination protocols.
 
-The remaining catalog work includes selecting verified apps/functions/chains, struct-field indexing and checking approval combinations against the delivered policy. App ABIs remain with the UI.
+### Configure, inspect and regenerate
+
+`readiness.ready` means the returned chains have locally complete inputs and at least one enabled asset operation. It does not check PRC20 availability, deployments, balances, live reserve flags or liquidity. `readiness.chains` gives per-chain `issues`, `disabledCalls`, `excludedCalls`, catalog `knownTokens` and `zeroBridgeLimits`. These are additive result fields; `rules` remains accepted by the existing create/update methods.
+
+The UI should collect chain, agent, token selections, raw-unit limits, gas budget and expiry. Show zero-cap calls as disabled. Present excluded calls explicitly. There is no SDK-selected 0.1 PC gas budget or 30-day expiry. A zero bridge limit can be intentional when assets are already at the destination; it is reported separately from operation readiness.
+
+```ts
+async function createConfiguredDex(
+  client: PushChain, agent: Address, tokenIn: Address, tokenOut: Address,
+) {
+  const configured = filledPreset(agent, tokenIn, tokenOut);
+  if (!configured.readiness.ready) {
+    // Render these issues in the configuration screen; do not present it as ready.
+    return { issues: configured.readiness.chains };
+  }
+  return client.agentic.create('My DEX agent', { rules: configured.rules });
+}
+
+async function replaceConfiguredDex(
+  client: PushChain, wallet: Address, rulesId: Hex,
+  agent: Address, tokenIn: Address, tokenOut: Address,
+) {
+  // Re-run get after editing tokens or limits. Changing rule.assets alone
+  // does not regenerate allowedCalls, token pins or approvals.
+  const configured = filledPreset(agent, tokenIn, tokenOut);
+  if (!configured.readiness.ready) throw new Error('Complete the preset inputs');
+  return client.agentic.wallet(wallet).rules.update({
+    rules: [{ rulesId, rule: configured.rules[0] }],
+  });
+}
+```
+
+Save the preset category and editable inputs in the UI if subsequent edits should regenerate the preset. On-chain rules do not retain preset provenance or display metadata. A regenerated result is a replacement: do not append it to the old allowedCalls or keep the old token approvals. An update creates a new rulesId and resets counters, as documented above.
+
+### Amount units and enforcement scope
+
+| Preset operation | Generated restriction |
+| --- | --- |
+| DEX swap | Selected input/output token equality, wallet recipient, maximum input amount |
+| Aave supply/withdraw/borrow/repay | Listed reserve token equality, wallet beneficiary, amount maximum |
+| Moonwell/Venus mint/redeemUnderlying/borrow/repayBorrow | Maximum in the market's underlying-token units |
+| EigenLayer deposit | Selected token equality and deposit amount maximum |
+| Lido wrap/unwrap | stETH/wstETH input limits respectively; their units are not interchangeable |
+| Lido submit | Native-value cap from the selected native asset's maxPerCall |
+
+Aave reserve choices come from the reviewed official address book; fixed-token markets only enable for their actual underlying. Unknown assets do not receive an Aave approval or a positive Aave operation cap. A reserve listing is not a guarantee that its current supply cap, pause state or liquidity allows a transaction.
+
+Market `redeem(uint256)` takes shares: it is excluded and `redeemUnderlying(uint256)` is provided instead. Lido's dynamic withdrawal arrays and position-based claims are also excluded because an underlying amount cap cannot safely be converted into those arguments by this pure helper. Custom rules remain possible through the normal rule API.
+
+**A per-call limit applies to each allowed contract call, not the sum of several calls in one transaction. `maxTotal` is the cumulative Push-outbound amount, not lifetime turnover on the destination.** These statements also hold when a call's tokens are already in the CEA. Destination lifetime or batch-total accounting requires contract support. Bounded approvals do not supply such accounting.
+
+The contract allows at most 32 pins across a universal rule. Expansion fails explicitly if the selected assets/apps exceed that ceiling; no restrictions are silently dropped. Two Aave reserves fit its four-operation template; three do not. Blank/incomplete inputs return zero-cap review calls, and regeneration replaces them with the selected token-specific calls.
 
 ## Validation
 
 Run `node packages/core/scripts/check-agw-docs.js` to typecheck these examples. Unit tests use the normal core Jest configuration. `jest.agw-local.config.ts` uses pinned real AGW contracts and a stub gateway. Live E2Es are opt-in under `__e2e__/agw`; preflight verifies the deployment and funding limits. Local tests do not prove destination delivery, and historical live results do not count as validation of a changed public API.
+
+
+### Live preset acceptance
+
+The opt-in `agw-presets` E2E group exercises real Donut-to-Sepolia protocol calls. From `packages/core`, run `npm run e2e:preflight -- --group agw-presets --dry-run`, then `npm run e2e:ci -- --group agw-presets`. It uses the existing E2E credentials in memory. Each scenario funds a fresh wallet with at most 65 PC plus a fresh agent's configured gas allocation; the Uniswap case also uses 0.000002 pETH. No mainnet transaction is part of this group.
+
+Uniswap uses destination WETH/Circle USDC; Aave uses its faucet LINK. Their generated preset calls and pins are retained, but bridge `assets` are set to `[]` because these destination tokens are not a supported SDK PRC20 pair. The owner funds the CEA separately. These tests establish swaps and lending against actual protocols, not the ability to bridge arbitrary assets. Missing liquidity, exhausted reserve caps or an unavailable faucet fail as prerequisites rather than silently skipping. Results are specific to Sepolia and do not certify the other catalog chains.
+
+
+The additional opt-in group `agw-presets-expanded` covers EigenLayer deposits on Sepolia; Uniswap swaps on Base/Arbitrum Sepolia; PancakeSwap plus Venus on BNB testnet; and Aave plus Moonwell on Base Sepolia. Use the same preflight/run commands with `--group agw-presets-expanded`. Each scenario funds a fresh wallet with at most 100 PC and checks any required destination-native PRC20 before transfer. Native-wrap cases use 10^12 raw native-token units. These are deposit/swap/redemption checks, not borrow/repay or every-market coverage.
+
+AGW token resolution uses the destination chain for ordinary token objects: an explicit Base or Arbitrum ETH token must not select Sepolia's PRC20 merely because its symbol/address is identical. An explicit Push PRC20 reference must name the same source chain as the destination; a mismatch fails before signing.

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+@pushchain/core@6.0.27-alpha.2 (2026-10-16)
+
+- feat: add bounded preset operations and configuration readiness
+
+---
+
+@pushchain/core@6.0.27-alpha.1 (2026-10-15)
+
+- fix: resolve AGW tokens by destination and expand live coverage
+- feat: add mainnet AGW presets and live protocol coverage
+- fix: return safe AGW preset review templates
+- feat: add verified testnet AGW preset templates
+- feat: migrate AGW SDK to deployed v6 contracts
+
+---
+
 @pushchain/core@6.0.27-alpha.0 (2026-10-12)
 
 - feat: align AGW rules and presets with October SDK feedback

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushchain/core",
-  "version": "6.0.27-alpha.0",
+  "version": "6.0.27-alpha.2",
   "homepage": "https://push.org",
   "keywords": [
     "pushchain",

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

@@ -1,4 +1,5 @@
-/** Public section-6 rules and internal adapters for the deployed v5 wire format.
+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';
@@ -14,6 +15,7 @@ export type AgenticProgressHook = (event: ProgressEvent) => void;
 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. */
@@ -94,6 +96,7 @@ export interface AssetCap {
     maxTotal?: bigint;
 }
 export interface AllowedCall {
+    pins?: ArgPinWire[];
     target: AgenticAddress;
     selector: Selector;
     /** Argument index whose address must be the wallet's destination account. */
@@ -192,13 +195,15 @@ export interface InternalRulesRecord {
 }
 /** 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: number;
+    arg: ArgumentPath;
     expected: AgenticHex | AgenticAddress | bigint | WalletMarker;
     max?: never;
     account?: never;
 } | {
-    arg: number;
+    arg: ArgumentPath;
     max: bigint;
     expected?: never;
     account?: never;

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

@@ -19,7 +19,7 @@ export declare enum AgenticCapability {
     ASSERT_SPENT_NATIVE = "assertSpentNative",
     /** checkpointCount + Checkpointed events. */
     CHECKPOINTS = "checkpoints",
-    /** Agent-door EVM outbound composition against v5 per-token caps. */
+    /** 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",

package/src/lib/agentic/capabilities.js

@@ -26,7 +26,7 @@ var AgenticCapability;
     AgenticCapability["ASSERT_SPENT_NATIVE"] = "assertSpentNative";
     /** checkpointCount + Checkpointed events. */
     AgenticCapability["CHECKPOINTS"] = "checkpoints";
-    /** Agent-door EVM outbound composition against v5 per-token caps. */
+    /** 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";

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

@@ -13,3 +13,8 @@ export declare function argumentOffset(inputs: readonly AbiParameter[] | undefin
 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;
+};

package/src/lib/agentic/codec/abi-layout.js

@@ -6,6 +6,7 @@ exports.isSingleWordStatic = isSingleWordStatic;
 exports.argumentOffset = argumentOffset;
 exports.encodeArgWord = encodeArgWord;
 exports.rawOffset = rawOffset;
+exports.argumentLocation = argumentLocation;
 const viem_1 = require("viem");
 const errors_1 = require("../errors");
 /**
@@ -85,7 +86,8 @@ function encodeArgWord(param, expected, what) {
     try {
         const isWord = typeof expected === 'string' && (0, viem_1.isHex)(expected) && expected.length === 66;
         if (param.type === 'address' && !isWord) {
-            if (typeof expected !== 'string' || !(0, viem_1.isAddress)(expected, { strict: false })) {
+            if (typeof expected !== 'string' ||
+                !(0, viem_1.isAddress)(expected, { strict: false })) {
                 throw new Error('expected an address');
             }
         }
@@ -95,9 +97,13 @@ function encodeArgWord(param, expected, what) {
         }
         // An already-encoded 32-byte word (as decoded rules return) is accepted
         // when it is a canonical encoding of this argument type.
-        if (typeof expected === 'string' && (0, viem_1.isHex)(expected) && expected.length === 66 && param.type !== 'bytes32') {
+        if (typeof expected === 'string' &&
+            (0, viem_1.isHex)(expected) &&
+            expected.length === 66 &&
+            param.type !== 'bytes32') {
             const [value] = (0, viem_1.decodeAbiParameters)([param], expected);
-            if ((0, viem_1.encodeAbiParameters)([param], [value]).toLowerCase() !== expected.toLowerCase()) {
+            if ((0, viem_1.encodeAbiParameters)([param], [value]).toLowerCase() !==
+                expected.toLowerCase()) {
                 throw new Error('word is not a canonical encoding');
             }
             return expected.toLowerCase();
@@ -118,4 +124,45 @@ function rawOffset(offset, what) {
 function invalid(message, cause) {
     return new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, message, { cause });
 }
+/** Absolute location of a scalar reached through static tuple/fixed-array indexes. */
+function argumentLocation(inputs, arg, what) {
+    if (!inputs)
+        throw invalid(`${what} paths require a full function signature`);
+    const path = typeof arg === 'number' ? [arg] : arg;
+    if (!Array.isArray(path) ||
+        path.length === 0 ||
+        path.length > 16 ||
+        path.some((i) => !Number.isSafeInteger(i) || i < 0))
+        throw invalid(`${what} has an invalid argument path`);
+    if (path[0] >= inputs.length)
+        throw invalid(`${what} argument path is out of range`);
+    let offset = 4 + inputs.slice(0, path[0]).reduce((n, p) => n + headSize(p), 0);
+    let param = inputs[path[0]];
+    for (const index of path.slice(1)) {
+        if (isDynamic(param))
+            throw invalid(`${what} cannot descend into a dynamic argument`);
+        const arr = arraySuffix(param.type);
+        if (arr && arr.length !== null) {
+            if (!Number.isSafeInteger(arr.length) || index >= arr.length)
+                throw invalid(`${what} fixed-array index is out of range`);
+            const child = { ...param, type: arr.base };
+            offset += index * headSize(child);
+            param = child;
+        }
+        else if (param.type === 'tuple') {
+            const fields = components(param);
+            if (index >= fields.length)
+                throw invalid(`${what} tuple index is out of range`);
+            offset += fields.slice(0, index).reduce((n, p) => n + headSize(p), 0);
+            param = fields[index];
+        }
+        else
+            throw invalid(`${what} path descends into a scalar`);
+    }
+    if (!isSingleWordStatic(param) ||
+        !Number.isSafeInteger(offset) ||
+        offset + 32 > UINT16_MAX)
+        throw invalid(`${what} must identify one static ABI word within the uint16 offset range`);
+    return { offset, param };
+}
 //# sourceMappingURL=abi-layout.js.map

package/src/lib/agentic/codec/defaults.d.ts

@@ -4,13 +4,13 @@
  * a fallback for these fields; update this table for future changes.
  *
  * Explicit zero always stays zero. In the native policy a zero value/amount
- * cap forbids positive value/amount, while maxCalls = 0 means unlimited.
+ * cap forbids positive value/amount, while maxCalls = uint32 maximum means unlimited.
  */
 export declare const UINT256_MAX: bigint;
 export interface DefaultRow {
     value: bigint;
     meaning: string;
-    source: 'product' | 'v5';
+    source: 'product' | 'v6';
 }
 export declare const AGENTIC_DEFAULTS: {
     readonly native: {

package/src/lib/agentic/codec/defaults.js

@@ -8,7 +8,7 @@ exports.withDefault = withDefault;
  * a fallback for these fields; update this table for future changes.
  *
  * Explicit zero always stays zero. In the native policy a zero value/amount
- * cap forbids positive value/amount, while maxCalls = 0 means unlimited.
+ * cap forbids positive value/amount, while maxCalls = uint32 maximum means unlimited.
  */
 exports.UINT256_MAX = BigInt(2) ** BigInt(256) - BigInt(1);
 exports.AGENTIC_DEFAULTS = {
@@ -29,7 +29,7 @@ exports.AGENTIC_DEFAULTS = {
             source: 'product',
         },
         maxCalls: {
-            value: BigInt(0),
+            value: BigInt(0xffffffff),
             meaning: 'unlimited calls until expiry',
             source: 'product',
         },

package/src/lib/agentic/codec/ids.d.ts

@@ -1,6 +1,6 @@
 import { type Address, type Hex } from 'viem';
 /**
- * Pure identity helpers mirroring the pinned AGW generation (v5):
+ * Pure identity helpers mirroring the pinned AGW generation (v6):
  *   smartsessions IdLib.toActionId / toConfigId / toPermissionId and
  *   AGWFactory._predict (OZ Clones immutable-args CREATE2).
  * Every input that changes the result is explicit — validator, factory and

package/src/lib/agentic/codec/ids.js

@@ -8,7 +8,7 @@ exports.deriveWallet = deriveWallet;
 const viem_1 = require("viem");
 const errors_1 = require("../errors");
 /**
- * Pure identity helpers mirroring the pinned AGW generation (v5):
+ * Pure identity helpers mirroring the pinned AGW generation (v6):
  *   smartsessions IdLib.toActionId / toConfigId / toPermissionId and
  *   AGWFactory._predict (OZ Clones immutable-args CREATE2).
  * Every input that changes the result is explicit — validator, factory and

package/src/lib/agentic/codec/native.d.ts

@@ -1,10 +1,11 @@
+import { type ArgPinWire } from './pins';
 import { type AbiParameter, type Address, type Hex } from 'viem';
 import type { NativeAction, NativeRule, NativeSingleRule } from '../agentic.types';
 import { type ParsedSelector } from './selectors';
-/** URP native limits at v5 (Types.sol MAX_PINS, AGW MAX_NATIVE_ACTIONS). */
+/** URP native limits at v6 (Types.sol MAX_PINS, AGW MAX_NATIVE_ACTIONS). */
 export declare const MAX_PINS = 8;
 export declare const MAX_NATIVE_ACTIONS = 8;
-/** NativeTerms (Types.sol:354-363 at v5). */
+/** NativeTerms in the pinned v6 Types.sol. */
 export interface NativeTermsWire {
     validUntil: number;
     target: Address;
@@ -18,10 +19,7 @@ export interface NativeTermsWire {
         maxTotal: bigint;
     };
     maxCalls: number;
-    pins: readonly {
-        offset: number;
-        expected: Hex;
-    }[];
+    pins: readonly ArgPinWire[];
 }
 export declare const NATIVE_TERMS_PARAM: AbiParameter;
 export interface NativeEncodeContext {

package/src/lib/agentic/codec/native.js

@@ -10,12 +10,13 @@ exports.decodeNativeTerms = decodeNativeTerms;
 exports.nativeTermsToRule = nativeTermsToRule;
 exports.nativeActionTermsToRule = nativeActionTermsToRule;
 exports.isUnlimited = isUnlimited;
+const pins_1 = require("./pins");
 const viem_1 = require("viem");
 const errors_1 = require("../errors");
 const abi_layout_1 = require("./abi-layout");
 const defaults_1 = require("./defaults");
 const selectors_1 = require("./selectors");
-/** URP native limits at v5 (Types.sol MAX_PINS, AGW MAX_NATIVE_ACTIONS). */
+/** URP native limits at v6 (Types.sol MAX_PINS, AGW MAX_NATIVE_ACTIONS). */
 exports.MAX_PINS = 8;
 exports.MAX_NATIVE_ACTIONS = 8;
 const UINT32_MAX = 2 ** 32 - 1;
@@ -42,10 +43,7 @@ exports.NATIVE_TERMS_PARAM = {
         {
             name: 'pins',
             type: 'tuple[]',
-            components: [
-                { name: 'offset', type: 'uint16' },
-                { name: 'expected', type: 'bytes32' },
-            ],
+            components: pins_1.ARG_PIN_COMPONENTS,
         },
     ],
 };
@@ -68,6 +66,7 @@ const SINGLE_ACTION_FIELDS = [
     'maxValueTotal',
     'maxCalls',
     'pins',
+    'wirePins',
     'amount',
 ];
 /**
@@ -106,6 +105,7 @@ function nativeActionsOf(rule) {
             maxValueTotal: single.maxValueTotal,
             maxCalls: single.maxCalls,
             pins: single.pins,
+            wirePins: single.wirePins,
             amount: single.amount,
             validUntil: single.validUntil,
         },
@@ -171,7 +171,8 @@ function nativeActionToTerms(rule, ctx) {
     }
     const parsed = (0, selectors_1.parseSelector)(rule.selector);
     const pinsIn = rule.pins ?? [];
-    if (parsed.valueOnly && (pinsIn.length > 0 || rule.amount)) {
+    if (parsed.valueOnly &&
+        (pinsIn.length > 0 || rule.wirePins?.length || rule.amount)) {
         throw invalid('a value-only rule cannot carry pins or an amount rule');
     }
     if (pinsIn.length > exports.MAX_PINS) {
@@ -243,9 +244,20 @@ function nativeActionToTerms(rule, ctx) {
     const maxCalls = rule.maxCalls === undefined
         ? Number(defaults_1.AGENTIC_DEFAULTS.native.maxCalls.value)
         : rule.maxCalls;
-    if (!Number.isInteger(maxCalls) || maxCalls < 0 || maxCalls > UINT32_MAX) {
+    if (!Number.isInteger(maxCalls) || maxCalls <= 0 || maxCalls > UINT32_MAX) {
         throw invalid('maxCalls must be a uint32 integer');
     }
+    try {
+        (0, pins_1.validatePins)(rule.wirePins ??
+            pins.map((p) => ({
+                offset: p.offset,
+                op: 0,
+                value: p.expected,
+            })));
+    }
+    catch (error) {
+        throw invalid(error.message);
+    }
     return {
         parsed,
         terms: {
@@ -256,7 +268,12 @@ function nativeActionToTerms(rule, ctx) {
             maxValueTotal,
             amount,
             maxCalls,
-            pins,
+            pins: rule.wirePins ??
+                pins.map((p) => ({
+                    offset: p.offset,
+                    op: 0,
+                    value: p.expected,
+                })),
         },
     };
 }
@@ -285,12 +302,8 @@ function nativeTermsToRule(terms, agent) {
         maxValueTotal: terms.maxValueTotal,
         maxCalls: Number(terms.maxCalls),
     };
-    if (terms.pins.length > 0) {
-        rule.pins = terms.pins.map((p) => ({
-            offset: Number(p.offset),
-            expected: p.expected.toLowerCase(),
-        }));
-    }
+    if (terms.pins.length > 0)
+        rule.wirePins = terms.pins.map((p) => ({ ...p }));
     if (terms.amount.enabled) {
         rule.amount = {
             offset: Number(terms.amount.offset),

package/src/lib/agentic/codec/pins.d.ts

@@ -0,0 +1,20 @@
+import type { Hex } from 'viem';
+export interface ArgPinWire {
+    offset: number;
+    op: 0 | 1;
+    value: Hex;
+}
+export declare const ARG_PIN_COMPONENTS: readonly [{
+    readonly name: "offset";
+    readonly type: "uint16";
+}, {
+    readonly name: "op";
+    readonly type: "uint8";
+}, {
+    readonly name: "value";
+    readonly type: "bytes32";
+}];
+export declare const UNLIMITED_CALLS = 4294967295;
+export declare const ANY_ACCOUNT_COUNT = 255;
+/** Validate every encoded constraint before signing. */
+export declare function validatePins(pins: readonly ArgPinWire[]): void;

package/src/lib/agentic/codec/pins.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANY_ACCOUNT_COUNT = exports.UNLIMITED_CALLS = exports.ARG_PIN_COMPONENTS = void 0;
+exports.validatePins = validatePins;
+exports.ARG_PIN_COMPONENTS = [
+    { name: 'offset', type: 'uint16' },
+    { name: 'op', type: 'uint8' },
+    { name: 'value', type: 'bytes32' },
+];
+exports.UNLIMITED_CALLS = 0xffffffff;
+exports.ANY_ACCOUNT_COUNT = 255;
+/** Validate every encoded constraint before signing. */
+function validatePins(pins) {
+    if (!Array.isArray(pins) || pins.length > 8)
+        throw new Error('pins must contain at most eight constraints');
+    const seen = new Set();
+    for (const p of pins) {
+        if (!Number.isInteger(p.offset) ||
+            p.offset < 4 ||
+            p.offset + 32 > 65535 ||
+            ![0, 1].includes(p.op) ||
+            !/^0x[0-9a-fA-F]{64}$/.test(p.value))
+            throw new Error('invalid argument pin');
+        if (seen.has(p.offset))
+            throw new Error('duplicate pin offset');
+        seen.add(p.offset);
+    }
+}
+//# sourceMappingURL=pins.js.map

package/src/lib/agentic/codec/rules.d.ts

@@ -38,7 +38,7 @@ export interface PreparedRule {
     universalTerms?: UniversalTermsWire;
     svmTerms?: SvmTermsWire;
 }
-/** Validate before signing. V5 permits several grants for the same agent/chain. */
+/** Validate before signing. V6 permits several grants for the same agent/chain. */
 export declare function prepareRules(rules: readonly InternalRule[], ctx: RuleEncodeContext & {
     /** Wallet owner; when given, an agent equal to it is AGENT_IS_OWNER. */
     owner?: Address;