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

package/AGW.md

@@ -10,6 +10,7 @@ Use an application-managed key; examples do not load secrets or execute automati
 import {
   PushChain,
   AgenticError,
+  AgenticRevertError,
   type Rule,
 } from '@pushchain/core';
 import {
@@ -116,6 +117,27 @@ The deployed v6 policy supports up to eight EQ/MAX pins per EVM destination call
 
 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.
 
+## Displaying errors in the UI
+
+Use `userMessage` for `AgenticError` and `AgenticRevertError`. Keep `code`, `message`, `hint`, `details`, `decodedError` and `cause` for diagnostics or application-specific translations. Unknown exceptions should get a neutral fallback instead of raw RPC/ABI text.
+
+```ts
+function walletErrorText(error: unknown): string {
+  if (error instanceof AgenticError || error instanceof AgenticRevertError) {
+    return error.userMessage;
+  }
+  return 'The request could not be completed. Check wallet activity before trying again.';
+}
+```
+
+Creation and rule-preparation errors include a zero-based `details.ruleIndex` when a rule can be identified, with `assetIndex`, `callIndex` and `field` where available. The UI message uses a one-based rule number. Use these details to show the error on the relevant rule instead of only in a footer. Read/receipt failures preserve their causes and transaction hashes; do not automatically retry a submitted transaction whose outcome is unknown.
+
+`TOKEN_ROUTE_UNAVAILABLE` means an asset cannot be resolved for transfers from Push. Choose a token with a supported route on this network, or wait for a verified PRC20 route for that exact token address. Changing a symbol does not create a route. Display `error.userMessage` and check preset readiness before creation.
+
+A DEX condition-limit failure reports `details.reason = 'RULE_CONSTRAINT_LIMIT'`, `actual`, `limit` and `callCount`. Conditions here are generated input checks (for example token, recipient and amount checks), rather than the number of visible function names. A stock two-token, single-router preset contains six allowed-call entries and twenty conditions. Appending the same call list again makes forty conditions. The SDK rejects this; it does not deduplicate, remove conditions or split authority automatically. Preserve per-chain rules and regenerate after edits rather than appending generated calls.
+
+For the review screen, show the actual network (including testnet name), selected token addresses and limits. Label maxGasPerCall as a maximum PC gas budget, not a guaranteed fee or execution gas-unit count. maxTotal meters cumulative Push outbounds; it is not a lifetime destination-spend limit.
+
 ## Solana destinations
 
 Rules use fixed-width signatures and numeric positions, without an IDL:
@@ -185,7 +207,7 @@ const { rules: reviewTemplates } = PushChain.utils.agentic.presets.get(
 // Supply the agent to get complete Rule[] configuration.
 const configuredPreset = PushChain.utils.agentic.presets.get(
   PushChain.CONSTANTS.AGENTIC.PRESETS.CATEGORY.LENDING,
-  { chainNamespace: 'eip155:11155111', agent: '0x0000000000000000000000000000000000001234', funding: 'destination' },
+  { chainNamespace: 'eip155:11155111', agent: '0x0000000000000000000000000000000000001234' },
 );
 // Destination assets must already be funded; no Push token exports are granted.
 // Show configuredPreset.readiness.chains[0].selectedAssets in the review UI.
@@ -197,7 +219,6 @@ function filledPreset(agent: Address, tokenIn: Address, tokenOut: Address) {
     PushChain.CONSTANTS.AGENTIC.PRESETS.CATEGORY.DEXES,
     {
       chainNamespace: 'eip155:11155111',
-      funding: 'destination',
       agent,
       validUntil: Math.floor(Date.now() / 1000) + 3600,
       maxGasPerCall: BigInt(10) ** BigInt(18),
@@ -235,13 +256,13 @@ These are small, protocol-specific subsets chosen to fit the 32-call/32-pin ceil
 | Arbitrum Sepolia | WETH / Circle USDC | Aave USDC |
 | BSC testnet | WBNB / Venus USDT | Venus USDT, USDC |
 
-Staking defaults are ETH/stETH/wstETH on Ethereum and the reviewed EigenLayer strategy's WETH on Sepolia. Testnet tokens with similar names can have different addresses; the returned addresses are authoritative. These tokens may lack Push PRC20 routes and can instead be used with destination-held balances. Defaults do not guarantee active reserves, liquidity, a Push PRC20 route or execution. In particular, an unmodified preset can fail rule preparation if its default assets lack PRC20 mappings. For destination-only use, pass `funding: 'destination'`: the SDK generates the operation constraints, returns empty rule bridge assets and retains selected token limits in readiness metadata. This grants no token export budget from Push and requires already-funded destination balances. Token addresses are returned as before; metadata was verified when defining the policy. No runtime metadata/price fetch is added to get.
+Staking defaults are ETH/stETH/wstETH on Ethereum and the reviewed EigenLayer strategy's WETH on Sepolia. Testnet tokens with similar names can have different addresses; the returned addresses are authoritative. Defaults do not guarantee active reserves, liquidity or a Push PRC20 route. An unmodified preset cannot be granted when its assets lack matching PRC20 routes. The SDK preserves the selected tokens and caps and reports unavailable routes; it never removes assets to bypass this check. No runtime metadata/price fetch is added to get.
 
 ### Funding and release-network checks
 
-`funding` defaults to `'push'`. Missing PRC20 registry entries produce `BRIDGE_ASSET_UNAVAILABLE`, and readiness is false while the returned rule retains all requested assets. No address or cap is silently replaced. `network` defaults to `TESTNET_DONUT` (`TESTNET` is accepted as an alias); use the connected client's Push network when supplying it. Networks without a verified AGW deployment report `AGW_NETWORK_UNAVAILABLE`.
+Missing PRC20 registry entries produce `BRIDGE_ASSET_UNAVAILABLE`, and readiness is false while the returned rule retains all requested assets. No address or cap is silently replaced. `network` defaults to `TESTNET_DONUT` (`TESTNET` is accepted as an alias). Networks without a verified AGW deployment report `AGW_NETWORK_UNAVAILABLE`.
 
-Use `funding: 'destination'` for the prefunded CEA workflow. Selected tokens still generate the same target/function/amount/recipient/spender restrictions, exposed alongside their caps in `readiness.chains[].selectedAssets`. Returned `rule.assets` is intentionally empty, which grants zero Push token-export authority. It is safe to pass these returned rules directly to create/update. The mode does not fund the destination, wrap ETH, mint testnet tokens or enable an unsupported network. Do not relabel it as bridge funding in the UI.
+The public preset API has no `funding` option. Remove it from existing integrations; supplying it now produces `INVALID_RULE` rather than silently changing permissions. Internal prefunded CEA test fixtures explicitly clear bridge assets to isolate protocol constraints. Those fixtures do not demonstrate that an unsupported preset route is executable.
 
 Existing mappings distinguish token identity by chain and address, including address casing for EVM. WETH/stETH Sepolia mappings and string/address-word source metadata are supported; mainnet or other-chain WETH is never aliased to them. Protocol mock LINK, Moonwell/Venus mocks and Circle testnet USDC can differ from the supported source tokens; they remain unavailable for bridge funding until real matching routes exist.
 
@@ -266,7 +287,7 @@ Explicit `validUntil` and `maxGasPerCall` override policy values; zero gas is pr
 
 ### Configure, inspect and regenerate
 
-`readiness.ready` requires complete configuration plus offline SDK deployment/destination/bridge-registry support for the selected funding mode. Per-chain `configurationReady` reports input completeness separately. These checks do not verify live balances, reserve flags, liquidity, current deployed bytecode or source identity; grant preparation still verifies wiring and token metadata on-chain before signing. `readiness.chains` gives per-chain `issues`, `disabledCalls`, `excludedCalls`, catalog `knownTokens`, `selectedAssets`, `bridgeAssets`, `funding` and `zeroBridgeLimits`. Display `selectedAssets` as the reviewed token/amount permissions in either mode; `rule.assets` describes Push bridge permissions only. `bridgeAssets` reports registry presence, not verified live deployment. Mainnet templates remain discoverable but have `DESTINATION_UNAVAILABLE` on Donut. These are additive result fields; `rules` remains accepted by the existing create/update methods.
+`readiness.ready` requires complete configuration plus offline SDK deployment, destination and bridge-registry support. Per-chain `configurationReady` reports input completeness separately. These checks do not verify live balances, reserve flags, liquidity or deployed bytecode. Grant preparation verifies wiring and token metadata on-chain before signing. Per-chain `selectedAssets` mirrors the selected rule assets; `bridgeAssets` reports registry presence, not verified live deployment. Mainnet templates remain discoverable but report `DESTINATION_UNAVAILABLE` on Donut. Check readiness before passing `rules` to create/update.
 
 Tokens and permission defaults come directly from the SDK: omitted `assets` populates the curated subset and its caps in every returned `rule.assets`. Omitted gas and expiry use the policy below. The caller supplies the agent and can filter chains; no per-network token selection is required. Show the generated permissions for owner review and allow explicit overrides. Regenerate via get after an edit so operation pins/approvals match the new caps. Show explicitly zero-cap calls as disabled and present excluded calls clearly. A zero bridge limit can be intentional when assets are already at the destination; it is reported separately from operation readiness.
 

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+@pushchain/core@6.0.27-alpha.4 (2026-10-20)
+
+- fix: remove preset funding mode and preserve asset limits
+- feat: sync v4 SDK changes without plan files
+
+---
+
 @pushchain/core@6.0.27-alpha.3 (2026-10-18)
 
 - feat: ship bounded preset defaults with funding checks

package/MARKETPLACE.md

@@ -0,0 +1,206 @@
+# Agentic marketplace and jobs
+
+This SDK checkpoint targets UniversalMarketplace v2 on Push Donut, its pUSDC kernel and AGW v6. It implements card management, JobSpec authoring and paid previews, preview/open, historical deposits and the kernel lifecycle. The evaluator is currently an EOA: there is no automatic verification, baseline or rating claim.
+
+`PushChain.initialize` now exposes `client.market` and `client.job`. Helpers are `PushChain.utils.market` and `PushChain.utils.job`; vocabulary is under `PushChain.CONSTANTS.AGENTIC`. There is no separate `client.evaluation` namespace. Read-only clients can discover cards and jobs.
+
+## Author a card
+
+Use verified application/token addresses and raw token units. The following helper returns permissions and a criteria template; it does not sign or send anything.
+
+```ts
+import { PushChain, MarketError, type AgentCardInput, type AgentCardRules, type JobPlan, type JobWatchCursor, type MarketDepositResult, type PreviewJobSpecOptions } from '@pushchain/core';
+import { parseAbi, type Address } from 'viem';
+
+function authorCard(app: Address, token: Address, receiptToken: Address) {
+  const { WALLET, PRINCIPAL, JOB } = PushChain.CONSTANTS.AGENTIC;
+  const read = PushChain.utils.job.prepareRead({
+    chain: PushChain.CONSTANTS.CHAIN.BNB_TESTNET,
+    target: receiptToken,
+    abi: parseAbi(['function balanceOf(address) view returns (uint256)']),
+    functionName: 'balanceOf',
+    args: [WALLET],
+  });
+  const jobSpecTemplate = PushChain.utils.job.buildJobSpecTemplate({
+    reads: [read],
+    checks: [{ read: 0, evaluation: JOB.EVALUATION.COMPARE, operation: JOB.OPERATION.GREATER_OR_EQUAL, target: { principalBps: 9990n } }],
+    logic: JOB.LOGIC.ALL,
+    allowedMutability: JOB.ALLOWED_MUTABILITY.NONE,
+  });
+  const rules: AgentCardRules = {
+    assets: [{ token, maxPerCall: PRINCIPAL, maxTotal: PRINCIPAL }],
+    principalAsset: 0,
+    maxGasPerCall: 10n ** 18n,
+    allowedCalls: [
+      { target: token, selector: 'approve(address,uint256)', pins: [{ arg: 0, expected: app }, { arg: 1, max: PRINCIPAL }] },
+      { target: app, selector: 'supply(address,uint256,address,uint16)', pins: [{ arg: 0, expected: token }, { arg: 1, max: PRINCIPAL }, { arg: 2, expected: WALLET }] },
+    ],
+  };
+  PushChain.utils.market.validateAgentCardRules(rules);
+  return { rules, jobSpecTemplate };
+}
+```
+
+`client.universal.read.prepare(options)` is the same pure authoring helper. `client.universal.read(prepared, options?)` sends a resolved prepared call and returns raw consensus bytes. WALLET/PARAM holes must first be resolved; the sender rejects them before a paid request. Existing async `universal.prepareRead(subject, options)` remains the paid-request preparation API. They produce different representations. A literal zero is never guessed to be a placeholder. Dynamic-layout placeholders are refused. Descriptions retain ABI function names in memory when available and apply explicit token decimals while retaining raw targets; chain-decoded specs fall back to selectors and addresses.
+
+Cards name one execution chain and one provider. Destination tokens resolve to verified Push PRC20 routes on that chain. An explicit `{ prc20: address }` is available for already-known Push tokens and is returned by lossless rule decoding. No route or same-symbol alias is invented. Structural validation alone does not establish deployment or liquidity readiness.
+
+Approvals are **allowed calls with spender/amount pins** in v2. There is no separate `approvals[]` field or automatic owner-approval deposit step. Principal caps meter outbound tokens from Push; they are not a destination-lifetime trading budget. Spec comparisons use raw units; the receipt token must have the units expected by the criterion.
+
+## Register, preview and open
+
+```ts
+async function registerOffer(
+  provider: PushChain,
+  listing: AgentCardInput,
+  app: Address,
+  token: Address,
+  receiptToken: Address,
+) {
+  const authored = authorCard(app, token, receiptToken);
+  return provider.market.agent.register(listing, authored);
+}
+
+async function openReviewedJob(owner: PushChain, cardId: bigint) {
+  const now = Math.floor(Date.now() / 1000);
+  const plan = await owner.market.preview(cardId, {
+    principal: 100_000_000n,
+    executeBy: now + 3600,
+    expiredAt: now + 86400,
+  });
+  // Render every mayDo/mayMove/judgedBy entry and the logic before signing.
+  return owner.market.openJob(plan, {
+    progressHook: event => console.log(event.id, event.message),
+  });
+}
+```
+
+Opening deploys/reuses the AGW, grants the card's exact resolved permissions and creates an Open job. It moves no principal or fee. The plan is revalidated before signing; changed card versions, nonces, occupancy or plan content require a new preview. OwnerIntent authorization uses the factory EIP-712 domain. Client submission can require a second wallet interaction; no relay is supplied in this checkpoint.
+
+Opening supports EVM typed-data signers. An external owner's UEA must already be deployed on Push (`OWNER_NOT_DEPLOYED` otherwise). The SDK checks the factory domain before prompting, then simulates the complete signed request through the real owner verifier before broadcasting. UEA and ERC-1271 acceptance follows the deployed contract; an EIP-7702 delegate without a compatible verifier fails simulation. Signing capability checks run before prompting; a verifier can reject the resulting signature after prompting. Provider writes use the connected signer's ordinary Push identity, including when the instance also has an AGW execution context.
+
+```ts
+async function recoverOpening(client: PushChain, reviewedPlan: JobPlan, txHash: string) {
+  const tx = await client.universal.trackTransaction(txHash);
+  return client.market.openJob(reviewedPlan, { resume: tx });
+}
+```
+
+If receipt lookup or post-state verification fails, keep the original plan and reported transaction hash. Resume verifies the mined input, event, permission ID, wallet ownership, kernel record and marketplace mappings without another signature or submission. A read-only client can recover an existing opening. Normal writes copy reviewed inputs before awaiting RPCs or wallet prompts. Provider registration/update also simulate the exact card write before submission. A reference ERC-1271 contract-owner adapter and compatible/incompatible EIP-7702 verifiers are exercised against real contracts in the local acceptance suite; custom wallets supply their own `UniversalSigner` transport.
+
+Native transport errors also retain `txHash` and, when confirmation is uncertain, `pendingTransactionHash` after broadcast. Atomic native sends never fall back to sequential calls after a hash exists. Track that hash before another attempt; a confirmed revert retains its hash without claiming that it is still pending.
+
+**Current destination readiness:** BSC Testnet has passing live open/cancel coverage. Sepolia, Base Sepolia and Arbitrum Sepolia have different CEA factories in the marketplace configuration and current SDK routing table; preview returns `CEA_MISMATCH`. The SDK does not substitute the marketplace's account for an independently derived account. Align the deployment/routing configuration before opening on those chains.
+
+Card IDs, versions, ratings and job IDs are bigint. `jobType` reads are the canonical bytes32 hash, not a guessed original name. `cards` walks IDs with bounded concurrency; summaries remain readable even if an unverified provider stored a malformed template. Full `card` decoding/preview rejects unsupported content. `agent.card`, `agent.update` and `agent.setActive` manage the provider's one card. Preserve raw `rulesBytes`/`jobSpecTemplateBytes` for archival rather than serializing away unknown wire metadata.
+
+## Fund and track the kernel lifecycle
+
+```ts
+async function depositForJob(owner: PushChain, jobId: bigint): Promise<MarketDepositResult> {
+  return owner.market.deposit(jobId, {
+    // Target wallet PC balance, not a gas quote for the whole job.
+    pcAmount: 10n ** 18n,
+    funding: 'push',
+    progressHook: event => console.log(event.id, event.message),
+  });
+}
+```
+
+`deposit` recovers the original principal and card version from the opening event and historical card state. It never sizes an old job from today's updated card. It tops up wallet balances to the principal, original reference fee and PC target; a shared principal/fee token is combined before subtracting the balance. `providerFee` explicitly overrides the fee reserve and `pcAmount` overrides the PC target. The default PC target is one per-call card gas cap, not a promise that all job execution is covered. This operation leaves the kernel escrow Open and makes no destination approval calls: those are pinned permissions granted to the agent in v2.
+
+The default source is the connected signer's Push identity, even on an instance configured to execute through an AGW. `funding: 'origin'` explicitly uses normal inbound `funds` transfers for registered assets from the connected origin chain; required tokens without such a route fail before any leg is sent. PC still comes from the signer's Push holdings. The underlying gateway's normal route, liquidity, balance and fee checks apply.
+
+Steps are separate transactions. `DEPOSIT_INCOMPLETE` retains `details.txs`, any `details.pending` broadcast hash and chain, and the original cause. The same client remembers submitted steps; pass `resume: previousSteps` when continuing with another client. After restarting, rehydrate recorded hashes with `universal.trackTransaction(hash, { chain })` before passing their transaction responses. Pending receipts must settle before another transfer, and a confirmed transfer whose target balance has since fallen requires manual review. Concurrent deposits on the same client are rejected. Coordinate other clients and avoid running the agent during deposits. Deposits require an Open, unexpired job and an enabled permission with no recorded asset spend. When archive state is unavailable or updates share the opening block, the SDK recovers the version from registration/update events and canonical transaction input, checking emitted content hashes, fee and immutable card identity. If neither source can authenticate it, `HISTORY_UNAVAILABLE` stops the operation.
+
+```ts
+async function priceAndFund(provider: PushChain, owner: PushChain, jobId: bigint) {
+  // First deposit the payment token, principal and PC appropriate to the job.
+  await (await provider.job.setBudget(jobId, 5_000_000n)).wait();
+  // Explicitly pass the price the client reviewed; never silently accept a re-quote.
+  return owner.job.fund(jobId, { expectedBudget: 5_000_000n });
+}
+
+async function trackJob(client: PushChain, provider: PushChain, jobId: bigint) {
+  const stop = client.job.watch(jobId, event => console.log(event.kind));
+  const job = await client.job.status(jobId);
+  await (await provider.job.submit(jobId, { deliverable: 'ipfs://deliverable' })).wait();
+  stop();
+  return job;
+}
+```
+
+The kernel currently accepts pUSDC (`USDC.eth`, 6 decimals) only; explicit mismatching payment tokens are rejected. A card's providerFee is a reference price. For an unchanged marketplace card version, omitted expectedBudget uses that reference; plain jobs or changed card versions need an explicit reviewed amount. A zero-price job is valid.
+
+For AGW clients, fund verifies ownership, rule/provider identity and expiry, then batches any necessary ERC20 allowance change and escrow funding through the owner door. This allowance is distinct from the AGW's automatic gateway allowance. Plain-client allowance/fund batching requires a supported atomic signer transport; the SDK does not silently fall back to sequential acceptance.
+
+`status` reads the kernel and hook, retains binary description bytes, decodes supported v2 JobSpecs, and recovers deliverable from submission logs. `evaluation.available` is false for this manual/unverified evaluator profile; frozen/baseline/verdict data is not fabricated. Plain text descriptions may have no decoded JobSpec. `list` can filter client/provider/status; `watch` polls bounded event ranges, reports read errors, supports a starting block and returns a stop function. It is not an indexer or a reorg-finality service.
+
+```ts
+function resumeJobEvents(client: PushChain, jobId: bigint, cursor?: JobWatchCursor) {
+  return client.job.watch(jobId, event => {
+    // Persist cursor only after your application handles the event.
+    if (event.kind !== 'Error') console.log(event.kind, event.cursor);
+  }, cursor ? { cursor } : { pollIntervalMs: 3000 });
+}
+```
+
+Each delivered event has an exact block/log cursor. Resuming excludes already delivered logs within the same block; duplicate RPC logs are delivered once. RPC failures retry the same range, consumer callback errors do not rewind delivery, and unsubscribe suppresses pending callbacks. A changed canonical cursor emits `WATCH_REORG` and stops; reload status and choose a reviewed restart block.
+
+```ts
+async function stopOpenJob(owner: PushChain, jobId: bigint) {
+  // For marketplace AGWs, one owner batch rejects the Open job and revokes its recorded grant.
+  return owner.job.cancel(jobId);
+}
+
+function marketplaceErrorText(error: unknown): string {
+  return error instanceof MarketError ? error.userMessage : 'Check transaction activity before retrying.';
+}
+```
+
+Cancellation is client-side Open-job rejection. It does not withdraw deposited wallet balances; those remain under the owner's existing transfer authority. A plain job has no marketplace grant to infer. Other terminal paths do not imply AGW permission revocation. `claimRefund` respects expiry/grace and remains available while the kernel is paused; a third party may trigger it, with funds returned to the recorded client.
+
+Plain jobs can use `job.create` with provider/evaluator/hook/expiry/paymentToken plus either binary jobSpec or text description. The kernel's Solidity string slot can carry binary JobSpec bytes; the SDK preserves them and retains the original createJob selector.
+
+## Paid criteria preview
+
+```ts
+async function previewCriteria(client: PushChain, template: ReturnType<typeof authorCard>['jobSpecTemplate'], wallet: Address) {
+  const options: PreviewJobSpecOptions = {
+    client, wallet, principal: 100_000_000n,
+    maxTotalFee: 10n ** 16n,
+    advanced: { timeout: 120_000 },
+  };
+  return PushChain.utils.job.previewJobSpec(template, options);
+}
+```
+
+This prepares every raw read, checks the total callback/protocol fee cap, then executes through the existing universal-read registry (or an explicit `callback`). Native transaction gas is separate from `maxTotalFee`. A real SDK client derives destination CEAs for template wallet holes using its configured routes; `accounts` supplies explicit destination addresses when needed. An AGW's Push address is never substituted for its destination account.
+
+The result includes raw values, decoded fields, request responses and fees. `pass` and each check are `true`, `false`, or `null` (unknown). NUMBER and PERCENTAGE require an explicit per-read `baseline`; missing baselines, zero percentage denominators and unavailable reads stay unknown. A preview is an observation, not an automatic evaluator verdict or proof that a job is complete. Raw EVM calls are also available as `universal.read(target, { chain, callData })` and return consensus bytes.
+
+`PREVIEW_INCOMPLETE` retains all known request IDs and transaction hashes. Track uncertain submissions before retrying. Pass `resume: requestIds` (one per read, in order) to finish without new requests or payment. Resume checks each on-chain destination, call, pin and confirmation requirement before evaluating; unrelated reads are refused. `fees.newlyPaid` is zero on recovery, while `fees.paid` retains the original request deposits. A zero `maxTotalFee` is valid for recovery.
+
+## Explicit placeholders
+
+- `job.verify`, baseline/prefund/retry integration: no compatible automatic evaluator is configured. A different linked evaluator source has a different wire and enum values.
+- Replacement JobSpecs, non-NONE marketplace criteria, recurring jobs and relay are unavailable.
+
+Unsupported paths throw before signing/sending. They do not return successful dummy results. Keep message, code, details and cause for diagnostics.
+
+## E2E validation
+
+From the repository root:
+
+```sh
+# Real deployed stack on an isolated Anvil fork; no private keys or public-chain writes.
+node node_modules/jest/bin/jest.js --config packages/core/jest.marketplace-local.config.ts --runInBand
+# Read-only live Donut acceptance.
+node node_modules/ts-node/dist/bin.js --compiler-options '{"module":"commonjs"}' packages/core/__e2e__/ci/run.ts --group marketplace
+# Explicit funded smoke, using packages/core/.env: fresh provider/card/owner/wallet, then cancel/revoke/deactivate.
+node node_modules/ts-node/dist/bin.js --compiler-options '{"module":"commonjs"}' packages/core/__e2e__/ci/run.ts --group marketplace-live
+# Owned-token acceptance: actual deposits, native/AGW escrow and payouts, BSC-origin principal bridging.
+node node_modules/ts-node/dist/bin.js --compiler-options '{"module":"commonjs"}' packages/core/__e2e__/ci/run.ts --group marketplace-funding
+```
+
+Marketplace groups stay out of the runner's default `all`. The basic live group spends bounded PC for gas/test wallets and read callbacks. The separate funding group uses owned test assets: 0.01 pUSDC per paid job, 0.01 USDT of bridged principal and up to 0.01 pBNB for source-gas setup. It cancels/revokes market jobs, completes plain jobs with a fresh controlled manual evaluator, returns principal/reserve/payout tokens and deactivates its card. The deployed marketplace evaluator remains unchanged. Pause/refund and signature variants use the local fork. The fork's UEA signature test uses a native submitter because Anvil has no Cosmos transport; live cases exercise actual external-owner transport. No automated verdict is implied by those results. Signature fixtures compile from repo-owned source at harness startup; Foundry and cached solc 0.8.26 are prerequisites.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushchain/core",
-  "version": "6.0.27-alpha.3",
+  "version": "6.0.27-alpha.4",
   "homepage": "https://push.org",
   "keywords": [
     "pushchain",
@@ -73,6 +73,7 @@
     "src/**/*.json",
     "README.md",
     "AGW.md",
+    "MARKETPLACE.md",
     "CHANGELOG.md"
   ],
   "devDependencies": {

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

@@ -33,78 +33,83 @@ function prepareRules(rules, ctx) {
         throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'rules must be an array');
     }
     return rules.map((rule, i) => {
-        if (!rule || typeof rule !== 'object') {
-            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `rules[${i}] is not an object`);
-        }
-        if (!(0, viem_1.isAddress)(rule.agent, { strict: false }) ||
-            /^0x0{40}$/i.test(rule.agent)) {
-            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `rules[${i}].agent must be a non-zero Push address`);
-        }
-        const agent = (0, viem_1.getAddress)(rule.agent);
-        if (ctx.owner && agent === (0, viem_1.getAddress)(ctx.owner)) {
-            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.AGENT_IS_OWNER, `rules[${i}].agent is the wallet owner; the owner uses the owner door`);
-        }
-        const chainNamespace = ruleChain(rule, ctx.pushChainNamespace);
-        if (isUniversalRule(rule) &&
-            rule.chainNamespace === ctx.pushChainNamespace) {
-            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `rules[${i}] names the connected Push chain; omit chainNamespace for a native rule`);
-        }
-        if ('ref' in rule) {
-            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'InternalRule ref is not supported; remove it from the input');
-        }
-        if (isSolanaRule(rule)) {
-            (0, capabilities_1.requireCapability)(ctx.capabilities, capabilities_1.AgenticCapability.UNIVERSAL_SVM_RULES);
-            const terms = ctx.svm?.get(rule);
-            if (!terms || !ctx.gateway)
-                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'SVM rules require resolved wallet context and validated instruction layouts');
-            return {
-                rule,
-                agent,
-                chainNamespace,
-                svmTerms: terms,
-                session: (0, session_1.buildSession)({
-                    validator: ctx.validator,
-                    rulesPolicy: ctx.rulesPolicy,
+        try {
+            if (!rule || typeof rule !== 'object') {
+                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `rules[${i}] is not an object`);
+            }
+            if (!(0, viem_1.isAddress)(rule.agent, { strict: false }) ||
+                /^0x0{40}$/i.test(rule.agent)) {
+                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `rules[${i}].agent must be a non-zero Push address`);
+            }
+            const agent = (0, viem_1.getAddress)(rule.agent);
+            if (ctx.owner && agent === (0, viem_1.getAddress)(ctx.owner)) {
+                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.AGENT_IS_OWNER, `rules[${i}].agent is the wallet owner; the owner uses the owner door`);
+            }
+            const chainNamespace = ruleChain(rule, ctx.pushChainNamespace);
+            if (isUniversalRule(rule) &&
+                rule.chainNamespace === ctx.pushChainNamespace) {
+                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `rules[${i}] names the connected Push chain; omit chainNamespace for a native rule`);
+            }
+            if ('ref' in rule) {
+                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'InternalRule ref is not supported; remove it from the input');
+            }
+            if (isSolanaRule(rule)) {
+                (0, capabilities_1.requireCapability)(ctx.capabilities, capabilities_1.AgenticCapability.UNIVERSAL_SVM_RULES);
+                const terms = ctx.svm?.get(rule);
+                if (!terms || !ctx.gateway)
+                    throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'SVM rules require resolved wallet context and validated instruction layouts');
+                return {
+                    rule,
                     agent,
-                    actions: [
-                        {
-                            target: ctx.gateway,
-                            selector: v6_1.SEND_OUTBOUND_SELECTOR,
-                            initData: (0, session_1.encodeEnvelope)(chainNamespace, (0, svm_terms_1.encodeSvmTerms)(terms, ctx.nowSeconds)),
-                        },
-                    ],
-                }),
-            };
+                    chainNamespace,
+                    svmTerms: terms,
+                    session: (0, session_1.buildSession)({
+                        validator: ctx.validator,
+                        rulesPolicy: ctx.rulesPolicy,
+                        agent,
+                        actions: [
+                            {
+                                target: ctx.gateway,
+                                selector: v6_1.SEND_OUTBOUND_SELECTOR,
+                                initData: (0, session_1.encodeEnvelope)(chainNamespace, (0, svm_terms_1.encodeSvmTerms)(terms, ctx.nowSeconds)),
+                            },
+                        ],
+                    }),
+                };
+            }
+            if (isUniversalRule(rule)) {
+                return (0, universal_1.encodeUniversalRule)(rule, ctx);
+            }
+            (0, capabilities_1.requireCapability)(ctx.capabilities, capabilities_1.AgenticCapability.NATIVE_RULES);
+            const actions = (0, native_1.nativeRuleToActionTerms)(rule, ctx).map((a) => a.terms);
+            const forbidden = [
+                '0x0000000000000000000000000000000000000000',
+                '0x0000000000000000000000000000000000000001',
+                ...(ctx.forbiddenTargets ?? []),
+            ].map((a) => a.toLowerCase());
+            actions.forEach((terms, j) => {
+                if (forbidden.includes(terms.target.toLowerCase())) {
+                    const where = actions.length > 1 ? `rules[${i}].actions[${j}]` : `rules[${i}]`;
+                    throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `${where}.target ${terms.target} is a wallet-infrastructure address the contracts refuse as a native target`);
+                }
+            });
+            // One rule, one rule ID: every action is a separate (target, selector)
+            // entry of the same session, each with its own stored terms.
+            const session = (0, session_1.buildSession)({
+                validator: ctx.validator,
+                agent,
+                rulesPolicy: ctx.rulesPolicy,
+                actions: actions.map((terms) => ({
+                    target: terms.target,
+                    selector: terms.selector,
+                    initData: (0, session_1.encodeEnvelope)(chainNamespace, (0, native_1.encodeNativeTerms)(terms)),
+                })),
+            });
+            return { rule, agent, chainNamespace, session, nativeTerms: actions };
         }
-        if (isUniversalRule(rule)) {
-            return (0, universal_1.encodeUniversalRule)(rule, ctx);
+        catch (error) {
+            throw (0, errors_1.ruleErrorContext)(error, i, rule?.chainNamespace);
         }
-        (0, capabilities_1.requireCapability)(ctx.capabilities, capabilities_1.AgenticCapability.NATIVE_RULES);
-        const actions = (0, native_1.nativeRuleToActionTerms)(rule, ctx).map((a) => a.terms);
-        const forbidden = [
-            '0x0000000000000000000000000000000000000000',
-            '0x0000000000000000000000000000000000000001',
-            ...(ctx.forbiddenTargets ?? []),
-        ].map((a) => a.toLowerCase());
-        actions.forEach((terms, j) => {
-            if (forbidden.includes(terms.target.toLowerCase())) {
-                const where = actions.length > 1 ? `rules[${i}].actions[${j}]` : `rules[${i}]`;
-                throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `${where}.target ${terms.target} is a wallet-infrastructure address the contracts refuse as a native target`);
-            }
-        });
-        // One rule, one rule ID: every action is a separate (target, selector)
-        // entry of the same session, each with its own stored terms.
-        const session = (0, session_1.buildSession)({
-            validator: ctx.validator,
-            agent,
-            rulesPolicy: ctx.rulesPolicy,
-            actions: actions.map((terms) => ({
-                target: terms.target,
-                selector: terms.selector,
-                initData: (0, session_1.encodeEnvelope)(chainNamespace, (0, native_1.encodeNativeTerms)(terms)),
-            })),
-        });
-        return { rule, agent, chainNamespace, session, nativeTerms: actions };
     });
 }
 //# sourceMappingURL=rules.js.map

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

@@ -61,11 +61,16 @@ function validateUniversalRuleShape(rule, nowSeconds) {
             (0, pins_1.validatePins)(call.pins ?? []);
         }
         catch (error) {
-            throw invalid(error.message);
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, error.message, {
+                cause: error,
+                details: {
+                    callIndex: i,
+                    field: `allowedCalls[${i}].pins`,
+                    chainNamespace: rule.chainNamespace,
+                },
+            });
         }
         pinCount += call.pins?.length ?? 0;
-        if (pinCount > 32)
-            throw invalid('at most 32 pins across all allowed calls');
         const key = `${call.target.toLowerCase()}:${parsed.selector}`;
         const restricted = !!call.pins?.length ||
             call.beneficiary !== undefined ||
@@ -74,11 +79,18 @@ function validateUniversalRuleShape(rule, nowSeconds) {
             throw invalid('an unpinned alternative would bypass restrictions for this target/selector');
         seen.set(key, restricted);
     });
+    if (pinCount > 32)
+        throw (0, errors_1.ruleConstraintLimit)(pinCount, rule.allowedCalls.length, rule.chainNamespace);
     const tokens = new Set();
     rule.assets.forEach((a, i) => {
         const address = typeof a.token === 'string' ? a.token : a.token?.address;
         if (typeof address !== 'string')
             throw invalid(`assets[${i}].token is missing an address`);
+        if (!(0, viem_1.isAddress)(address, { strict: false }))
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'The selected token has an invalid address.', {
+                userMessage: 'The selected token has an invalid address. Select the token again.',
+                details: { assetIndex: i, field: `assets[${i}].token` },
+            });
         const key = address.toLowerCase();
         if (tokens.has(key))
             throw invalid(`assets[${i}] duplicates an earlier token`);

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/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;