@allorc/a423-sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.3.0
+
+- Add optional ethers-based `/escrow` entry point and a compiled ERC-20 reference contract.
+- Enforce EIP-712 worker consent, exact custody amounts, one immutable submission, verifier approval before release, expiry refunds, disputes, arbitrated splits and agreed timeout allocation.
+- Add pre-broadcast signed-transaction journaling, coordinated nonce allocation, canonical receipt/term/event validation and external transaction evidence adoption.
+- Ship escrow-specific transitions and documentation. Contract is experimental, unaudited and not deployed by the package.
+- Add local-EVM lifecycle, failure, recovery and confirmation tests.
+
 ## 0.2.0
 
 - Add opt-in `@allorc/a423-sdk/workflow` exports: workflow engine, Next.js-compatible handler, typed HTTP client and canonical agreement hashing.

package/ESCROW.md

@@ -0,0 +1,161 @@
+# Reference on-chain escrow (0.3.0)
+
+This opt-in module implements a real ERC-20 escrow path. The generic workflow remains provider-independent. It includes Solidity source, reproducibly compiled ABI/bytecode, an ethers v6 adapter and local-EVM tests. It is experimental and has not received an independent security audit; deploy to a local chain/testnet for evaluation. No contract is deployed automatically and no funds move merely by installing the package.
+
+## Installation and deployment
+
+```sh
+npm install @allorc/a423-sdk@0.3.0 ethers@^6.15.0
+```
+
+```ts
+import { ContractFactory } from 'ethers';
+import { ESCROW_ABI, ESCROW_BYTECODE } from '@allorc/a423-sdk/escrow';
+const contract = await new ContractFactory(ESCROW_ABI, ESCROW_BYTECODE, deploymentSigner)
+  .deploy(standardTokenAddress);
+await contract.waitForDeployment();
+```
+
+Deployment is an explicit, separately authorised transaction. Each deployment supports one immutable token. There are no owner withdrawals, token replacements, upgrades or pause switches. Standard ERC-20 transfers must preserve exact sender/recipient amounts. Fee-on-transfer/rebasing/blacklisting/pausable tokens are unsupported; an issuer blocking transfers can defeat timeout liveness. Arbitrary token code cannot be made safe by SDK validation. Use a reviewed token and verify the deployed contract bytecode/configuration before trusting it. Forced token transfers do not create job credits; there is no recovery sweep for unsolicited deposits.
+
+## Exact agreement recipe
+
+Include every application-specific condition in JSON terms. Include this `escrow` object with these field names. IDs, application identities and wallet addresses are separate concepts; use a trusted identity-to-wallet registry.
+
+```js
+const terms = {
+  task: { description: 'Your task', acceptance: { /* your criteria */ } },
+  escrow: {
+    chain_id: '31337',
+    contract: escrowAddress,
+    token: tokenAddress,
+    amount: '100', // raw integer token units, NOT necessarily 100 displayed tokens
+    payer: payerAddress,
+    worker: workerAddress,
+    verifier: verifierAddress,
+    arbitrator: arbitratorAddress,
+    work_deadline: workDeadlineSeconds,
+    review_deadline: reviewDeadlineSeconds,
+    resolution_deadline: resolutionDeadlineSeconds,
+    timeout_worker_bps: 2500, // agreed fallback: 25% worker, 75% payer
+  },
+};
+```
+
+All deadlines are absolute Unix seconds and strictly increasing. The work deadline must be in the future at funding. `amount` is a positive uint256 decimal string. The SHA-256 hash of the entire canonical terms object is stored on-chain; it includes payment rules and the task criteria. The Solidity EIP-712 terms digest is a separate encoding for worker consent. `jobId` is SHA-256 of UTF-8 `a423:escrow:v1:` plus the application job ID. One job ID may only be funded once per deployed contract.
+
+The arbitrator must differ from payer and worker. The verifier may be the payer: this is a trusted verifier policy, not trustless proof of output quality. The reference contract supports EOA EIP-712 worker signatures using ECDSA; ERC-1271 smart account worker signatures are not implemented. Use another adapter/contract for that capability.
+
+## Connect Next.js and the workflow
+
+```ts
+import { createWorkflow, createWorkflowHandler } from '@allorc/a423-sdk/workflow';
+import { createEscrowAdapters, escrowTransitions } from '@allorc/a423-sdk/escrow';
+
+const adapters = createEscrowAdapters({
+  provider,
+  chainId,
+  contractAddress: escrowAddress,
+  tokenAddress,
+  confirmations: requiredConfirmations,
+  transactions: durableTransactionStore,
+  signerFor: async actor => signerRegistry.getSigner(actor),
+  addressFor: async actor => signerRegistry.getAddress(actor),
+  validateArtifact: async ({ job, resultHash }) => {
+    // Fetch exact bytes, check digest and evaluate accepted criteria.
+    // Return true only after all checks pass.
+    return artifactService.validate(job, resultHash);
+  },
+});
+const workflow = createWorkflow({
+  store: durableWorkflowStore,
+  adapters: { ...adapters, expire: applicationExpiryAdapter },
+  transitions: escrowTransitions,
+  validateTerms: applicationTermsValidator,
+  authorize: applicationPolicy,
+});
+const handler = createWorkflowHandler({ workflow, authenticate: authenticateRequest });
+// In app/api/a423/[...path]/route.ts:
+export const runtime = 'nodejs';
+export { handler as GET, handler as POST };
+```
+
+All application services in this example must be supplied. Configure explicit `arbitrator` alongside requester, worker and verifier in job participants. `addressFor` must map all four authenticated IDs to the agreed addresses. `signerFor` must reject unknown actors and apply spending/delegation approvals. The adapter uses offline `signTransaction`, so custodial/local/KMS signers must support it. It does not prompt a browser wallet or bypass human approval. Do not use keys in client React code.
+
+## Acceptance is not locking
+
+1. Create a job, quote terms, and record both actors accepting the same revision/hash using the workflow API.
+2. Obtain a worker signature over the final on-chain terms:
+
+   ```ts
+   import { workerConsent } from '@allorc/a423-sdk/escrow';
+   const consent = workerConsent(acceptedJob, { chainId, contractAddress: escrowAddress, tokenAddress });
+   const signature = await workerSigner.signTypedData(consent.domain, consent.types, consent.value);
+   ```
+
+   The worker should inspect the terms it signs. EIP-712 binds consent to chain, contract, job, parties, amount, deadlines, timeout allocation and the whole agreement hash. The payer authorises the actual funding transaction.
+3. Call `workflow.act(id, 'fund', { worker_signature: signature }, { actor: requesterId, idempotencyKey: 'fund_1' })`.
+4. The adapter grants token allowance if needed (zero reset first when necessary), then calls the reference contract's `fund`. **Approval alone does not lock money.** The contract checks the worker signature, transfers the exact amount into custody, stores all terms and emits `Funded` atomically.
+5. Pending results keep the workflow `accepted` with a `pending` operation. Display “funding pending”, not “locked”. Retry the same action/key to progress approval/funding. Only successful, sufficiently confirmed, canonically included receipts plus matching event and on-chain terms produce `funded`.
+6. Start work via `start`; it rereads the actual escrow and deadline. The SDK does not run the worker. Dispatch through a durable queue only after this gate succeeds.
+
+To automatically initiate funding after the second acceptance, orchestrate the above from your application after obtaining payer authorisation. Off-chain acceptance cannot force a wallet to sign. Do not change the UI to “funded” at acceptance time.
+
+## Full lifecycle and exact inputs
+
+| Action | Input | On-chain restriction / result |
+|---|---|---|
+| fund | `{ worker_signature }` | Payer only; valid worker consent; exact token transfer; new job ID |
+| start | `{}` | Adapter checks all terms, funded state and unexpired work deadline; no transaction |
+| submit | `{ result_hash: '0x…64 hex chars' }` | Worker only; before work deadline; nonzero artifact commitment |
+| verify | `{}` | Callback validates actual artifact; verifier transaction must match submitted digest and review deadline |
+| release | `{}` | Verifier only, verified state, before resolution deadline; full worker payout |
+| refund | `{}` | Anyone on-chain after work deadline, only if no submission; full payer refund |
+| dispute | `{ reason_hash: '0x…64 hex chars' }` | Party only, submitted/verified and before resolution deadline; blocks ordinary release |
+| resolve | `{ worker_amount: '40' }` | Arbitrator only, disputed, by resolution deadline; remainder refunded to payer |
+| timeout | `{}` | Funded/running: expiry refund. Submitted/verified/disputed: agreed fallback allocation after resolution deadline |
+
+`escrowTransitions` makes dispute an actual on-chain operation, gives resolve to the arbitrator and adds timeout. Resolution and timeout end in workflow `settled`; inspect evidence `worker_paid`, `amount` and contract state to distinguish paid/refunded/split. Contract settlement states: 5 Paid, 6 Refunded, 7 Split. Event reasons: 0 release, 1 expired-unsubmitted refund, 2 arbitration, 3 submitted timeout.
+
+A verifier can approve and release before a dispute is opened; there is no guaranteed challenge window or objective quality oracle. Rejected artifact verification leaves the workflow submitted and clears pending, allowing a dispute. The contract enforces that submission and verifier approval exist; the application verifier still judges task quality. For resubmission/milestones, use a separate contract policy: the reference contract permits one immutable submission and one settlement, not partial milestone releases. Arbitration can split the one escrow.
+
+Cancellation and quote expiry before funding remain workflow/application policies and move no tokens. The reference module does not supply a scheduler or a governor registry.
+
+## Recovery and journal requirements
+
+The workflow job is written before any effect. The transaction journal separately stores signed raw transactions **before broadcasting**, including hash, destination, calldata and signer. Retries reuse the winning journal record and rebroadcast the same bytes; they do not create another payment or nonce. Do not expose raw signed transactions in public workflow metadata/receipts. Treat the journal as protected operational storage.
+
+Implement `TransactionStore`:
+
+- `get(id)`: retrieve a durable record.
+- `create(id, record)`: atomic insert-if-absent; return boolean. Never overwrite an existing signed transaction.
+- `reserveNonce(scope, minimum, operationId)`: transactionally allocate per-chain/address nonces, at least the RPC pending nonce; the same operation must always retrieve its original reservation. Every process using the account must coordinate through this allocator. External wallet activity requires an explicit operational policy.
+
+`createMemoryTransactionStore()` is only for tests. Production needs a real database implementation. A crash after nonce reservation but before journaling must resume that operation to fill its reserved nonce; later transactions may remain blocked behind it. No automatic fee replacement/cancellation is included. A genuinely stuck transaction requires deliberate recovery with the same nonce and updated journal lineage; do not blindly assign a new nonce. Prefer dedicated signer accounts to uncontrolled mixed wallet usage.
+
+`reconcile` only observes existing journal entries and never signs/broadcasts. If an approval is confirmed but the funding transaction has not yet been created, reconcile returns pending; retry the original fund action/key to authorise progression. After a signed transaction is journaled but not broadcast, execute retries rebroadcast the identical bytes. After broadcast/mining but before the workflow write, reconcile verifies and adopts its evidence. Explicit `rejected` results permit a deliberate new attempt with a new action key; an unknown network outcome stays pending or throws with the pending record retained.
+
+For externally submitted transactions, pass `transaction_hash` in the action input from the beginning (in addition to the normal fields). The adapter observes it without broadcasting and checks the configured contract, exact agreement, action event and allocation. This supports recording permissionless refunds/timeouts submitted by a keeper or another account. Use the correct workflow action; it cannot adopt arbitrary unrelated transfers. Supplying an incorrect hash fails closed and leaves pending for investigation; do not change persisted input to hide errors.
+
+RPC chain ID and immutable token are checked; event emitter, job ID, agreement hash, all stored terms, event amounts and results are verified. Evidence contains transaction/block hash and required confirmation depth. Readers need historical state access for the receipt block. The adapter checks current canonical inclusion at observation time; confirmations are a configurable risk policy, not an absolute finality guarantee. There is no continuous reorg watcher or automatic rollback of already completed workflow states. A production chain integration must monitor disappearing evidence and suspend/reconcile affected work explicitly. Chain outages preserve uncertainty and cannot be repaired by SDK code.
+
+No timeout is automatic: a keeper or participant must submit a transaction, and the chain must process it. Deadlines provide an eligible escape path under the agreed allocation; they do not guarantee execution during censorship, chain failure or broken token transfers.
+
+## Verification and receipts
+
+Artifact input is a bytes32 commitment. The application chooses the hashing scheme and storage format; for SHA-256, hash the exact delivered bytes, not a mutable URL. The verifier callback must check both bytes and accepted criteria. There is no generic LLM quality proof.
+
+Funding, submission, verification and settlement effects return JSON-safe chain evidence. Workflow receipts retain those observations; they are not live PDFs or perpetual assertions of finality. Fresh PDF/evidence services should recheck canonical receipts and commitments at read time and format raw units with the actual token decimals.
+
+## Development checks
+
+From the source repository:
+
+```sh
+npm ci --ignore-scripts
+npm run build:escrow
+npm test
+npm pack --dry-run --ignore-scripts
+```
+
+The local-EVM suite exercises custody, consent binding, permissions, submission-before-release, expiry refund, arbitration splits, timeout allocation, unsupported token rejection, recovery, external evidence adoption and confirmation depth. Solidity compiler and OpenZeppelin versions are pinned in dev dependencies; ethers is an optional peer used only by `/escrow`. Core/workflow do not load it.

package/INTEGRATION.md

@@ -3,11 +3,17 @@
 Install after the maintainer publishes:
 
 ```sh
-npm install @allorc/a423-sdk@0.2.0
+npm install @allorc/a423-sdk@0.3.0
 ```
 
 For testing before publication, install the maintainer's `npm pack` tarball instead. Do not silently install 0.1 and assume the workflow entry point exists.
 
+## Reference escrow option
+
+Read `ESCROW.md` first. The package now includes a concrete `/escrow` adapter plus `ESCROW_ABI`/`ESCROW_BYTECODE` and Solidity source. This contract differs from the old MVP contract: it requires EIP-712 worker consent, verifier approval, explicit arbitration and timeout terms. Do not point this adapter at the old contract. Use a fresh local/testnet deployment for evaluation or write a separately tested legacy adapter.
+
+Use `createEscrowAdapters` and `escrowTransitions` when testing the reference path. Implement both the durable workflow store and protected transaction journal with atomic nonce reservation, map all four roles to trusted wallets, and supply artifact validation. Retain the reference lifecycle tests below. Deployment or real fund movement requires separate authorisation.
+
 ## Task
 
 Integrate the opt-in `@allorc/a423-sdk/workflow` API into the existing MVP. Inspect the installed README, declarations and exports first. Preserve the existing app until a complete equivalent journey passes. Do not introduce demo keys, positional signer lookup, unknown-agent fallback, or authentication based only on x-agent-id. Do not deploy or move real funds as part of integration tests.

package/NOTICE

@@ -0,0 +1,24 @@
+The compiled A423Escrow artifact incorporates OpenZeppelin Contracts 5.4.0.
+
+The MIT License (MIT)
+
+Copyright (c) 2016-2025 Zeppelin Group Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
+# Reference escrow in 0.3.0
+
+The optional `@allorc/a423-sdk/escrow` module now provides a deployable ERC-20 reference contract and matching ethers adapter. It implements actual on-chain custody, worker-signed funding consent, submission and verifier approval before release, expiry refunds, disputes, arbitration splits and an agreed deadline fallback. It does not deploy or move funds automatically.
+
+See [ESCROW.md](./ESCROW.md) for exact terms, Next.js setup, wallet authorisation, transaction journal requirements, lifecycle inputs, recovery and limitations. Use `escrowTransitions` with this adapter: the default generic dispute transition alone does not write to the chain. Core/workflow APIs remain available without ethers.
+
 # Configurable workflows in 0.2.0
 
 The new `@allorc/a423-sdk/workflow` entry point provides middleware for agent job lifecycles. It supports different task types and payment systems through application-supplied policies and adapters. It does not assume a particular blockchain, token, wallet, artifact format, database or AI framework. This is experimental software with a reference lifecycle; it does not promise every possible business workflow.

package/SECURITY.md

@@ -7,3 +7,8 @@ Authentication must be supplied. Never treat a public ID, public ingredients or
 Settlement adapters must durably deduplicate the SDK's stable key across retries and concurrent calls. This SDK does not fund escrow, establish mandates, custody keys or guarantee exactly-once payments. Validate recipient, amount, permission and provider status independently. Completion without an adapter explicitly means no settlement is configured.
 
 Do not include tokens, private keys, customer data or live exploit details in public reports. Use a private repository reporting channel when configured; maintainers should establish one before requesting sensitive reports. Never log credentials. No private security contact is invented by this initial package.
+
+
+## Reference escrow
+
+The 0.3 reference contract is experimental and not independently audited. Its trust model includes the chosen verifier/arbitrator and the timeout allocation both parties accepted. EOA signatures only; standard exact-transfer tokens only. Read ESCROW.md before deployment. Never expose raw signed transaction journals, use memory stores for production custody, or share signer nonces across uncoordinated processes. Confirmation policy is not continuous reorg monitoring.

package/contracts/A423Escrow.sol

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+import {EIP712} from "@openzeppelin/contracts/utils/cryptography/EIP712.sol";
+import {ECDSA} from "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
+
+/// @notice Experimental reference escrow for standard, non-rebasing ERC20 tokens.
+/// No admin withdrawals/upgrades. Arbitration and timeout allocation are agreed before funding.
+contract A423Escrow is ReentrancyGuard, EIP712 {
+    using SafeERC20 for IERC20;
+    enum State { None, Funded, Submitted, Verified, Disputed, Paid, Refunded, Split }
+    struct Terms {
+        bytes32 jobId;
+        address payer;
+        address worker;
+        address verifier;
+        address arbitrator;
+        uint256 amount;
+        uint64 workDeadline;
+        uint64 reviewDeadline;
+        uint64 resolutionDeadline;
+        uint16 timeoutWorkerBps;
+        bytes32 agreementHash;
+    }
+    struct Job { Terms terms; State state; bytes32 resultHash; uint256 workerPaid; }
+    IERC20 public immutable token;
+    mapping(bytes32 => Job) private jobs;
+    bytes32 public constant TERMS_TYPEHASH = keccak256("Terms(bytes32 jobId,address payer,address worker,address verifier,address arbitrator,uint256 amount,uint64 workDeadline,uint64 reviewDeadline,uint64 resolutionDeadline,uint16 timeoutWorkerBps,bytes32 agreementHash)");
+    event Funded(bytes32 indexed jobId, bytes32 indexed agreementHash, address indexed payer, address worker, uint256 amount);
+    event Submitted(bytes32 indexed jobId, bytes32 resultHash);
+    event Verified(bytes32 indexed jobId, bytes32 resultHash);
+    event Disputed(bytes32 indexed jobId, bytes32 reasonHash);
+    event Settled(bytes32 indexed jobId, uint256 workerAmount, uint256 payerAmount, uint8 reason);
+    error InvalidTerms();
+    error WrongState();
+    error Unauthorized();
+    error Deadline();
+    error TokenAmountMismatch();
+
+    constructor(address token_) EIP712("A423Escrow", "1") {
+        if (token_.code.length == 0) revert InvalidTerms();
+        token = IERC20(token_);
+    }
+    function termsDigest(Terms calldata t) public view returns (bytes32) {
+        return _hashTypedDataV4(keccak256(abi.encode(TERMS_TYPEHASH, t)));
+    }
+    function getJob(bytes32 id) external view returns (Job memory) { return jobs[id]; }
+    /// Payer transaction plus worker EIP712 signature establish bilateral on-chain consent.
+    function fund(Terms calldata t, bytes calldata workerSignature) external nonReentrant {
+        if (msg.sender != t.payer) revert Unauthorized();
+        if (jobs[t.jobId].state != State.None) revert WrongState();
+        if (t.jobId == bytes32(0) || t.agreementHash == bytes32(0) || t.amount == 0 || t.worker == address(0) || t.worker == t.payer || t.verifier == address(0) || t.arbitrator == address(0) || t.arbitrator == t.payer || t.arbitrator == t.worker || t.timeoutWorkerBps > 10000) revert InvalidTerms();
+        if (t.workDeadline <= block.timestamp || t.reviewDeadline <= t.workDeadline || t.resolutionDeadline <= t.reviewDeadline) revert InvalidTerms();
+        if (ECDSA.recover(termsDigest(t), workerSignature) != t.worker) revert Unauthorized();
+        jobs[t.jobId] = Job(t, State.Funded, bytes32(0), 0);
+        uint256 beforeBalance = token.balanceOf(address(this));
+        token.safeTransferFrom(t.payer, address(this), t.amount);
+        if (token.balanceOf(address(this)) != beforeBalance + t.amount) revert TokenAmountMismatch();
+        emit Funded(t.jobId, t.agreementHash, t.payer, t.worker, t.amount);
+    }
+    function submit(bytes32 id, bytes32 resultHash) external {
+        Job storage j = jobs[id];
+        if (msg.sender != j.terms.worker) revert Unauthorized();
+        if (j.state != State.Funded) revert WrongState();
+        if (block.timestamp > j.terms.workDeadline) revert Deadline();
+        if (resultHash == bytes32(0)) revert InvalidTerms();
+        j.resultHash = resultHash; j.state = State.Submitted;
+        emit Submitted(id, resultHash);
+    }
+    function verify(bytes32 id, bytes32 resultHash) external {
+        Job storage j = jobs[id];
+        if (msg.sender != j.terms.verifier) revert Unauthorized();
+        if (j.state != State.Submitted) revert WrongState();
+        if (block.timestamp > j.terms.reviewDeadline) revert Deadline();
+        if (resultHash != j.resultHash) revert InvalidTerms();
+        j.state = State.Verified; emit Verified(id, resultHash);
+    }
+    function release(bytes32 id) external nonReentrant {
+        Job storage j = jobs[id];
+        if (msg.sender != j.terms.verifier) revert Unauthorized();
+        if (j.state != State.Verified) revert WrongState();
+        if (block.timestamp > j.terms.resolutionDeadline) revert Deadline();
+        _settle(id, j, j.terms.amount, 0);
+    }
+    function refundExpired(bytes32 id) external nonReentrant {
+        Job storage j = jobs[id];
+        if (j.state != State.Funded) revert WrongState();
+        if (block.timestamp <= j.terms.workDeadline) revert Deadline();
+        _settle(id, j, 0, 1);
+    }
+    function dispute(bytes32 id, bytes32 reasonHash) external {
+        Job storage j = jobs[id];
+        if (msg.sender != j.terms.payer && msg.sender != j.terms.worker && msg.sender != j.terms.verifier) revert Unauthorized();
+        if (j.state != State.Submitted && j.state != State.Verified) revert WrongState();
+        if (block.timestamp > j.terms.resolutionDeadline) revert Deadline();
+        j.state = State.Disputed; emit Disputed(id, reasonHash);
+    }
+    function resolve(bytes32 id, uint256 workerAmount) external nonReentrant {
+        Job storage j = jobs[id];
+        if (msg.sender != j.terms.arbitrator) revert Unauthorized();
+        if (j.state != State.Disputed) revert WrongState();
+        if (block.timestamp > j.terms.resolutionDeadline || workerAmount > j.terms.amount) revert InvalidTerms();
+        _settle(id, j, workerAmount, 2);
+    }
+    /// Permissionless liveness fallback; requires an actual transaction after the deadline.
+    function timeout(bytes32 id) external nonReentrant {
+        Job storage j = jobs[id];
+        if (j.state != State.Submitted && j.state != State.Verified && j.state != State.Disputed) revert WrongState();
+        if (block.timestamp <= j.terms.resolutionDeadline) revert Deadline();
+        // Quotient/remainder avoids overflowing amount * bps.
+        uint256 amount = (j.terms.amount / 10000) * j.terms.timeoutWorkerBps + ((j.terms.amount % 10000) * j.terms.timeoutWorkerBps) / 10000;
+        _settle(id, j, amount, 3);
+    }
+    function _settle(bytes32 id, Job storage j, uint256 workerAmount, uint8 reason) private {
+        uint256 payerAmount = j.terms.amount - workerAmount;
+        j.state = workerAmount == 0 ? State.Refunded : payerAmount == 0 ? State.Paid : State.Split;
+        j.workerPaid = workerAmount;
+        if (workerAmount > 0) _transferExact(j.terms.worker, workerAmount);
+        if (payerAmount > 0) _transferExact(j.terms.payer, payerAmount);
+        emit Settled(id, workerAmount, payerAmount, reason);
+    }
+    function _transferExact(address to, uint256 amount) private {
+        uint256 beforeBalance = token.balanceOf(address(this));
+        uint256 beforeRecipient = token.balanceOf(to);
+        token.safeTransfer(to, amount);
+        if (token.balanceOf(address(this)) != beforeBalance - amount || token.balanceOf(to) != beforeRecipient + amount) revert TokenAmountMismatch();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allorc/a423-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Experimental Next.js-friendly agent job SDK with typed HTTP client and pluggable storage, authentication and settlement",
   "license": "MIT",
   "type": "commonjs",
@@ -16,6 +16,16 @@
       "types": "./src/workflow.d.ts",
       "import": "./src/workflow.mjs",
       "require": "./src/workflow.cjs"
+    },
+    "./escrow": {
+      "import": {
+        "types": "./src/escrow/index.d.mts",
+        "default": "./src/escrow/index.mjs"
+      },
+      "require": {
+        "types": "./src/escrow/index.d.ts",
+        "default": "./src/escrow/index.cjs"
+      }
     }
   },
   "files": [
@@ -32,15 +42,22 @@
     "src/workflow.mjs",
     "src/workflow.d.ts",
     "INTEGRATION.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "src/escrow",
+    "contracts/A423Escrow.sol",
+    "ESCROW.md",
+    "NOTICE"
   ],
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "test": "node --test",
+    "test": "node --test test/*.test.cjs",
     "pack:check": "npm pack --dry-run --ignore-scripts",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm run typecheck && npm test",
+    "build:escrow": "node scripts/compile-escrow.cjs",
+    "typecheck": "tsc --noEmit --strict --module nodenext --moduleResolution nodenext --target es2022 --lib es2022,dom test/workflow-types.mts test/escrow-types.mts test/escrow-types.cts",
+    "pretest": "npm run build:escrow"
   },
   "publishConfig": {
     "access": "public"
@@ -59,5 +76,20 @@
   "homepage": "https://github.com/Allorc-official/A423-SDK#readme",
   "bugs": {
     "url": "https://github.com/Allorc-official/A423-SDK/issues"
+  },
+  "peerDependencies": {
+    "ethers": "^6.15.0"
+  },
+  "peerDependenciesMeta": {
+    "ethers": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@openzeppelin/contracts": "5.4.0",
+    "ethers": "6.15.0",
+    "ganache": "7.9.2",
+    "solc": "0.8.30",
+    "typescript": "5.9.3"
   }
 }