@perkos/agent-sdk 0.7.1 → 0.8.0-rc.1

package/docs/WALLET_SIGNER_SETUP.md

@@ -0,0 +1,52 @@
+# Operator-owned wallet and signer preparation
+
+This is a separate operator checklist, **not a Nayori wallet-generation or custody service**.
+Your existing agent and LLM are already running. Return to [agent onboarding](EXISTING_AGENT.md)
+after preparing a signer. Nayori never needs your private key or model-provider credentials.
+
+## Existing wallet or new wallet
+
+Reuse a dedicated testnet signer if it meets these controls. Otherwise create a dedicated wallet
+using your reviewed Stacks-compatible wallet tooling or a separately maintained Stacks.js operator
+utility. Verify the dependency/version and network; do not ask an LLM to invent a key or use a
+public test fixture. Keep generation and recovery outside the Nayori SDK and agent's tool set.
+
+1. Store the key in your own protected signer storage, outside repositories and agent-readable
+   files. Encrypt backups under operator control. A mode-0600 file alone is not an encrypted backup.
+2. Verify restoration derives the same public testnet address before funding. Never show the key
+   or recovery phrase in tickets, prompts, logs, terminal recordings or documentation.
+3. Give each independently operated buyer/provider a separate identity and signer boundary.
+   Keep transaction sender and the intended registered metadata wallet aligned; registry ownership
+   follows `creator` (transaction sender), not an arbitrary metadata wallet.
+4. Fund only the test assets and STX network fees needed for the authorized test. Do not send
+   mainnet assets to an example/fixture or assume a displayed testnet balance is spendable mainnet value.
+
+## Human-approved or autonomous signatures
+
+- A browser wallet can request human approval through the SDK's browser signer interface.
+- An autonomous agent requests a bounded operation from **your own signer service**. An
+  operator-maintained Stacks.js implementation can validate, construct and sign transactions.
+  This library option is not a turnkey managed signing service supplied by Nayori.
+- Integrate your signer through the documented `PerkOSSigner` interface or the reviewed QA
+  custody bridge. A callback that loads a key in the LLM's process is not an isolation boundary.
+
+Before enabling autonomous signing, enforce:
+
+- Authenticated caller and role; allowed network, contracts, functions and recipients.
+- Explicit per-operation amount, total budget, expiry, asset and STX gas caps.
+- Exact arguments/post-conditions; no arbitrary transaction bytes or module paths selected by an LLM.
+- Separate OS identity/process and private mounts; no shared key access, sudo or Docker socket.
+- Durable intent/nonce/txid journal and serialized use of one wallet across workers.
+- Stop on ambiguous signing/broadcast; inspect chain/mempool before retrying, never delete the journal.
+- An operator-controlled disable switch; test denied actions with signing off first.
+
+SDK spending policies are per-process checks, not a replacement for persistent signer-side
+authorization. The candidate [custody guide](HERMES_CUSTODY.md) documents a restricted QA example;
+it is not a general-purpose production custody service or externally audited wallet manager.
+
+## Safe handoff to the agent
+
+Provide only public network/identity/configuration and the restricted tool or authenticated IPC
+entry point. Keep signer credentials out of prompts and tool arguments. Prove that an allowed
+testnet registration can be requested, a forbidden role/action is denied and the agent cannot
+read key material. Then continue with [registration and confirmation](EXISTING_AGENT.md#4-register-and-verify-the-agent).

package/examples/service-fees.ts

@@ -0,0 +1,36 @@
+import {
+  PerkOSClient,
+  quoteServiceFee,
+  type AmountLike,
+  type PaymentAsset,
+} from "../src/index.js";
+
+/** Signer-free report. It neither grants consent nor broadcasts a transaction. */
+export async function inspectEarnedServiceFee(
+  client: PerkOSClient,
+  asset: PaymentAsset,
+  jobId: AmountLike
+) {
+  if (!client.supportsServiceFees(asset))
+    return { kind: "no-service-fee-generation" as const };
+  const job = await client.getJob(asset, jobId);
+  if (!job) throw new Error("Job not found");
+  const fees = await client.getJobServiceFee(asset, jobId);
+  const quote = quoteServiceFee(job.budget);
+  return {
+    kind: "earned-service-fee" as const,
+    asset,
+    jobId: job.id.toString(),
+    gross: quote.gross.toString(),
+    potentialFee: quote.fee.toString(),
+    netIfEvaluated: (fees.waiver ? quote.gross : quote.net).toString(),
+    treasury: fees.treasury,
+    chargedFee: (fees.settlement?.chargedFee ?? 0n).toString(),
+    refundedFee: (fees.settlement?.refundedFee ?? 0n).toString(),
+    refundOutstanding:
+      !!fees.waiver &&
+      !!fees.settlement &&
+      fees.settlement.chargedFee > fees.settlement.refundedFee,
+    gas: "Separate STX network fee",
+  };
+}

package/examples/testnet-journal.ts

@@ -0,0 +1,57 @@
+import { closeSync, constants, fstatSync, fsyncSync, openSync, readFileSync, writeSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+
+type Entry = { key: string; intent: string; state: "attempting" | "broadcast"; txid?: string };
+
+/** Append-only journal; caller must hold its exclusive lock. Keep outside Git. */
+export class QuickstartJournal {
+  private readonly fd: number;
+  private readonly entries: Entry[];
+  constructor(path: string) {
+    if (!isAbsolute(path)) throw new Error("journal_absolute_path_required");
+    this.fd = openSync(path, constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+    const stat = fstatSync(this.fd);
+    if (!stat.isFile() || (stat.mode & 0o777) !== 0o600 || stat.nlink !== 1 || stat.size > 1_048_576 ||
+        (process.getuid && stat.uid !== process.getuid())) {
+      closeSync(this.fd); throw new Error("unsafe_journal");
+    }
+    try {
+      this.entries = readFileSync(this.fd, "utf8").split("\n").filter(Boolean).map(line => JSON.parse(line) as Entry);
+      if (this.entries.some(item => !item || typeof item.key !== "string" || !/^[0-9a-f]{64}$/.test(item.intent) ||
+          !["attempting", "broadcast"].includes(item.state) ||
+          (item.state === "broadcast" && !/^0x[0-9a-f]{64}$/.test(item.txid ?? "")))) throw new Error("invalid_journal");
+    } catch { closeSync(this.fd); throw new Error("journal_requires_reconciliation"); }
+  }
+  close() { closeSync(this.fd); }
+  lookup(key: string, intent: string): Entry | undefined {
+    const entries = this.entries.filter(item => item.key === key);
+    if (entries.some(item => item.intent !== intent)) throw new Error("journal_intent_mismatch");
+    return entries.at(-1);
+  }
+  append(entry: Entry) {
+    const bytes = Buffer.from(JSON.stringify(entry) + "\n");
+    let offset = 0;
+    while (offset < bytes.length) offset += writeSync(this.fd, bytes, offset);
+    fsyncSync(this.fd); this.entries.push(entry);
+  }
+}
+export function intentHash(value: unknown): string {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+export async function checkpointedTransaction(
+  journal: QuickstartJournal, key: string, intent: string, send: () => Promise<string>,
+): Promise<string> {
+  const prior = journal.lookup(key, intent);
+  if (prior) {
+    if (prior.state !== "broadcast" || !/^0x[0-9a-f]{64}$/.test(prior.txid ?? "")) {
+      throw new Error("ambiguous_attempt_requires_reconciliation");
+    }
+    return prior.txid!;
+  }
+  journal.append({ key, intent, state: "attempting" });
+  const txid = await send();
+  if (!/^0x[0-9a-f]{64}$/.test(txid)) throw new Error("invalid_txid_requires_reconciliation");
+  journal.append({ key, intent, state: "broadcast", txid });
+  return txid;
+}