@absol-labs/agent 0.1.0

package/src/frameworks/eliza.ts

@@ -0,0 +1,776 @@
+import type {
+  Action,
+  ActionExample,
+  Content,
+  HandlerCallback,
+  Plugin,
+} from "@elizaos/core";
+import { isAddress, isHex } from "viem";
+import { z } from "zod/v3";
+
+import {
+  discoverServices as defaultDiscoverServices,
+  type DiscoverServicesOptions,
+  type ServiceListing,
+} from "../discovery/registry.js";
+import { checkMandate, type SignedSpendMandate } from "../mandates/mandate.js";
+import {
+  type MandateAuthorizedStreamActionInput,
+  type ReclaimAuthorizedStreamInput,
+  type ReclaimVerifiedStreamResult,
+  type StreamProofTransactionResult,
+  type StreamStatusView,
+  type VerifiedStreamAgentOpener,
+} from "../sdk/client.js";
+
+/**
+ * Base Sepolia is the only settlement network Metrik supports today (Model A,
+ * single-chain USDC on Base).
+ */
+export const METRIK_ELIZA_SETTLEMENT_CHAIN_ID = 84532;
+
+const addressSchema = z
+  .string()
+  .refine((value) => isAddress(value), "must be an EVM address");
+const bytes32Schema = z
+  .string()
+  .refine(
+    (value) => isHex(value, { strict: true }) && value.length === 66,
+    "must be bytes32 hex",
+  );
+const decimalStringSchema = z.preprocess(
+  (value) =>
+    typeof value === "bigint" || typeof value === "number"
+      ? value.toString()
+      : value,
+  z.string().regex(/^(0|[1-9]\d*)$/, "must be a base-10 integer string"),
+);
+
+const spendMandateInputSchema = z.object({
+  maxPerStreamUsdc: decimalStringSchema,
+  maxTotalUsdc: decimalStringSchema,
+  maxRatePerSecondUsdc: decimalStringSchema,
+  maxDurationSeconds: z.number().int().positive(),
+  allowedOperators: z.array(addressSchema).optional(),
+  expiresAt: z.number().int().positive(),
+});
+
+const signedSpendMandateInputSchema = z.object({
+  mandateId: bytes32Schema,
+  owner: addressSchema,
+  chainId: z.number().int().positive(),
+  issuedAt: z.number().int().nonnegative(),
+  mandate: spendMandateInputSchema,
+  signature: z
+    .string()
+    .refine(
+      (value) => isHex(value, { strict: true }) && value.length === 132,
+      "must be a 65-byte signature",
+    ),
+});
+
+const discoverActionSchema = z.object({
+  category: z.string().min(1).optional(),
+  limit: z.number().int().positive().optional(),
+});
+
+const hireActionSchema = z.object({
+  operator: addressSchema,
+  serviceRef: bytes32Schema,
+  budgetUsdc: decimalStringSchema,
+  ratePerSecondUsdc: decimalStringSchema,
+  maxDurationSeconds: z.number().int().positive(),
+  signedMandate: signedSpendMandateInputSchema,
+});
+
+const streamStatusActionSchema = z.object({
+  streamId: bytes32Schema,
+});
+
+const reclaimActionSchema = z.object({
+  streamId: bytes32Schema,
+  closeFirst: z.boolean().optional(),
+  signedMandate: signedSpendMandateInputSchema,
+});
+
+const closeActionSchema = z.object({
+  streamId: bytes32Schema,
+  signedMandate: signedSpendMandateInputSchema,
+});
+
+/**
+ * Canonical ElizaOS action names (UPPER_SNAKE_CASE) the Metrik plugin registers.
+ */
+export const METRIK_ELIZA_ACTION_NAMES = {
+  DISCOVER: "DISCOVER_SERVICES",
+  HIRE: "HIRE_VERIFIED_SERVICE",
+  STATUS: "CHECK_STREAM_STATUS",
+  RECLAIM: "RECLAIM_UNSPENT",
+  CLOSE: "CLOSE_STREAM",
+} as const;
+
+export type MetrikElizaActionName =
+  | "DISCOVER_SERVICES"
+  | "HIRE_VERIFIED_SERVICE"
+  | "CHECK_STREAM_STATUS"
+  | "RECLAIM_UNSPENT"
+  | "CLOSE_STREAM";
+
+export interface MetrikElizaActionInputs {
+  readonly DISCOVER_SERVICES: z.input<typeof discoverActionSchema>;
+  readonly HIRE_VERIFIED_SERVICE: z.input<typeof hireActionSchema>;
+  readonly CHECK_STREAM_STATUS: z.input<typeof streamStatusActionSchema>;
+  readonly RECLAIM_UNSPENT: z.input<typeof reclaimActionSchema>;
+  readonly CLOSE_STREAM: z.input<typeof closeActionSchema>;
+}
+
+export interface MetrikElizaMandateStateResolver {
+  getSpentSoFarUsdc(owner: `0x${string}`): Promise<bigint>;
+  getRevokedMandateIds(owner: `0x${string}`): Promise<readonly `0x${string}`[]>;
+}
+
+/**
+ * The subset of the Metrik SDK the Eliza actions drive. `VerifiedStreamAgentClient`
+ * satisfies this structurally, so the plugin reuses the exact same SDK client +
+ * mandate-guard path as the AgentKit action provider — no forked business logic.
+ */
+export interface MetrikElizaClient extends Pick<
+  VerifiedStreamAgentOpener,
+  "openVerifiedStream"
+> {
+  getStreamStatus(streamId: `0x${string}`): Promise<StreamStatusView>;
+  reclaimStream(
+    input: ReclaimAuthorizedStreamInput,
+  ): Promise<ReclaimVerifiedStreamResult>;
+  closeStream(
+    input: MandateAuthorizedStreamActionInput,
+  ): Promise<StreamProofTransactionResult>;
+}
+
+export interface MetrikElizaPluginOptions {
+  readonly agentClient: MetrikElizaClient;
+  readonly mandateStateResolver?: Partial<MetrikElizaMandateStateResolver>;
+  readonly now?: () => number;
+  readonly pluginName?: string;
+  /**
+   * Discovery driver for the `DISCOVER_SERVICES` action. Defaults to the live
+   * registry-backed `discoverServices`; tests inject a double.
+   */
+  readonly discoverServices?: (
+    opts?: DiscoverServicesOptions,
+  ) => Promise<ServiceListing[]>;
+}
+
+type ElizaActionEnvelope = {
+  readonly action: MetrikElizaActionName;
+  readonly input: unknown;
+};
+
+const DEFAULT_MANDATE_STATE_RESOLVER: MetrikElizaMandateStateResolver = {
+  getSpentSoFarUsdc: async () => 0n,
+  getRevokedMandateIds: async () => [],
+};
+
+/**
+ * Build the Metrik ElizaOS plugin. The returned plugin registers four
+ * mandate-gated actions — `HIRE_VERIFIED_SERVICE`, `CHECK_STREAM_STATUS`,
+ * `RECLAIM_UNSPENT`, and `CLOSE_STREAM` — that let an Eliza agent hire, monitor,
+ * and unwind verified service streams on Base without ever bypassing the signed
+ * spend mandate. Every fund-moving action is fail-closed: the mandate guard runs
+ * BEFORE any transaction and throws on breach.
+ */
+export function createMetrikElizaPlugin(
+  options: MetrikElizaPluginOptions,
+): Plugin {
+  const resolver = {
+    ...DEFAULT_MANDATE_STATE_RESOLVER,
+    ...options.mandateStateResolver,
+  } satisfies MetrikElizaMandateStateResolver;
+  const now = options.now ?? (() => Math.floor(Date.now() / 1000));
+
+  return {
+    name: options.pluginName ?? "@absol-labs/agent/metrik-verified-services",
+    description:
+      "Mandate-gated Metrik actions for hiring, monitoring, reclaiming, and closing verified service streams on Base. x402 proves the payment, Metrik proves the delivery.",
+    actions: [
+      createDiscoverAction(options.discoverServices ?? defaultDiscoverServices),
+      createHireAction(options.agentClient, resolver, now),
+      createStatusAction(options.agentClient),
+      createReclaimAction(options.agentClient, resolver, now),
+      createCloseAction(options.agentClient, resolver, now),
+    ],
+  };
+}
+
+/**
+ * Convenience alias mirroring the `metrikActionProvider()` naming used by the
+ * AgentKit adapter. Same factory as {@link createMetrikElizaPlugin}.
+ */
+export const metrikElizaPlugin = createMetrikElizaPlugin;
+
+/**
+ * @deprecated Use {@link createMetrikElizaPlugin}. Retained for backward
+ * compatibility; the action names it registers are now the canonical
+ * UPPER_SNAKE_CASE ElizaOS names.
+ */
+export const createElizaVerifiedStreamPlugin = createMetrikElizaPlugin;
+
+export function createMetrikElizaContent<TAction extends MetrikElizaActionName>(
+  action: TAction,
+  input: MetrikElizaActionInputs[TAction],
+  text?: string,
+): Content {
+  return {
+    ...(text === undefined ? {} : { text }),
+    actions: [action],
+    source: "metrik",
+    metrik: {
+      action,
+      input,
+    } satisfies ElizaActionEnvelope,
+  };
+}
+
+/**
+ * @deprecated Use {@link createMetrikElizaContent}.
+ */
+export const createElizaVerifiedStreamContent = createMetrikElizaContent;
+
+function createDiscoverAction(
+  discover: (opts?: DiscoverServicesOptions) => Promise<ServiceListing[]>,
+): Action {
+  return {
+    name: "DISCOVER_SERVICES",
+    similes: [
+      "DISCOVER_VERIFIED_SERVICES",
+      "FIND_SERVICES",
+      "browse the metrik marketplace",
+      "what services can i hire",
+    ],
+    description:
+      "Discover verified third-party services on the Metrik marketplace. Returns each seller's payout operator, serviceRef, and endpoint for listings whose operator signature is cryptographically verified — the entry point before HIRE_VERIFIED_SERVICE.",
+    examples: createExamples("DISCOVER_SERVICES"),
+    validate: async (_runtime, message) =>
+      canParseElizaActionInput(message.content, "DISCOVER_SERVICES"),
+    handler: async (_runtime, message, _state, _options, callback) => {
+      try {
+        const input = parseElizaActionInput(
+          message.content,
+          "DISCOVER_SERVICES",
+        );
+        const listings = await discover({
+          ...(input.category === undefined ? {} : { category: input.category }),
+          ...(input.limit === undefined ? {} : { limit: input.limit }),
+        });
+        const text = `discovered ${listings.length} verified service${listings.length === 1 ? "" : "s"}`;
+        const data = { services: listings };
+        return await successResult(text, data, callback);
+      } catch (error) {
+        return await failureResult(asErrorMessage(error), callback);
+      }
+    },
+  };
+}
+
+function createHireAction(
+  agentClient: MetrikElizaClient,
+  resolver: MetrikElizaMandateStateResolver,
+  now: () => number,
+): Action {
+  return {
+    name: "HIRE_VERIFIED_SERVICE",
+    similes: [
+      "HIRE_SERVICE",
+      "OPEN_VERIFIED_STREAM",
+      "hire a verified service",
+      "pay for a service with metrik",
+      "open a verified payment stream",
+    ],
+    description:
+      "Hire a third-party service through Metrik: escrow USDC on Base for a per-second verified-delivery stream. Payment accrues only for delivery the oracle proves; unspent funds stay reclaimable. Refuses before any transaction if the hire would exceed the signed spend mandate.",
+    examples: createExamples("HIRE_VERIFIED_SERVICE"),
+    validate: async (_runtime, message) =>
+      canParseElizaActionInput(message.content, "HIRE_VERIFIED_SERVICE"),
+    handler: async (_runtime, message, _state, _options, callback) => {
+      try {
+        const input = parseElizaActionInput(
+          message.content,
+          "HIRE_VERIFIED_SERVICE",
+        );
+        const signedMandate = parseSignedMandateInput(input.signedMandate);
+        const nowSeconds = now();
+        const spentSoFarUsdc = await resolver.getSpentSoFarUsdc(
+          signedMandate.owner as `0x${string}`,
+        );
+        const revokedMandateIds = await resolver.getRevokedMandateIds(
+          signedMandate.owner as `0x${string}`,
+        );
+        // Mandate guard runs BEFORE any transaction — fail closed on breach.
+        const decision = await checkMandate(
+          signedMandate,
+          {
+            operator: input.operator as `0x${string}`,
+            budgetUsdc: BigInt(input.budgetUsdc),
+            ratePerSecondUsdc: BigInt(input.ratePerSecondUsdc),
+            maxDurationSeconds: input.maxDurationSeconds,
+          },
+          spentSoFarUsdc,
+          {
+            nowSeconds,
+            revokedMandateIds,
+          },
+        );
+        if (!decision.allowed) {
+          return await failureResult(
+            `mandate denied: ${decision.reason ?? "unknown"}`,
+            callback,
+          );
+        }
+
+        const result = await agentClient.openVerifiedStream({
+          operator: input.operator as `0x${string}`,
+          serviceRef: input.serviceRef as `0x${string}`,
+          budgetUsdc: BigInt(input.budgetUsdc),
+          ratePerSecondUsdc: BigInt(input.ratePerSecondUsdc),
+          maxDurationSeconds: input.maxDurationSeconds,
+          signedMandate,
+          spentSoFarUsdc,
+          nowSeconds,
+          revokedMandateIds,
+        });
+        const text = `opened verified service stream ${result.streamId} on chain ${result.handle.chainId}`;
+        const data = {
+          streamId: result.streamId,
+          txHash: result.txHash,
+          approveTxHash: result.approveTxHash,
+          handle: {
+            streamId: result.handle.streamId,
+            escrow: result.handle.escrow,
+            chainId: result.handle.chainId,
+          },
+        };
+
+        return await successResult(text, data, callback);
+      } catch (error) {
+        return await failureResult(asErrorMessage(error), callback);
+      }
+    },
+  };
+}
+
+function createStatusAction(agentClient: MetrikElizaClient): Action {
+  return {
+    name: "CHECK_STREAM_STATUS",
+    similes: [
+      "GET_STREAM_STATUS",
+      "MONITOR_STREAM",
+      "check my metrik stream",
+      "is the service still delivering",
+    ],
+    description:
+      "Read the current Metrik stream status — verified accrual, active/paused state (two failed checks auto-pause), and claimable/reclaimable USDC — plus whether the agent should stop work.",
+    examples: createExamples("CHECK_STREAM_STATUS"),
+    validate: async (_runtime, message) =>
+      canParseElizaActionInput(message.content, "CHECK_STREAM_STATUS"),
+    handler: async (_runtime, message, _state, _options, callback) => {
+      try {
+        const input = parseElizaActionInput(
+          message.content,
+          "CHECK_STREAM_STATUS",
+        );
+        const status = await agentClient.getStreamStatus(
+          input.streamId as `0x${string}`,
+        );
+        const data = serializeStreamStatus(
+          status,
+          input.streamId as `0x${string}`,
+        );
+        const text = `stream ${input.streamId} is ${status.stream.status}`;
+        return await successResult(text, data, callback);
+      } catch (error) {
+        return await failureResult(asErrorMessage(error), callback);
+      }
+    },
+  };
+}
+
+function createReclaimAction(
+  agentClient: MetrikElizaClient,
+  resolver: MetrikElizaMandateStateResolver,
+  now: () => number,
+): Action {
+  return {
+    name: "RECLAIM_UNSPENT",
+    similes: [
+      "RECLAIM_STREAM",
+      "RECLAIM_FUNDS",
+      "get my unspent usdc back",
+      "refund the remaining balance",
+    ],
+    description:
+      "Reclaim unspent escrowed USDC from a verified stream back to the buyer under the original signed mandate. Set closeFirst to close an active stream before reclaiming.",
+    examples: createExamples("RECLAIM_UNSPENT"),
+    validate: async (_runtime, message) =>
+      canParseElizaActionInput(message.content, "RECLAIM_UNSPENT"),
+    handler: async (_runtime, message, _state, _options, callback) => {
+      try {
+        const input = parseElizaActionInput(message.content, "RECLAIM_UNSPENT");
+        const authorized = await buildAuthorizedStreamInput(
+          input.streamId,
+          input.signedMandate,
+          resolver,
+          now,
+        );
+        const result = await agentClient.reclaimStream({
+          ...authorized,
+          ...(input.closeFirst === undefined
+            ? {}
+            : { closeFirst: input.closeFirst }),
+        });
+        const text = `reclaimed stream ${input.streamId}`;
+        const data = {
+          closeTxHash: result.closeResult?.txHash ?? null,
+          reclaimTxHash: result.reclaimResult.txHash,
+        };
+
+        return await successResult(text, data, callback);
+      } catch (error) {
+        return await failureResult(asErrorMessage(error), callback);
+      }
+    },
+  };
+}
+
+function createCloseAction(
+  agentClient: MetrikElizaClient,
+  resolver: MetrikElizaMandateStateResolver,
+  now: () => number,
+): Action {
+  return {
+    name: "CLOSE_STREAM",
+    similes: [
+      "CLOSE_VERIFIED_STREAM",
+      "STOP_STREAM",
+      "close the metrik stream",
+      "stop paying the service",
+    ],
+    description:
+      "Close a Metrik stream, finalizing accrual and halting further payment, under the same signed mandate controls. Follow with RECLAIM_UNSPENT to return the remaining balance to the buyer.",
+    examples: createExamples("CLOSE_STREAM"),
+    validate: async (_runtime, message) =>
+      canParseElizaActionInput(message.content, "CLOSE_STREAM"),
+    handler: async (_runtime, message, _state, _options, callback) => {
+      try {
+        const input = parseElizaActionInput(message.content, "CLOSE_STREAM");
+        const authorized = await buildAuthorizedStreamInput(
+          input.streamId,
+          input.signedMandate,
+          resolver,
+          now,
+        );
+        const result = await agentClient.closeStream(authorized);
+        const text = `closed stream ${input.streamId}`;
+        const data = { closeTxHash: result.txHash };
+        return await successResult(text, data, callback);
+      } catch (error) {
+        return await failureResult(asErrorMessage(error), callback);
+      }
+    },
+  };
+}
+
+async function buildAuthorizedStreamInput(
+  streamId: string,
+  signedMandateInput: z.input<typeof signedSpendMandateInputSchema>,
+  resolver: MetrikElizaMandateStateResolver,
+  now: () => number,
+): Promise<MandateAuthorizedStreamActionInput> {
+  const signedMandate = parseSignedMandateInput(signedMandateInput);
+  const nowSeconds = now();
+  const spentSoFarUsdc = await resolver.getSpentSoFarUsdc(
+    signedMandate.owner as `0x${string}`,
+  );
+  const revokedMandateIds = await resolver.getRevokedMandateIds(
+    signedMandate.owner as `0x${string}`,
+  );
+  return {
+    streamId: streamId as `0x${string}`,
+    signedMandate,
+    spentSoFarUsdc,
+    nowSeconds,
+    revokedMandateIds,
+  };
+}
+
+function createExamples(action: MetrikElizaActionName): ActionExample[][] {
+  const exampleMandate = {
+    mandateId: `0x${"55".repeat(32)}`,
+    owner: "0x1111111111111111111111111111111111111111",
+    chainId: 84532,
+    issuedAt: 1_900_000_000,
+    mandate: {
+      maxPerStreamUsdc: "100000000",
+      maxTotalUsdc: "300000000",
+      maxRatePerSecondUsdc: "2000000",
+      maxDurationSeconds: 86400,
+      expiresAt: 2_000_000_000,
+    },
+    signature: `0x${"aa".repeat(65)}`,
+  } as const;
+
+  switch (action) {
+    case "DISCOVER_SERVICES":
+      return [
+        [
+          {
+            name: "{{user1}}",
+            content: createMetrikElizaContent(action, {
+              category: "inference",
+              limit: 5,
+            }),
+          },
+          {
+            name: "{{agentName}}",
+            content: {
+              text: "discovered 3 verified services",
+              actions: [action],
+            },
+          },
+        ],
+      ];
+    case "HIRE_VERIFIED_SERVICE":
+      return [
+        [
+          {
+            name: "{{user1}}",
+            content: createMetrikElizaContent(action, {
+              operator: "0x2222222222222222222222222222222222222222",
+              serviceRef: `0x${"11".repeat(32)}`,
+              budgetUsdc: "90000000",
+              ratePerSecondUsdc: "1000000",
+              maxDurationSeconds: 3600,
+              signedMandate: exampleMandate,
+            }),
+          },
+          {
+            name: "{{agentName}}",
+            content: {
+              text: "opened verified service stream 0x...",
+              actions: [action],
+            },
+          },
+        ],
+      ];
+    case "CHECK_STREAM_STATUS":
+      return [
+        [
+          {
+            name: "{{user1}}",
+            content: createMetrikElizaContent(action, {
+              streamId: `0x${"44".repeat(32)}`,
+            }),
+          },
+          {
+            name: "{{agentName}}",
+            content: {
+              text: "stream 0x... is active",
+              actions: [action],
+            },
+          },
+        ],
+      ];
+    case "RECLAIM_UNSPENT":
+      return [
+        [
+          {
+            name: "{{user1}}",
+            content: createMetrikElizaContent(action, {
+              streamId: `0x${"44".repeat(32)}`,
+              closeFirst: true,
+              signedMandate: exampleMandate,
+            }),
+          },
+          {
+            name: "{{agentName}}",
+            content: {
+              text: "reclaimed stream 0x...",
+              actions: [action],
+            },
+          },
+        ],
+      ];
+    case "CLOSE_STREAM":
+      return [
+        [
+          {
+            name: "{{user1}}",
+            content: createMetrikElizaContent(action, {
+              streamId: `0x${"44".repeat(32)}`,
+              signedMandate: exampleMandate,
+            }),
+          },
+          {
+            name: "{{agentName}}",
+            content: {
+              text: "closed stream 0x...",
+              actions: [action],
+            },
+          },
+        ],
+      ];
+  }
+}
+
+function canParseElizaActionInput(
+  content: Content,
+  action: MetrikElizaActionName,
+): boolean {
+  try {
+    parseElizaActionInput(content, action as never);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseElizaActionInput(
+  content: Content,
+  action: "DISCOVER_SERVICES",
+): z.output<typeof discoverActionSchema>;
+function parseElizaActionInput(
+  content: Content,
+  action: "HIRE_VERIFIED_SERVICE",
+): z.output<typeof hireActionSchema>;
+function parseElizaActionInput(
+  content: Content,
+  action: "CHECK_STREAM_STATUS",
+): z.output<typeof streamStatusActionSchema>;
+function parseElizaActionInput(
+  content: Content,
+  action: "RECLAIM_UNSPENT",
+): z.output<typeof reclaimActionSchema>;
+function parseElizaActionInput(
+  content: Content,
+  action: "CLOSE_STREAM",
+): z.output<typeof closeActionSchema>;
+function parseElizaActionInput(
+  content: Content,
+  action: MetrikElizaActionName,
+) {
+  const envelope = parseElizaActionEnvelope(content);
+  if (envelope.action !== action) {
+    throw new Error(`expected ${action} payload, received ${envelope.action}`);
+  }
+
+  switch (action) {
+    case "DISCOVER_SERVICES":
+      return discoverActionSchema.parse(envelope.input);
+    case "HIRE_VERIFIED_SERVICE":
+      return hireActionSchema.parse(envelope.input);
+    case "CHECK_STREAM_STATUS":
+      return streamStatusActionSchema.parse(envelope.input);
+    case "RECLAIM_UNSPENT":
+      return reclaimActionSchema.parse(envelope.input);
+    case "CLOSE_STREAM":
+      return closeActionSchema.parse(envelope.input);
+  }
+}
+
+function parseElizaActionEnvelope(content: Content): ElizaActionEnvelope {
+  const envelope = content.metrik;
+  if (
+    envelope === null ||
+    typeof envelope !== "object" ||
+    !("action" in envelope) ||
+    !("input" in envelope)
+  ) {
+    throw new Error("missing content.metrik action envelope");
+  }
+
+  const action = (envelope as { action: unknown }).action;
+  if (
+    action !== "DISCOVER_SERVICES" &&
+    action !== "HIRE_VERIFIED_SERVICE" &&
+    action !== "CHECK_STREAM_STATUS" &&
+    action !== "RECLAIM_UNSPENT" &&
+    action !== "CLOSE_STREAM"
+  ) {
+    throw new Error("unsupported content.metrik action");
+  }
+
+  return {
+    action,
+    input: (envelope as { input: unknown }).input,
+  };
+}
+
+function parseSignedMandateInput(
+  value: z.input<typeof signedSpendMandateInputSchema>,
+): SignedSpendMandate {
+  const parsed = signedSpendMandateInputSchema.parse(value);
+  return {
+    ...parsed,
+    mandateId: parsed.mandateId as `0x${string}`,
+    owner: parsed.owner as `0x${string}`,
+    signature: parsed.signature as `0x${string}`,
+    mandate: {
+      ...parsed.mandate,
+      maxPerStreamUsdc: BigInt(parsed.mandate.maxPerStreamUsdc),
+      maxTotalUsdc: BigInt(parsed.mandate.maxTotalUsdc),
+      maxRatePerSecondUsdc: BigInt(parsed.mandate.maxRatePerSecondUsdc),
+    },
+  };
+}
+
+function serializeStreamStatus(
+  result: StreamStatusView,
+  streamId: `0x${string}`,
+) {
+  return {
+    streamId,
+    shouldStop: result.stream.status !== "active",
+    stream: {
+      ...result.stream,
+      deposit: result.stream.deposit.toString(),
+      ratePerSecond: result.stream.ratePerSecond.toString(),
+      accrued: result.stream.accrued.toString(),
+      claimed: result.stream.claimed.toString(),
+      lastSequence: result.stream.lastSequence.toString(),
+    },
+    claimable: result.claimable.toString(),
+    reclaimable: result.reclaimable.toString(),
+  };
+}
+
+async function successResult(
+  text: string,
+  data: Record<string, unknown>,
+  callback?: HandlerCallback,
+) {
+  await callback?.({
+    text,
+    source: "metrik",
+    metrik: data,
+  });
+  return {
+    success: true,
+    text,
+    data,
+  };
+}
+
+async function failureResult(text: string, callback?: HandlerCallback) {
+  await callback?.({
+    text,
+    source: "metrik",
+    error: true,
+  });
+  return {
+    success: false,
+    error: text,
+  };
+}
+
+function asErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}