@absol-labs/agent 0.1.0

package/src/mcp/stdio.ts

@@ -0,0 +1,8 @@
+import { startVerifiedStreamMcpServerStdio } from "./server.js";
+
+startVerifiedStreamMcpServerStdio().catch((error) => {
+  console.error(
+    error instanceof Error ? error.message : "failed to start MCP server",
+  );
+  process.exit(1);
+});

package/src/sdk/client.ts

@@ -0,0 +1,222 @@
+import {
+  StreamProofClient,
+  type HireComputeResult,
+  type StreamProofClientConfig,
+  type StreamProofStream,
+} from "@absol-labs/sdk";
+
+import {
+  checkMandate,
+  verifyMandateOwnerSignature,
+  type HireRequest,
+  type MandateDecision,
+  type SignedSpendMandate,
+} from "../mandates/mandate.js";
+
+export interface OpenVerifiedStreamInput {
+  readonly operator: `0x${string}`;
+  readonly serviceRef: `0x${string}`;
+  readonly budgetUsdc: bigint;
+  readonly ratePerSecondUsdc: bigint;
+  readonly maxDurationSeconds: number;
+  readonly signedMandate: SignedSpendMandate;
+  readonly spentSoFarUsdc: bigint;
+  readonly nowSeconds: number;
+  readonly revokedMandateIds?: Iterable<`0x${string}`>;
+}
+
+export interface StreamStatusView {
+  readonly stream: StreamProofStream;
+  readonly claimable: bigint;
+  readonly reclaimable: bigint;
+}
+
+export interface ReclaimVerifiedStreamOptions {
+  readonly closeFirst?: boolean;
+}
+
+export interface ReclaimVerifiedStreamResult {
+  readonly closeResult: StreamProofTransactionResult | null;
+  readonly reclaimResult: StreamProofTransactionResult;
+}
+
+export type StreamProofTransactionResult = Awaited<
+  ReturnType<StreamProofClient["claim"]>
+>;
+
+export interface MandateAuthorizedStreamActionInput {
+  readonly streamId: `0x${string}`;
+  readonly signedMandate: SignedSpendMandate;
+  readonly spentSoFarUsdc: bigint;
+  readonly nowSeconds: number;
+  readonly revokedMandateIds?: Iterable<`0x${string}`>;
+}
+
+export interface ReclaimAuthorizedStreamInput
+  extends MandateAuthorizedStreamActionInput, ReclaimVerifiedStreamOptions {}
+
+export interface AgentSdkClient {
+  hireAkashCompute(input: {
+    readonly operator: `0x${string}`;
+    readonly serviceRef: `0x${string}`;
+    readonly budgetUsdc: bigint;
+    readonly ratePerSecond: bigint;
+    readonly maxDurationSeconds: number;
+  }): Promise<HireComputeResult>;
+  getStream(streamId: `0x${string}`): Promise<StreamProofStream>;
+  claimable(streamId: `0x${string}`): Promise<bigint>;
+  reclaimable(streamId: `0x${string}`): Promise<bigint>;
+  claim(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
+  close(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
+  reclaim(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
+}
+
+export type AgentSdkClientFactory = (
+  config: StreamProofClientConfig,
+) => AgentSdkClient;
+
+export interface VerifiedStreamAgentOpener {
+  openVerifiedStream(
+    input: OpenVerifiedStreamInput,
+  ): Promise<HireComputeResult>;
+}
+
+export class MandateDeniedError extends Error {
+  readonly reason: NonNullable<MandateDecision["reason"]>;
+
+  constructor(reason: NonNullable<MandateDecision["reason"]>) {
+    super(`mandate denied: ${reason}`);
+    this.name = "MandateDeniedError";
+    this.reason = reason;
+  }
+}
+
+export class VerifiedStreamAgentClient implements VerifiedStreamAgentOpener {
+  private readonly sdkClient: AgentSdkClient;
+
+  constructor(
+    config: StreamProofClientConfig,
+    options: { readonly createSdkClient?: AgentSdkClientFactory } = {},
+  ) {
+    this.sdkClient = (options.createSdkClient ?? defaultSdkClientFactory)(
+      config,
+    );
+  }
+
+  async openVerifiedStream(
+    input: OpenVerifiedStreamInput,
+  ): Promise<HireComputeResult> {
+    const decision = await checkMandate(
+      input.signedMandate,
+      toHireRequest(input),
+      input.spentSoFarUsdc,
+      {
+        nowSeconds: input.nowSeconds,
+        ...(input.revokedMandateIds === undefined
+          ? {}
+          : { revokedMandateIds: input.revokedMandateIds }),
+      },
+    );
+    if (!decision.allowed) {
+      throw new MandateDeniedError(decision.reason ?? "mandate-expired");
+    }
+
+    return await this.sdkClient.hireAkashCompute({
+      operator: input.operator,
+      serviceRef: input.serviceRef,
+      budgetUsdc: input.budgetUsdc,
+      ratePerSecond: input.ratePerSecondUsdc,
+      maxDurationSeconds: input.maxDurationSeconds,
+    });
+  }
+
+  async getStreamStatus(streamId: `0x${string}`): Promise<StreamStatusView> {
+    const [stream, claimable, reclaimable] = await Promise.all([
+      this.sdkClient.getStream(streamId),
+      this.sdkClient.claimable(streamId),
+      this.sdkClient.reclaimable(streamId),
+    ]);
+
+    return { stream, claimable, reclaimable };
+  }
+
+  async claimStream(
+    input: MandateAuthorizedStreamActionInput,
+  ): Promise<StreamProofTransactionResult> {
+    await this.authorizeExistingStreamAction(input);
+    return await this.sdkClient.claim(input.streamId);
+  }
+
+  async closeStream(
+    input: MandateAuthorizedStreamActionInput,
+  ): Promise<StreamProofTransactionResult> {
+    await this.authorizeBuyerRecovery(input);
+    return await this.sdkClient.close(input.streamId);
+  }
+
+  async reclaimStream(
+    input: ReclaimAuthorizedStreamInput,
+  ): Promise<ReclaimVerifiedStreamResult> {
+    await this.authorizeBuyerRecovery(input);
+    const closeResult = input.closeFirst
+      ? await this.sdkClient.close(input.streamId)
+      : null;
+    const reclaimResult = await this.sdkClient.reclaim(input.streamId);
+    return { closeResult, reclaimResult };
+  }
+
+  /**
+   * Authorizes a BUYER-RECOVERY action (close / reclaim). These only return
+   * unspent funds to the buyer or stop payment, so they are authorized on
+   * mandate-owner signature ALONE — never gated by expiry, revocation, or caps,
+   * which would otherwise let a lapsed mandate strand the buyer's own funds.
+   */
+  private async authorizeBuyerRecovery(
+    input: MandateAuthorizedStreamActionInput,
+  ): Promise<void> {
+    const decision = await verifyMandateOwnerSignature(input.signedMandate);
+    if (!decision.allowed) {
+      throw new MandateDeniedError(decision.reason ?? "invalid-signature");
+    }
+  }
+
+  private async authorizeExistingStreamAction(
+    input: MandateAuthorizedStreamActionInput,
+  ): Promise<void> {
+    const stream = await this.sdkClient.getStream(input.streamId);
+    const decision = await checkMandate(
+      input.signedMandate,
+      {
+        operator: stream.operator as `0x${string}`,
+        budgetUsdc: 0n,
+        ratePerSecondUsdc: 0n,
+        maxDurationSeconds: 0,
+      },
+      input.spentSoFarUsdc,
+      {
+        nowSeconds: input.nowSeconds,
+        ...(input.revokedMandateIds === undefined
+          ? {}
+          : { revokedMandateIds: input.revokedMandateIds }),
+      },
+    );
+    if (!decision.allowed) {
+      throw new MandateDeniedError(decision.reason ?? "mandate-expired");
+    }
+  }
+}
+
+function defaultSdkClientFactory(
+  config: StreamProofClientConfig,
+): AgentSdkClient {
+  return new StreamProofClient(config);
+}
+
+function toHireRequest(input: OpenVerifiedStreamInput): HireRequest {
+  return {
+    operator: input.operator,
+    budgetUsdc: input.budgetUsdc,
+    ratePerSecondUsdc: input.ratePerSecondUsdc,
+    maxDurationSeconds: input.maxDurationSeconds,
+  };
+}

package/src/wallet/provider.ts

@@ -0,0 +1,197 @@
+import { type StreamProofClientConfig } from "@absol-labs/sdk";
+import {
+  CdpClient,
+  type EvmServerAccount,
+  type EvmSmartAccount,
+} from "@coinbase/cdp-sdk";
+import type { Account } from "viem";
+import { privateKeyToAccount, toAccount } from "viem/accounts";
+import { z } from "zod";
+
+import {
+  VerifiedStreamAgentClient,
+  type AgentSdkClientFactory,
+} from "../sdk/client.js";
+
+const privateKeySchema = z
+  .string()
+  .regex(/^0x[0-9a-fA-F]{64}$/, "must be a 32-byte private key");
+const booleanStringSchema = z
+  .enum(["true", "false", "1", "0"])
+  .transform((value) => value === "true" || value === "1");
+
+const cdpWalletEnvSchema = z.object({
+  CDP_API_KEY_ID: z.string().min(1, "CDP_API_KEY_ID is required"),
+  CDP_API_KEY_SECRET: z.string().min(1, "CDP_API_KEY_SECRET is required"),
+  CDP_WALLET_SECRET: z.string().min(1, "CDP_WALLET_SECRET is required"),
+  METRIK_AGENT_CDP_OWNER_NAME: z
+    .string()
+    .min(1, "METRIK_AGENT_CDP_OWNER_NAME is required"),
+  METRIK_AGENT_CDP_SMART_ACCOUNT_NAME: z.string().optional(),
+  METRIK_AGENT_CDP_CREATE_SMART_ACCOUNT: booleanStringSchema.optional(),
+});
+
+export class AgentWalletConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AgentWalletConfigError";
+  }
+}
+
+export interface CdpWalletConfig {
+  readonly apiKeyId?: string;
+  readonly apiKeySecret?: string;
+  readonly walletSecret?: string;
+  readonly ownerName: string;
+  readonly smartAccountName?: string;
+  readonly createSmartAccount?: boolean;
+}
+
+export type AgentWalletInput =
+  | {
+      readonly injectedAccount: Account;
+    }
+  | {
+      readonly cdp: CdpWalletConfig;
+    };
+
+export interface ResolvedAgentWallet {
+  readonly source: "injected" | "cdp";
+  readonly account: Account;
+  readonly cdpOwner?: EvmServerAccount;
+  readonly smartAccount?: EvmSmartAccount;
+}
+
+export interface CdpClientLike {
+  readonly evm: {
+    getOrCreateAccount(options: {
+      readonly name: string;
+    }): Promise<EvmServerAccount>;
+    getOrCreateSmartAccount(options: {
+      readonly name: string;
+      readonly owner: EvmServerAccount;
+    }): Promise<EvmSmartAccount>;
+  };
+}
+
+export interface ResolveAgentWalletOptions {
+  readonly createCdpClient?: (config: CdpWalletConfig) => CdpClientLike;
+}
+
+export interface CreateWalletBackedAgentClientOptions extends ResolveAgentWalletOptions {
+  readonly createSdkClient?: AgentSdkClientFactory;
+}
+
+export interface WalletBackedAgentClient {
+  readonly wallet: ResolvedAgentWallet;
+  readonly agentClient: VerifiedStreamAgentClient;
+}
+
+export async function resolveAgentWallet(
+  input: AgentWalletInput,
+  options: ResolveAgentWalletOptions = {},
+): Promise<ResolvedAgentWallet> {
+  if ("injectedAccount" in input) {
+    return {
+      source: "injected",
+      account: input.injectedAccount,
+    };
+  }
+
+  const cdpClient = (options.createCdpClient ?? defaultCdpClientFactory)(
+    input.cdp,
+  );
+  const owner = await cdpClient.evm.getOrCreateAccount({
+    name: input.cdp.ownerName,
+  });
+  const smartAccount = input.cdp.createSmartAccount
+    ? await cdpClient.evm.getOrCreateSmartAccount({
+        name: input.cdp.smartAccountName ?? `${input.cdp.ownerName}-smart`,
+        owner,
+      })
+    : undefined;
+
+  return {
+    source: "cdp",
+    account: toAccount(owner),
+    cdpOwner: owner,
+    ...(smartAccount === undefined ? {} : { smartAccount }),
+  };
+}
+
+export async function createWalletBackedAgentClient(
+  sdkConfig: StreamProofClientConfig,
+  walletInput: AgentWalletInput,
+  options: CreateWalletBackedAgentClientOptions = {},
+): Promise<WalletBackedAgentClient> {
+  const wallet = await resolveAgentWallet(walletInput, options);
+  const agentClient = new VerifiedStreamAgentClient(
+    {
+      ...sdkConfig,
+      account: wallet.account,
+    },
+    {
+      ...(options.createSdkClient === undefined
+        ? {}
+        : { createSdkClient: options.createSdkClient }),
+    },
+  );
+
+  return { wallet, agentClient };
+}
+
+export function parseAgentWalletEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): AgentWalletInput {
+  if (env.METRIK_AGENT_PRIVATE_KEY !== undefined) {
+    const privateKey = privateKeySchema.safeParse(env.METRIK_AGENT_PRIVATE_KEY);
+    if (!privateKey.success) {
+      throw new AgentWalletConfigError(
+        privateKey.error.issues.map((issue) => issue.message).join("; "),
+      );
+    }
+
+    return {
+      injectedAccount: privateKeyToAccount(privateKey.data as `0x${string}`),
+    };
+  }
+
+  const parsed = cdpWalletEnvSchema.safeParse(env);
+  if (!parsed.success) {
+    throw new AgentWalletConfigError(
+      parsed.error.issues.map((issue) => issue.message).join("; "),
+    );
+  }
+
+  return {
+    cdp: {
+      apiKeyId: parsed.data.CDP_API_KEY_ID,
+      apiKeySecret: parsed.data.CDP_API_KEY_SECRET,
+      walletSecret: parsed.data.CDP_WALLET_SECRET,
+      ownerName: parsed.data.METRIK_AGENT_CDP_OWNER_NAME,
+      ...(parsed.data.METRIK_AGENT_CDP_SMART_ACCOUNT_NAME === undefined
+        ? {}
+        : {
+            smartAccountName: parsed.data.METRIK_AGENT_CDP_SMART_ACCOUNT_NAME,
+          }),
+      ...(parsed.data.METRIK_AGENT_CDP_CREATE_SMART_ACCOUNT === undefined
+        ? {}
+        : {
+            createSmartAccount:
+              parsed.data.METRIK_AGENT_CDP_CREATE_SMART_ACCOUNT,
+          }),
+    },
+  };
+}
+
+function defaultCdpClientFactory(config: CdpWalletConfig): CdpClientLike {
+  return new CdpClient({
+    ...(config.apiKeyId === undefined ? {} : { apiKeyId: config.apiKeyId }),
+    ...(config.apiKeySecret === undefined
+      ? {}
+      : { apiKeySecret: config.apiKeySecret }),
+    ...(config.walletSecret === undefined
+      ? {}
+      : { walletSecret: config.walletSecret }),
+  });
+}