@allorc/a423-sdk 0.3.0 → 0.5.0

package/src/escrow/index.cjs

@@ -6,9 +6,13 @@ const ABI = artifact.abi;
 const TOKEN_ABI = ['function allowance(address,address) view returns(uint256)','function approve(address,uint256) returns(bool)'];
 const TERMS_TYPES = { Terms: [ ['jobId','bytes32'],['payer','address'],['worker','address'],['verifier','address'],['arbitrator','address'],['amount','uint256'],['workDeadline','uint64'],['reviewDeadline','uint64'],['resolutionDeadline','uint64'],['timeoutWorkerBps','uint16'],['agreementHash','bytes32'] ].map(([name,type])=>({name,type})) };
 const transitions = {
-  dispute: {from:['submitted','verified'],roles:['requester','worker','verifier'],to:'disputed',effect:true},
+  propose_settlement: {from:['funded','running','submitted','verified'],roles:['requester','worker'],to:'settlement_negotiation',effect:true},
+  counter_settlement: {from:['settlement_negotiation'],roles:['requester','worker'],to:'settlement_negotiation',effect:true},
+  accept_settlement: {from:['settlement_negotiation'],roles:['requester','worker'],to:'settled',effect:true},
+  refund: {from:['funded','running','settlement_negotiation','disputed'],roles:['requester'],to:'refunded',effect:true},
+  dispute: {from:['funded','running','submitted','verified','settlement_negotiation'],roles:['requester','worker','verifier'],to:'disputed',effect:true},
   resolve: {from:['disputed'],roles:['arbitrator'],to:'settled',effect:true},
-  timeout: {from:['funded','running','submitted','verified','disputed'],roles:['requester','worker','verifier','arbitrator'],to:'settled',effect:true}
+  timeout: {from:['funded','running','submitted','verified','disputed','settlement_negotiation'],roles:['requester','worker','verifier','arbitrator'],to:'settled',effect:true}
 };
 function check(condition,message) { if(!condition) throw new Error('Escrow: '+message); }
 function positive(value,name) { check(typeof value==='string' && /^[1-9][0-9]*$/.test(value),name+' must be a positive decimal string');const n=BigInt(value);check(n<(1n<<256n),name+' exceeds uint256');return n; }
@@ -31,10 +35,13 @@ function createMemoryTransactionStore() {
   return {
     async get(id){return records.has(id)?structuredClone(records.get(id)):null;},
     async create(id,record){if(records.has(id))return false;records.set(id,structuredClone(record));return true;},
+    async list(){return [...records].map(([id,record])=>({id,...structuredClone(record)}));},
+    async appendReplacement(id,expectedHash,replacement){const record=records.get(id);check(record&&(record.replacements?.at(-1)?.hash||record.hash)===expectedHash,'Replacement conflict');record.replacements=[...(record.replacements||[]),structuredClone(replacement)];},
     async reserveNonce(scope,minimum,operationId){const key=scope+':'+operationId;if(reservations.has(key))return reservations.get(key);const nonce=Math.max(minimum,nonces.get(scope)||0);nonces.set(scope,nonce+1);reservations.set(key,nonce);return nonce;}
   };
 }
-function createEscrowAdapters({provider,chainId,contractAddress,tokenAddress,signerFor,addressFor,transactions,confirmations,validateArtifact}={}) {
+function createEscrowAdapters({provider,chainId,contractAddress,tokenAddress,signerFor,addressFor,transactions,confirmations,validateArtifact,authorizeTransaction}={}) {
+  check(typeof authorizeTransaction==='function','authorizeTransaction is required before any signing or broadcast');
   check(provider && typeof signerFor==='function' && typeof addressFor==='function','provider, signerFor and addressFor required');
   check(Number.isSafeInteger(chainId)&&chainId>0 && Number.isSafeInteger(confirmations)&&confirmations>0,'explicit chain ID and positive confirmations required');
   check(transactions && ['get','create','reserveNonce'].every(k=>typeof transactions[k]==='function'),'durable transaction journal required');
@@ -63,6 +70,7 @@ function createEscrowAdapters({provider,chainId,contractAddress,tokenAddress,sig
     let record=await transactions.get(id);
     if(!record && reconcile)return {status:'pending',reference:id};
     if(!record) {
+      if(await authorizeTransaction({job:structuredClone(ctx.job),operation:structuredClone(ctx.operation),actor:ctx.operation.actor,step:suffix,to:getAddress(to),data,phase:'sign'})!==true)return {status:'rejected',reason:'Signing policy denied before signing'};
       const signer=await signerFor(ctx.operation.actor);
       const address=getAddress(await signer.getAddress());
       check(address===getAddress(await addressFor(ctx.operation.actor)),'signer ownership mismatch');
@@ -75,17 +83,20 @@ function createEscrowAdapters({provider,chainId,contractAddress,tokenAddress,sig
       const raw=await signer.signTransaction(request);
       const tx=Transaction.from(raw);
       check(tx.from===address && Number(tx.chainId)===chainId && tx.to===getAddress(to) && tx.data===data && tx.nonce===nonce && tx.value===0n,'signed transaction mismatch');
-      await transactions.create(id,{hash:tx.hash,raw,to:getAddress(to),data,from:address});
+      await transactions.create(id,{hash:tx.hash,raw,to:getAddress(to),data,from:address,created_at:new Date().toISOString()});
       record=await transactions.get(id);
     }
     check(record.to===getAddress(to) && record.data===data && record.from===getAddress(await addressFor(ctx.operation.actor)),'journal request mismatch');
-    let r=await receipt(record.hash);
+    const attempts=[record,...(record.replacements||[])];
+    let active=attempts.at(-1),r=null;
+    for(const attempt of attempts){const observed=await receipt(attempt.hash);if(observed){r=observed;active=attempt;break;}}
     if(!r && !reconcile) {
-      try {await provider.broadcastTransaction(record.raw);} catch(err) {if(!await provider.getTransaction(record.hash))throw err;}
-      r=await receipt(record.hash);
+      check(await authorizeTransaction({job:structuredClone(ctx.job),operation:structuredClone(ctx.operation),actor:ctx.operation.actor,step:suffix,to:getAddress(to),data,phase:'broadcast'})===true,'broadcast policy denied');
+      try {await provider.broadcastTransaction(active.raw);} catch(err) {if(!await provider.getTransaction(active.hash))throw err;}
+      r=await receipt(active.hash);
     }
-    if(!r)return {status:'pending',reference:record.hash};
-    if(r.status!==1)return {status:'rejected',reason:'Transaction reverted',reference:record.hash};
+    if(!r)return {status:'pending',reference:active.hash};
+    if(r.status!==1)return {status:'rejected',reason:'Transaction reverted',reference:active.hash};
     return {receipt:r};
   }
   async function observe(ctx,t,suffix,method,args,eventName,validate,reconcile) {
@@ -101,19 +112,52 @@ function createEscrowAdapters({provider,chainId,contractAddress,tokenAddress,sig
     const event=logs.find(log=>log?.name===eventName && log.args.jobId===t.jobId);
     check(event,'matching '+eventName+' event missing');
     const snapshot=await contract.getJob(t.jobId,{blockTag:r.blockNumber});match(snapshot,t);validate(snapshot,event);
-    return {status:'confirmed',evidence:{chain_id:String(chainId),contract:config.contractAddress,token:config.tokenAddress,job_id:t.jobId,agreement_hash:t.agreementHash,transaction_hash:r.hash,block_number:r.blockNumber,block_hash:r.blockHash,confirmations,event:eventName,amount:t.amount.toString(),payer:t.payer,worker:t.worker,verifier:t.verifier,arbitrator:t.arbitrator,result_hash:snapshot.resultHash,worker_paid:snapshot.workerPaid.toString(),state:Number(snapshot.state),observed_at:new Date().toISOString()}};
+    return {status:'confirmed',evidence:require('../operations/index.cjs').validateEscrowEvidence({chain_id:String(chainId),contract:config.contractAddress,token:config.tokenAddress,job_id:t.jobId,agreement_hash:t.agreementHash,transaction_hash:r.hash,block_number:r.blockNumber,block_hash:r.blockHash,confirmations,event:eventName,escrow_version:Number(snapshot.proposal.revision),proposal_hash:snapshot.proposal.proposalHash,proposal_worker_amount:snapshot.proposal.workerAmount.toString(),proposal_expires_at:Number(snapshot.proposal.expiresAt),proposal_proposer:snapshot.proposal.proposer,settlement_reason:eventName==='Settled'?Number(event.args.reason):null,reason_hash:eventName==='Disputed'?event.args.reasonHash:null,amount:t.amount.toString(),payer:t.payer,worker:t.worker,verifier:t.verifier,arbitrator:t.arbitrator,result_hash:snapshot.resultHash,worker_paid:snapshot.workerPaid.toString(),state:Number(snapshot.state),observed_at:new Date().toISOString()})};
   }
   function adapter(run){return {execute:ctx=>run(ctx,false),reconcile:ctx=>run(ctx,true)};}
   const state=(s,n)=>check(Number(s.state)===n,'unexpected escrow state');
   const settled=(s,e,t)=>{check([5,6,7].includes(Number(s.state)),'not settled');check(e.args.workerAmount+e.args.payerAmount===t.amount && e.args.workerAmount===s.workerPaid,'settlement amount mismatch');};
+  async function propose(ctx,reconcile){
+    const {settlementProposal}=require('./negotiation.cjs');
+    const t=await context(ctx.job);let proposal;
+    try {proposal=settlementProposal(ctx.job,ctx.input);}catch(error){return {status:'rejected',reason:error.message};}
+    return observe(ctx,t,'propose_settlement','proposeSettlement',[t.jobId,ctx.input.expected_revision,BigInt(proposal.worker_amount),proposal.proposal_hash,proposal.expires_at],'SettlementProposed',(s,e)=>{
+      check(Number(s.state)===8,'negotiation is not active');
+      check(Number(e.args.revision)===proposal.escrow_version && e.args.proposalHash===proposal.proposal_hash && e.args.workerAmount===BigInt(proposal.worker_amount) && e.args.payerAmount===BigInt(proposal.payer_amount) && Number(e.args.expiresAt)===proposal.expires_at && getAddress(e.args.proposer)===getAddress(ctx.settlementActorAddress), 'proposal event mismatch');
+    },reconcile);
+  }
+  const proposeAdapter=adapter(async(ctx,r)=>{ctx.settlementActorAddress=getAddress(await addressFor(ctx.operation.actor));return propose(ctx,r);});
   return {
+    propose_settlement:proposeAdapter,
+    counter_settlement:proposeAdapter,
+    accept_settlement:adapter(async(ctx,r)=>{
+      const {settlementConsent}=require('./negotiation.cjs');const t=await context(ctx.job);const p=ctx.job.negotiation?.current;
+      if(!p || ctx.input.expected_revision!==p.escrow_version || ctx.input.proposal_hash!==p.proposal_hash)return {status:'rejected',reason:'Accept the exact current proposal hash and revision'};
+      let consent;try{consent=settlementConsent(ctx.job,config);}catch(error){return {status:'rejected',reason:error.message};}
+      let method='acceptSettlement',args=[t.jobId,p.escrow_version,p.proposal_hash];
+      if(ctx.input.payer_signature!==undefined || ctx.input.worker_signature!==undefined){
+        if(typeof ctx.input.payer_signature!=='string'||typeof ctx.input.worker_signature!=='string')return {status:'rejected',reason:'Both party signatures required for relayed settlement'};
+        method='settleByConsent';args=[consent.value,ctx.input.payer_signature,ctx.input.worker_signature];
+      }else if(ctx.job.negotiation.current.proposer_id===ctx.operation.actor)return {status:'rejected',reason:'Counterparty must accept; proposer cannot self-accept'};
+      const result=await observe(ctx,t,'accept_settlement',method,args,'Settled',(s,e)=>{settled(s,e,t);check(Number(e.args.reason)===4 && e.args.workerAmount===BigInt(p.worker_amount) && e.args.payerAmount===BigInt(p.payer_amount) && Number(s.proposal.revision)===p.escrow_version && s.proposal.proposalHash===p.proposal_hash,'closing allocation mismatch');},r);
+      if(result.status==='confirmed'){
+        const receipt=await provider.getTransactionReceipt(result.evidence.transaction_hash);
+        const accepted=receipt.logs.filter(l=>getAddress(l.address)===config.contractAddress).map(l=>{try{return iface.parseLog(l);}catch{return null;}}).find(e=>e?.name==='SettlementAccepted'&&e.args.jobId===t.jobId);
+        check(accepted&&Number(accepted.args.revision)===p.escrow_version&&accepted.args.proposalHash===p.proposal_hash,'matching settlement acceptance missing');
+      }
+      return result;
+    }),
     fund:adapter(async(ctx,reconcile)=>{
       const t=await context(ctx.job);
       check([ctx.job.participants.requester,ctx.job.participants.worker].every(p=>ctx.job.agreement.accepted_by.includes(p)),'both acceptances required');
       if(typeof ctx.input.worker_signature!=='string')return {status:'rejected',reason:'worker_signature required'};
       // Consent is checked locally as well as by the contract before moving tokens.
       const {verifyTypedData}=require('ethers');const c=workerConsent(ctx.job,config);
-      try {if(getAddress(verifyTypedData(c.domain,c.types,c.value,ctx.input.worker_signature))!==t.worker)return {status:'rejected',reason:'Invalid worker consent'};} catch {return {status:'rejected',reason:'Invalid worker consent'};}
+      const digest=TypedDataEncoder.hash(c.domain,c.types,c.value);
+      if(await provider.getCode(t.worker)!=='0x'){
+        const smart=new Contract(t.worker,['function isValidSignature(bytes32,bytes) view returns(bytes4)'],provider);
+        try {if(await smart.isValidSignature(digest,ctx.input.worker_signature)!=='0x1626ba7e')return {status:'rejected',reason:'Invalid smart-account worker consent'};}catch(err){if(err.code==='CALL_EXCEPTION')return {status:'rejected',reason:'Smart-account consent reverted'};throw err;}
+      }else {try {if(getAddress(verifyTypedData(c.domain,c.types,c.value,ctx.input.worker_signature))!==t.worker)return {status:'rejected',reason:'Invalid worker consent'};} catch {return {status:'rejected',reason:'Invalid worker consent'};}}
       // Never send further approvals if the funding transaction already exists in the journal.
       if(!ctx.input.transaction_hash && !await transactions.get(ctx.operation.id+':fund')) {
         let allowance=await token.allowance(t.payer,config.contractAddress);
@@ -131,7 +175,9 @@ function createEscrowAdapters({provider,chainId,contractAddress,tokenAddress,sig
     refund:adapter(async(ctx,r)=>{const t=await context(ctx.job);return observe(ctx,t,'refund','refundExpired',[t.jobId],'Settled',(s,e)=>{state(s,6);settled(s,e,t);check(e.args.payerAmount===t.amount && Number(e.args.reason)===1,'not an expiry refund');},r);}),
     dispute:adapter(async(ctx,r)=>{const t=await context(ctx.job);const reason=bytes32(ctx.input.reason_hash);return observe(ctx,t,'dispute','dispute',[t.jobId,reason],'Disputed',(s,e)=>{check(Number(s.state)>=4,'missing dispute');check(e.args.reasonHash===reason,'reason mismatch');},r);}),
     resolve:adapter(async(ctx,r)=>{const t=await context(ctx.job);check(typeof ctx.input.worker_amount==='string' && /^(0|[1-9][0-9]*)$/.test(ctx.input.worker_amount),'worker_amount must be decimal string');const amount=BigInt(ctx.input.worker_amount);check(amount<=t.amount,'resolution exceeds escrow');return observe(ctx,t,'resolve','resolve',[t.jobId,amount],'Settled',(s,e)=>{settled(s,e,t);check(e.args.workerAmount===amount && Number(e.args.reason)===2,'resolution mismatch');},r);}),
-    timeout:adapter(async(ctx,r)=>{const t=await context(ctx.job);const method=['funded','running'].includes(ctx.job.state)?'refundExpired':'timeout';return observe(ctx,t,'timeout',method,[t.jobId],'Settled',(s,e)=>{settled(s,e,t);const expected=method==='refundExpired'?0n:(t.amount*BigInt(t.timeoutWorkerBps))/10000n;check(e.args.workerAmount===expected && Number(e.args.reason)===(method==='refundExpired'?1:3),'timeout allocation mismatch');},r);})
+    timeout:adapter(async(ctx,r)=>{const t=await context(ctx.job);const snapshot=await contract.getJob(t.jobId);const method=snapshot.resultHash===ZeroHash?'refundExpired':'timeout';return observe(ctx,t,'timeout',method,[t.jobId],'Settled',(s,e)=>{settled(s,e,t);const expected=method==='refundExpired'?0n:(t.amount*BigInt(t.timeoutWorkerBps))/10000n;check(e.args.workerAmount===expected && Number(e.args.reason)===(method==='refundExpired'?1:3),'timeout allocation mismatch');},r);})
   };
 }
 module.exports={createEscrowAdapters,createMemoryTransactionStore,workerConsent,escrowTerms,escrowTransitions:transitions,ESCROW_ABI:ABI,ESCROW_BYTECODE:artifact.bytecode};
+
+Object.assign(module.exports,require('./services.cjs'),require('./negotiation.cjs'));

package/src/escrow/index.d.mts

@@ -6,9 +6,11 @@ export interface ContractTerms {
   amount: bigint; workDeadline: number; reviewDeadline: number; resolutionDeadline: number;
   timeoutWorkerBps: number; agreementHash: string;
 }
-export interface TransactionRecord { hash: string; raw: string; to: string; data: string; from: string }
+export interface TransactionRecord { created_at?: string; replacements?: TransactionRecord[]; hash: string; raw: string; to: string; data: string; from: string }
 export interface TransactionStore {
   get(id: string): Promise<TransactionRecord | null>;
+  list(): Promise<Array<TransactionRecord & {id: string}>>;
+  appendReplacement(id: string, expectedHash: string, replacement: TransactionRecord): Promise<void>;
   /** Atomic insert if absent; caller reads winner before broadcasting. */
   create(id: string, record: TransactionRecord): Promise<boolean>;
   /** Atomically reserve a nonce per chain/address; same operationId always returns same nonce. */
@@ -21,10 +23,11 @@ export interface EscrowAdapterOptions extends EscrowConfiguration {
   signerFor(actor: string): Promise<Signer>;
   addressFor(actor: string): Promise<string>;
   transactions: TransactionStore;
+  authorizeTransaction(context: { job: WorkflowJob; operation: AdapterContext['operation']; actor: string; step: string; to: string; data: string; phase: 'sign' | 'broadcast' }): Promise<boolean>;
   confirmations: number;
   validateArtifact?(context: { job: WorkflowJob; resultHash: string }): Promise<boolean>;
 }
-export function createEscrowAdapters(options: EscrowAdapterOptions): Record<'fund'|'start'|'submit'|'verify'|'release'|'refund'|'dispute'|'resolve'|'timeout', EscrowAdapter>;
+export function createEscrowAdapters(options: EscrowAdapterOptions): Record<'fund'|'start'|'submit'|'verify'|'release'|'refund'|'dispute'|'resolve'|'timeout'|'propose_settlement'|'counter_settlement'|'accept_settlement', EscrowAdapter>;
 export function createMemoryTransactionStore(): TransactionStore;
 export function escrowTerms(job: WorkflowJob, config: EscrowConfiguration): ContractTerms;
 export function workerConsent(job: WorkflowJob, config: EscrowConfiguration): {
@@ -34,3 +37,15 @@ export function workerConsent(job: WorkflowJob, config: EscrowConfiguration): {
 export const escrowTransitions: Record<string, Transition>;
 export const ESCROW_ABI: InterfaceAbi;
 export const ESCROW_BYTECODE: string;
+
+export function createEscrowRegistry(configurations: EscrowAdapterOptions[]): ReturnType<typeof createEscrowAdapters>;
+export function createEvidenceRevalidator(options: EscrowConfiguration & {provider: Provider;confirmations: number}): (job: WorkflowJob,evidence: any) => Promise<{status: 'valid' | 'invalid' | 'insufficient_confirmations';[key: string]: unknown}>;
+export function createManagedSigner(options: {address: string;provider: Provider;signDigest(digest: string,context: any): Promise<string>;authorize(context: any): Promise<boolean>}): Signer;
+export function createDelegationAuthorizer(options: {expiresAt: number;chainIds: number[];contracts: string[];selectors: string[];maxValue?: string;maxFeePerGas: string;maxGasLimit: string;now?(): number}): (context: any) => Promise<boolean>;
+export function replacePendingTransaction(options: {id: string;transactions: TransactionStore;provider: Provider;signer: Signer;authorize(context: any): Promise<boolean>;maxFeePerGas: bigint;maxPriorityFeePerGas: bigint}): Promise<{hash: string;raw: string}>;
+export function createFeeReplacementWorker(options: {transactions: TransactionStore;provider: Provider;signerForRecord(record: TransactionRecord): Promise<Signer>;authorize(context: any): Promise<boolean>;minAgeMs?: number;maxAttempts?: number;maxFeePerGas: bigint;maxPriorityFeePerGas: bigint}): () => Promise<any[]>;
+
+export function createEscrowIndexer(options: {provider: Provider;chainId: number;contractAddress: string;confirmations: number;fromBlock: number;kv: import('../storage/index.js').KeyValueStore;onEvent(event: any): Promise<void>;onReorg(event: any): Promise<void>;batchSize?: number}): () => Promise<{indexed: number;through?: number}>;
+
+export function settlementProposal(job: WorkflowJob,input: {worker_amount: string;payer_amount?: string;expected_revision: number;expires_at: number;reason: string;claims?: import('../workflow.js').SettlementClaim[]}): import('../workflow.js').SettlementProposal;
+export function settlementConsent(job: WorkflowJob,configuration: EscrowConfiguration): {domain: {name: string;version: string;chainId: number;verifyingContract: string};types: Record<string,TypedDataField[]>;value: {jobId: string;agreementHash: string;escrowVersion: number;workerAmount: bigint;payerAmount: bigint;proposalHash: string;expiresAt: number}};

package/src/escrow/index.d.ts

@@ -6,9 +6,11 @@ export interface ContractTerms {
   amount: bigint; workDeadline: number; reviewDeadline: number; resolutionDeadline: number;
   timeoutWorkerBps: number; agreementHash: string;
 }
-export interface TransactionRecord { hash: string; raw: string; to: string; data: string; from: string }
+export interface TransactionRecord { created_at?: string; replacements?: TransactionRecord[]; hash: string; raw: string; to: string; data: string; from: string }
 export interface TransactionStore {
   get(id: string): Promise<TransactionRecord | null>;
+  list(): Promise<Array<TransactionRecord & {id: string}>>;
+  appendReplacement(id: string, expectedHash: string, replacement: TransactionRecord): Promise<void>;
   /** Atomic insert if absent; caller reads winner before broadcasting. */
   create(id: string, record: TransactionRecord): Promise<boolean>;
   /** Atomically reserve a nonce per chain/address; same operationId always returns same nonce. */
@@ -21,10 +23,11 @@ export interface EscrowAdapterOptions extends EscrowConfiguration {
   signerFor(actor: string): Promise<Signer>;
   addressFor(actor: string): Promise<string>;
   transactions: TransactionStore;
+  authorizeTransaction(context: { job: WorkflowJob; operation: AdapterContext['operation']; actor: string; step: string; to: string; data: string; phase: 'sign' | 'broadcast' }): Promise<boolean>;
   confirmations: number;
   validateArtifact?(context: { job: WorkflowJob; resultHash: string }): Promise<boolean>;
 }
-export function createEscrowAdapters(options: EscrowAdapterOptions): Record<'fund'|'start'|'submit'|'verify'|'release'|'refund'|'dispute'|'resolve'|'timeout', EscrowAdapter>;
+export function createEscrowAdapters(options: EscrowAdapterOptions): Record<'fund'|'start'|'submit'|'verify'|'release'|'refund'|'dispute'|'resolve'|'timeout'|'propose_settlement'|'counter_settlement'|'accept_settlement', EscrowAdapter>;
 export function createMemoryTransactionStore(): TransactionStore;
 export function escrowTerms(job: WorkflowJob, config: EscrowConfiguration): ContractTerms;
 export function workerConsent(job: WorkflowJob, config: EscrowConfiguration): {
@@ -34,3 +37,15 @@ export function workerConsent(job: WorkflowJob, config: EscrowConfiguration): {
 export const escrowTransitions: Record<string, Transition>;
 export const ESCROW_ABI: InterfaceAbi;
 export const ESCROW_BYTECODE: string;
+
+export function createEscrowRegistry(configurations: EscrowAdapterOptions[]): ReturnType<typeof createEscrowAdapters>;
+export function createEvidenceRevalidator(options: EscrowConfiguration & {provider: Provider;confirmations: number}): (job: WorkflowJob,evidence: any) => Promise<{status: 'valid' | 'invalid' | 'insufficient_confirmations';[key: string]: unknown}>;
+export function createManagedSigner(options: {address: string;provider: Provider;signDigest(digest: string,context: any): Promise<string>;authorize(context: any): Promise<boolean>}): Signer;
+export function createDelegationAuthorizer(options: {expiresAt: number;chainIds: number[];contracts: string[];selectors: string[];maxValue?: string;maxFeePerGas: string;maxGasLimit: string;now?(): number}): (context: any) => Promise<boolean>;
+export function replacePendingTransaction(options: {id: string;transactions: TransactionStore;provider: Provider;signer: Signer;authorize(context: any): Promise<boolean>;maxFeePerGas: bigint;maxPriorityFeePerGas: bigint}): Promise<{hash: string;raw: string}>;
+export function createFeeReplacementWorker(options: {transactions: TransactionStore;provider: Provider;signerForRecord(record: TransactionRecord): Promise<Signer>;authorize(context: any): Promise<boolean>;minAgeMs?: number;maxAttempts?: number;maxFeePerGas: bigint;maxPriorityFeePerGas: bigint}): () => Promise<any[]>;
+
+export function createEscrowIndexer(options: {provider: Provider;chainId: number;contractAddress: string;confirmations: number;fromBlock: number;kv: import('../storage/index.js').KeyValueStore;onEvent(event: any): Promise<void>;onReorg(event: any): Promise<void>;batchSize?: number}): () => Promise<{indexed: number;through?: number}>;
+
+export function settlementProposal(job: WorkflowJob,input: {worker_amount: string;payer_amount?: string;expected_revision: number;expires_at: number;reason: string;claims?: import('../workflow.js').SettlementClaim[]}): import('../workflow.js').SettlementProposal;
+export function settlementConsent(job: WorkflowJob,configuration: EscrowConfiguration): {domain: {name: string;version: string;chainId: number;verifyingContract: string};types: Record<string,TypedDataField[]>;value: {jobId: string;agreementHash: string;escrowVersion: number;workerAmount: bigint;payerAmount: bigint;proposalHash: string;expiresAt: number}};

package/src/escrow/index.mjs

@@ -1,2 +1,2 @@
 import escrow from './index.cjs';
-export const { createEscrowAdapters, createMemoryTransactionStore, workerConsent, escrowTerms, escrowTransitions, ESCROW_ABI, ESCROW_BYTECODE } = escrow;
+export const { createEscrowAdapters, createMemoryTransactionStore, workerConsent, escrowTerms, escrowTransitions, ESCROW_ABI, ESCROW_BYTECODE, createEscrowRegistry, createEvidenceRevalidator, createManagedSigner, createDelegationAuthorizer, replacePendingTransaction, createFeeReplacementWorker, createEscrowIndexer, settlementProposal, settlementConsent } = escrow;

package/src/escrow/negotiation.cjs

@@ -0,0 +1,13 @@
+'use strict';
+const {getAddress}=require('ethers');
+const TYPES={ClosingSettlement:[['jobId','bytes32'],['agreementHash','bytes32'],['escrowVersion','uint64'],['workerAmount','uint256'],['payerAmount','uint256'],['proposalHash','bytes32'],['expiresAt','uint64']].map(([name,type])=>({name,type}))};
+function check(ok,message){if(!ok)throw new TypeError(message);}
+const {settlementProposal}=require('../closing.cjs');
+function settlementConsent(job,configuration){
+ const {escrowTerms}=require('./index.cjs');const t=escrowTerms(job,configuration),p=job.negotiation?.current;
+ check(p&&job.negotiation.status==='open','Open settlement proposal required');
+ const canonical=settlementProposal(job,{worker_amount:p.worker_amount,payer_amount:p.payer_amount,expected_revision:p.escrow_version-1,expires_at:p.expires_at,reason:p.reason,claims:p.claims});
+ check(canonical.proposal_hash===p.proposal_hash,'Stored proposal claims or allocation changed');
+ return {domain:{name:'A423Escrow',version:'1',chainId:configuration.chainId,verifyingContract:getAddress(configuration.contractAddress)},types:TYPES,value:{jobId:t.jobId,agreementHash:t.agreementHash,escrowVersion:p.escrow_version,workerAmount:BigInt(p.worker_amount),payerAmount:BigInt(p.payer_amount),proposalHash:p.proposal_hash,expiresAt:p.expires_at}};
+}
+module.exports={settlementProposal,settlementConsent};

package/src/escrow/services.cjs

@@ -0,0 +1,122 @@
+'use strict';
+const {Contract,Interface,AbstractSigner,Transaction,Signature,verifyMessage,verifyTypedData,recoverAddress,hashMessage,TypedDataEncoder,getAddress,ZeroHash}=require('ethers');
+const {ESCROW_ABI,escrowTerms,createEscrowAdapters}=require('./index.cjs');
+const {validateEscrowEvidence}=require('../operations/index.cjs');
+function check(ok,message){if(!ok)throw Error(message);}
+function createEscrowRegistry(configurations){
+ const map=new Map();for(const c of configurations){const key=c.chainId+':'+getAddress(c.contractAddress).toLowerCase();check(!map.has(key),'Duplicate escrow configuration');map.set(key,createEscrowAdapters(c));}
+ const actions=['fund','start','submit','verify','release','refund','dispute','resolve','timeout','propose_settlement','counter_settlement','accept_settlement'];const result={};for(const action of actions){result[action]={};for(const method of ['execute','reconcile'])result[action][method]=ctx=>{const e=ctx.job.agreement?.terms.escrow;const adapter=map.get(e?.chain_id+':'+getAddress(e?.contract).toLowerCase());check(adapter,'Escrow not registered');return adapter[action][method](ctx);};}return result;
+}
+/** Fresh historical evidence verification. Returns invalid, insufficient_confirmations, or valid; RPC failures throw. */
+function createEvidenceRevalidator({provider,chainId,contractAddress,tokenAddress,confirmations}={}){
+ const config={chainId,contractAddress:getAddress(contractAddress),tokenAddress:getAddress(tokenAddress)},contract=new Contract(config.contractAddress,ESCROW_ABI,provider),iface=new Interface(ESCROW_ABI);
+ check(Number.isSafeInteger(confirmations)&&confirmations>0,'Explicit confirmations required');
+ return async(job,evidence)=>{
+  validateEscrowEvidence(evidence);const t=escrowTerms(job,config);
+  if(Number((await provider.getNetwork()).chainId)!==chainId)throw Error('RPC chain mismatch');
+  if(getAddress(await contract.token())!==config.tokenAddress)throw Error('Escrow token mismatch');
+  const invalid=message=>({status:'invalid',message});
+  if(evidence.chain_id!==String(chainId)||getAddress(evidence.contract)!==config.contractAddress||getAddress(evidence.token)!==config.tokenAddress)return invalid('Evidence destination mismatch');
+  const receipt=await provider.getTransactionReceipt(evidence.transaction_hash);
+  if(!receipt||receipt.status!==1||receipt.blockHash!==evidence.block_hash||receipt.blockNumber!==evidence.block_number)return invalid('Receipt missing, reverted or changed');
+  const block=await provider.getBlock(receipt.blockNumber),head=await provider.getBlock('latest');
+  if(!block||block.hash!==receipt.blockHash)return invalid('Orphaned receipt');
+  if(head.number-block.number+1<confirmations)return {status:'insufficient_confirmations'};
+  const logs=receipt.logs.filter(l=>getAddress(l.address)===config.contractAddress).map(l=>{try{return iface.parseLog(l);}catch{return null;}});
+  const event=logs.find(l=>l?.name===evidence.event&&l.args.jobId===t.jobId);if(!event)return invalid('Event absent');
+  const snapshot=await contract.getJob(t.jobId,{blockTag:receipt.blockNumber});
+  for(const [key,value] of Object.entries(t))if(String(snapshot.terms[key]).toLowerCase()!==String(value).toLowerCase())return invalid('Agreement '+key+' mismatch');
+  const expected={amount:t.amount.toString(),payer:t.payer,worker:t.worker,verifier:t.verifier,arbitrator:t.arbitrator,job_id:t.jobId,agreement_hash:t.agreementHash,result_hash:snapshot.resultHash,worker_paid:snapshot.workerPaid.toString(),state:Number(snapshot.state)};
+  for(const [key,value] of Object.entries(expected))if(String(evidence[key]).toLowerCase()!==String(value).toLowerCase())return invalid('Cached '+key+' mismatch');
+  if(event.name==='Funded'&&(event.args.amount!==t.amount||getAddress(event.args.payer)!==t.payer||getAddress(event.args.worker)!==t.worker||event.args.agreementHash!==t.agreementHash))return invalid('Funding fields mismatch');
+  if(['Submitted','Verified'].includes(event.name)&&event.args.resultHash!==snapshot.resultHash)return invalid('Artifact mismatch');
+  if(event.name==='Disputed'&&event.args.reasonHash!==evidence.reason_hash)return invalid('Dispute reason mismatch');
+  if(event.name==='SettlementProposed'&&(Number(event.args.revision)!==evidence.escrow_version||event.args.proposalHash!==evidence.proposal_hash||event.args.workerAmount.toString()!==evidence.proposal_worker_amount||Number(event.args.expiresAt)!==evidence.proposal_expires_at||getAddress(event.args.proposer)!==getAddress(evidence.proposal_proposer)))return invalid('Proposal fields mismatch');
+  if(evidence.escrow_version!==undefined && (Number(snapshot.proposal.revision)!==evidence.escrow_version||snapshot.proposal.proposalHash!==evidence.proposal_hash||snapshot.proposal.workerAmount.toString()!==evidence.proposal_worker_amount||Number(snapshot.proposal.expiresAt)!==evidence.proposal_expires_at||getAddress(snapshot.proposal.proposer)!==getAddress(evidence.proposal_proposer)))return invalid('Cached proposal mismatch');
+  if(event.name==='Settled'&&Number(event.args.reason)===4){const acceptance=logs.find(l=>l?.name==='SettlementAccepted'&&l.args.jobId===t.jobId);if(!acceptance||Number(acceptance.args.revision)!==evidence.escrow_version||acceptance.args.proposalHash!==evidence.proposal_hash)return invalid('Mutual acceptance missing');}
+  if(event.name==='Settled'&&(event.args.workerAmount!==snapshot.workerPaid||event.args.payerAmount+event.args.workerAmount!==t.amount||Number(event.args.reason)!==evidence.settlement_reason))return invalid('Settlement mismatch');
+  return {status:'valid',transaction_hash:receipt.hash,block_hash:block.hash,confirmations:head.number-block.number+1};
+ };
+}
+/** Noncustodial integration surface: the injected digest signer may call a KMS/HSM or remote signer. */
+function createManagedSigner({address,provider,signDigest,authorize}={}){
+ address=getAddress(address);check(typeof signDigest==='function'&&typeof authorize==='function','Digest signer and authorization required');
+ class ManagedSigner extends AbstractSigner {
+  async getAddress(){return address;}
+  connect(next){return createManagedSigner({address,provider:next,signDigest,authorize});}
+  async signature(digest,context){check(await authorize(context)===true,'Managed signer authorization denied');const signature=Signature.from(await signDigest(digest,context));check(getAddress(recoverAddress(digest,signature))===address,'Remote signer returned wrong key');return signature;}
+  async signTransaction(request){const copy={...request};if(copy.from){check(getAddress(copy.from)===address,'Wrong signing account');delete copy.from;}const transaction=Transaction.from(copy);const signature=await this.signature(transaction.unsignedHash,{kind:'transaction',transaction:copy});transaction.signature=signature;return transaction.serialized;}
+  async signMessage(message){return (await this.signature(hashMessage(message),{kind:'message',message})).serialized;}
+  async signTypedData(domain,types,value){return (await this.signature(TypedDataEncoder.hash(domain,types,value),{kind:'typed_data',domain,types,value})).serialized;}
+ }
+ return new ManagedSigner(provider);
+}
+/** Explicit bounded same-nonce replacement; never change recipient/calldata/value. Journal preserves lineage. */
+async function replacePendingTransaction({id,transactions,provider,signer,authorize,maxFeePerGas,maxPriorityFeePerGas}={}){
+ const record=await transactions.get(id);check(record,'Unknown transaction');
+ for(const attempt of [record,...(record.replacements||[])])check(!await provider.getTransactionReceipt(attempt.hash),'An attempt is already mined; reconcile instead');
+ const last=record.replacements?.at(-1)||record;const old=Transaction.from(last.raw);
+ check(old.type===2,'Only EIP-1559 replacements supported');
+ const fee=BigInt(maxFeePerGas),tip=BigInt(maxPriorityFeePerGas);
+ check(fee>=(old.maxFeePerGas*125n+99n)/100n&&tip>=(old.maxPriorityFeePerGas*125n+99n)/100n&&tip<=fee,'Replacement must raise both fees at least 25%');
+ check(await authorize({record,fee,tip})===true,'Replacement not authorized');
+ check(getAddress(await signer.getAddress())===old.from,'Wrong replacement signer');
+ const request={chainId:old.chainId,nonce:old.nonce,to:old.to,data:old.data,value:old.value,gasLimit:old.gasLimit,type:2,accessList:old.accessList,maxFeePerGas:fee,maxPriorityFeePerGas:tip};
+ const raw=await signer.signTransaction(request),tx=Transaction.from(raw);check(tx.from===old.from&&tx.to===old.to&&tx.data===old.data&&tx.value===old.value&&tx.nonce===old.nonce&&tx.chainId===old.chainId&&tx.gasLimit===old.gasLimit&&tx.maxFeePerGas===fee&&tx.maxPriorityFeePerGas===tip,'Replacement signer changed intent');
+ check(typeof transactions.appendReplacement==='function','Durable replacement journal required');
+ await transactions.appendReplacement(id,last.hash,{hash:tx.hash,raw,to:record.to,data:record.data,from:record.from,created_at:new Date().toISOString()});
+ return {hash:tx.hash,raw}; // persisted first; adapter resume broadcasts all known attempts safely.
+}
+module.exports={createEscrowRegistry,createEvidenceRevalidator,createManagedSigner,replacePendingTransaction};
+/** Opt-in bounded fee replacement planning; broadcasting remains the original action's resume path. */
+function createFeeReplacementWorker({transactions,provider,signerForRecord,authorize,minAgeMs=60000,maxAttempts=3,maxFeePerGas,maxPriorityFeePerGas}={}){
+ check(Number.isSafeInteger(minAgeMs)&&minAgeMs>0&&Number.isSafeInteger(maxAttempts)&&maxAttempts>=1,'Invalid replacement bounds');
+ const cap=BigInt(maxFeePerGas),tipCap=BigInt(maxPriorityFeePerGas);
+ return async()=>{const results=[];for(const record of await transactions.list()){
+  if((record.replacements?.length||0)>=maxAttempts||!record.created_at||Date.now()-Date.parse(record.replacements?.at(-1)?.created_at||record.created_at)<minAgeMs)continue;
+  const attempts=[record,...(record.replacements||[])];let mined=false;for(const a of attempts)if(await provider.getTransactionReceipt(a.hash)){mined=true;break;}if(mined)continue;
+  const last=Transaction.from(attempts.at(-1).raw);if(last.type!==2)continue;
+  const fee=(last.maxFeePerGas*125n+99n)/100n,tip=(last.maxPriorityFeePerGas*125n+99n)/100n;if(fee>cap||tip>tipCap){results.push({id:record.id,status:'cap_reached'});continue;}
+  try{const result=await replacePendingTransaction({id:record.id,transactions,provider,signer:await signerForRecord(record),authorize,maxFeePerGas:fee,maxPriorityFeePerGas:tip});results.push({id:record.id,status:'prepared',hash:result.hash});}catch(error){results.push({id:record.id,status:'error',error:error.message});}
+ }return results;};
+}
+module.exports.createFeeReplacementWorker=createFeeReplacementWorker;
+/** Concrete transaction-only delegation policy, evaluated again for every signature. */
+function createDelegationAuthorizer({expiresAt,chainIds,contracts,selectors,maxValue='0',maxFeePerGas,maxGasLimit,now=()=>Date.now()}={}){
+ check(Number.isSafeInteger(expiresAt)&&Array.isArray(chainIds)&&Array.isArray(contracts)&&Array.isArray(selectors),'Explicit delegation bounds required');
+ const allowed=new Set(contracts.map(a=>getAddress(a))),methods=new Set(selectors);
+ const valueCap=BigInt(maxValue),feeCap=BigInt(maxFeePerGas),gasCap=BigInt(maxGasLimit);
+ return async context=>{if(context.kind!=='transaction'||Math.floor(now()/1000)>=expiresAt)return false;const t=context.transaction;
+  if(!chainIds.map(String).includes(String(t.chainId))||!t.to||!allowed.has(getAddress(t.to))||!methods.has((t.data||'0x').slice(0,10)))return false;
+  if(BigInt(t.value||0)>valueCap||BigInt(t.gasLimit||0)>gasCap||BigInt(t.maxFeePerGas||t.gasPrice||0)>feeCap)return false;
+  return true;
+ };
+}
+module.exports.createDelegationAuthorizer=createDelegationAuthorizer;
+/** Incremental confirmed log indexer. Consumers must deduplicate key and handle orphan notifications. */
+function createEscrowIndexer({provider,chainId,contractAddress,confirmations,fromBlock,kv,onEvent,onReorg,batchSize=1000}={}){
+ check(Number.isSafeInteger(fromBlock)&&fromBlock>=0&&Number.isSafeInteger(confirmations)&&confirmations>0&&Number.isSafeInteger(batchSize)&&batchSize>0&&batchSize<=10000,'Explicit indexing bounds required');
+ check(kv&&typeof onEvent==='function'&&typeof onReorg==='function','Durable cursor and callbacks required');
+ const address=getAddress(contractAddress),iface=new Interface(ESCROW_ABI),scope=chainId+':'+address;
+ return async()=>{
+  check(Number((await provider.getNetwork()).chainId)===chainId,'Indexer RPC chain mismatch');
+  let cursor=await kv.get('index-cursors',scope);
+  if(cursor){const block=await provider.getBlock(cursor.block);if(!block||block.hash!==cursor.hash){await onReorg({scope,previous:cursor});
+    for(const row of await kv.list('index-events:'+scope)){const b=await provider.getBlock(row.value.block_number);if(!b||b.hash!==row.value.block_hash)await kv.put('index-events:'+scope,row.id,{...row.value,orphaned:true});}
+    cursor=null;await kv.put('index-cursors',scope,null);
+  }}
+  const head=await provider.getBlock('latest'),start=cursor?cursor.block+1:fromBlock,end=Math.min(head.number-confirmations+1,start+batchSize-1);if(end<start)return {indexed:0};
+  const scanEnd=await provider.getBlock(end);
+  const logs=await provider.getLogs({address,fromBlock:start,toBlock:end});let indexed=0;
+  for(const log of logs){let parsed;try{parsed=iface.parseLog(log);}catch{continue;}if(!parsed)continue;
+   const key=log.blockHash+':'+log.transactionHash+':'+log.index;
+   const old=await kv.get('index-events:'+scope,key);if(old?.delivered&&!old.orphaned)continue;
+   const event={key,chain_id:String(chainId),contract:address,block_number:log.blockNumber,block_hash:log.blockHash,transaction_hash:log.transactionHash,log_index:log.index,event:parsed.name,args:parsed.fragment.inputs.reduce((obj,input,i)=>{const value=parsed.args[i];obj[input.name]=typeof value==='bigint'?value.toString():value;return obj;},{}),orphaned:false,delivered:false};
+   await kv.put('index-events:'+scope,key,event);await onEvent(event);await kv.put('index-events:'+scope,key,{...event,delivered:true});indexed++;
+  }
+  const endBlock=await provider.getBlock(end);
+  if(!endBlock||endBlock.hash!==scanEnd.hash){await onReorg({scope,during_scan:true});for(const row of await kv.list('index-events:'+scope)){const block=await provider.getBlock(row.value.block_number);if(!block||block.hash!==row.value.block_hash)await kv.put('index-events:'+scope,row.id,{...row.value,orphaned:true});}return {indexed,reorg:true};}
+  await kv.put('index-cursors',scope,{block:end,hash:endBlock.hash});return {indexed,through:end};
+ };
+}
+module.exports.createEscrowIndexer=createEscrowIndexer;

package/src/operations/application.cjs

@@ -0,0 +1,40 @@
+'use strict';
+const {createWorkflowHandler}=require('../workflow.cjs');
+function createChatTools({workflow,store,queue,actor}={}){
+ const {enqueueRunningJobs}=require('./index.cjs');
+ const act=(action)=>async({job_id,input={},idempotency_key})=>workflow.act(job_id,action,input,{actor,idempotencyKey:idempotency_key});
+ return {
+  send_job_offer:async({id,worker_id,verifier_id,arbitrator_id,terms,metadata={}})=>{
+   let job=await workflow.create({id,participants:{requester:actor,worker:worker_id,verifier:verifier_id,arbitrator:arbitrator_id},metadata},actor);
+   if(terms)job=await workflow.act(job.id,'quote',{terms},{actor,idempotencyKey:'initial_quote'});return job;
+  },
+  propose_quote:act('quote'),accept_quote:act('accept'),fund_escrow:act('fund'),submit_job:act('submit'),verify_job:act('verify'),release_escrow:act('release'),refund_escrow:act('refund'),dispute_job:act('dispute'),resolve_job:act('resolve'),timeout_job:act('timeout'),propose_settlement:act('propose_settlement'),counter_settlement:act('counter_settlement'),accept_settlement:act('accept_settlement'),request_cancellation:act('propose_settlement'),cancel_job:act('cancel'),
+  work_on_job:async(input)=>{const job=await act('start')(input);if(!job.pending&&job.state==='running')await enqueueRunningJobs({store,queue});return job;}
+ };
+}
+function createApplicationHandler({workflow,store,queue,authenticate,revalidate,consentFor,settlementConsentFor,legacyState=async()=>({}),authorityHandler,basePath='/api/a423'}={}){
+ const {createEventStream,freshReceipts,renderReceiptPdf}=require('./index.cjs');
+ const protocol=createWorkflowHandler({workflow,authenticate,basePath});const events=createEventStream({store,authenticate});
+ return async request=>{
+  const path=new URL(request.url).pathname;
+  if(path.startsWith('/api/a423-auth/')&&authorityHandler)return authorityHandler(request);
+  if(path.startsWith(basePath+'/'))return protocol(request);
+  if(request.method!=='GET')return Response.json({error:'not found'},{status:404});
+  if(path==='/api/a423-events')return events(request);
+  const actor=await authenticate(request);if(!actor)return Response.json({error:'unauthenticated'},{status:401});
+  try{
+   if(path==='/api/state'){
+    const jobs=await Promise.all((await store.list({actor,limit:1000})).map(async job=>({...job,safety:await store.getSafety(job.id)})));const wallet_transactions=jobs.flatMap(j=>j.evidence.filter(e=>e.evidence.transaction_hash).map(e=>({job_id:j.id,action:e.action,...e.evidence})));
+    return Response.json({...await legacyState(actor),a423:{jobs,wallet_transactions}},{headers:{'cache-control':'no-store'}});
+   }
+   const receipt=/^\/api\/a423-receipts\/([A-Za-z0-9_-]{1,128})(\.pdf)?$/.exec(path);
+   if(receipt){const data=await freshReceipts({workflow,id:receipt[1],actor,revalidate});if(receipt[2])return new Response(Buffer.from(await renderReceiptPdf(data)),{headers:{'content-type':'application/pdf','cache-control':'no-store'}});return Response.json(data,{headers:{'cache-control':'no-store'}});}
+   const closing=/^\/api\/a423-settlement-consent\/([A-Za-z0-9_-]{1,128})$/.exec(path);
+   if(closing){const job=await workflow.get(closing[1],actor);if(![job.participants.requester,job.participants.worker].includes(actor))return Response.json({error:'settlement party required'},{status:403});if(!settlementConsentFor)throw Error('Settlement consent not configured');const typed=await settlementConsentFor(job);return Response.json(JSON.parse(JSON.stringify(typed,(_,v)=>typeof v==='bigint'?v.toString():v)),{headers:{'cache-control':'no-store'}});}
+   const consent=/^\/api\/a423-worker-consent\/([A-Za-z0-9_-]{1,128})$/.exec(path);
+   if(consent){const job=await workflow.get(consent[1],actor);if(job.participants.worker!==actor)return Response.json({error:'worker required'},{status:403});if(!consentFor)throw Error('Wallet consent not configured');const typed=await consentFor(job);return Response.json(JSON.parse(JSON.stringify(typed,(_,v)=>typeof v==='bigint'?v.toString():v)),{headers:{'cache-control':'no-store'}});}
+   return Response.json({error:'not found'},{status:404});
+  }catch(error){return Response.json({error:error.code||'EVIDENCE_OR_CONFIGURATION_UNAVAILABLE'},{status:error.code==='NOT_FOUND'?404:503});}
+ };
+}
+module.exports={createChatTools,createApplicationHandler};

package/src/operations/factory.cjs

@@ -0,0 +1,33 @@
+'use strict';
+const {createWorkflow,hashAgreement}=require('../workflow.cjs');
+const {createCredentialAuthenticator,createAuthorityHandler}=require('../authority/index.cjs');
+function createEscrowApplication({storage,authority,escrows,signerFor,addressFor,limitsFor,approveSigning,validateArtifact,execute,keeperEnabled=false,allowAuthorityRequest=async()=>false,requireIndependentArbitrator=true}={}){
+ const {createEscrowRegistry,createEvidenceRevalidator,escrowTerms,workerConsent,settlementConsent,escrowTransitions}=require('../escrow/index.cjs');
+ const {validateTask,validateEscrowEvidence,createSpendingAuthorizer,createExpiryAdapter,createApplicationHandler,createChatTools}=require('./index.cjs');
+ if(!storage||!authority||!Array.isArray(escrows)||!escrows.length||typeof approveSigning!=='function'||typeof limitsFor!=='function')throw new TypeError('Explicit storage, authority, escrow configurations and spending/signing approvals required');
+ const registry=new Map(escrows.map(c=>[String(c.chainId)+':'+c.contractAddress.toLowerCase(),c]));
+ const configFor=job=>{const e=job.agreement?.terms.escrow;const c=registry.get(e?.chain_id+':'+e?.contract?.toLowerCase());if(!c)throw Error('Unregistered escrow');return c;};
+ const checkPolicy=async context=>{
+  if(typeof authority.isActive!=='function'||await authority.isActive(context.actor)!==true)return false;
+  if((await storage.jobs.getSafety(context.job.id))?.blocked)return false;
+  const e=context.job.agreement.terms.escrow;
+  if(requireIndependentArbitrator&&[e.payer,e.worker,e.verifier].map(a=>a.toLowerCase()).includes(e.arbitrator.toLowerCase()))return false;
+  return await approveSigning(context)===true;
+ };
+ const authorizeTransaction=createSpendingAuthorizer({spending:storage.spending,limitsFor,authorize:checkPolicy});
+ const adapters=createEscrowRegistry(escrows.map(c=>({...c,signerFor,addressFor,transactions:storage.transactions,authorizeTransaction,validateArtifact})));
+ const workflow=createWorkflow({store:storage.jobs,adapters:{...adapters,expire:createExpiryAdapter()},transitions:escrowTransitions,
+  authorize:async({actor})=>authority.isActive(actor),
+  validateTerms:terms=>{validateTask(terms.task);const job={id:'terms_validation',agreement:{terms,hash:hashAgreement(terms)}};escrowTerms(job,configFor(job));},
+  validateEvidence:({evidence})=>{if(evidence.transaction_hash)validateEscrowEvidence(evidence);}
+ });
+ const validators=new Map(escrows.map(c=>[String(c.chainId)+':'+c.contractAddress.toLowerCase(),createEvidenceRevalidator(c)]));
+ const revalidate=(job,evidence)=>validators.get(String(configFor(job).chainId)+':'+configFor(job).contractAddress.toLowerCase())(job,evidence);
+ const authenticate=createCredentialAuthenticator({authority});
+ const applicationOptions={workflow,store:storage.jobs,queue:storage.queue,authenticate,revalidate,consentFor:async job=>workerConsent(job,configFor(job)),settlementConsentFor:async job=>settlementConsent(job,configFor(job)),authorityHandler:createAuthorityHandler({authority,allowRequest:allowAuthorityRequest})};
+ const workerOptions={authority,actorFor:async job=>job.pending?.actor||job.participants.requester,allowExecute:keeperEnabled,
+  execute,beforeExecute:async job=>{await workflow.assertSafe(job.id,job.participants.worker);if(!await authority.isActive(job.participants.worker))return false;const result=await adapters.start.execute({job,input:{},operation:{actor:job.participants.worker}});return result.status==='confirmed';}
+ };
+ return {workflow,applicationOptions,workerOptions,handler:createApplicationHandler(applicationOptions),chatTools:actor=>createChatTools({workflow,store:storage.jobs,queue:storage.queue,actor})};
+}
+module.exports={createEscrowApplication};

package/src/operations/index.cjs

@@ -0,0 +1,106 @@
+'use strict';
+const {createHash,createHmac,randomUUID}=require('node:crypto');
+const hash=x=>createHash('sha256').update(x).digest('hex');
+function assert(ok,message){if(!ok)throw new TypeError(message);}
+function validateTask(task){
+ assert(task&&typeof task==='object'&&!Array.isArray(task),'Task required');
+ for(const name of ['id','type','description'])assert(typeof task[name]==='string'&&task[name].trim()&&task[name].length<=16000,'Invalid task '+name);
+ assert(Array.isArray(task.deliverables)&&task.deliverables.length>0&&task.deliverables.length<=100,'Deliverables required');
+ const ids=new Set();for(const d of task.deliverables){assert(d&&typeof d.id==='string'&&!ids.has(d.id),'Unique deliverable IDs required');ids.add(d.id);assert(typeof d.media_type==='string'&&typeof d.description==='string','Deliverable media_type and description required');}
+ assert(task.acceptance&&typeof task.acceptance.validator==='string'&&typeof task.acceptance.version==='string'&&task.acceptance.criteria&&typeof task.acceptance.criteria==='object','Versioned acceptance criteria required');
+ JSON.stringify(task);return structuredClone(task);
+}
+function validateEscrowEvidence(e){
+ assert(e&&typeof e==='object','Escrow evidence required');
+ for(const key of ['chain_id','amount','worker_paid'])assert(typeof e[key]==='string'&&/^(0|[1-9][0-9]*)$/.test(e[key]),'Invalid evidence '+key);
+ for(const key of ['contract','token','payer','worker','verifier','arbitrator'])assert(/^0x[0-9a-fA-F]{40}$/.test(e[key]),'Invalid evidence '+key);
+ for(const key of ['job_id','agreement_hash','transaction_hash','block_hash','result_hash'])assert(/^0x[0-9a-fA-F]{64}$/.test(e[key]),'Invalid evidence '+key);
+ assert(Number.isSafeInteger(e.block_number)&&e.block_number>=0&&Number.isSafeInteger(e.confirmations)&&e.confirmations>0,'Invalid evidence block');
+ assert(['Funded','Submitted','Verified','Disputed','Settled','SettlementProposed'].includes(e.event),'Invalid evidence event');
+ assert(Number.isInteger(e.state)&&e.state>=1&&e.state<=8&&BigInt(e.worker_paid)<=BigInt(e.amount),'Invalid evidence allocation/state');
+ return structuredClone(e);
+}
+function createSpendingAuthorizer({spending,limitsFor,authorize}={}){
+ assert(spending&&typeof limitsFor==='function'&&typeof authorize==='function','Spending store, limitsFor and authorize required');
+ return async context=>{
+  if(await authorize(context)!==true)return false;
+  if(['fund','approve','approve_zero'].includes(context.step)){
+   const e=context.job.agreement.terms.escrow,limits=await limitsFor(context);
+   try {await spending.reserve({...limits,id:hash(JSON.stringify([e.chain_id,e.contract.toLowerCase(),context.job.id])),scope:JSON.stringify([e.chain_id,e.payer.toLowerCase(),e.token.toLowerCase()]),amount:e.amount});}catch(error){if(error.code==='SPENDING_LIMIT_EXCEEDED')return false;throw error;}
+  }
+  return true;
+ };
+}
+/** Resume is deliberately separate from observe-only reconcile; caller must authorize execution. */
+async function runMaintenanceOnce({workflow,store,actorFor,allowExecute=false,now=Date.now()}={}){
+ const results=[];let after='';
+ while(true){const jobs=await store.list({after,limit:100});if(!jobs.length)break;after=jobs.at(-1).id;
+  for(const job of jobs){try{
+   const actor=await actorFor(job);if(!actor)continue;
+   let result=job;
+   if(job.pending){result=await workflow.reconcile(job.id,actor);if(result.pending&&allowExecute)result=await workflow.resume(job.id,actor);}
+   else if(job.agreement){const e=job.agreement.terms.escrow;const seconds=Math.floor(now/1000);let action;
+    if(e&&(['funded','running'].includes(job.state)||(['settlement_negotiation','disputed'].includes(job.state)&&!job.submission))&&seconds>e.work_deadline)action='timeout';
+    if(e&&['submitted','verified','disputed','settlement_negotiation'].includes(job.state)&&seconds>e.resolution_deadline)action='timeout';
+    const expiry=job.agreement.terms.expires_at;
+    if(['quoted','accepted'].includes(job.state)&&Number.isSafeInteger(expiry)&&seconds>expiry)action='expire';
+    if(action&&allowExecute)result=await workflow.act(job.id,action,{}, {actor,idempotencyKey:'keeper_'+hash(job.id+':'+action)});
+   }
+   results.push({id:job.id,state:result.state,pending:!!result.pending});
+  }catch(error){results.push({id:job.id,error:error.message});}}
+ }
+ return results;
+}
+function createExpiryAdapter({now=()=>Date.now()}={}){const run=async({job})=>{
+ const expiry=job.agreement?.terms.expires_at;
+ if(!Number.isSafeInteger(expiry)||Math.floor(now()/1000)<=expiry)return {status:'rejected',reason:'Agreement has not expired'};
+ return {status:'confirmed',evidence:{expires_at:expiry,observed_at:new Date(now()).toISOString()}};
+};return {execute:run,reconcile:run};}
+async function runExecutionOnce({workflow,queue,execute,beforeExecute,leaseMs=30000}={}){
+ const item=await queue.claim({kind:'execution',leaseMs});if(!item)return null;
+ const controller=new AbortController();
+ const heartbeat=setInterval(async()=>{try{if(!await queue.heartbeat(item.id,item.lease,{leaseMs}))throw Error('Execution lease lost');const current=await workflow.assertSafe(item.payload.job_id,item.payload.actor);if(current.state!=='running')throw Error('Work paused');}catch(error){controller.abort(error);}},Math.max(1,Math.min(1000,Math.floor(leaseMs/3))));
+ try{
+  let result=item.result;
+  if(!result){const job=await workflow.assertSafe(item.payload.job_id,item.payload.actor);assert(job.state==='running','Work requires running state');validateTask(job.agreement.terms.task);assert(typeof beforeExecute==='function'&&await beforeExecute(job)===true,'Execution eligibility check required');result=await execute({job,idempotencyKey:item.id,signal:controller.signal});assert(await queue.checkpoint(item.id,item.lease,result),'Execution lease lost');}
+  assert(typeof result.result_hash==='string','Execution must return artifact commitment');
+  const job=await workflow.act(item.payload.job_id,'submit',result,{actor:item.payload.actor,idempotencyKey:'execution_'+hash(item.id)});
+  assert(await queue.complete(item.id,item.lease,{job_id:job.id,state:job.state}),'Execution lease lost');return job;
+ }catch(error){await queue.retry(item.id,item.lease,{delayMs:1000});throw error;}finally{clearInterval(heartbeat);}
+}
+async function enqueueRunningJobs({store,queue}){let after='',count=0;while(true){const jobs=await store.list({after,limit:100});if(!jobs.length)break;after=jobs.at(-1).id;for(const j of jobs)if(j.state==='running'&&!j.pending){const event=j.events.filter(e=>e.type==='start.confirmed').at(-1);if(event&&await queue.enqueue({id:'execution_'+hash(j.id+':'+event.sequence),kind:'execution',payload:{job_id:j.id,actor:j.participants.worker}}))count++;}}return count;}
+function createEventStream({store,authenticate,pollMs=1000,maxDurationMs=25000}={}){
+ return async request=>{
+  const actor=await authenticate(request);if(!actor)return Response.json({error:'unauthenticated'},{status:401});
+  let cursor=Number(request.headers.get('last-event-id')||new URL(request.url).searchParams.get('after')||0);if(!Number.isSafeInteger(cursor)||cursor<0)return Response.json({error:'invalid cursor'},{status:400});
+  let closed=false,timer;const encoder=new TextEncoder(),began=Date.now();
+  const stream=new ReadableStream({start(controller){const tick=async()=>{if(closed)return;try{const events=await store.events({actor,after:cursor,limit:100});for(const event of events){cursor=event.cursor;controller.enqueue(encoder.encode(`id: ${cursor}\nevent: a423\ndata: ${JSON.stringify(event)}\n\n`));}if(request.signal.aborted||Date.now()-began>=maxDurationMs){closed=true;controller.close();return;}controller.enqueue(encoder.encode(': heartbeat\n\n'));timer=setTimeout(tick,pollMs);}catch(e){closed=true;controller.error(e);}};void tick();},cancel(){closed=true;clearTimeout(timer);}});
+  return new Response(stream,{headers:{'content-type':'text/event-stream','cache-control':'no-store','x-accel-buffering':'no'}});
+ };
+}
+function createWebhookDispatcher({queue,kv,subscriptions,secretFor,fetch:fetchImpl=globalThis.fetch,timeoutMs=10000}={}){
+ assert(queue&&kv&&Array.isArray(subscriptions)&&typeof secretFor==='function','Webhook configuration required');
+ const targets=new Map();for(const s of subscriptions){const u=new URL(s.url);assert(u.protocol==='https:'&&!u.username&&!u.password&&!u.hash,'Use explicitly configured HTTPS webhook destinations');targets.set(s.id,{...s,url:u.href});}
+ return {
+  async project(store){for(const s of targets.values()){const events=await store.events({actor:s.actor,after:(await kv.get('webhook-cursors',s.id))?.cursor||s.after||0,limit:1000});for(const event of events){await queue.enqueue({id:'webhook_'+hash(s.id+':'+event.cursor),kind:'webhook',payload:{subscription:s.id,event}});await kv.put('webhook-cursors',s.id,{cursor:event.cursor});}}},
+  async deliverOne(){const item=await queue.claim({kind:'webhook',leaseMs:timeoutMs+5000});if(!item)return null;try{
+   const target=targets.get(item.payload.subscription);assert(target,'Subscription removed');const body=JSON.stringify(item.payload.event),timestamp=String(Math.floor(Date.now()/1000));const secret=await secretFor(target.id);assert(typeof secret==='string'&&secret.length>=32,'Webhook signing secret must have at least 32 characters');
+   const signature=createHmac('sha256',secret).update(timestamp+'.'+body).digest('hex');const response=await fetchImpl(target.url,{method:'POST',body,headers:{'content-type':'application/json','a423-delivery-id':item.id,'a423-timestamp':timestamp,'a423-signature':'v1='+signature},redirect:'error',signal:AbortSignal.timeout(timeoutMs)});
+   await response.body?.cancel();if(!response.ok)throw Error('Webhook HTTP '+response.status);await queue.complete(item.id,item.lease,{status:response.status});return {id:item.id,status:'delivered'};
+  }catch(error){await queue.retry(item.id,item.lease,{delayMs:Math.min(3600000,1000*2**Math.min(item.attempts,12))});return {id:item.id,status:'retry',error:error.message};}}
+ };
+}
+async function watchEvidenceOnce({store,revalidate}){const results=[];let after='';while(true){const jobs=await store.list({after,limit:100});if(!jobs.length)break;after=jobs.at(-1).id;for(const job of jobs){if(!job.evidence.length)continue;const checks=[];for(const item of job.evidence)if(item.evidence.transaction_hash){try{checks.push(await revalidate(job,item.evidence));}catch(error){checks.push({status:'unavailable',message:'Evidence provider unavailable'});}}
+ const blocked=checks.some(c=>c.status!=='valid');const safety={blocked,checks,checked_at:new Date().toISOString()};await store.setSafety(job.id,safety);results.push({id:job.id,...safety});}}return results;}
+async function freshReceipts({workflow,id,actor,revalidate}){const job=await workflow.get(id,actor);for(const p of job.negotiation?.history||[]){const canonical=require('../closing.cjs').settlementProposal(job,{worker_amount:p.worker_amount,payer_amount:p.payer_amount,expected_revision:p.escrow_version-1,expires_at:p.expires_at,reason:p.reason,claims:p.claims});assert(canonical.proposal_hash===p.proposal_hash,'Stored settlement claims changed');}const checks=[];for(const item of job.evidence)if(item.evidence.transaction_hash){const result=await revalidate(job,item.evidence);assert(result.status==='valid','Receipt evidence is not currently valid: '+result.status);checks.push(result);}return {...await workflow.receipts(id,actor),revalidated_at:new Date().toISOString(),checks};}
+async function renderReceiptPdf(receipt){const {PDFDocument,StandardFonts}=require('pdf-lib');const pdf=await PDFDocument.create(),font=await pdf.embedFont(StandardFonts.Courier);let page,y;const newPage=()=>{page=pdf.addPage([595,842]);y=800;};newPage();const text=JSON.stringify(receipt,null,2).replace(/[^\x20-\x7e\n]/g,'?');for(const line of ['A423 Evidence Receipt',...text.split('\n')])for(let i=0;i<Math.max(1,line.length);i+=88){if(y<40)newPage();page.drawText(line.slice(i,i+88),{x:32,y,size:9,font});y-=12;}return pdf.save();}
+function planLegacyMigration(records){return records.map(record=>({id:record.id,state:record.state,automatic:false,reason:['funded','running','submitted','verified','paid','settlement_pending','completed'].includes(String(record.state).toLowerCase())?'Existing custody/evidence must stay with original contract; do not relabel':'Requires reviewed participant and accepted-terms mapping; create a new job with provenance'}));}
+module.exports={validateTask,validateEscrowEvidence,createSpendingAuthorizer,runMaintenanceOnce,createExpiryAdapter,runExecutionOnce,enqueueRunningJobs,createEventStream,createWebhookDispatcher,watchEvidenceOnce,freshReceipts,renderReceiptPdf,planLegacyMigration};
+
+async function migrateUnfundedLegacy({records,workflow,map,actor}){
+ const created=[];for(const source of records){assert(['offered','draft','quoted','accepted'].includes(String(source.state).toLowerCase()),'Funded/terminal legacy records cannot be automatically migrated');const target=await map(structuredClone(source));assert(target.id&&target.id!==source.id,'Use a new explicit job ID');const job=await workflow.create({...target,metadata:{...target.metadata,migration:{source_id:source.id,source_state:source.state,source_hash:hash(JSON.stringify(source)),accepted_terms_carried:false}}},actor);created.push(job);}return created;
+}
+module.exports.migrateUnfundedLegacy=migrateUnfundedLegacy;
+Object.assign(module.exports,require('./application.cjs'));
+
+Object.assign(module.exports,require('./factory.cjs'));