@mantle-agent/client 0.0.0-stage → 0.1.0

package/src/owner.ts

@@ -0,0 +1,414 @@
+import { formatEther, type Address, type Hex, type SignedAuthorization } from "viem";
+import {
+  type RootSigner,
+  callFromJson,
+  sign7702Authorization,
+  signedBatchedCallTypedData,
+  transactionFromJson,
+  type CallJson,
+  type TransactionJson,
+} from "@mantle-agent/core";
+import {
+  addPlatformDelegate,
+  createAgentWallet,
+  type OwnerApi,
+  type PolicyIntent,
+  type SignedTurnkeyRequest,
+} from "@mantle-agent/custody/owner";
+import type { OwnerRequest, RuntimeStatus } from "./agent.js";
+
+export type { OwnerRequest, OwnerRequestKind, RuntimeStatus } from "./agent.js";
+import { request, type Fetch } from "./http.js";
+
+export { ClientError } from "./http.js";
+
+/**
+ * Everything the owner does with Turnkey, on their own device and with their own credential (passkey in
+ * production). The platform is never involved in these calls. See `@mantle-agent/client/browser` for the passkey
+ * implementation.
+ */
+export interface OwnerTurnkey {
+  readonly kind: "passkey" | "dev-key";
+  /** Creates the owner's credential for signup (passkey prompt in production). */
+  register(ownerName: string): Promise<SignupCredential>;
+  /** A whoami stamped against the parent org, so login works from any device. */
+  stampWhoami(): Promise<SignedTurnkeyRequest>;
+  /** The owner acting inside their sub-org (wallets, users, policies). */
+  owner(subOrgId: string): OwnerApi;
+  /** The agent EOA's root key, for the owner's signatures. */
+  rootSigner(subOrgId: string, address: Address): RootSigner;
+}
+
+/** What signup sends to the API: a passkey attestation, or (dev only) an API public key. */
+export type SignupCredential =
+  | { passkey: { authenticatorName: string; challenge: string; attestation: unknown } }
+  | { apiPublicKey: string };
+
+/**
+ * The owner's side of the Mantle Agent API (the confirmation page backend). Holds the owner session once logged
+ * in; pass it to the flow functions below.
+ */
+export class OwnerClient {
+  token: string | null = null;
+  private readonly fetchImpl: Fetch;
+
+  constructor(
+    readonly baseUrl: string,
+    fetchImpl?: Fetch,
+  ) {
+    this.fetchImpl = fetchImpl ?? ((...a) => fetch(...a));
+  }
+
+  async call<T>(method: "GET" | "POST", path: string, body?: unknown): Promise<T> {
+    return (await request<T>(this.fetchImpl, this.baseUrl, method, path, { token: this.token, body })).body;
+  }
+}
+
+
+export type Platform = {
+  chainId: number;
+  caliburEntry: Address;
+  hook: Address;
+  targets: Address[];
+  executor: Address;
+  platformApiPublicKey: string;
+  turnkeyOrganizationId: string;
+};
+
+export type Owner = { ownerId: string; subOrgId: string; turnkeyUserId: string; daUserId: string | null; custodyVerified: boolean };
+export type Session = { token: string; expiresAt: string; owner: Owner };
+
+export const platform = (api: OwnerClient) => api.call<Platform>("GET", "/v1/platform");
+
+// ---------------------------------------------------------------------------------------------------------------
+// Sign up / log in / custody
+// ---------------------------------------------------------------------------------------------------------------
+
+export async function logIn(api: OwnerClient, tk: OwnerTurnkey): Promise<Session> {
+  const session = await api.call<Session>("POST", "/v1/owner/login", await tk.stampWhoami());
+  api.token = session.token;
+  return session;
+}
+
+/** New owner: create the credential (passkey prompt), let the API create the owner's Turnkey space, log in. */
+export async function signUp(api: OwnerClient, tk: OwnerTurnkey, ownerName: string): Promise<Session> {
+  const credential = await tk.register(ownerName);
+  await api.call("POST", "/v1/owner/signup", { ownerName, ...credential });
+  return logIn(api, tk);
+}
+
+/**
+ * One-time custody setup from the owner's own session: add the platform as a non-root user that can only sign
+ * what later policies allow, then have the API verify it with Turnkey.
+ */
+export async function ensureCustody(api: OwnerClient, tk: OwnerTurnkey, session: Session): Promise<Session> {
+  if (session.owner.custodyVerified) return session;
+  const { platformApiPublicKey } = await platform(api);
+  const { daUserId } = await addPlatformDelegate(tk.owner(session.owner.subOrgId), {
+    subOrgId: session.owner.subOrgId,
+    platformApiPublicKey,
+  });
+  const owner = await api.call<Owner>("POST", "/v1/owner/custody", { daUserId });
+  return { ...session, owner };
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Claims and agents
+// ---------------------------------------------------------------------------------------------------------------
+
+export type PendingClaim = {
+  claimId: string;
+  userCode: string;
+  agentName: string;
+  host: string;
+  fingerprint: string;
+  expiresAt: string;
+  /** Limits the agent proposed; after approval they come back as an authorize request (`requestId`). */
+  proposal: string[] | null;
+};
+
+export const lookupClaim = (api: OwnerClient, code: string) =>
+  api.call<PendingClaim>("GET", `/v1/owner/claims/${encodeURIComponent(code.trim().toUpperCase())}`);
+
+/**
+ * The owner checked the fingerprint against the CLI's: create the agent's own wallet in their space and approve.
+ * The API reads the wallet back from Turnkey before accepting it.
+ */
+export async function approveClaim(
+  api: OwnerClient,
+  tk: OwnerTurnkey,
+  session: Session,
+  claim: PendingClaim,
+): Promise<{ agentId: string; requestId: string | null }> {
+  const wallet = await createAgentWallet(tk.owner(session.owner.subOrgId), {
+    subOrgId: session.owner.subOrgId,
+    agentId: claim.claimId,
+  });
+  return api.call("POST", `/v1/owner/claims/${claim.claimId}/approve`, { walletId: wallet.walletId, fingerprint: claim.fingerprint });
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Owner requests: the agent asks in chat, the owner confirms here (PRD WEB-01/03)
+// ---------------------------------------------------------------------------------------------------------------
+
+export const getRequest = (api: OwnerClient, requestId: string) => api.call<OwnerRequest>("GET", `/v1/owner/requests/${requestId}`);
+export const pendingRequests = (api: OwnerClient) => api.call<OwnerRequest[]>("GET", "/v1/owner/requests");
+export const rejectRequest = (api: OwnerClient, requestId: string) => api.call<OwnerRequest>("POST", `/v1/owner/requests/${requestId}/reject`);
+
+/**
+ * The owner confirmed the summary. Signing kinds return the operation to run with `runOperation` (the same one
+ * again if the page was reloaded before it finished); auto-run kinds take effect right away (`prepared: null`).
+ */
+export const approveRequest = (api: OwnerClient, requestId: string) =>
+  api.call<{ request: OwnerRequest; prepared: PreparedOperation | null }>("POST", `/v1/owner/requests/${requestId}/approve`);
+
+export type AgentSummary = {
+  agent_id: string;
+  name: string;
+  status: "pending" | "active" | "stopped";
+  account: Address | null;
+  balanceWei: string | null;
+};
+export const listAgents = (api: OwnerClient) => api.call<AgentSummary[]>("GET", "/v1/owner/agents");
+
+// ---------------------------------------------------------------------------------------------------------------
+// Owner operations (authorize / renew / revoke)
+// ---------------------------------------------------------------------------------------------------------------
+
+/** PRD WAL-02 step 2 inputs for UIs that start an authorization themselves (MNT amounts in whole units). */
+export type AuthorizeForm = {
+  perTradeMnt: string;
+  periodMnt: string;
+  totalMnt: string;
+  periodHours: number;
+  durationDays: number;
+  maxSlippagePercent: number;
+};
+
+export const DEFAULT_LIMITS: AuthorizeForm = {
+  perTradeMnt: "2",
+  periodMnt: "10",
+  totalMnt: "20",
+  periodHours: 24,
+  durationDays: 7,
+  maxSlippagePercent: 2,
+};
+
+const wei = (mnt: string) => {
+  if (!/^\d+(\.\d{1,18})?$/.test(mnt)) throw new Error(`invalid MNT amount: ${mnt}`);
+  const [whole, frac = ""] = mnt.split(".");
+  return (BigInt(whole!) * 10n ** 18n + BigInt(frac.padEnd(18, "0"))).toString();
+};
+
+export type PreparedOperation = {
+  operationId: string;
+  kind: "authorize" | "renew" | "revoke" | "withdraw";
+  status: "prepared" | "submitted" | "confirmed" | "failed";
+  account: Address;
+  chainId: number;
+  call?: CallJson;
+  /** withdraw: a plain transaction from the agent account, paid by it. */
+  transaction?: TransactionJson;
+  authorization?: { contractAddress: Address; chainId: number; nonce: number };
+  turnkeyPolicy?: PolicyIntent;
+  retirePolicyId?: string | null;
+  error: string | null;
+};
+
+export const prepareAuthorize = (api: OwnerClient, agentId: string, f: AuthorizeForm) =>
+  api.call<PreparedOperation>("POST", `/v1/owner/agents/${agentId}/authorize`, {
+    perTradeCap: wei(f.perTradeMnt),
+    periodCap: wei(f.periodMnt),
+    totalCap: wei(f.totalMnt),
+    periodSeconds: Math.round(f.periodHours * 3600),
+    durationSeconds: Math.round(f.durationDays * 86_400),
+    maxSlippageBps: Math.round(f.maxSlippagePercent * 100),
+  });
+
+export const prepareRenew = (api: OwnerClient, agentId: string, durationDays: number) =>
+  api.call<PreparedOperation>("POST", `/v1/owner/agents/${agentId}/renew`, { durationSeconds: Math.round(durationDays * 86_400) });
+
+export const prepareRevoke = (api: OwnerClient, agentId: string) =>
+  api.call<PreparedOperation>("POST", `/v1/owner/agents/${agentId}/revoke`);
+
+/** PRD WAL-06: MNT or a token, an exact amount (whole units, 18 decimals) or everything. */
+export const prepareWithdraw = (api: OwnerClient, agentId: string, p: { to: Address; asset: "MNT" | Address; amount: string | "max" }) =>
+  api.call<PreparedOperation>("POST", `/v1/owner/agents/${agentId}/withdraw`, {
+    to: p.to,
+    asset: p.asset,
+    amount: p.amount === "max" ? "max" : wei(p.amount),
+  });
+
+/** Emergency stop: everything server-side now, plus the on-chain revoke to sign (null if no session). */
+export const emergencyStop = (api: OwnerClient, agentId: string) =>
+  api.call<{ stopped: true; revokedCredentials: number; revoke: PreparedOperation | null }>("POST", `/v1/owner/agents/${agentId}/stop`);
+
+export type StepName = "policy" | "authorization" | "signature" | "transaction" | "submit" | "confirm" | "cleanup";
+export type StepState = { name: StepName; status: "todo" | "running" | "done" | "failed" | "skipped"; error?: string };
+
+/** Progress of one operation; pass it back to `runOperation` to retry from the step that failed (PRD WEB-01). */
+export type OperationRun = {
+  prepared: PreparedOperation;
+  steps: StepState[];
+  policyId?: string;
+  authorization?: SignedAuthorization;
+  signature?: Hex;
+  signedTransaction?: Hex;
+};
+
+export function startRun(prepared: PreparedOperation): OperationRun {
+  if (prepared.transaction) {
+    return {
+      prepared,
+      steps: [
+        { name: "transaction", status: "todo" },
+        { name: "submit", status: "todo" },
+        { name: "confirm", status: "todo" },
+      ],
+    };
+  }
+  const steps: StepState[] = [
+    { name: "policy", status: prepared.turnkeyPolicy ? "todo" : "skipped" },
+    { name: "authorization", status: prepared.authorization ? "todo" : "skipped" },
+    { name: "signature", status: "todo" },
+    { name: "submit", status: "todo" },
+    { name: "confirm", status: "todo" },
+    { name: "cleanup", status: prepared.retirePolicyId ? "todo" : "skipped" },
+  ];
+  return { prepared, steps };
+}
+
+/**
+ * Executes the owner's part of an operation step by step. Completed steps are never repeated, so a retry after a
+ * failure does not create a second Turnkey policy or a second signature.
+ */
+export async function runOperation(
+  api: OwnerClient,
+  tk: OwnerTurnkey,
+  session: Session,
+  run: OperationRun,
+  opts: { onChange?: (run: OperationRun) => void; pollMs?: number; timeoutMs?: number } = {},
+): Promise<OperationRun> {
+  const { prepared } = run;
+  const subOrgId = session.owner.subOrgId;
+  const root = () => tk.rootSigner(subOrgId, prepared.account);
+  const owner = tk.owner(subOrgId);
+  let state = { ...run, steps: run.steps.map((s) => ({ ...s })) };
+  const set = (name: StepName, patch: Partial<StepState>) => {
+    state = { ...state, steps: state.steps.map((s) => (s.name === name ? { ...s, ...patch } : s)) };
+    opts.onChange?.(state);
+  };
+
+  const actions: Record<StepName, () => Promise<void>> = {
+    policy: async () => {
+      const { policyIds } = await owner.createPolicies({ organizationId: subOrgId, policies: [prepared.turnkeyPolicy!] });
+      state = { ...state, policyId: policyIds[0]! };
+    },
+    authorization: async () => {
+      const a = prepared.authorization!;
+      state = { ...state, authorization: await sign7702Authorization(root(), { chainId: a.chainId, nonce: a.nonce }) };
+    },
+    signature: async () => {
+      const typed = signedBatchedCallTypedData({ account: prepared.account, chainId: prepared.chainId }, callFromJson(prepared.call!));
+      state = { ...state, signature: await root().signTypedData(typed) };
+    },
+    transaction: async () => {
+      state = { ...state, signedTransaction: await root().signTransaction(transactionFromJson(prepared.transaction!)) };
+    },
+    submit: async () => {
+      if (state.signedTransaction) {
+        await api.call("POST", `/v1/owner/operations/${prepared.operationId}/submit`, { signedTransaction: state.signedTransaction });
+        return;
+      }
+      const a = state.authorization;
+      await api.call("POST", `/v1/owner/operations/${prepared.operationId}/submit`, {
+        signature: state.signature,
+        ...(state.policyId ? { policyId: state.policyId } : {}),
+        ...(a ? { authorization: { address: a.address, chainId: a.chainId, nonce: a.nonce, r: a.r, s: a.s, yParity: a.yParity } } : {}),
+      });
+    },
+    confirm: async () => {
+      const deadline = Date.now() + (opts.timeoutMs ?? 120_000);
+      for (;;) {
+        const op = await api.call<PreparedOperation>("GET", `/v1/owner/operations/${prepared.operationId}`);
+        if (op.status === "confirmed") return;
+        if (op.status === "failed") throw new Error(op.error ?? "operation failed on chain");
+        if (Date.now() > deadline) throw new Error("still waiting for the chain; check again shortly");
+        await new Promise((r) => setTimeout(r, opts.pollMs ?? 1_500));
+      }
+    },
+    // Renew: drop the policy the new one replaced. Revoke: drop the session policy so Turnkey stops signing too.
+    cleanup: async () => {
+      await owner.deletePolicies({ organizationId: subOrgId, policyIds: [prepared.retirePolicyId!] });
+    },
+  };
+
+  for (const step of state.steps) {
+    if (step.status === "done" || step.status === "skipped") continue;
+    set(step.name, { status: "running", error: undefined });
+    try {
+      await actions[step.name]();
+      set(step.name, { status: "done" });
+    } catch (err) {
+      set(step.name, { status: "failed", error: err instanceof Error ? err.message : String(err) });
+      return state;
+    }
+  }
+  return state;
+}
+
+export const runSucceeded = (run: OperationRun) => run.steps.every((s) => s.status === "done" || s.status === "skipped");
+
+/** Human summary of what the owner is about to sign (PRD WAL-02 step 4: show before confirming). */
+export function describeLimits(f: AuthorizeForm): string[] {
+  return [
+    `每笔最多 ${f.perTradeMnt} MNT`,
+    `每 ${f.periodHours} 小时最多 ${f.periodMnt} MNT`,
+    `总共最多 ${f.totalMnt} MNT（卖出不会恢复额度）`,
+    `有效期 ${f.durationDays} 天`,
+    `最大滑点 ${f.maxSlippagePercent}%`,
+    "只能买卖白名单协议上的代币，只能卖出本次授权期间买入的代币",
+    "不能提现、不能修改权限",
+  ];
+}
+
+export const formatMnt = (weiValue: string | bigint) => `${formatEther(BigInt(weiValue))} MNT`;
+
+// ---------------------------------------------------------------------------------------------------------------
+// Auto-run (PRD RUN-02/03)
+// ---------------------------------------------------------------------------------------------------------------
+
+/** Wizard step 3 inputs for scheduled runs. */
+export type RuntimeForm = {
+  enabled: boolean;
+  intervalHours: number;
+  maxTradesPerRun: number;
+  maxTradesPerDay: number;
+  maxSpendPerDayMnt: string;
+  maxLlmCostPerDayUsd: number;
+};
+
+export const DEFAULT_RUNTIME_FORM: RuntimeForm = {
+  enabled: false,
+  intervalHours: 1,
+  maxTradesPerRun: 2,
+  maxTradesPerDay: 10,
+  maxSpendPerDayMnt: "5",
+  maxLlmCostPerDayUsd: 5,
+};
+
+export const getRuntime = (api: OwnerClient, agentId: string) => api.call<RuntimeStatus>("GET", `/v1/owner/agents/${agentId}/runtime`);
+
+export const configureRuntime = (api: OwnerClient, agentId: string, f: RuntimeForm) =>
+  api.call<RuntimeStatus>("POST", `/v1/owner/agents/${agentId}/runtime`, {
+    enabled: f.enabled,
+    intervalSeconds: Math.round(f.intervalHours * 3600),
+    maxRunSeconds: Math.min(600, Math.round(f.intervalHours * 3600)),
+    maxTradesPerRun: f.maxTradesPerRun,
+    maxTradesPerDay: f.maxTradesPerDay,
+    maxSpendPerDay: wei(f.maxSpendPerDayMnt),
+    maxLlmCostPerDayUsd: f.maxLlmCostPerDayUsd,
+  });
+
+export const runtimeCommand = (api: OwnerClient, agentId: string, kind: "pause" | "resume" | "run_now") =>
+  api.call<{ commandId: string }>("POST", `/v1/owner/agents/${agentId}/runtime/${kind}`);