@arcproof/sdk-elizaos 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @arcproof/sdk-elizaos
+
+ElizaOS plugin adapter for [`@arcproof/sdk`](../sdk): expose a bonded, independently-verified, real-payment flow as a real ElizaOS `Action`/`Plugin`.
+
+## Install
+
+```bash
+npm install @arcproof/sdk @arcproof/sdk-elizaos @elizaos/core
+```
+
+## Usage
+
+```ts
+import { createArcProofAction, createArcProofPlugin } from "@arcproof/sdk-elizaos";
+import { VerifierRegistry, ARC_TESTNET } from "@arcproof/sdk";
+
+const action = createArcProofAction({
+  name: "CHECK_TRUE_APR",
+  description: "Independently verifies a loan's true APR before answering, paying the specialist only if it checks out.",
+  trustedAgentConfig: { network: ARC_TESTNET, contractAddress, verifiers: myVerifierRegistry },
+  requester, // WalletCredential
+  settler, // WalletCredential
+  providerAddresses: { "lending-apr-agent-v1": "0x...", "lending-eligibility-agent-v1": "0x..." },
+  budgetAmount: 0.05,
+  // gatherClaims can be a single @arcproof/sdk-langchain gatherer, or a full
+  // orchestrator (createLangChainOrchestrator) that itself decides which
+  // specialists this specific request needs -- ElizaOS never has to know
+  // the difference, it just sees the natural-language reply either way.
+  gatherClaims: myOrchestratorOrGatherer,
+  buildContext: (message) => ({ loanId: extractLoanId(message.content.text), requestText: message.content.text }),
+});
+
+const plugin = createArcProofPlugin({
+  name: "arcproof-trust-layer",
+  description: "Bonded, independently-verified agent actions with real on-chain payment.",
+  actions: [action],
+});
+
+// register `plugin` with your ElizaOS character/project as you would any other plugin
+```
+
+## Why this doesn't import types from `@elizaos/core`
+
+`@elizaos/core`'s top-level barrel (`dist/index.d.ts`) re-exports both `./types` (which defines `Action`/`Plugin` as types) and `./actions` (a same-named runtime export) via `export *`. TypeScript silently drops an ambiguous re-exported name rather than erroring, so `import type { Action } from "@elizaos/core"` fails at typecheck time even though the type genuinely exists in the package (confirmed against `@elizaos/core@1.7.2`'s actual `.d.ts` files).
+
+This package defines structurally-identical local types (`ElizaAction`, `ElizaPlugin`, etc.) instead of depending on that fragile export path. TypeScript's structural typing makes the objects this package builds assignable to the real `Action`/`Plugin` types wherever your actual ElizaOS runtime code expects them -- `@elizaos/core` is still a declared peer dependency because you need the real package installed to run an agent at all.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import { type TrustedAgentConfig, type SettlementResult, type Claim, type WalletCredential } from "@arcproof/sdk";
+export interface ElizaContent {
+    text?: string;
+    [key: string]: unknown;
+}
+export interface ElizaMemory {
+    content: ElizaContent;
+    [key: string]: unknown;
+}
+export interface ElizaState {
+    values: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface ElizaActionExample {
+    name: string;
+    content: ElizaContent;
+}
+export interface ElizaActionResult {
+    text?: string;
+    values?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+    success: boolean;
+    error?: string | Error;
+}
+export type ElizaHandlerCallback = (response: ElizaContent) => Promise<unknown>;
+export type ElizaValidator = (runtime: unknown, message: ElizaMemory, state?: ElizaState) => Promise<boolean>;
+export type ElizaHandler = (runtime: unknown, message: ElizaMemory, state?: ElizaState, options?: unknown, callback?: ElizaHandlerCallback, responses?: ElizaMemory[]) => Promise<ElizaActionResult | void | undefined>;
+export interface ElizaAction {
+    name: string;
+    description: string;
+    similes?: string[];
+    examples?: ElizaActionExample[][];
+    validate: ElizaValidator;
+    handler: ElizaHandler;
+    [key: string]: unknown;
+}
+export interface ElizaPlugin {
+    name: string;
+    description: string;
+    actions?: ElizaAction[];
+    [key: string]: unknown;
+}
+export interface ArcProofActionOptions {
+    /** ElizaOS action name, e.g. "CHECK_TRUE_APR" -- convention is SCREAMING_SNAKE_CASE. */
+    name: string;
+    description: string;
+    similes?: string[];
+    examples?: ElizaActionExample[][];
+    trustedAgentConfig: TrustedAgentConfig;
+    requester: WalletCredential;
+    settler: WalletCredential;
+    providerAddresses: Record<string, string>;
+    budgetAmount: number;
+    gatherClaims: (context: Record<string, unknown>) => Promise<Claim[]>;
+    /** Extracts job context (e.g. a loan id, an account, a protocol slug) from the incoming message. */
+    buildContext: (message: ElizaMemory, state?: ElizaState) => Record<string, unknown>;
+    /** Custom trigger condition -- defaults to "always applies" (ElizaOS's own routing/prompting decides whether to invoke this action at all). */
+    validate?: ElizaValidator;
+    /** Formats the settlement result into the text ElizaOS sends back to the user. */
+    formatResponse?: (result: SettlementResult) => string;
+}
+/**
+ * Builds a real ElizaOS Action that runs a full bonded job (lock -> gather
+ * -> verify -> settle/refund) whenever ElizaOS decides to invoke it.
+ * Every payment is a real Arc transaction -- nothing here is simulated
+ * just because it's running inside an agent framework instead of a
+ * standalone script.
+ */
+export declare function createArcProofAction(options: ArcProofActionOptions): ElizaAction;
+/** Bundles one or more ArcProof actions into a real, installable ElizaOS Plugin. */
+export declare function createArcProofPlugin(options: {
+    name: string;
+    description: string;
+    actions: ElizaAction[];
+}): ElizaPlugin;

package/dist/index.js

@@ -0,0 +1,88 @@
+/**
+ * ElizaOS plugin adapter for @arcproof/sdk: exposes a bonded,
+ * independently-verified, real-payment flow as an ElizaOS Action.
+ *
+ * Shapes below (ElizaAction/ElizaPlugin/etc.) are structurally verified
+ * against @elizaos/core@1.7.2's actual dist/types/*.d.ts definitions
+ * (Action, Plugin, Handler, Validator, Memory, State, Content,
+ * ActionResult, ActionExample), not guessed from memory -- but
+ * deliberately NOT imported from "@elizaos/core" directly: that
+ * package's top-level barrel (dist/index.d.ts) re-exports both
+ * ./types (which defines `Action`/`Plugin` as types) and ./actions
+ * (which defines a same-named runtime export), and TypeScript silently
+ * drops an ambiguous `export *` name rather than erroring -- confirmed
+ * live (`Module has no exported member 'Action'` etc. even though the
+ * type genuinely exists in the package). Defining structurally-identical
+ * local types sidesteps that import ambiguity entirely; TypeScript's
+ * structural typing makes the object this module builds assignable to
+ * the real Plugin/Action types wherever a consumer's actual ElizaOS
+ * runtime code expects them.
+ *
+ * The action's handler calls runTrustedJob() under the hood: lock a real
+ * budget, run your gatherClaims() step (any framework -- often
+ * @arcproof/sdk-langchain wrapping the same LangChain.js agent this
+ * ElizaOS character already uses for its model calls), independently
+ * verify every claim, then release/refund real on-chain payment based on
+ * the verdict. ElizaOS only ever sees the natural-language in and out;
+ * the trust mechanics are identical to the LangChain.js-only path.
+ */
+import { randomUUID } from "node:crypto";
+import { runTrustedJob } from "@arcproof/sdk";
+function defaultFormatResponse(result) {
+    const lines = [`Verdict: ${result.overall_verdict.toUpperCase()} (paid ${result.total_paid_usdc.toFixed(4)})`, ""];
+    for (const c of result.claims) {
+        lines.push(`- [${c.claim_type}] ${c.claim_text} -> ${c.verification_status}${c.verification_note ? ` (${c.verification_note})` : ""}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Builds a real ElizaOS Action that runs a full bonded job (lock -> gather
+ * -> verify -> settle/refund) whenever ElizaOS decides to invoke it.
+ * Every payment is a real Arc transaction -- nothing here is simulated
+ * just because it's running inside an agent framework instead of a
+ * standalone script.
+ */
+export function createArcProofAction(options) {
+    return {
+        name: options.name,
+        description: options.description,
+        similes: options.similes ?? [],
+        examples: options.examples ?? [],
+        validate: options.validate ?? (async () => true),
+        handler: async (_runtime, message, state, _handlerOptions, callback) => {
+            const jobId = randomUUID();
+            const context = { jobId, ...options.buildContext(message, state) };
+            try {
+                const params = {
+                    jobId,
+                    budgetAmount: options.budgetAmount,
+                    requester: options.requester,
+                    settler: options.settler,
+                    providerAddresses: options.providerAddresses,
+                    gatherClaims: options.gatherClaims,
+                    context,
+                };
+                const result = await runTrustedJob(options.trustedAgentConfig, params);
+                const text = (options.formatResponse ?? defaultFormatResponse)(result);
+                if (callback)
+                    await callback({ text });
+                return { text, success: true, data: { settlement: result } };
+            }
+            catch (e) {
+                const text = `Couldn't complete that verified request: ${e}`;
+                if (callback)
+                    await callback({ text });
+                return { text, success: false, error: e instanceof Error ? e : String(e) };
+            }
+        },
+    };
+}
+/** Bundles one or more ArcProof actions into a real, installable ElizaOS Plugin. */
+export function createArcProofPlugin(options) {
+    return {
+        name: options.name,
+        description: options.description,
+        actions: options.actions,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@arcproof/sdk-elizaos",
+  "version": "0.1.0",
+  "description": "ElizaOS plugin for @arcproof/sdk -- expose a bonded, independently-verified, real-payment action inside an ElizaOS agent.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": ["arcproof", "elizaos", "ai-agents", "verification", "plugin"],
+  "license": "MIT",
+  "peerDependencies": {
+    "@arcproof/sdk": "^0.1.0",
+    "@elizaos/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@arcproof/sdk": "*",
+    "typescript": "^5.7.3",
+    "@types/node": "^22.10.5"
+  }
+}