@taskforest/dark-forest 0.1.0 → 0.1.2

package/README.md

@@ -1,9 +1,67 @@
 # @taskforest/dark-forest
 
-Dark Forest payment helpers for TaskForest.
+Private machine payments for TaskForest.
 
-This package is intentionally separate from `@taskforest/sdk`.
-Use it when you need MagicBlock PER delegation, payment-channel orchestration, or Dark Forest demo flows.
+`@taskforest/dark-forest` is the payment layer for running metered agent payments through a private execution environment.
+It helps you combine:
+
+- TaskForest jobs,
+- MPP-style metered payment flows,
+- MagicBlock PER delegation,
+- private settlement tracking.
+
+If `@taskforest/sdk` is the layer for posting and managing work, `@taskforest/dark-forest` is the layer for paying for that work privately.
+
+## What It Does
+
+This package gives you helpers for:
+
+- creating a Dark Forest escrow wrapper for a TaskForest job,
+- delegating payment execution to MagicBlock PER,
+- tracking metered per-request or per-call payment sessions,
+- recording final settlement on-chain,
+- reading escrow and settlement state back into your app.
+
+This is designed for private machine-to-machine payment flows where agents are paid incrementally, but you do not want every intermediate payment signal exposed publicly.
+
+Session tracking defaults to an in-memory store for fast starts and demos.
+For production, you can inject your own session store so metering survives process restarts.
+
+## Why Use It
+
+Standard machine payment flows are useful, but public payment trails can leak strategy:
+
+- how often an agent is called,
+- what endpoints are hot,
+- how much a task is costing in real time,
+- which workers or tools are being used.
+
+Dark Forest is for the case where you want MPP-style metering, but with privacy around the execution and payment flow.
+
+You can think of it as:
+
+- MPP for agent payments,
+- with private execution routing,
+- and on-chain settlement boundaries.
+
+## Relationship To MPP
+
+`@taskforest/dark-forest` is compatible with the idea of a machine payment protocol:
+
+- open a payment session,
+- meter usage as requests are served,
+- accumulate payment state,
+- settle the final amount.
+
+The difference is that Dark Forest is focused on private machine payments.
+
+Instead of exposing the full payment trail publicly, your app can:
+
+- delegate into PER,
+- track incremental usage privately,
+- commit the final settlement outcome on-chain.
+
+That makes it a good fit for agent markets, private inference, paid tools, private bidding, and metered workflows where visibility itself is sensitive.
 
 ## Install
 
@@ -11,9 +69,236 @@ Use it when you need MagicBlock PER delegation, payment-channel orchestration, o
 npm install @taskforest/dark-forest
 ```
 
-## Scope
+Typical companion packages:
+
+```bash
+npm install @coral-xyz/anchor @solana/web3.js
+```
+
+## What You Get
+
+```ts
+import {
+  DarkForestPayments,
+  DARK_FOREST_PROGRAM_ID,
+  ESCROW_SEED,
+  LocalStorageSessionStore,
+  MemorySessionStore,
+  SETTLEMENT_SEED,
+  PER_ENDPOINTS,
+  TEE_VALIDATORS,
+} from '@taskforest/dark-forest'
+```
+
+- `DarkForestPayments`: helper class for escrow, delegation, session metering, and settlement.
+- `MemorySessionStore`: default in-memory session store. Replace this in production with your own persistent implementation.
+- `LocalStorageSessionStore`: browser-persistent session store for demos and lightweight apps.
+- `DARK_FOREST_PROGRAM_ID`: Dark Forest payments program ID.
+- `ESCROW_SEED` / `SETTLEMENT_SEED`: PDA seeds for escrow and settlement records.
+- `PER_ENDPOINTS`: known PER endpoints.
+- `TEE_VALIDATORS`: known validator public keys.
+
+## Basic Setup
+
+```ts
+import { AnchorProvider } from '@coral-xyz/anchor'
+import { Keypair } from '@solana/web3.js'
+import { DarkForestPayments } from '@taskforest/dark-forest'
+import paymentsIdl from './idl/taskforest_payments.json'
+
+const wallet = Keypair.generate()
+const provider = new AnchorProvider(connection, { publicKey: wallet.publicKey } as never, {
+  commitment: 'confirmed',
+})
+
+const darkForest = new DarkForestPayments(provider, paymentsIdl as never)
+```
+
+## Production Session Store
+
+The SDK now accepts a pluggable session store:
+
+```ts
+import { DarkForestPayments, type SessionStore } from '@taskforest/dark-forest'
+
+const sessionStore: SessionStore = {
+  async get(escrowId) {
+    return await db.loadSession(escrowId)
+  },
+  async set(session) {
+    await db.saveSession(session)
+  },
+  async delete(escrowId) {
+    await db.deleteSession(escrowId)
+  },
+}
+
+const darkForest = new DarkForestPayments(provider, paymentsIdl as never, {
+  sessionStore,
+})
+```
+
+That lets you meter private machine payments durably instead of relying on process memory.
+
+For browser demos or lightweight clients:
+
+```ts
+import { DarkForestPayments, LocalStorageSessionStore } from '@taskforest/dark-forest'
+
+const darkForest = new DarkForestPayments(provider, paymentsIdl as never, {
+  sessionStore: new LocalStorageSessionStore(window.localStorage),
+})
+```
+
+## Example: Create Escrow For A TaskForest Job
+
+```ts
+import { PublicKey } from '@solana/web3.js'
+
+const jobPubkey = new PublicKey('...')
+
+const tx = await darkForest.createEscrowWrapper(
+  101,
+  jobPubkey,
+  0.25,
+)
+
+console.log('escrow tx:', tx)
+```
+
+This links a Dark Forest payment wrapper to a TaskForest job.
+
+## Example: Delegate To PER
+
+```ts
+import { TEE_VALIDATORS } from '@taskforest/dark-forest'
+
+const tx = await darkForest.delegateToPer(101, TEE_VALIDATORS.devnet)
+console.log('delegate tx:', tx)
+```
+
+This moves the payment flow into a private execution environment.
+
+## Example: Start A Private Metered Session
+
+```ts
+import { PER_ENDPOINTS } from '@taskforest/dark-forest'
+
+const session = await darkForest.startPrivateSession(101, jobPubkey, {
+  agentEndpoint: 'https://agent.example.com',
+  token: 'SOL',
+  budgetLamports: 50_000_000,
+  perEndpoint: PER_ENDPOINTS.devnet,
+})
+
+console.log(session.sessionId)
+```
+
+This is the main private machine payment entry point:
+
+- create escrow,
+- delegate to PER,
+- begin metered session tracking.
+
+## Example: Record Incremental Usage
+
+```ts
+await darkForest.recordPayment(101, 500_000)
+await darkForest.recordPayment(101, 500_000)
+
+const session = darkForest.getActiveSession(101)
+console.log(session?.requestCount)
+console.log(session?.totalPaid)
+```
+
+Use this for:
+
+- pay-per-request,
+- pay-per-tool-call,
+- pay-per-inference,
+- metered agent execution.
+
+## Example: Off-Chain TDX Verification Boundary
+
+Full Intel TDX quote and certificate-chain verification should happen off-chain.
+The on-chain program verifies a signed attestation envelope derived from a successful verifier result.
+
+```ts
+import {
+  JsonTdxQuoteVerifier,
+  buildVerifiedAttestationEnvelope,
+  DarkForestPayments,
+} from '@taskforest/dark-forest'
+
+const verifier = new JsonTdxQuoteVerifier(TEE_VALIDATORS.devnet)
+const verified = await verifier.verifyQuote(rawQuoteBytes, {
+  allowedMrTd: ['...'],
+  allowedRtmr0: ['...'],
+  requireCertificateChain: true,
+  trustedRootFingerprints: ['...'],
+})
+
+const envelope = buildVerifiedAttestationEnvelope(
+  101,
+  jobPubkey,
+  sessionIdBytes,
+  verified,
+)
+
+const report = DarkForestPayments.buildAttestationReport(envelope)
+const sigIx = DarkForestPayments.buildAttestationSignatureInstruction(validatorSigner, report)
+
+await darkForest.verifyTeeAttestation(101, report, envelope.teePubkey, sigIx)
+```
+
+This gives you a production-safe split:
+
+- off-chain verifier handles quote parsing, certificate-chain validation, collateral, and measurement policy
+- on-chain program enforces a signed, state-bound attestation result
+
+## Example: Close Session And Settle
+
+```ts
+const settleTx = await darkForest.closeSession(101)
+console.log('settlement tx:', settleTx)
+```
+
+This commits the final settlement amount after the metered session is complete.
+
+## Example: Read Escrow / Settlement State
+
+```ts
+const escrow = await darkForest.getEscrow(101)
+const settlement = await darkForest.getSettlement(101)
+
+console.log(escrow?.status)
+console.log(settlement?.totalPaid)
+```
+
+## Example: Derive PDAs
+
+```ts
+import { DarkForestPayments } from '@taskforest/dark-forest'
+
+const escrowPda = DarkForestPayments.escrowPda(101)
+const settlementPda = DarkForestPayments.settlementPda(101)
+```
+
+## Suggested Flow
+
+1. Create a job with TaskForest.
+2. Create a Dark Forest escrow wrapper for that job.
+3. Delegate payment execution into PER.
+4. Meter machine usage privately with `recordPayment()`.
+5. Close the session and record final settlement.
+6. Read settlement state for UI, reconciliation, or audits.
+
+## Best Fit
+
+This package is most useful when you are building:
 
-- Escrow wrapper helpers
-- PER endpoints and validator constants
-- MPP session orchestration helpers
-- Settlement state reads
+- private paid agents,
+- metered AI APIs,
+- private tool execution,
+- hidden bid or routing systems,
+- machine-to-machine payment flows where intermediate payment visibility is a disadvantage.

package/dist/__tests__/dark-forest.test.js

@@ -14,6 +14,19 @@ const index_1 = require("../index");
     strict_1.default.equal(index_1.PER_ENDPOINTS.devnet, 'https://tee.magicblock.app');
     strict_1.default.ok(index_1.TEE_VALIDATORS.devnet);
 });
+(0, node_test_1.default)('builds deterministic attestation report envelopes', () => {
+    const report = index_1.DarkForestPayments.buildAttestationReport({
+        escrowId: 42,
+        jobPubkey: index_1.DARK_FOREST_PROGRAM_ID,
+        validator: index_1.TEE_VALIDATORS.devnet,
+        teePubkey: Array(32).fill(7),
+        mppSessionId: Array(32).fill(9),
+        issuedAt: 100,
+        expiresAt: 200,
+    });
+    strict_1.default.equal(report.length, 160);
+    strict_1.default.equal(report.subarray(0, 4).toString('utf8'), 'TFAT');
+});
 (0, node_test_1.default)('derives deterministic escrow and settlement PDAs', () => {
     const escrowOne = index_1.DarkForestPayments.escrowPda(42);
     const escrowTwo = index_1.DarkForestPayments.escrowPda(42);
@@ -31,7 +44,7 @@ const index_1 = require("../index");
 });
 (0, node_test_1.default)('tracks an in-memory private session lifecycle', async () => {
     const payments = Object.create(index_1.DarkForestPayments.prototype);
-    payments.activeSessions = new Map();
+    payments.sessionStore = new index_1.MemorySessionStore();
     payments.createEscrowWrapper = async () => 'escrow-tx';
     payments.delegateToPer = async () => 'delegate-tx';
     payments.recordSettlement = async () => 'settlement-tx';
@@ -43,13 +56,13 @@ const index_1 = require("../index");
     });
     strict_1.default.equal(session.escrowId, 77);
     strict_1.default.equal(session.isActive, true);
-    strict_1.default.equal(payments.getActiveSession(77)?.requestCount, 0);
+    strict_1.default.equal((await payments.getActiveSession(77))?.requestCount, 0);
     await payments.recordPayment(77, 500000);
-    strict_1.default.equal(payments.getActiveSession(77)?.totalPaid, 500000);
-    strict_1.default.equal(payments.getActiveSession(77)?.requestCount, 1);
+    strict_1.default.equal((await payments.getActiveSession(77))?.totalPaid, 500000);
+    strict_1.default.equal((await payments.getActiveSession(77))?.requestCount, 1);
     const tx = await payments.closeSession(77);
     strict_1.default.equal(tx, 'settlement-tx');
-    strict_1.default.equal(payments.getActiveSession(77), undefined);
+    strict_1.default.equal(await payments.getActiveSession(77), undefined);
 });
 (0, node_test_1.default)('returns null for unreadable escrow and settlement accounts', async () => {
     const payments = Object.create(index_1.DarkForestPayments.prototype);
@@ -62,3 +75,38 @@ const index_1 = require("../index");
     strict_1.default.equal(await payments.getEscrow(5), null);
     strict_1.default.equal(await payments.getSettlement(5), null);
 });
+(0, node_test_1.default)('persists sessions in local storage compatible store', async () => {
+    const backing = new Map();
+    const storage = {
+        getItem(key) { return backing.get(key) ?? null; },
+        setItem(key, value) { backing.set(key, value); },
+        removeItem(key) { backing.delete(key); },
+        clear() { backing.clear(); },
+        key(index) { return Array.from(backing.keys())[index] ?? null; },
+        get length() { return backing.size; },
+    };
+    const store = new index_1.LocalStorageSessionStore(storage);
+    await store.set({ sessionId: 'abc', escrowId: 5, totalPaid: 7, requestCount: 2, isActive: true });
+    strict_1.default.equal((await store.get(5))?.sessionId, 'abc');
+    await store.delete(5);
+    strict_1.default.equal(await store.get(5), null);
+});
+(0, node_test_1.default)('verifies json-backed tdx quote claims against policy and builds attestation envelope', async () => {
+    const verifier = new index_1.JsonTdxQuoteVerifier(index_1.TEE_VALIDATORS.devnet);
+    const now = Math.floor(Date.now() / 1000);
+    const quote = Buffer.from(JSON.stringify({
+        teePubkey: Array(32).fill(3),
+        mrTd: 'abcd',
+        rtmr0: 'ef01',
+        issuedAt: now - 60,
+        expiresAt: now + 300,
+    }));
+    const verified = await verifier.verifyQuote(quote, {
+        allowedMrTd: ['abcd'],
+        allowedRtmr0: ['ef01'],
+    });
+    const envelope = (0, index_1.buildVerifiedAttestationEnvelope)(9, index_1.DARK_FOREST_PROGRAM_ID, Array(32).fill(4), verified);
+    strict_1.default.equal(envelope.escrowId, 9);
+    strict_1.default.equal(envelope.validator.toBase58(), index_1.TEE_VALIDATORS.devnet.toBase58());
+    strict_1.default.equal(envelope.teePubkey.length, 32);
+});

package/dist/index.d.ts

@@ -1,10 +1,9 @@
-/// <reference types="node" />
-/// <reference types="node" />
 import { AnchorProvider, type Idl } from '@coral-xyz/anchor';
-import { Connection, PublicKey } from '@solana/web3.js';
+import { Connection, type Keypair, PublicKey, type TransactionInstruction } from '@solana/web3.js';
+export * from './verifier';
 export declare const DARK_FOREST_PROGRAM_ID: PublicKey;
-export declare const ESCROW_SEED: Buffer;
-export declare const SETTLEMENT_SEED: Buffer;
+export declare const ESCROW_SEED: Buffer<ArrayBuffer>;
+export declare const SETTLEMENT_SEED: Buffer<ArrayBuffer>;
 export declare const TEE_VALIDATORS: {
     readonly mainnet: PublicKey;
     readonly devnet: PublicKey;
@@ -27,6 +26,26 @@ export type MppSessionState = {
     requestCount: number;
     isActive: boolean;
 };
+export interface SessionStore {
+    get(escrowId: number): Promise<MppSessionState | null>;
+    set(session: MppSessionState): Promise<void>;
+    delete(escrowId: number): Promise<void>;
+}
+export declare class MemorySessionStore implements SessionStore {
+    private sessions;
+    get(escrowId: number): Promise<MppSessionState | null>;
+    set(session: MppSessionState): Promise<void>;
+    delete(escrowId: number): Promise<void>;
+}
+export declare class LocalStorageSessionStore implements SessionStore {
+    private readonly storage;
+    private readonly prefix;
+    constructor(storage: Storage, prefix?: string);
+    private key;
+    get(escrowId: number): Promise<MppSessionState | null>;
+    set(session: MppSessionState): Promise<void>;
+    delete(escrowId: number): Promise<void>;
+}
 export interface EscrowState {
     escrowId: number;
     jobPubkey: PublicKey;
@@ -49,22 +68,36 @@ export interface SettlementState {
     settledAt: number;
     settlementHash: number[];
 }
+export interface TeeAttestationEnvelope {
+    escrowId: number;
+    jobPubkey: PublicKey;
+    validator: PublicKey;
+    teePubkey: number[];
+    mppSessionId: number[];
+    issuedAt: number;
+    expiresAt: number;
+}
+export interface DarkForestPaymentsOptions {
+    sessionStore?: SessionStore;
+}
 export declare class DarkForestPayments {
     private program;
     private provider;
-    private activeSessions;
-    constructor(provider: AnchorProvider, idl: Idl);
+    private sessionStore;
+    constructor(provider: AnchorProvider, idl: Idl, options?: DarkForestPaymentsOptions);
     connectToPer(endpoint?: string): Connection;
+    static buildAttestationReport(envelope: TeeAttestationEnvelope): Buffer;
+    static buildAttestationSignatureInstruction(validatorSigner: Keypair, report: Buffer): TransactionInstruction;
     createEscrowWrapper(escrowId: number, jobPubkey: PublicKey, depositSol: number, mppSessionId?: number[]): Promise<string>;
     delegateToPer(escrowId: number, validator?: PublicKey): Promise<string>;
-    verifyTeeAttestation(escrowId: number, attestationReport: Buffer, teePubkey: number[]): Promise<string>;
+    verifyTeeAttestation(escrowId: number, attestationReport: Buffer, teePubkey: number[], signatureInstruction?: TransactionInstruction): Promise<string>;
     recordSettlement(escrowId: number, totalPaidSol: number): Promise<string>;
     startPrivateSession(escrowId: number, jobPubkey: PublicKey, config: MppSessionConfig): Promise<MppSessionState>;
     recordPayment(escrowId: number, amountLamports: number): Promise<void>;
     closeSession(escrowId: number): Promise<string>;
+    getActiveSession(escrowId: number): Promise<MppSessionState | undefined>;
     getEscrow(escrowId: number): Promise<EscrowState | null>;
     getSettlement(escrowId: number): Promise<SettlementState | null>;
-    getActiveSession(escrowId: number): MppSessionState | undefined;
     static escrowPda(escrowId: number): PublicKey;
     static settlementPda(escrowId: number): PublicKey;
 }

package/dist/index.js

@@ -1,8 +1,23 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DarkForestPayments = exports.PER_ENDPOINTS = exports.TEE_VALIDATORS = exports.SETTLEMENT_SEED = exports.ESCROW_SEED = exports.DARK_FOREST_PROGRAM_ID = void 0;
+exports.DarkForestPayments = exports.LocalStorageSessionStore = exports.MemorySessionStore = exports.PER_ENDPOINTS = exports.TEE_VALIDATORS = exports.SETTLEMENT_SEED = exports.ESCROW_SEED = exports.DARK_FOREST_PROGRAM_ID = void 0;
 const anchor_1 = require("@coral-xyz/anchor");
 const web3_js_1 = require("@solana/web3.js");
+__exportStar(require("./verifier"), exports);
 exports.DARK_FOREST_PROGRAM_ID = new web3_js_1.PublicKey('4hNP2tU5r5GgyASTrou84kWHbCwdyXVJJN4mve99rjgs');
 exports.ESCROW_SEED = Buffer.from('escrow');
 exports.SETTLEMENT_SEED = Buffer.from('settlement');
@@ -15,6 +30,41 @@ exports.PER_ENDPOINTS = {
     devnet: 'https://tee.magicblock.app',
     devnetRouter: 'https://devnet-router.magicblock.app',
 };
+class MemorySessionStore {
+    constructor() {
+        this.sessions = new Map();
+    }
+    async get(escrowId) {
+        return this.sessions.get(escrowId) ?? null;
+    }
+    async set(session) {
+        this.sessions.set(session.escrowId, session);
+    }
+    async delete(escrowId) {
+        this.sessions.delete(escrowId);
+    }
+}
+exports.MemorySessionStore = MemorySessionStore;
+class LocalStorageSessionStore {
+    constructor(storage, prefix = 'taskforest:dark-forest:session:') {
+        this.storage = storage;
+        this.prefix = prefix;
+    }
+    key(escrowId) {
+        return `${this.prefix}${escrowId}`;
+    }
+    async get(escrowId) {
+        const raw = this.storage.getItem(this.key(escrowId));
+        return raw ? JSON.parse(raw) : null;
+    }
+    async set(session) {
+        this.storage.setItem(this.key(session.escrowId), JSON.stringify(session));
+    }
+    async delete(escrowId) {
+        this.storage.removeItem(this.key(escrowId));
+    }
+}
+exports.LocalStorageSessionStore = LocalStorageSessionStore;
 function deriveEscrowPda(escrowId) {
     return web3_js_1.PublicKey.findProgramAddressSync([exports.ESCROW_SEED, new anchor_1.BN(escrowId).toArrayLike(Buffer, 'le', 8)], exports.DARK_FOREST_PROGRAM_ID);
 }
@@ -22,14 +72,33 @@ function deriveSettlementPda(escrowId) {
     return web3_js_1.PublicKey.findProgramAddressSync([exports.SETTLEMENT_SEED, new anchor_1.BN(escrowId).toArrayLike(Buffer, 'le', 8)], exports.DARK_FOREST_PROGRAM_ID);
 }
 class DarkForestPayments {
-    constructor(provider, idl) {
-        this.activeSessions = new Map();
+    constructor(provider, idl, options = {}) {
         this.provider = provider;
         this.program = new anchor_1.Program(idl, provider);
+        this.sessionStore = options.sessionStore ?? new MemorySessionStore();
     }
     connectToPer(endpoint = exports.PER_ENDPOINTS.devnet) {
         return new web3_js_1.Connection(endpoint, 'confirmed');
     }
+    static buildAttestationReport(envelope) {
+        return Buffer.concat([
+            Buffer.from('TFAT'),
+            Buffer.from([1, 0, 0, 0]),
+            new anchor_1.BN(envelope.escrowId).toArrayLike(Buffer, 'le', 8),
+            envelope.jobPubkey.toBuffer(),
+            envelope.validator.toBuffer(),
+            Buffer.from(envelope.teePubkey),
+            Buffer.from(envelope.mppSessionId),
+            new anchor_1.BN(envelope.issuedAt).toTwos(64).toArrayLike(Buffer, 'le', 8),
+            new anchor_1.BN(envelope.expiresAt).toTwos(64).toArrayLike(Buffer, 'le', 8),
+        ]);
+    }
+    static buildAttestationSignatureInstruction(validatorSigner, report) {
+        return web3_js_1.Ed25519Program.createInstructionWithPrivateKey({
+            privateKey: validatorSigner.secretKey,
+            message: report,
+        });
+    }
     async createEscrowWrapper(escrowId, jobPubkey, depositSol, mppSessionId = Array(32).fill(0)) {
         const [escrowPda] = deriveEscrowPda(escrowId);
         return this.program.methods
@@ -42,36 +111,50 @@ class DarkForestPayments {
         })
             .rpc();
     }
-    async delegateToPer(escrowId, validator = exports.TEE_VALIDATORS.devnet) {
+    async delegateToPer(escrowId, validator) {
         const [escrowPda] = deriveEscrowPda(escrowId);
-        return this.program.methods
-            .delegateToPer()
+        const method = this.program.methods
+            .delegateToPer(new anchor_1.BN(escrowId))
             .accounts({
             pda: escrowPda,
             payer: this.provider.wallet.publicKey,
-            validator,
-        })
-            .rpc();
+        });
+        if (validator) {
+            return method
+                .remainingAccounts([{ pubkey: validator, isSigner: false, isWritable: false }])
+                .rpc();
+        }
+        return method.rpc();
     }
-    async verifyTeeAttestation(escrowId, attestationReport, teePubkey) {
+    async verifyTeeAttestation(escrowId, attestationReport, teePubkey, signatureInstruction) {
         const [escrowPda] = deriveEscrowPda(escrowId);
-        return this.program.methods
+        const method = this.program.methods
             .verifyTeeAttestation(new anchor_1.BN(escrowId), attestationReport, teePubkey)
             .accounts({
             escrow: escrowPda,
+            validator: this.provider.wallet.publicKey,
             payer: this.provider.wallet.publicKey,
-        })
+            instructionsSysvar: web3_js_1.SYSVAR_INSTRUCTIONS_PUBKEY,
+        });
+        if (signatureInstruction) {
+            return method.preInstructions([signatureInstruction]).rpc();
+        }
+        return method
             .rpc();
     }
     async recordSettlement(escrowId, totalPaidSol) {
         const [escrowPda] = deriveEscrowPda(escrowId);
         const [settlementPda] = deriveSettlementPda(escrowId);
+        const escrow = await this.getEscrow(escrowId);
+        if (!escrow)
+            throw new Error(`Escrow ${escrowId} not found`);
         return this.program.methods
             .recordSettlement(new anchor_1.BN(escrowId), new anchor_1.BN(Math.floor(totalPaidSol * web3_js_1.LAMPORTS_PER_SOL)))
             .accounts({
             escrow: escrowPda,
             settlementRecord: settlementPda,
             poster: this.provider.wallet.publicKey,
+            agent: escrow.agent,
             payer: this.provider.wallet.publicKey,
             systemProgram: web3_js_1.SystemProgram.programId,
         })
@@ -90,26 +173,32 @@ class DarkForestPayments {
             requestCount: 0,
             isActive: true,
         };
-        this.activeSessions.set(escrowId, session);
+        await this.sessionStore.set(session);
         return session;
     }
     async recordPayment(escrowId, amountLamports) {
-        const session = this.activeSessions.get(escrowId);
+        const session = await this.sessionStore.get(escrowId);
         if (!session || !session.isActive)
             throw new Error('No active session for this escrow');
-        session.totalPaid += amountLamports;
-        session.requestCount += 1;
+        await this.sessionStore.set({
+            ...session,
+            totalPaid: session.totalPaid + amountLamports,
+            requestCount: session.requestCount + 1,
+        });
     }
     async closeSession(escrowId) {
-        const session = this.activeSessions.get(escrowId);
+        const session = await this.sessionStore.get(escrowId);
         if (!session)
             throw new Error('No session for this escrow');
-        session.isActive = false;
+        await this.sessionStore.set({ ...session, isActive: false });
         const totalPaidSol = session.totalPaid / web3_js_1.LAMPORTS_PER_SOL;
         const tx = await this.recordSettlement(escrowId, totalPaidSol);
-        this.activeSessions.delete(escrowId);
+        await this.sessionStore.delete(escrowId);
         return tx;
     }
+    async getActiveSession(escrowId) {
+        return (await this.sessionStore.get(escrowId)) ?? undefined;
+    }
     async getEscrow(escrowId) {
         const [escrowPda] = deriveEscrowPda(escrowId);
         try {
@@ -151,9 +240,6 @@ class DarkForestPayments {
             return null;
         }
     }
-    getActiveSession(escrowId) {
-        return this.activeSessions.get(escrowId);
-    }
     static escrowPda(escrowId) {
         return deriveEscrowPda(escrowId)[0];
     }

package/dist/verifier.d.ts

@@ -0,0 +1,47 @@
+import { PublicKey } from '@solana/web3.js';
+export interface TdxQuoteVerificationPolicy {
+    allowedMrTd?: string[];
+    allowedRtmr0?: string[];
+    allowedRtmr1?: string[];
+    allowedRtmr2?: string[];
+    allowedRtmr3?: string[];
+    requireCertificateChain?: boolean;
+    trustedRootFingerprints?: string[];
+    notAfterGraceSeconds?: number;
+}
+export interface TdxQuoteClaims {
+    teePubkey: Uint8Array;
+    mrTd?: string;
+    rtmr0?: string;
+    rtmr1?: string;
+    rtmr2?: string;
+    rtmr3?: string;
+    issuedAt: number;
+    expiresAt: number;
+    certificateChainPem?: string[];
+}
+export interface VerifiedTdxQuote {
+    claims: TdxQuoteClaims;
+    verifier: PublicKey;
+    verifiedAt: number;
+}
+export interface TdxQuoteVerifier {
+    verifyQuote(quote: Uint8Array, policy: TdxQuoteVerificationPolicy): Promise<VerifiedTdxQuote>;
+}
+export interface VerifiedAttestationEnvelope {
+    escrowId: number;
+    jobPubkey: PublicKey;
+    validator: PublicKey;
+    teePubkey: number[];
+    mppSessionId: number[];
+    issuedAt: number;
+    expiresAt: number;
+}
+export declare function verifyCertificateChainPem(chainPem: string[], trustedRootFingerprints?: string[], nowSec?: number, graceSeconds?: number): void;
+export declare function assertTdxQuotePolicy(claims: TdxQuoteClaims, policy: TdxQuoteVerificationPolicy, nowSec?: number): void;
+export declare class JsonTdxQuoteVerifier implements TdxQuoteVerifier {
+    private readonly verifier;
+    constructor(verifier: PublicKey);
+    verifyQuote(quote: Uint8Array, policy: TdxQuoteVerificationPolicy): Promise<VerifiedTdxQuote>;
+}
+export declare function buildVerifiedAttestationEnvelope(escrowId: number, jobPubkey: PublicKey, mppSessionId: number[], verified: VerifiedTdxQuote): VerifiedAttestationEnvelope;

package/dist/verifier.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonTdxQuoteVerifier = void 0;
+exports.verifyCertificateChainPem = verifyCertificateChainPem;
+exports.assertTdxQuotePolicy = assertTdxQuotePolicy;
+exports.buildVerifiedAttestationEnvelope = buildVerifiedAttestationEnvelope;
+const node_crypto_1 = require("node:crypto");
+function normalizeHex(value) {
+    return value?.toLowerCase().replace(/^0x/, '');
+}
+function sha256Hex(data) {
+    return (0, node_crypto_1.createHash)('sha256').update(data).digest('hex');
+}
+function ensureAllowed(label, value, allowed) {
+    if (!allowed || allowed.length === 0)
+        return;
+    const normalized = normalizeHex(value);
+    const expected = new Set(allowed.map((item) => normalizeHex(item)));
+    if (!normalized || !expected.has(normalized)) {
+        throw new Error(`TDX policy mismatch for ${label}`);
+    }
+}
+function verifyCertificateChainPem(chainPem, trustedRootFingerprints, nowSec = Math.floor(Date.now() / 1000), graceSeconds = 0) {
+    if (!chainPem.length)
+        throw new Error('Missing certificate chain');
+    const certs = chainPem.map((pem) => new node_crypto_1.X509Certificate(pem));
+    for (let i = 0; i < certs.length; i += 1) {
+        const cert = certs[i];
+        const now = nowSec * 1000;
+        if (Date.parse(cert.validFrom) > now)
+            throw new Error('Certificate not yet valid');
+        if (Date.parse(cert.validTo) + graceSeconds * 1000 < now)
+            throw new Error('Certificate expired');
+        if (i < certs.length - 1) {
+            const issuer = certs[i + 1];
+            if (!cert.verify(issuer.publicKey))
+                throw new Error('Certificate chain signature invalid');
+        }
+    }
+    if (trustedRootFingerprints?.length) {
+        const root = certs[certs.length - 1];
+        const fingerprint = sha256Hex(root.raw);
+        const trusted = new Set(trustedRootFingerprints.map((item) => normalizeHex(item)));
+        if (!trusted.has(normalizeHex(fingerprint))) {
+            throw new Error('Certificate root is not trusted');
+        }
+    }
+}
+function assertTdxQuotePolicy(claims, policy, nowSec = Math.floor(Date.now() / 1000)) {
+    if (claims.issuedAt > nowSec)
+        throw new Error('TDX quote is not yet valid');
+    if (claims.expiresAt < nowSec)
+        throw new Error('TDX quote has expired');
+    ensureAllowed('mrTd', claims.mrTd, policy.allowedMrTd);
+    ensureAllowed('rtmr0', claims.rtmr0, policy.allowedRtmr0);
+    ensureAllowed('rtmr1', claims.rtmr1, policy.allowedRtmr1);
+    ensureAllowed('rtmr2', claims.rtmr2, policy.allowedRtmr2);
+    ensureAllowed('rtmr3', claims.rtmr3, policy.allowedRtmr3);
+    if (policy.requireCertificateChain) {
+        verifyCertificateChainPem(claims.certificateChainPem ?? [], policy.trustedRootFingerprints, nowSec, policy.notAfterGraceSeconds ?? 0);
+    }
+}
+class JsonTdxQuoteVerifier {
+    constructor(verifier) {
+        this.verifier = verifier;
+    }
+    async verifyQuote(quote, policy) {
+        const claims = JSON.parse(Buffer.from(quote).toString('utf8'));
+        assertTdxQuotePolicy(claims, policy);
+        return {
+            claims,
+            verifier: this.verifier,
+            verifiedAt: Math.floor(Date.now() / 1000),
+        };
+    }
+}
+exports.JsonTdxQuoteVerifier = JsonTdxQuoteVerifier;
+function buildVerifiedAttestationEnvelope(escrowId, jobPubkey, mppSessionId, verified) {
+    return {
+        escrowId,
+        jobPubkey,
+        validator: verified.verifier,
+        teePubkey: Array.from(verified.claims.teePubkey),
+        mppSessionId,
+        issuedAt: verified.claims.issuedAt,
+        expiresAt: verified.claims.expiresAt,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taskforest/dark-forest",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Dark Forest payment helpers for TaskForest: MPP wrapper, PER delegation, and settlement utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",