@oobe-protocol-labs/synapse-sap-sdk 0.8.0 → 0.9.1

package/dist/types/registries/metaplex-bridge.d.ts

@@ -0,0 +1,228 @@
+/**
+ * @module registries/metaplex-bridge
+ * @description Bridge between Synapse Agent Protocol (SAP) and Metaplex
+ * Core's `AgentIdentity` external plugin adapter (mpl-core ≥ 1.9.0).
+ *
+ * ## Why this design (verified against mpl-core PR #258, v1.9.0)
+ *
+ * The MPL Core `AgentIdentity` plugin has exactly one field:
+ *
+ * ```ts
+ * type AgentIdentity = { uri: string };
+ * ```
+ *
+ * The URI must point to an **EIP-8004** agent registration JSON. There is
+ * no on-chain executive list, no `addExecutive` / `delegateExecutionV1`
+ * instruction. Capabilities, services, executives, and reputation live
+ * off-chain in that JSON. The plugin only hooks the `Execute` lifecycle
+ * event, allowing the URI's authority to gate execution.
+ *
+ * The most efficient SAP × MPL integration therefore is:
+ *
+ *   1. SAP serves a **live EIP-8004 JSON** at a deterministic URL derived
+ *      from the SAP `AgentAccount` PDA (e.g.
+ *      `https://explorer.oobeprotocol.ai/agents/<sapAgentPda>/eip-8004.json`).
+ *   2. The MPL Core asset attaches an `AgentIdentity` adapter whose `uri`
+ *      points to that URL.
+ *   3. Every SAP write (capability change, vault delegate add/revoke, x402
+ *      tier update) is reflected in the JSON automatically — **no second
+ *      transaction required, on either chain or for any wallet.**
+ *
+ * One SAP transaction = both protocols updated. That is the efficiency
+ * win that motivated the Phase 1 redesign on 2026-04-22.
+ *
+ * @category Registries
+ * @since v0.9.0
+ * @see https://github.com/metaplex-foundation/mpl-core/pull/258
+ * @see https://eips.ethereum.org/EIPS/eip-8004
+ */
+import { PublicKey, type TransactionInstruction } from "@solana/web3.js";
+import type { SapProgram } from "../modules/base";
+import type { AgentAccountData, AgentStatsData } from "../types";
+/**
+ * @interface Eip8004Service
+ * @description One service entry in an EIP-8004 registration document.
+ * @category Registries
+ * @since v0.9.0
+ */
+export interface Eip8004Service {
+    readonly id: string;
+    readonly type: string;
+    readonly url: string;
+    readonly priceLamports?: string;
+}
+/**
+ * @interface Eip8004Registration
+ * @description Subset of an EIP-8004 registration document used by the
+ * bridge. Hosts may include additional fields; they are passed through
+ * via `extra`.
+ * @category Registries
+ * @since v0.9.0
+ */
+export interface Eip8004Registration {
+    readonly version: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly synapseAgent: string;
+    readonly authority: string;
+    readonly capabilities: readonly string[];
+    readonly services: readonly Eip8004Service[];
+    readonly executives: readonly {
+        wallet: string;
+        expiresAt: string | null;
+    }[];
+    readonly updatedAt: string;
+    readonly extra?: Record<string, unknown>;
+}
+/**
+ * @interface AttachAgentIdentityOpts
+ * @description Parameters for {@link MetaplexBridge.buildAttachAgentIdentityIx}.
+ * @category Registries
+ * @since v0.9.0
+ */
+export interface AttachAgentIdentityOpts {
+    readonly asset: PublicKey;
+    readonly authority: PublicKey;
+    readonly payer?: PublicKey;
+    readonly sapAgentOwner: PublicKey;
+    readonly registrationBaseUrl: string;
+    readonly rpcUrl: string;
+}
+/**
+ * @interface UpdateAgentIdentityUriOpts
+ * @description Parameters for {@link MetaplexBridge.buildUpdateAgentIdentityUriIx}.
+ * @category Registries
+ * @since v0.9.0
+ */
+export interface UpdateAgentIdentityUriOpts {
+    readonly asset: PublicKey;
+    readonly authority: PublicKey;
+    readonly payer?: PublicKey;
+    readonly newUri: string;
+    readonly rpcUrl: string;
+}
+/**
+ * @interface MplAgentSnapshot
+ * @description Subset of an MPL Core Asset relevant to the bridge.
+ * @category Registries
+ * @since v0.9.0
+ */
+export interface MplAgentSnapshot {
+    readonly asset: PublicKey;
+    readonly owner: PublicKey;
+    readonly name: string | null;
+    readonly agentIdentityUri: string | null;
+    readonly registration: Eip8004Registration | null;
+}
+/**
+ * @interface UnifiedProfile
+ * @description Merged read-only profile combining SAP identity and an
+ * (optional) MPL Core asset side. The `linked` flag is `true` when the
+ * MPL asset's `AgentIdentity.uri` references the SAP agent PDA both in
+ * the URL path and in the `synapseAgent` JSON field.
+ * @category Registries
+ * @since v0.9.0
+ */
+export interface UnifiedProfile {
+    readonly sap: {
+        readonly pda: PublicKey;
+        readonly identity: AgentAccountData | null;
+        readonly stats: AgentStatsData | null;
+    };
+    readonly mpl: MplAgentSnapshot | null;
+    readonly linked: boolean;
+}
+/**
+ * @name MetaplexBridge
+ * @description Read-side merger and write-side instruction composer for
+ * SAP × Metaplex Core `AgentIdentity` integration.
+ *
+ * Linking is **single-transaction**: the MPL `addExternalPluginAdapterV1`
+ * instruction sets a URI that points at SAP's live registration host.
+ * Subsequent SAP state changes propagate automatically — no extra MPL
+ * transaction required.
+ *
+ * @category Registries
+ * @since v0.9.0
+ */
+export declare class MetaplexBridge {
+    private readonly program;
+    constructor(program: SapProgram);
+    /**
+     * @name deriveRegistrationUrl
+     * @description Compute the deterministic EIP-8004 registration URL for
+     * a SAP agent. Hosts MUST serve the JSON at exactly this path so that
+     * {@link MetaplexBridge.verifyLink} validates without external config.
+     *
+     * @since v0.9.0
+     */
+    deriveRegistrationUrl(sapAgentPda: PublicKey, baseUrl: string): string;
+    /**
+     * @name buildEip8004Registration
+     * @description Build a canonical EIP-8004 JSON document for a SAP agent.
+     * Designed to be called server-side by a registry host.
+     *
+     * @since v0.9.0
+     */
+    buildEip8004Registration(args: {
+        sapAgentOwner: PublicKey;
+        services?: readonly Eip8004Service[];
+        extra?: Record<string, unknown>;
+    }): Promise<Eip8004Registration>;
+    /**
+     * @name buildAttachAgentIdentityIx
+     * @description Build the MPL Core `addExternalPluginAdapterV1`
+     * `TransactionInstruction` that attaches an `AgentIdentity` plugin
+     * pointing at SAP's live EIP-8004 registration URL.
+     *
+     * @since v0.9.0
+     */
+    buildAttachAgentIdentityIx(opts: AttachAgentIdentityOpts): Promise<TransactionInstruction>;
+    /**
+     * @name buildUpdateAgentIdentityUriIx
+     * @description Build the MPL Core `updateExternalPluginAdapterV1`
+     * instruction that re-points an existing `AgentIdentity` plugin.
+     *
+     * @since v0.9.0
+     */
+    buildUpdateAgentIdentityUriIx(opts: UpdateAgentIdentityUriOpts): Promise<TransactionInstruction>;
+    /**
+     * @name getUnifiedProfile
+     * @description Fetch a merged view of an agent across SAP and Metaplex.
+     * Provide `wallet` (SAP-first) or `asset` (MPL-first), or both.
+     *
+     * @since v0.9.0
+     */
+    getUnifiedProfile(input: {
+        wallet?: PublicKey;
+        asset?: PublicKey;
+        rpcUrl: string;
+    }): Promise<UnifiedProfile>;
+    /**
+     * @name verifyLink
+     * @description Verify the bidirectional link between an MPL Core asset
+     * and a SAP agent. Returns `true` only when both URL and JSON sides
+     * reference the SAP agent PDA.
+     *
+     * @since v0.9.0
+     */
+    verifyLink(args: {
+        asset: PublicKey;
+        sapAgentPda: PublicKey;
+        rpcUrl: string;
+    }): Promise<boolean>;
+    private get accounts();
+    private fetchAgentNullable;
+    private fetchStatsNullable;
+    private fetchActiveVaultDelegates;
+    private fetchMplSnapshot;
+    private extractAgentIdentityUri;
+    private fetchEip8004Safe;
+    private buildAddExternalPluginIx;
+    private firstWeb3Ix;
+    private umiIxToWeb3;
+    private detectLink;
+    private readString;
+    private readCapabilities;
+}
+//# sourceMappingURL=metaplex-bridge.d.ts.map

package/dist/types/registries/metaplex-bridge.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/synapse-sap-sdk",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "TypeScript SDK for the Synapse Agent Protocol (SAP v2) on Solana Mainnet/Devnet",
   "license": "MIT",
   "main": "dist/cjs/index.js",
@@ -97,6 +97,11 @@
       "require": "./dist/cjs/registries/builder.js",
       "types": "./dist/types/registries/builder.d.ts"
     },
+    "./registries/metaplex-bridge": {
+      "import": "./dist/esm/registries/metaplex-bridge.js",
+      "require": "./dist/cjs/registries/metaplex-bridge.js",
+      "types": "./dist/types/registries/metaplex-bridge.d.ts"
+    },
     "./idl": {
       "import": "./dist/esm/idl/index.js",
       "require": "./dist/cjs/idl/index.js",
@@ -156,19 +161,25 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@coral-xyz/anchor": "^0.32.1",
-    "@solana/web3.js": "^1.98.0"
+    "@coral-xyz/anchor": ">=0.30.0",
+    "@solana/web3.js": ">=1.90.0"
   },
   "devDependencies": {
+    "@metaplex-foundation/mpl-core": "^1.10.0",
+    "@metaplex-foundation/umi": "^1.5.0",
+    "@metaplex-foundation/umi-bundle-defaults": "^1.5.1",
     "typescript": "^5.7.3",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
     "@coral-xyz/anchor": ">=0.30.0",
+    "@metaplex-foundation/mpl-core": ">=1.9.0",
+    "@metaplex-foundation/umi": ">=0.9.0",
+    "@metaplex-foundation/umi-bundle-defaults": ">=0.9.0",
     "@solana/web3.js": ">=1.90.0",
     "@triton-one/yellowstone-grpc": ">=1.0.0",
-    "zod": ">=3.20.0",
-    "pg": ">=8.0.0"
+    "pg": ">=8.0.0",
+    "zod": ">=3.20.0"
   },
   "peerDependenciesMeta": {
     "zod": {
@@ -179,6 +190,15 @@
     },
     "@triton-one/yellowstone-grpc": {
       "optional": true
+    },
+    "@metaplex-foundation/mpl-core": {
+      "optional": true
+    },
+    "@metaplex-foundation/umi": {
+      "optional": true
+    },
+    "@metaplex-foundation/umi-bundle-defaults": {
+      "optional": true
     }
   },
   "engines": {

package/src/core/client.ts

@@ -45,6 +45,7 @@ import { DiscoveryRegistry } from "../registries/discovery";
 import { X402Registry } from "../registries/x402";
 import { SessionManager } from "../registries/session";
 import { AgentBuilder } from "../registries/builder";
+import { MetaplexBridge } from "../registries/metaplex-bridge";
 
 // IDL is embedded inside the SDK — no external workspace dependency
 import idl from "../idl/synapse_agent_sap.json";
@@ -132,6 +133,7 @@ export class SapClient {
   #discovery?: DiscoveryRegistry;
   #x402?: X402Registry;
   #session?: SessionManager;
+  #metaplex?: MetaplexBridge;
 
   private constructor(program: SapProgram) {
     this.program = program;
@@ -497,4 +499,34 @@ export class SapClient {
   get builder(): AgentBuilder {
     return new AgentBuilder(this.program);
   }
+
+  /**
+   * @name metaplex
+   * @description Bridge between SAP and the Metaplex Agent Kit
+   * (MPL Core Asset + AgentIdentity plugin). Read-side merges SAP
+   * `AgentAccount` with MPL Core asset metadata; write-side composes
+   * atomic dual-protocol delegation instructions.
+   *
+   * Requires the optional peer dependencies
+   * `@metaplex-foundation/mpl-core` and
+   * `@metaplex-foundation/umi-bundle-defaults`. They are imported lazily
+   * the first time a method that needs them is called, so consumers that
+   * do not use the bridge incur zero overhead.
+   *
+   * @returns {MetaplexBridge} The lazily-instantiated `MetaplexBridge` singleton.
+   * @category Registries
+   * @since v0.9.0
+   * @see {@link MetaplexBridge}
+   *
+   * @example
+   * ```ts
+   * const profile = await client.metaplex.getUnifiedProfile({
+   *   wallet: agentWallet,
+   *   rpcUrl: "https://api.mainnet-beta.solana.com",
+   * });
+   * ```
+   */
+  get metaplex(): MetaplexBridge {
+    return (this.#metaplex ??= new MetaplexBridge(this.program));
+  }
 }

package/src/index.ts

@@ -373,6 +373,7 @@ export {
   X402Registry,
   SessionManager,
   AgentBuilder,
+  MetaplexBridge,
 } from "./registries/index";
 export type {
   DiscoveredAgent,
@@ -398,4 +399,10 @@ export type {
   ToolInput,
   RegisterResult,
   RegisterWithToolsResult,
+  UnifiedProfile,
+  MplAgentSnapshot,
+  Eip8004Registration,
+  Eip8004Service,
+  AttachAgentIdentityOpts,
+  UpdateAgentIdentityUriOpts,
 } from "./registries/index";

package/src/registries/index.ts

@@ -76,3 +76,13 @@ export type {
   RegisterResult,
   RegisterWithToolsResult,
 } from "./builder";
+
+export { MetaplexBridge } from "./metaplex-bridge";
+export type {
+  UnifiedProfile,
+  MplAgentSnapshot,
+  Eip8004Registration,
+  Eip8004Service,
+  AttachAgentIdentityOpts,
+  UpdateAgentIdentityUriOpts,
+} from "./metaplex-bridge";