@mantle-agent/client 0.0.0-stage → 0.1.0

package/src/agent.ts

@@ -0,0 +1,337 @@
+import type { Address, Hex } from "viem";
+import { ClientError, request, type Fetch } from "./http.js";
+
+export type CredentialKind = "trading" | "social" | "runtime";
+export type Credentials = Record<CredentialKind, { token: string; expiresAt: string }>;
+
+/** What the agent signs with when proving it holds the key that started a claim. */
+export type AgentKey = {
+  /** Ed25519 public key, 32 raw bytes as hex. */
+  publicKey: string;
+  /** Ed25519 signature over `message` (UTF-8), 64 bytes as hex. */
+  sign(message: string): string | Promise<string>;
+};
+
+export type Claim = {
+  claimId: string;
+  claimUrl: string;
+  userCode: string;
+  fingerprint: string;
+  expiresAt: string;
+  /** Proposed limits as the owner will see them, or null. */
+  proposal: string[] | null;
+};
+
+export type Side = "buy" | "sell";
+
+/** Amounts are decimal strings in wei (18 decimals), as the API returns them. */
+export type Quote = {
+  quoteId: string;
+  side: Side;
+  adapter: Address;
+  token: Address;
+  amountIn: string;
+  expectedOut: string;
+  minAmountOut: string;
+  expiresAt: string;
+};
+
+export type IntentStatus = "accepted" | "submitted" | "pending" | "confirmed" | "failed" | "unknown";
+
+export type Intent = {
+  intentId: string;
+  requestId: string;
+  quoteId: string;
+  side: Side;
+  token: Address;
+  amountIn: string;
+  minAmountOut: string;
+  status: IntentStatus;
+  txHash: Hex | null;
+  amountOut: string | null;
+  errorCode: string | null;
+  error: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type DimensionState = "active" | "expiring" | "expired" | "revoked" | "none";
+
+export type RuntimeStatus = {
+  enabled: boolean;
+  paused: boolean;
+  nextRunAt: string | null;
+  config: {
+    intervalSeconds: number;
+    maxRunSeconds: number;
+    maxTradesPerRun: number;
+    maxTradesPerDay: number;
+    maxSpendPerDayWei: string;
+    maxLlmCostPerDayUsd: number;
+  };
+  today: { trades: number; spendWei: string; llmCostUsd: number };
+  running: { leaseId: string; expiresAt: string; trades: number } | null;
+  pendingCommands: { commandId: string; kind: string }[];
+} | null;
+
+export type AgentStatus = {
+  agent: { agentId: string; name: string; status: "pending" | "active" | "stopped"; account: Address | null };
+  balanceWei: string | null;
+  session: {
+    keyHash: Hex;
+    state: DimensionState;
+    expiresAt: string;
+    maxSlippageBps: number;
+    limits: { perTradeCap: string; periodCap: string; totalCap: string };
+    remaining: { perTrade: string; period: string; total: string } | null;
+  } | null;
+  credentials: { kind: CredentialKind; state: DimensionState; expiresAt: string; lastUsedAt: string | null }[];
+  runtime: RuntimeStatus;
+  recentTrades: Intent[];
+};
+
+export type Lease =
+  | { granted: false; reason: "disabled" | "paused" | "not_due" | "budget_exhausted"; nextRunAt: string | null }
+  | {
+      granted: true;
+      leaseId: string;
+      expiresAt: string;
+      budget: { trades: number; spendWei: string; llmCostUsd: number };
+      commands: { commandId: string; kind: "pause" | "resume" | "run_now"; createdAt: string }[];
+    };
+
+/** Session limits an agent can ask for (PRD WAL-02). Amounts in MNT wei; the owner confirms them with a passkey. */
+export type SessionLimits = {
+  perTradeCap: bigint;
+  periodCap: bigint;
+  totalCap: bigint;
+  periodSeconds: number;
+  durationSeconds: number;
+  maxSlippageBps: number;
+};
+
+const MNT = 10n ** 18n;
+/** PRD V1 defaults: 2 MNT per trade, 10 MNT per 24 h, 20 MNT in total, 7 days, 2 % slippage. */
+export const DEFAULT_SESSION_LIMITS: SessionLimits = {
+  perTradeCap: 2n * MNT,
+  periodCap: 10n * MNT,
+  totalCap: 20n * MNT,
+  periodSeconds: 86_400,
+  durationSeconds: 7 * 86_400,
+  maxSlippageBps: 200,
+};
+
+/** Scheduled-run budgets (PRD RUN-02/03), on top of the on-chain limits. */
+export type AutoRunSettings = {
+  enabled: boolean;
+  intervalSeconds: number;
+  maxRunSeconds: number;
+  maxTradesPerRun: number;
+  maxTradesPerDay: number;
+  maxSpendPerDay: bigint;
+  maxLlmCostPerDayUsd: number;
+};
+
+export type OwnerRequestKind = "authorize" | "renew" | "revoke" | "withdraw" | "runtime" | "resume";
+
+/**
+ * Something only the owner can do, asked for by the agent. Relay `confirmUrl` and `summary` to the owner; they
+ * confirm on the page with a passkey. `completed` once it took effect (on chain for signing kinds).
+ */
+export type OwnerRequest = {
+  requestId: string;
+  agentId: string;
+  agentName: string;
+  kind: OwnerRequestKind;
+  status: "pending" | "approved" | "completed" | "rejected" | "expired" | "superseded";
+  createdBy: "agent" | "claim";
+  summary: string[];
+  warnings: string[];
+  confirmUrl: string;
+  expiresAt: string;
+  createdAt: string;
+  operation: { operationId: string; status: "prepared" | "submitted" | "confirmed" | "failed"; error: string | null } | null;
+  note: string | null;
+};
+
+const limitsJson = (l: SessionLimits) => ({
+  perTradeCap: l.perTradeCap.toString(),
+  periodCap: l.periodCap.toString(),
+  totalCap: l.totalCap.toString(),
+  periodSeconds: l.periodSeconds,
+  durationSeconds: l.durationSeconds,
+  maxSlippageBps: l.maxSlippageBps,
+});
+
+const FINAL: ReadonlySet<IntentStatus> = new Set(["confirmed", "failed", "unknown"]);
+
+/** Must match the API's claimProofMessage. */
+export const claimProofMessage = (claimId: string) => `mantle-agent-claim:${claimId}`;
+
+/**
+ * PRD IDN-02: register the agent key, hand the owner a link + code + fingerprint via `onClaim`, then poll with a
+ * proof of the key until the owner approves. Returns the credentials exactly once; store them securely.
+ */
+export async function connectAgent(params: {
+  baseUrl: string;
+  agentName: string;
+  host: string;
+  key: AgentKey;
+  /** Show this to the owner. Compare `fingerprint` with one computed locally from the key. */
+  onClaim: (claim: Claim) => void | Promise<void>;
+  /** Limits to propose: the owner confirms them right after claiming, in the same visit. */
+  authorize?: SessionLimits;
+  pollMs?: number;
+  fetch?: Fetch;
+}): Promise<{ agentId: string; credentials: Credentials }> {
+  const claim = await startClaim(params);
+  await params.onClaim(claim);
+  for (;;) {
+    const result = await exchangeClaim({ ...params, claimId: claim.claimId });
+    if (result.status === "exchanged") return result;
+    await new Promise((r) => setTimeout(r, params.pollMs ?? 2_000));
+  }
+}
+
+/** First half of `connectAgent`: register the key and get the link + code + fingerprint for the owner. */
+export async function startClaim(params: {
+  baseUrl: string;
+  agentName: string;
+  host: string;
+  key: AgentKey;
+  authorize?: SessionLimits;
+  fetch?: Fetch;
+}): Promise<Claim> {
+  const { body } = await request<Claim>(params.fetch ?? fetch, params.baseUrl, "POST", "/v1/claims", {
+    body: {
+      agentName: params.agentName,
+      host: params.host,
+      publicKey: params.key.publicKey,
+      ...(params.authorize ? { authorize: limitsJson(params.authorize) } : {}),
+    },
+  });
+  return body;
+}
+
+export type ClaimResult = { status: "pending"; expiresAt: string } | { status: "exchanged"; agentId: string; credentials: Credentials };
+
+/**
+ * Second half of `connectAgent`, one attempt: `pending` until the owner approves, then the credentials exactly once.
+ * Stateless, so an agent can start a claim, end its turn, and check again later (CLAIM_EXPIRED once it lapsed).
+ */
+export async function exchangeClaim(params: { baseUrl: string; claimId: string; key: AgentKey; fetch?: Fetch }): Promise<ClaimResult> {
+  const signature = await params.key.sign(claimProofMessage(params.claimId));
+  const { body } = await request<ClaimResult>(params.fetch ?? fetch, params.baseUrl, "POST", `/v1/claims/${params.claimId}/exchange`, {
+    body: { signature },
+  });
+  return body;
+}
+
+/**
+ * The agent's side of a Mantle Agent Account. It can only do what the owner authorized: trade within on-chain
+ * limits, read its status, manage its own scheduled runs, and stop itself. It never holds a private key.
+ */
+export class AgentClient {
+  private readonly fetchImpl: Fetch;
+  /** Set when running inside a scheduled run; trades are charged to that run's budget. */
+  leaseId: string | undefined;
+
+  constructor(
+    readonly baseUrl: string,
+    private readonly credentials: Partial<Credentials> | null,
+    opts: { fetch?: Fetch; leaseId?: string } = {},
+  ) {
+    this.fetchImpl = opts.fetch ?? ((...a) => fetch(...a));
+    this.leaseId = opts.leaseId;
+  }
+
+  private async call<T>(method: "GET" | "POST", path: string, kind: CredentialKind, opts: { body?: unknown; headers?: Record<string, string> } = {}) {
+    const token = this.credentials?.[kind]?.token;
+    if (!token) throw new ClientError("NOT_CONNECTED", "no credentials; connect the agent first");
+    return request<T>(this.fetchImpl, this.baseUrl, method, path, { ...opts, token });
+  }
+
+  async status(): Promise<AgentStatus> {
+    return (await this.call<AgentStatus>("GET", "/v1/status", "trading")).body;
+  }
+
+  /** Price a trade. Valid ~30 s and for one trade. `amountIn` is wei (MNT for buys, tokens for sells). */
+  async quote(params: { side: Side; token: Address; amountIn: bigint }): Promise<Quote> {
+    return (await this.call<Quote>("POST", "/v1/quotes", "trading", { body: params })).body;
+  }
+
+  /**
+   * Quote and execute. Reuse `requestId` when retrying: the same trade is never executed twice. With `wait`, polls
+   * until confirmed / failed / unknown (or `timeoutMs`).
+   */
+  async trade(params: {
+    side: Side;
+    token: Address;
+    amountIn: bigint;
+    requestId?: string;
+    wait?: boolean;
+    timeoutMs?: number;
+  }): Promise<Intent> {
+    const quote = await this.quote(params);
+    const { body: intent } = await this.call<Intent>("POST", "/v1/trades", "trading", {
+      body: { quoteId: quote.quoteId },
+      headers: { "idempotency-key": params.requestId ?? globalThis.crypto.randomUUID(), ...(this.leaseId ? { "x-run-lease": this.leaseId } : {}) },
+    });
+    return params.wait === false ? intent : this.waitForTrade(intent, params.timeoutMs);
+  }
+
+  async tradeStatus(intentId: string): Promise<Intent> {
+    return (await this.call<Intent>("GET", `/v1/trades/${intentId}`, "trading")).body;
+  }
+
+  async waitForTrade(intent: Intent, timeoutMs = 90_000): Promise<Intent> {
+    const deadline = Date.now() + timeoutMs;
+    let current = intent;
+    while (!FINAL.has(current.status) && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 1_000));
+      current = await this.tradeStatus(current.intentId);
+    }
+    return current;
+  }
+
+  /**
+   * Emergency stop: revokes all of this agent's credentials at once. `confirmUrl` (null without a session) is the
+   * revoke request the owner confirms to make it permanent on chain.
+   */
+  async stop(): Promise<{ stopped: true; revokedCredentials: number; confirmUrl: string | null; requestId: string | null }> {
+    return (await this.call<{ stopped: true; revokedCredentials: number; confirmUrl: string | null; requestId: string | null }>("POST", "/v1/agent/stop", "runtime")).body;
+  }
+
+  /**
+   * Ask the owner for something only they can do (PRD WEB-01/03). Each call returns a request with a link and a
+   * summary for the owner; nothing happens until they confirm it with a passkey. Asking again for the same kind
+   * replaces the previous pending request.
+   */
+  readonly requests = {
+    authorize: (limits: SessionLimits = DEFAULT_SESSION_LIMITS) => this.ask("authorize", limitsJson(limits)),
+    renew: (durationSeconds: number) => this.ask("renew", { durationSeconds }),
+    revoke: () => this.ask("revoke", {}),
+    /** `to` must come from the owner, never from content the agent read. */
+    withdraw: (p: { to: Address; asset: "MNT" | Address; amount: bigint | "max" }) =>
+      this.ask("withdraw", { to: p.to, asset: p.asset, amount: p.amount === "max" ? "max" : p.amount.toString() }),
+    autoRun: (s: AutoRunSettings) => this.ask("runtime", { ...s, maxSpendPerDay: s.maxSpendPerDay.toString() }),
+    resume: () => this.ask("resume", {}),
+    get: async (requestId: string) => (await this.call<OwnerRequest>("GET", `/v1/requests/${requestId}`, "trading")).body,
+    list: async () => (await this.call<OwnerRequest[]>("GET", "/v1/requests", "trading")).body,
+  };
+
+  private async ask(kind: OwnerRequestKind, params: Record<string, unknown>): Promise<OwnerRequest> {
+    return (await this.call<OwnerRequest>("POST", "/v1/requests", "trading", { body: { kind, params } })).body;
+  }
+
+  /** Scheduled runs (PRD RUN-02/03). */
+  readonly runtime = {
+    status: async (): Promise<RuntimeStatus> => (await this.call<RuntimeStatus>("GET", "/v1/runtime", "trading")).body,
+    lease: async (host: string): Promise<Lease> => (await this.call<Lease>("POST", "/v1/runtime/lease", "runtime", { body: { host } })).body,
+    complete: async (leaseId: string, report: { summary?: string; llmCostUsd?: number } = {}) =>
+      void (await this.call("POST", `/v1/runtime/lease/${leaseId}/complete`, "runtime", { body: report })),
+    ack: async (commandId: string) => void (await this.call("POST", `/v1/runtime/commands/${commandId}/ack`, "runtime")),
+    /** Agents may pause themselves; only the owner resumes. */
+    pause: async () => (await this.call<{ commandId: string }>("POST", "/v1/runtime/pause", "runtime")).body,
+  };
+}

package/src/browser.ts

@@ -0,0 +1,62 @@
+// Browser-only: Turnkey passkey (production) and dev-key owners for the confirmation page.
+import { ApiKeyStamper } from "@turnkey/api-key-stamper";
+import { generateP256KeyPair } from "@turnkey/crypto";
+import { Turnkey, TurnkeyBrowserClient } from "@turnkey/sdk-browser";
+import type { Address } from "viem";
+import { rootSigner, TURNKEY_API_BASE_URL, type OwnerApi, type SignedTurnkeyRequest } from "@mantle-agent/custody/owner";
+import type { OwnerTurnkey } from "./owner.js";
+
+type Client = OwnerApi & {
+  stampGetWhoami(input: { organizationId: string }): Promise<SignedTurnkeyRequest | undefined>;
+};
+
+function fromClient(kind: OwnerTurnkey["kind"], client: Client, parentOrgId: string, register: OwnerTurnkey["register"]): OwnerTurnkey {
+  return {
+    kind,
+    register,
+    async stampWhoami() {
+      const signed = await client.stampGetWhoami({ organizationId: parentOrgId });
+      if (!signed) throw new Error("could not produce a signed login request");
+      return signed;
+    },
+    owner: () => client,
+    rootSigner: (subOrgId, address) =>
+      rootSigner({ client: client as unknown as Parameters<typeof rootSigner>[0]["client"], subOrgId, rootAddress: address }),
+  };
+}
+
+/** Production: every owner action is approved with a passkey bound to this site (rpId = hostname). */
+export function passkeyTurnkey(params: { parentOrgId: string; rpId?: string; apiBaseUrl?: string }): OwnerTurnkey {
+  const rpId = params.rpId ?? window.location.hostname;
+  const sdk = new Turnkey({ apiBaseUrl: params.apiBaseUrl ?? TURNKEY_API_BASE_URL, defaultOrganizationId: params.parentOrgId, rpId });
+  const client = sdk.passkeyClient();
+  return fromClient("passkey", client as unknown as Client, params.parentOrgId, async (ownerName) => {
+    const { encodedChallenge, attestation } = await client.createUserPasskey({
+      publicKey: { rp: { id: rpId, name: "Mantle Agent Account" }, user: { name: ownerName, displayName: ownerName } },
+    });
+    return { passkey: { authenticatorName: `passkey-${Date.now()}`, challenge: encodedChallenge, attestation } };
+  });
+}
+
+const DEV_KEY_STORAGE = "mantle-agent:dev-owner-key";
+
+/**
+ * Development only (no passkeys, e.g. local or automated testing): a P-256 API key kept in this browser stands in
+ * for the passkey. The API accepts such owners only with ALLOW_API_KEY_OWNERS=true.
+ */
+export function devKeyTurnkey(params: { parentOrgId: string; apiBaseUrl?: string; storage?: Storage }): OwnerTurnkey {
+  const storage = params.storage ?? window.localStorage;
+  let saved = storage.getItem(DEV_KEY_STORAGE);
+  if (!saved) {
+    const kp = generateP256KeyPair();
+    saved = JSON.stringify({ publicKey: kp.publicKey, privateKey: kp.privateKey });
+    storage.setItem(DEV_KEY_STORAGE, saved);
+  }
+  const key = JSON.parse(saved) as { publicKey: string; privateKey: string };
+  const client = new TurnkeyBrowserClient({
+    stamper: new ApiKeyStamper({ apiPublicKey: key.publicKey, apiPrivateKey: key.privateKey }),
+    apiBaseUrl: params.apiBaseUrl ?? TURNKEY_API_BASE_URL,
+    organizationId: params.parentOrgId,
+  });
+  return fromClient("dev-key", client as unknown as Client, params.parentOrgId, async () => ({ apiPublicKey: key.publicKey }));
+}

package/src/http.ts

@@ -0,0 +1,46 @@
+/**
+ * A failure with the Mantle Agent API's stable error code (or a local one such as NOT_CONNECTED or
+ * API_UNREACHABLE). React to `code`, not to the message.
+ */
+export class ClientError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly details?: unknown,
+    readonly status?: number,
+  ) {
+    super(message);
+  }
+}
+
+export type Fetch = typeof fetch;
+
+export type RequestOptions = { token?: string | null; body?: unknown; headers?: Record<string, string> };
+
+/** JSON request against the API; non-2xx responses become ClientError with the API's code. */
+export async function request<T>(
+  fetchImpl: Fetch,
+  baseUrl: string,
+  method: "GET" | "POST",
+  path: string,
+  opts: RequestOptions = {},
+): Promise<{ status: number; body: T }> {
+  const headers: Record<string, string> = { ...opts.headers };
+  if (opts.body !== undefined) headers["content-type"] = "application/json";
+  if (opts.token) headers["authorization"] = `Bearer ${opts.token}`;
+  let res: Response;
+  try {
+    res = await fetchImpl(`${baseUrl}${path}`, {
+      method,
+      headers,
+      ...(opts.body === undefined ? {} : { body: JSON.stringify(opts.body, (_k, v) => (typeof v === "bigint" ? v.toString() : v)) }),
+    });
+  } catch (err) {
+    throw new ClientError("API_UNREACHABLE", `cannot reach ${baseUrl}`, { reason: String(err) });
+  }
+  const body = (await res.json().catch(() => ({}))) as T & { code?: string; message?: string; details?: unknown };
+  if (res.status >= 400) {
+    throw new ClientError(body.code ?? `HTTP_${res.status}`, body.message ?? res.statusText, body.details, res.status);
+  }
+  return { status: res.status, body };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+// Agent side (no Turnkey, no custody). Owner flows: "@mantle-agent/client/owner"; browser passkey: "@mantle-agent/client/browser".
+export * from "./http.js";
+export * from "./agent.js";