@taskforest/dark-forest 0.1.0

package/README.md

@@ -0,0 +1,19 @@
+# @taskforest/dark-forest
+
+Dark Forest payment helpers 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.
+
+## Install
+
+```bash
+npm install @taskforest/dark-forest
+```
+
+## Scope
+
+- Escrow wrapper helpers
+- PER endpoints and validator constants
+- MPP session orchestration helpers
+- Settlement state reads

package/dist/__tests__/dark-forest.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const web3_js_1 = require("@solana/web3.js");
+const index_1 = require("../index");
+(0, node_test_1.default)('exports stable public constants', () => {
+    strict_1.default.equal(index_1.DARK_FOREST_PROGRAM_ID.toBase58(), '4hNP2tU5r5GgyASTrou84kWHbCwdyXVJJN4mve99rjgs');
+    strict_1.default.equal(index_1.ESCROW_SEED.toString(), 'escrow');
+    strict_1.default.equal(index_1.SETTLEMENT_SEED.toString(), 'settlement');
+    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)('derives deterministic escrow and settlement PDAs', () => {
+    const escrowOne = index_1.DarkForestPayments.escrowPda(42);
+    const escrowTwo = index_1.DarkForestPayments.escrowPda(42);
+    const settlementOne = index_1.DarkForestPayments.settlementPda(42);
+    const settlementTwo = index_1.DarkForestPayments.settlementPda(42);
+    strict_1.default.equal(escrowOne.toBase58(), escrowTwo.toBase58());
+    strict_1.default.equal(settlementOne.toBase58(), settlementTwo.toBase58());
+    strict_1.default.notEqual(escrowOne.toBase58(), settlementOne.toBase58());
+});
+(0, node_test_1.default)('connectToPer returns a Solana connection', () => {
+    const payments = Object.create(index_1.DarkForestPayments.prototype);
+    const connection = payments.connectToPer(index_1.PER_ENDPOINTS.devnet);
+    strict_1.default.ok(connection instanceof web3_js_1.Connection);
+    strict_1.default.equal(connection.rpcEndpoint, index_1.PER_ENDPOINTS.devnet);
+});
+(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.createEscrowWrapper = async () => 'escrow-tx';
+    payments.delegateToPer = async () => 'delegate-tx';
+    payments.recordSettlement = async () => 'settlement-tx';
+    const session = await payments.startPrivateSession(77, index_1.DARK_FOREST_PROGRAM_ID, {
+        agentEndpoint: 'https://agent.taskforest.xyz',
+        token: 'SOL',
+        budgetLamports: 1500000,
+        perEndpoint: index_1.PER_ENDPOINTS.devnet,
+    });
+    strict_1.default.equal(session.escrowId, 77);
+    strict_1.default.equal(session.isActive, true);
+    strict_1.default.equal(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);
+    const tx = await payments.closeSession(77);
+    strict_1.default.equal(tx, 'settlement-tx');
+    strict_1.default.equal(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);
+    payments.program = {
+        account: {
+            escrowWrapper: { fetch: async () => { throw new Error('missing'); } },
+            settlementRecord: { fetch: async () => { throw new Error('missing'); } },
+        },
+    };
+    strict_1.default.equal(await payments.getEscrow(5), null);
+    strict_1.default.equal(await payments.getSettlement(5), null);
+});

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { AnchorProvider, type Idl } from '@coral-xyz/anchor';
+import { Connection, PublicKey } from '@solana/web3.js';
+export declare const DARK_FOREST_PROGRAM_ID: PublicKey;
+export declare const ESCROW_SEED: Buffer;
+export declare const SETTLEMENT_SEED: Buffer;
+export declare const TEE_VALIDATORS: {
+    readonly mainnet: PublicKey;
+    readonly devnet: PublicKey;
+};
+export declare const PER_ENDPOINTS: {
+    readonly mainnet: "https://mainnet-tee.magicblock.app";
+    readonly devnet: "https://tee.magicblock.app";
+    readonly devnetRouter: "https://devnet-router.magicblock.app";
+};
+export type MppSessionConfig = {
+    agentEndpoint: string;
+    token: 'SOL' | 'USDC' | 'PYUSD';
+    budgetLamports: number;
+    perEndpoint: string;
+};
+export type MppSessionState = {
+    sessionId: string;
+    escrowId: number;
+    totalPaid: number;
+    requestCount: number;
+    isActive: boolean;
+};
+export interface EscrowState {
+    escrowId: number;
+    jobPubkey: PublicKey;
+    poster: PublicKey;
+    agent: PublicKey;
+    deposited: number;
+    status: 'Active' | 'Delegated' | 'Settled';
+    teePubkey: number[];
+    teeVerified: boolean;
+    mppSessionId: number[];
+    createdAt: number;
+}
+export interface SettlementState {
+    escrowId: number;
+    jobPubkey: PublicKey;
+    poster: PublicKey;
+    agent: PublicKey;
+    totalDeposited: number;
+    totalPaid: number;
+    settledAt: number;
+    settlementHash: number[];
+}
+export declare class DarkForestPayments {
+    private program;
+    private provider;
+    private activeSessions;
+    constructor(provider: AnchorProvider, idl: Idl);
+    connectToPer(endpoint?: string): Connection;
+    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>;
+    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>;
+    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

@@ -0,0 +1,164 @@
+"use strict";
+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;
+const anchor_1 = require("@coral-xyz/anchor");
+const web3_js_1 = require("@solana/web3.js");
+exports.DARK_FOREST_PROGRAM_ID = new web3_js_1.PublicKey('4hNP2tU5r5GgyASTrou84kWHbCwdyXVJJN4mve99rjgs');
+exports.ESCROW_SEED = Buffer.from('escrow');
+exports.SETTLEMENT_SEED = Buffer.from('settlement');
+exports.TEE_VALIDATORS = {
+    mainnet: new web3_js_1.PublicKey('MTEWGuqxUpYZGFJQcp8tLN7x5v9BSeoFHYWQQ3n3xzo'),
+    devnet: new web3_js_1.PublicKey('FnE6VJT5QNZdedZPnCoLsARgBwoE6DeJNjBs2H1gySXA'),
+};
+exports.PER_ENDPOINTS = {
+    mainnet: 'https://mainnet-tee.magicblock.app',
+    devnet: 'https://tee.magicblock.app',
+    devnetRouter: 'https://devnet-router.magicblock.app',
+};
+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);
+}
+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();
+        this.provider = provider;
+        this.program = new anchor_1.Program(idl, provider);
+    }
+    connectToPer(endpoint = exports.PER_ENDPOINTS.devnet) {
+        return new web3_js_1.Connection(endpoint, 'confirmed');
+    }
+    async createEscrowWrapper(escrowId, jobPubkey, depositSol, mppSessionId = Array(32).fill(0)) {
+        const [escrowPda] = deriveEscrowPda(escrowId);
+        return this.program.methods
+            .createEscrowWrapper(new anchor_1.BN(escrowId), new anchor_1.BN(Math.floor(depositSol * web3_js_1.LAMPORTS_PER_SOL)), mppSessionId)
+            .accounts({
+            job: jobPubkey,
+            escrow: escrowPda,
+            poster: this.provider.wallet.publicKey,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .rpc();
+    }
+    async delegateToPer(escrowId, validator = exports.TEE_VALIDATORS.devnet) {
+        const [escrowPda] = deriveEscrowPda(escrowId);
+        return this.program.methods
+            .delegateToPer()
+            .accounts({
+            pda: escrowPda,
+            payer: this.provider.wallet.publicKey,
+            validator,
+        })
+            .rpc();
+    }
+    async verifyTeeAttestation(escrowId, attestationReport, teePubkey) {
+        const [escrowPda] = deriveEscrowPda(escrowId);
+        return this.program.methods
+            .verifyTeeAttestation(new anchor_1.BN(escrowId), attestationReport, teePubkey)
+            .accounts({
+            escrow: escrowPda,
+            payer: this.provider.wallet.publicKey,
+        })
+            .rpc();
+    }
+    async recordSettlement(escrowId, totalPaidSol) {
+        const [escrowPda] = deriveEscrowPda(escrowId);
+        const [settlementPda] = deriveSettlementPda(escrowId);
+        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,
+            payer: this.provider.wallet.publicKey,
+            systemProgram: web3_js_1.SystemProgram.programId,
+        })
+            .rpc();
+    }
+    async startPrivateSession(escrowId, jobPubkey, config) {
+        const depositSol = config.budgetLamports / web3_js_1.LAMPORTS_PER_SOL;
+        const sessionId = `dark-${escrowId}-${Date.now()}`;
+        const sessionIdBytes = Array.from(Buffer.from(sessionId.padEnd(32, '\0').slice(0, 32)));
+        await this.createEscrowWrapper(escrowId, jobPubkey, depositSol, sessionIdBytes);
+        await this.delegateToPer(escrowId);
+        const session = {
+            sessionId,
+            escrowId,
+            totalPaid: 0,
+            requestCount: 0,
+            isActive: true,
+        };
+        this.activeSessions.set(escrowId, session);
+        return session;
+    }
+    async recordPayment(escrowId, amountLamports) {
+        const session = this.activeSessions.get(escrowId);
+        if (!session || !session.isActive)
+            throw new Error('No active session for this escrow');
+        session.totalPaid += amountLamports;
+        session.requestCount += 1;
+    }
+    async closeSession(escrowId) {
+        const session = this.activeSessions.get(escrowId);
+        if (!session)
+            throw new Error('No session for this escrow');
+        session.isActive = false;
+        const totalPaidSol = session.totalPaid / web3_js_1.LAMPORTS_PER_SOL;
+        const tx = await this.recordSettlement(escrowId, totalPaidSol);
+        this.activeSessions.delete(escrowId);
+        return tx;
+    }
+    async getEscrow(escrowId) {
+        const [escrowPda] = deriveEscrowPda(escrowId);
+        try {
+            const account = await this.program.account.escrowWrapper.fetch(escrowPda);
+            const statusMap = { 0: 'Active', 1: 'Delegated', 2: 'Settled' };
+            return {
+                escrowId: account.escrowId.toNumber(),
+                jobPubkey: account.jobPubkey,
+                poster: account.poster,
+                agent: account.agent,
+                deposited: account.deposited.toNumber(),
+                status: statusMap[account.status.active !== undefined ? 0 : account.status.delegated !== undefined ? 1 : 2] ?? 'Active',
+                teePubkey: account.teePubkey,
+                teeVerified: account.teeVerified,
+                mppSessionId: account.mppSessionId,
+                createdAt: account.createdAt.toNumber(),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    async getSettlement(escrowId) {
+        const [settlementPda] = deriveSettlementPda(escrowId);
+        try {
+            const account = await this.program.account.settlementRecord.fetch(settlementPda);
+            return {
+                escrowId: account.escrowId.toNumber(),
+                jobPubkey: account.jobPubkey,
+                poster: account.poster,
+                agent: account.agent,
+                totalDeposited: account.totalDeposited.toNumber(),
+                totalPaid: account.totalPaid.toNumber(),
+                settledAt: account.settledAt.toNumber(),
+                settlementHash: account.settlementHash,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    getActiveSession(escrowId) {
+        return this.activeSessions.get(escrowId);
+    }
+    static escrowPda(escrowId) {
+        return deriveEscrowPda(escrowId)[0];
+    }
+    static settlementPda(escrowId) {
+        return deriveSettlementPda(escrowId)[0];
+    }
+}
+exports.DarkForestPayments = DarkForestPayments;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@taskforest/dark-forest",
+  "version": "0.1.0",
+  "description": "Dark Forest payment helpers for TaskForest: MPP wrapper, PER delegation, and settlement utilities",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "solana",
+    "taskforest",
+    "payments",
+    "magicblock",
+    "per",
+    "mpp"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jimmdd/taskforest-protocol"
+  },
+  "homepage": "https://taskforest.xyz",
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test dist/__tests__/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@coral-xyz/anchor": "^0.30.1",
+    "@solana/web3.js": "^1.95.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}