@pushchain/core 6.0.25 → 6.0.27-alpha.0

package/AGW.md

@@ -0,0 +1,194 @@
+# 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.
+
+## Connect
+
+Use an application-managed key; examples do not load secrets or execute automatically.
+
+```ts
+import {
+  PushChain,
+  AgenticError,
+  type Rule,
+} from '@pushchain/core';
+import {
+  createWalletClient,
+  http,
+  parseEther,
+  encodeFunctionData,
+  erc20Abi,
+  type Address,
+  type Hex,
+} from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+
+type WalletTransaction = Awaited<ReturnType<PushChain['universal']['sendTransaction']>>;
+
+const NETWORK = PushChain.CONSTANTS.PUSH_NETWORK.TESTNET_DONUT;
+const PUSH = PushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUT;
+const SEPOLIA = PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA;
+const ETH = PushChain.CONSTANTS.MOVEABLE.TOKEN.ETHEREUM_SEPOLIA.ETH;
+
+async function connectPush(key: Hex, wallet?: Address): Promise<PushChain> {
+  const walletClient = createWalletClient({
+    account: privateKeyToAccount(key),
+    transport: http('https://evm.donut.rpc.push.org/'),
+  });
+  const signer = await PushChain.utils.signer.toUniversalFromKeypair(
+    walletClient,
+    { chain: PUSH, library: PushChain.CONSTANTS.LIBRARY.ETHEREUM_VIEM },
+  );
+  return PushChain.initialize(signer, {
+    network: NETWORK,
+    ...(wallet ? { agenticWallet: wallet } : {}),
+  });
+}
+```
+
+## Create and manage rules
+
+Every chain uses `Rule.allowedCalls`. Omit `chainNamespace` for Push. The agent is always its Push address: a native EOA or an external signer's UEA. The owner cannot be its own agent.
+
+```ts
+async function createNative(owner: PushChain, agent: Address, token: Address, recipient: Address) {
+  const rule: Rule = {
+    agent,
+    validUntil: Math.floor(Date.now() / 1000) + 3600,
+    allowedCalls: [{
+      target: token,
+      selector: 'transfer(address,uint256)',
+      pins: [{ arg: 0, expected: recipient }, { arg: 1, max: 10n }],
+    }],
+  };
+  return owner.agentic.create('operations', { rules: [rule] });
+}
+
+async function manage(owner: PushChain, address: Address, id: Hex) {
+  const wallet = owner.agentic.wallet(address);
+  const record = await wallet.rules.get(id);
+  // Reads preserve the constraints needed by update.
+  const changed = await wallet.rules.update({
+    rules: [{ rulesId: id, rule: { ...record.rule, validUntil: record.validUntil + 3600 } }],
+  });
+  await wallet.setLabel('renamed'); // direct cosmetic write; no checkpoint
+  await wallet.rules.delete([changed.rules[0].rulesId]);
+  // Delete all requires an explicit target:
+  // await wallet.rules.delete({ all: true });
+  return wallet.info();
+}
+```
+
+`derive({ index? })` returns the predicted address, index and deployment state. `list()` enumerates the connected owner's wallets. A wallet handle provides `info`, `owner`, `checkpoints`, `setLabel`, and `rules.list/get/add/update/delete`. Deleted rules are not returned in v1. Rule IDs may change during update.
+
+`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.
+
+## 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.
+
+`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.
+
+## EVM destinations
+
+```ts
+function evmRule(agent: Address, target: Address): Rule {
+  return {
+    agent,
+    chainNamespace: SEPOLIA,
+    validUntil: Math.floor(Date.now() / 1000) + 3600,
+    assets: [{ token: ETH, maxPerCall: 1_000n, maxTotal: 10_000n }],
+    maxGasPerCall: parseEther('20'),
+    allowedCalls: [{
+      target,
+      selector: 'deposit(address,uint256)',
+      pins: [{ arg: 0, expected: PushChain.CONSTANTS.AGENTIC.WALLET }],
+    }],
+  };
+}
+```
+
+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.
+
+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.
+
+## Solana destinations
+
+Rules use fixed-width signatures and numeric positions, without an IDL:
+
+```ts
+function solanaRule(agent: Address, program: string): Rule {
+  return {
+    agent,
+    chainNamespace: PushChain.CONSTANTS.CHAIN.SOLANA_DEVNET,
+    validUntil: Math.floor(Date.now() / 1000) + 3600,
+    maxGasPerCall: parseEther('20'),
+    allowedCalls: [{
+      target: program,
+      selector: 'receive_sol(u64)',
+      pins: [
+        { account: 2, expected: PushChain.CONSTANTS.AGENTIC.WALLET },
+        { arg: 0, max: 1_000n },
+      ],
+    }],
+  };
+}
+```
+
+Use the program's actual account positions. `{ account, expected: WALLET, token: mint }` pins the wallet's ATA, using the verified mint/token-program context. Fixed integer, bool, pubkey and fixed-array layouts are supported; dynamic or undefined layouts fail before signing. Raw eight-byte discriminators support account pins; argument pins also need argument types. A nonzero per-call EVM `maxValue` has no Solana encoding.
+
+Solana reads return `format: 'decoded'` with exact stored discriminators, offsets and constraints. This raw form is accepted by `rules.update`, preserving restrictions without inventing an IDL. Reusing it for another wallet/gateway is rejected. Send-data encoding still uses the existing `utils.helpers.encodeTxData` IDL helper; rule authoring and transaction encoding are separate operations.
+
+## Spend, checkpoints and execution
+
+`rules.get/list` return `spent`. Universal spend contains one entry per asset in stored order. A single native call has scalar value/amount/call counters. Several native calls return `spent.actions`, with each entry identified by target and selector; unrelated token amounts are not summed.
+
+Native historical terms with lifetime limits or differing per-action expiries that the new public shape cannot preserve return an explicit capability error rather than silently dropping restrictions.
+
+Connect with `PushChain.initialize(signer, { agenticWallet: address })` to send from the wallet. Signer identity determines the owner or agent door. Native agent arrays are atomic and every call passes policy checks. `from` cannot be overridden. Responses identify the wallet as `from` and signer as `origin`, including wait/replay results.
+
+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
+
+The October 12 contract feedback is not deployed. Until it is verified:
+
+- 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.
+
+`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`.
+
+## 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.
+
+```ts
+const { presets } = PushChain.utils.agentic.presets.list({ type: 'CATEGORY' });
+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.
+
+function filledPreset(agent: Address) {
+  return PushChain.utils.agentic.presets.get(
+    PushChain.CONSTANTS.AGENTIC.PRESETS.CATEGORY.DEXES,
+    { agent, validUntil: Math.floor(Date.now() / 1000) + 3600 },
+  ).rules;
+}
+```
+
+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.
+
+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.
+
+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.
+
+## 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.

package/CHANGELOG.md

@@ -1,3 +1,77 @@
+@pushchain/core@6.0.27-alpha.0 (2026-10-12)
+
+- feat: align AGW rules and presets with October SDK feedback
+- feat: add AGW v5 wallet and rules SDK
+- test: mirror the restructured Universal Read docs playgrounds
+
+---
+
+@pushchain/core@6.0.26 (2026-09-23)
+
+- docs: changelog for read-state docs parity
+- feat: align read-state API with the Universal Read docs
+- fix: race prune and archive for Push receipts and block results
+- feat: add Solana account reads and update read registry
+
+---
+
+@pushchain/core (unreleased)
+
+Changes on `feature/readstate-docs-parity` since 6.0.25, aligning Universal Read with the
+push-chain-website docs (PR #1244).
+
+### Breaking
+
+- Solana token reads detect SPL Token vs Token-2022 from the mint's owner. The
+  `tokenProgram` option is removed and now throws.
+- The Donut Universal Read Registry default is
+  `0x00000000000000000000000000000000000000b2`. Results stored on the previous
+  registry stay there; tracking by request ID still works.
+- `READ-TX-199-01` (level SUCCESS) now fires only when `outcome` is `SUCCESS`. A
+  FULFILLED read that did not work (source error, callback failure, undecodable
+  result, unconfirmed delivery) ends on `READ-TX-199-02`, whose `status` is the
+  outcome name.
+
+### Added
+
+- Solana account reads with `idl`, the counterpart of `abi`. The account layout is
+  picked by its 8-byte discriminator; the optional `functionName` names the layout
+  (snake, camel or Pascal case) and types `value`. With the program id as the
+  subject, `functionName` plus positional `args` derive the PDA from the seeds the
+  IDL declares. `accountName` is not supported and throws with a hint.
+- EVM contract-call reads accept any ABI function, including `nonpayable` and
+  `payable`. Validators run the call as an `eth_call` simulation at the pinned
+  block, so it returns data and never executes.
+- `response.outcome` (`PushChain.CONSTANTS.READ.OUTCOME`): one answer to "did it
+  work" — `SUCCESS`, `SOURCE_ERROR`, `CALLBACK_FAILED`, `DECODE_FAILED`,
+  `EXPIRED`, `FAILED`, `ABORTED`, `PENDING`, or `UNKNOWN` (delivery unconfirmed).
+- `response.requestIdUint`: the request ID as the `uint256` contracts key results by.
+- Progress events: `READ-TX-104-03` Looking Up Request, `104-04` Request Found,
+  `104-05` Request Not Found (lookup timeout), `105-04` Approaching Expiry (once per
+  `wait()`, at 30 or fewer Push blocks left) and `102-04` Preflight Stale (a read
+  prepared more than 60 s before `executeReads`).
+
+### Improved
+
+- `trackRead` on a settled read returns in about 1 s instead of about 19 s on
+  Donut. Fulfil and settle receipts are fetched in parallel, and Push receipts
+  are requested from the prune RPC and the archive at the same time.
+- `callback.gasLimit` is optional for custom targets and defaults to `500_000n`,
+  like the registry. Unused callback budget is refunded.
+- Refund events `READ-TX-106-05/06` also fire for expired reads.
+- `value` is typed `unknown` for ABIs not declared `as const`; a single-output
+  function decodes to the bare value, not an array.
+
+### Fixed
+
+- `explorerUrl` and Donut's viem `blockExplorers` pointed at
+  `explorer.donut.push.org`, which does not resolve. They now use
+  `https://donut.push.network`.
+- Refunds of expired reads older than the prune window came back `undefined`.
+  Cosmos block results now fall back to the archive RPC.
+
+---
+
 @pushchain/core@6.0.25 (2026-09-16)
 
 - docs: document read-state and transaction fixes

package/README.md

@@ -8,6 +8,8 @@ Push Chain is a true universal L1 that is 100% EVM compatible. It allows develop
 
 ## Documentation
 
+For AGW v5 in this branch, see the [agentic wallet integration guide](AGW.md) for creation, rules, funding, execution and recovery.
+
 For full documentation, API references, and guides, visit:  
 👉 [Push Chain Developer Docs](https://push.org/docs)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushchain/core",
-  "version": "6.0.25",
+  "version": "6.0.27-alpha.0",
   "homepage": "https://push.org",
   "keywords": [
     "pushchain",
@@ -51,6 +51,11 @@
   },
   "scripts": {
     "build:proto": "scripts/protoc-generate.sh",
+    "docs:check:agw": "node scripts/check-agw-docs.js",
+    "agw:verify": "node scripts/agw-verify.js",
+    "agw:check:package": "node scripts/check-agw-package.js",
+    "agw:check:api": "node scripts/check-agw-api.js",
+    "agw:check:runtimes": "node scripts/check-agw-runtimes.js",
     "e2e:list": "ts-node --transpile-only __e2e__/ci/run.ts --list",
     "e2e:verify": "ts-node --transpile-only __e2e__/ci/run.ts --verify",
     "e2e:preflight": "ts-node --transpile-only __e2e__/ci/preflight.ts",
@@ -67,6 +72,7 @@
     "src/**/*.d.ts",
     "src/**/*.json",
     "README.md",
+    "AGW.md",
     "CHANGELOG.md"
   ],
   "devDependencies": {

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

@@ -0,0 +1,23 @@
+import type { AgenticRuntime } from './runtime';
+import type { AgenticAddress, AgenticNamespace, AgenticWallet, CreateOptions, CreateResult, WalletSummary } from './agentic.types';
+/**
+ * client.agentic — owner-side AGW management (spec section 1). Ownership is
+ * always the connected signer's Push identity (EOA, or the UEA for its origin
+ * chain), never the AGW an agentic client exposes as universal.account.
+ */
+export declare class AgenticNamespaceImpl implements AgenticNamespace {
+    private readonly runtime;
+    constructor(runtime: AgenticRuntime);
+    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;
+}

package/src/lib/agentic/agentic.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgenticNamespaceImpl = void 0;
+const public_rule_1 = require("./public-rule");
+const capabilities_1 = require("./capabilities");
+const deployments_1 = require("./deployments");
+const create_1 = require("./management/create");
+const common_1 = require("./management/common");
+const wallets_1 = require("./reads/wallets");
+const wallet_1 = require("./wallet");
+const progress_hook_types_1 = require("../progress-hook/progress-hook.types");
+/**
+ * client.agentic — owner-side AGW management (spec section 1). Ownership is
+ * always the connected signer's Push identity (EOA, or the UEA for its origin
+ * chain), never the AGW an agentic client exposes as universal.account.
+ */
+class AgenticNamespaceImpl {
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    async derive(opts) {
+        const gen = (0, deployments_1.currentGeneration)(this.runtime.network);
+        (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.WALLET_READS);
+        const owner = this.runtime.signerPushAccount();
+        const r = await (0, wallets_1.deriveForOwner)(this.runtime.reader, gen, owner, opts?.index);
+        (0, common_1.emitAgentic)(this.runtime, undefined, progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_101, r.address, r.index, r.deployed);
+        return {
+            address: r.address,
+            index: r.index,
+            deployed: r.deployed,
+        };
+    }
+    async create(label, options) {
+        return (0, create_1.createWallet)(this.runtime, label, {
+            ...options,
+            rules: (0, public_rule_1.publicRules)(options?.rules),
+        });
+    }
+    async list() {
+        const gen = (0, deployments_1.currentGeneration)(this.runtime.network);
+        (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.WALLET_READS);
+        const wallets = await (0, wallets_1.listForOwner)(this.runtime.reader, gen, this.runtime.signerPushAccount());
+        return { wallets };
+    }
+    wallet(address) {
+        return new wallet_1.AgenticWalletHandle(this.runtime, address);
+    }
+}
+exports.AgenticNamespaceImpl = AgenticNamespaceImpl;
+//# sourceMappingURL=agentic.js.map