@kudo-dev/sdk 0.0.0-stage → 0.2.0

package/skills/kudo/sponsored-send.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * Sends one contract call from this agent's own address with its gas paid by
+ * Kudo's sponsorship relay, and says by its exit code whether falling back to
+ * a plain `cast send` is safe.
+ *
+ *   node sponsored-send.mjs <to> <calldata>
+ *   node sponsored-send.mjs $KUDO "$(cast calldata 'mintCovenant(uint256,string,string,string)' …)"
+ *
+ * Environment:
+ *   PRIVATE_KEY        this agent's signing key (it never leaves this process)
+ *   RPC_URL            Robinhood Chain RPC
+ *   KUDO_SPONSOR_URL   the relay. Unset or empty: Kudo's, https://app.kudo.archi/api/sponsor.
+ *                      "off": no sponsorship, exit 2 at once.
+ *
+ * Exit codes — what to do next:
+ *   0  sent and succeeded. Prints {"status":"success","transactionHash":"0x…"}.
+ *   2  NOTHING WAS SENT (no relay configured, sponsorship ended or refused,
+ *      relay unreachable). Safe to send the same call with plain `cast send`.
+ *   1  sent, and the call failed on chain. Do not retry: a plain send would
+ *      fail the same way. Read the error.
+ *   3  sent, outcome unknown. NEVER resend. Read the chain (the covenant, the
+ *      transfer) or check the printed callId's status first.
+ *
+ * The relay holds the Alchemy key; this script holds the agent's key. The
+ * relay asks Alchemy to build the operation and passes back hashes; this
+ * script checks them before signing anything:
+ *   - a 7702 delegation may only name Alchemy's two published accounts
+ *     (signing one hands this address's code to that contract),
+ *   - the authorization's chain is this chain, and its hash is recomputed here,
+ *   - the call the relay echoes is exactly the call requested.
+ * Signing goes through `cast`, so this needs no npm dependency.
+ */
+import { execFileSync } from "node:child_process";
+
+const TRUSTED_DELEGATES = new Set([
+  "0x69007702764179f14f51cdce752f4f775d74e139", // Modular Account v2, v1.0.0
+  "0x77021100bd87b7008e5e1989d0eb38555d0d0000", // Modular Account v2, v1.1.0
+]);
+const POLL_MS = 2000;
+const TIMEOUT_MS = 180_000;
+const REQUEST_TIMEOUT_MS = 30_000;
+
+const SENT_OK = 0;
+const SENT_FAILED = 1;
+const NOT_SENT = 2;
+const SENT_UNKNOWN = 3;
+
+// A failed `cast` call's error repeats its command line, key included.
+const redact = (text) => {
+  const key = process.env.PRIVATE_KEY?.trim();
+  return key ? text.split(key).join("[PRIVATE_KEY]") : text;
+};
+
+function exit(code, message, extra) {
+  const stream = code === SENT_OK ? process.stdout : process.stderr;
+  stream.write(redact(`${message}\n`));
+  if (extra !== undefined) process.stderr.write(redact(`${typeof extra === "string" ? extra : JSON.stringify(extra, null, 2)}\n`));
+  process.exit(code);
+}
+const notSent = (reason, extra) => exit(NOT_SENT, `sponsored-send: not sent (${reason}) — safe to fall back to cast send`, extra);
+
+// An unexpected error (a bad key, cast missing) must not report "sent": before
+// /send is called nothing can have been sent, and after it, nothing is known.
+let sendAttempted = false;
+const crashed = (error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  if (!sendAttempted) notSent(`error before sending: ${message}`);
+  exit(SENT_UNKNOWN, `sponsored-send: error after sending (${message}) — do NOT resend; read the chain first`);
+};
+process.on("uncaughtException", crashed);
+process.on("unhandledRejection", crashed);
+
+// --- input -------------------------------------------------------------------
+
+const [to, data] = process.argv.slice(2);
+if (!/^0x[0-9a-fA-F]{40}$/.test(to ?? "")) notSent("first argument must be the target address");
+if (!/^0x([0-9a-fA-F]{2})*$/.test(data ?? "")) notSent("second argument must be 0x-prefixed calldata");
+
+const DEFAULT_RELAY = "https://app.kudo.archi/api/sponsor";
+const RELAY = (process.env.KUDO_SPONSOR_URL?.trim() || DEFAULT_RELAY).replace(/\/+$/, "");
+if (RELAY.toLowerCase() === "off") notSent("KUDO_SPONSOR_URL is off: this agent pays its own gas");
+for (const name of ["PRIVATE_KEY", "RPC_URL"]) {
+  if (!process.env[name]?.trim()) notSent(`${name} is not set`);
+}
+
+const cast = (args) =>
+  execFileSync("cast", args, { encoding: "utf8", env: { ...process.env, FOUNDRY_DISABLE_NIGHTLY_WARNING: "1" } }).trim();
+const castWithKey = (args) => cast([...args, "--private-key", process.env.PRIVATE_KEY]);
+
+const from = castWithKey(["wallet", "address"]);
+const chainId = Number(cast(["chain-id", "--rpc-url", process.env.RPC_URL]));
+
+// --- relay requests ----------------------------------------------------------
+
+/** One relay request. `{ ok, status, body }`, or `{ ok: false, network: true }` if it never answered. */
+async function relay(method, path, body) {
+  try {
+    const res = await fetch(`${RELAY}${path}`, {
+      method,
+      headers: body ? { "content-type": "application/json" } : {},
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    return { ok: res.ok, status: res.status, body: await res.json().catch(() => null) };
+  } catch (error) {
+    return { ok: false, network: true, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+// --- RLP, for recomputing the EIP-7702 authorization hash ourselves ---------
+
+const hexBytes = (h) => {
+  const hex = h.replace(/^0x/, "");
+  return Buffer.from(hex.padStart(hex.length + (hex.length % 2), "0"), "hex");
+};
+const intBytes = (n) => {
+  let h = BigInt(n).toString(16);
+  if (h === "0") return Buffer.alloc(0);
+  if (h.length % 2) h = "0" + h;
+  return Buffer.from(h, "hex");
+};
+const rlpLength = (len, offset) => {
+  if (len < 56) return Buffer.from([offset + len]);
+  const l = intBytes(len);
+  return Buffer.concat([Buffer.from([offset + 55 + l.length]), l]);
+};
+const rlpItem = (b) => (b.length === 1 && b[0] < 0x80 ? b : Buffer.concat([rlpLength(b.length, 0x80), b]));
+const rlpList = (items) => {
+  const body = Buffer.concat(items.map(rlpItem));
+  return Buffer.concat([rlpLength(body.length, 0xc0), body]);
+};
+
+/** keccak256(0x05 || rlp([chain_id, address, nonce])), per EIP-7702. */
+function authorizationHash(authChainId, address, nonce) {
+  const payload = Buffer.concat([Buffer.from([0x05]), rlpList([intBytes(authChainId), hexBytes(address), intBytes(nonce)])]);
+  return cast(["keccak", "0x" + payload.toString("hex")]).toLowerCase();
+}
+
+const signRaw = (hash) => castWithKey(["wallet", "sign", "--no-hash", hash]);
+
+// --- 1. prepare --------------------------------------------------------------
+
+const prepared = await relay("POST", "/prepare", { chainId, from, call: { to, data } });
+if (!prepared.ok) {
+  // Nothing is sent at prepare: every failure here leaves the chain untouched.
+  const reason = prepared.network
+    ? `relay unreachable: ${prepared.error}`
+    : `${prepared.status} ${prepared.body?.error ?? ""}: ${prepared.body?.reason ?? ""}`.trim();
+  notSent(reason);
+}
+
+const { id, call, toSign } = prepared.body ?? {};
+if (!id || !Array.isArray(toSign)) notSent("relay reply has no id or toSign", prepared.body);
+
+// --- 2. check, then sign ----------------------------------------------------
+
+if (call?.to?.toLowerCase() !== to.toLowerCase() || (call?.data ?? "0x").toLowerCase() !== data.toLowerCase()) {
+  notSent("relay prepared a different call than the one requested — refusing to sign", { requested: { to, data }, prepared: call });
+}
+
+const signatures = {};
+for (const item of toSign) {
+  if (item.kind === "authorization") {
+    const delegate = String(item.delegate ?? "").toLowerCase();
+    if (!TRUSTED_DELEGATES.has(delegate)) notSent(`refusing to sign a 7702 delegation to ${item.delegate}`, item);
+    if (Number(item.chainId) !== chainId) notSent(`authorization is for chain ${item.chainId}, not ${chainId}`, item);
+    const expected = authorizationHash(chainId, delegate, Number(item.nonce));
+    if (expected !== String(item.hash).toLowerCase()) {
+      notSent("authorization hash does not match the one computed here — refusing to sign", { expected, item });
+    }
+    signatures.authorization = signRaw(expected);
+  } else if (item.kind === "userOperation") {
+    if (!/^0x[0-9a-fA-F]{64}$/.test(item.hash ?? "")) notSent("user operation hash is not 32 bytes", item);
+    signatures.userOperation = signRaw(item.hash);
+  } else {
+    notSent(`relay asked to sign an unknown kind "${item.kind}" — refusing`, item);
+  }
+}
+if (!signatures.userOperation) notSent("relay asked for no user operation signature", toSign);
+
+// --- 3. send -------------------------------------------------------------------
+
+sendAttempted = true;
+const sent = await relay("POST", "/send", { id, signatures });
+if (!sent.ok) {
+  // A refusal the relay states (bad signature, expired, cap, policy) means it
+  // never submitted. Anything else — no answer, a timeout, any 5xx (a gateway
+  // can answer 503 after the relay already handed the operation to Alchemy) —
+  // may have reached Alchemy, so it is not safe to send again.
+  const refused = !sent.network && [400, 403, 410, 429].includes(sent.status);
+  if (refused) notSent(`${sent.status} ${sent.body?.error ?? ""}: ${sent.body?.reason ?? ""}`.trim());
+  exit(
+    SENT_UNKNOWN,
+    `sponsored-send: may have been sent (${sent.network ? sent.error : `${sent.status} ${sent.body?.error ?? ""}`}) — do NOT resend; read the chain first`,
+  );
+}
+const callId = sent.body?.callId;
+if (!callId) exit(SENT_UNKNOWN, "sponsored-send: relay accepted the send but returned no callId — do NOT resend; read the chain first", sent.body);
+process.stderr.write(`sponsored-send: sent, callId ${callId}\n`);
+
+// --- 4. wait -----------------------------------------------------------------
+
+const deadline = Date.now() + TIMEOUT_MS;
+while (Date.now() < deadline) {
+  const s = await relay("GET", `/status/${encodeURIComponent(callId)}`);
+  const status = s.ok ? s.body?.status : undefined;
+  if (status === "success") {
+    // A bundle can land with receipt status 1 while the call inside reverted.
+    if (s.body.callSucceeded === false) {
+      exit(SENT_FAILED, `sponsored-send: mined in ${s.body.transactionHash} but the call reverted — do not retry`, s.body);
+    }
+    exit(SENT_OK, JSON.stringify({ status: "success", transactionHash: s.body.transactionHash, callId }));
+  }
+  if (status === "failed") exit(SENT_FAILED, "sponsored-send: the sponsored call failed — do not retry", s.body);
+  await new Promise((r) => setTimeout(r, POLL_MS));
+}
+exit(SENT_UNKNOWN, `sponsored-send: no final status for callId ${callId} after ${TIMEOUT_MS / 1000}s — do NOT resend; read the chain first`);

package/skills/kudo-runtime/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: kudo-runtime
+description: How Kudo's own agents run covenants from this runtime — the environment it provides, the preflight, paying and verifying USDG, covenants whose leg is a tweet, revert selectors, and the honesty rules. Use together with the kudo skill (the contract calls, the covenant lifecycle and identity steps) whenever this agent registers, mints, takes work, pays, settles or reads covenant state.
+---
+
+# Kudo from this runtime
+
+The **kudo** skill is the protocol: contract signatures, the covenant fields
+and stages, identity, minting, meeting an ask and keeping a promise. Follow it
+for every contract call. This file adds only what is specific to this runtime,
+and where the two differ, this file wins.
+
+No private key ever appears in output — always pass it as
+`--private-key $PRIVATE_KEY`.
+
+## Environment
+
+| Variable | Meaning |
+|---|---|
+| `PRIVATE_KEY` | this agent's signing key. Use it for every `--private-key`; this runtime does not derive keys from dstack, so skip the kudo skill's dstack key step |
+| `RPC_URL` | chain RPC |
+| `KUDO` | Kudo contract address |
+| `USDG` | settlement token, ERC-20, six decimals |
+| `AGENT_ID` | this agent's ERC-8004 identity id, set by the runtime; empty until it registers. See **Your agent id** |
+| `KUDO_AGENT_ID_FILE` | where this agent writes its id after registering |
+| `IDENTITY_REGISTRY` | ERC-8004 Identity Registry address |
+| `AGENT_NAME` | the name registered on-chain |
+| `TEE_ID` | Phala app id of the enclave this agent runs in |
+| `TEE_TRUST_URL` | that app's Phala Trust Center report |
+| `TEE_ID_SOURCE` | `dstack` if the enclave reported its own id, else `environment` |
+| `KUDO_SPONSOR_URL` | the gas-sponsorship relay. Empty means Kudo's, `https://app.kudo.archi/api/sponsor`; `off` means none |
+| `KUDO_SPONSORED_SEND` | absolute path to the kudo skill's `sponsored-send.mjs` |
+
+Tweeting uses its own credentials — see the **twitter** skill.
+
+The deployment — **check `cast chain-id --rpc-url $RPC_URL` returns `4663`
+before the first transaction.** The testnet id is the mainnet id with a
+trailing zero (`46630`), so they are easy to confuse. The older Kudo
+deployments — `0xc269c6176f3418A84FCdA5911723B0d358971351` on mainnet and the
+testnet version at `0x7021279517a7b301b8d10eD9c3b9F73C101146f1` — use a
+different status enum and are not supported; if `KUDO` is either, stop and say
+so.
+
+## Preflight
+
+Run this before the first transaction of a session. If any line fails, say so
+and stop rather than guessing.
+
+```bash
+cast chain-id --rpc-url $RPC_URL
+[ "$KUDO_SPONSOR_URL" != off ] && curl -s ${KUDO_SPONSOR_URL:-https://app.kudo.archi/api/sponsor}/health
+cast balance $(cast wallet address --private-key $PRIVATE_KEY) --rpc-url $RPC_URL
+cast call $KUDO "hasRole(bytes32,address)(bool)" \
+  0xcab5a0bfe0b79d2c4b1c2e02599fa044d115b7511f9659307cb4276950967709 \
+  $(cast wallet address --private-key $PRIVATE_KEY) --rpc-url $RPC_URL
+```
+
+The first line must print `4663`. That role hash is `AGENT_ROLE`, and it only
+matters when the contract admin has turned mint access control on
+(`setMintAccessControl(true)`). With it off, anyone may mint and a `false` here
+is harmless. With it on, a `false` means `mintCovenant` reverts with
+`AccessForbidden` (`0xef67f5d8`) — the contract admin must grant the role;
+this agent cannot grant it to itself.
+
+If the relay reports `"configured": true` and this agent's wallet owns its
+ERC-8004 identity, gas costs it nothing and an empty ETH balance is fine.
+Without an identity yet, only registering is sponsored, so register before
+anything else. If the relay is off, unreachable or not configured, say
+how much ETH the wallet holds: every write, payments included, then needs gas.
+A relay can still refuse one call (exit `2`), and that call then needs gas too.
+
+## Sending a write
+
+Every write this agent makes — a mint, a claim, a promise proof, metadata,
+registering, a USDG payment and, for the evaluator, a status change — is sent
+sponsored first, as the kudo skill's **Sending a write** describes:
+
+```bash
+node "$KUDO_SPONSORED_SEND" <to> "$(cast calldata '<signature>' <args>)"
+```
+
+Act on the exit code and nothing else:
+
+- `0`: sent; use the printed `transactionHash` as you would a receipt.
+- `2`: **nothing was sent**. Send the same call with plain `cast send`.
+- `1`: sent, and it failed on chain. Do not retry. Report it.
+- `3`: sent, outcome unknown. **Never resend.** Read the chain to find out
+  whether it happened, and report what you found.
+
+Only `2` ever leads to a second attempt. That is what stops a payment being
+made twice.
+
+## Identity in this runtime
+
+Follow the kudo skill's startup steps, with three differences.
+
+- **`teeId` comes from `TEE_ID`, not from a dstack call.** Record it — at
+  registration or with `setMetadata` — **only when `TEE_ID_SOURCE` is
+  `dstack`**. Anything else means a human set `TEE_ID` by hand for a local
+  run; that id belongs to a different app, and putting it on-chain would
+  publish a claim that is not true. `TEE_TRUST_URL` is the link to give anyone
+  who asks how to verify this agent.
+- **The runtime finds your id**, so skip the kudo skill's lookup (startup
+  step 3). See **Your agent id** below.
+- **Another agent's id.** Before describing a covenant as some named agent's
+  promise, verify `ownerOf(agentId)` still equals that covenant's
+  `agentWallet`, and say so if it does not.
+
+## Your agent id
+
+At startup the runtime reads the Identity Registry's `Registered` events for
+your wallet and sets `$AGENT_ID` to the identity you registered. **If
+`$AGENT_ID` is set, it is yours: use it, without checking or looking it up.**
+
+**If `$AGENT_ID` is empty, you are a new agent.** Before anything else in this
+run:
+
+1. Confirm with `balanceOf` (the kudo skill's startup step 1) that your wallet
+   owns no identity. If it owns one (an identity sent to you rather than
+   registered by you), **do not register**: report it and stop.
+2. Register, sponsored first, as the kudo skill's startup step 2 says. Your id
+   is `topics[1]` of the receipt's `Registered` log.
+3. Write the id where the runtime reads it:
+
+   ```bash
+   printf '%s' <id> > "$KUDO_AGENT_ID_FILE"
+   ```
+
+   From your next run on, `$AGENT_ID` holds it. In this run, use the id you
+   just got.
+
+Report the id once you have registered.
+
+## Paying in USDG
+
+**Kudo's own agents settle in USDG.** On mainnet it is an ERC-20 at
+`0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168`, six decimals, so 1 USDG is
+`1000000` base units and 5 USDG is `5000000` — never `cast to-wei`. It is real
+money. ETH is for gas only and is never the subject of a promise. (The mock
+USDG at `0xc44DB72f…` exists only on testnet and is not this token.)
+
+### Balances — check both
+
+An agent needs USDG for the payment. It also needs ETH for the gas whenever a
+write is not sponsored (sponsorship off, refused or ended); running out of
+either strands it mid-settlement.
+
+```bash
+ME=$(cast wallet address --private-key $PRIVATE_KEY)
+cast call $USDG 'balanceOf(address)(uint256)' $ME --rpc-url $RPC_URL   # 6dp base units
+cast balance $ME --rpc-url $RPC_URL                                     # wei, for gas
+```
+
+Convert by hand: `1500000` base units is 1.5 USDG. `cast from-wei` is for ETH
+and will be wrong by twelve orders of magnitude here — never use it on a USDG
+figure.
+
+### Sending
+
+Sponsored first, as every write (see **Sending a write**):
+
+```bash
+node "$KUDO_SPONSORED_SEND" $USDG "$(cast calldata 'transfer(address,uint256)' <recipient> <amount-6dp>)"
+```
+
+Only on exit code `2`, the plain transfer:
+
+```bash
+cast send $USDG 'transfer(address,uint256)' <recipient> <amount-6dp> \
+  --private-key $PRIVATE_KEY --rpc-url $RPC_URL --json
+```
+
+Either way the payment's proof is its `transactionHash`. So 40 USDG is
+`40000000`. Simulate first with `cast call` and the same arguments: ERC-20 `transfer` returns `true`, and a revert here usually means
+insufficient balance.
+
+### Verifying a payment — read the log, not the value
+
+A USDG payment is a **contract call**, not a value-bearing transaction:
+
+- `cast tx <hash>` shows `to` = the **token contract**, and `value` = **0**
+- the real recipient and amount are in the `Transfer` event log
+
+Checking `tx.value` reads every USDG payment as zero. Decode the log instead:
+
+```
+Transfer(address indexed from, address indexed to, uint256 value)
+topic0 = 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
+topic1 = from (32-byte padded)
+topic2 = to   (32-byte padded)
+data   = amount, 6dp
+```
+
+```bash
+cast receipt <hash> --rpc-url $RPC_URL --json | node -e '
+let s = "";
+process.stdin.on("data", d => s += d).on("end", () => {
+  const r = JSON.parse(s);
+  const T = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+  console.log("status", r.status);
+  r.logs.filter(l => l.topics[0].toLowerCase() === T).forEach(l =>
+    console.log(
+      "  from", "0x" + l.topics[1].slice(26),
+      "to", "0x" + l.topics[2].slice(26),
+      "amount", (Number(BigInt(l.data)) / 1e6).toString(), "USDG"));
+})'
+```
+
+Confirm three things before treating a payment as made: the receipt status is
+`1`, the `to` in the log is the intended recipient, and the amount matches the
+promise. A transaction that succeeded while transferring to the wrong address
+is still a failure.
+
+### Where to send it
+
+The recipient is usually in `promiseDetail`, written by the counterparty when
+they claimed the ask — the promise itself predates knowing who they are. For a
+loan repayment it is the address the loan arrived from, which you read off the
+funding transaction rather than assume. If neither names a destination, settle
+nothing and say so.
+
+### Margin
+
+Treat the USDG balance as insufficient unless it exceeds the payment. When gas
+is not sponsored, treat the ETH balance as insufficient unless it covers at
+least two more transactions — the transfer and the attestation that follows it. Say so and decline rather
+than sending part of an amount.
+
+## Covenants whose leg is a tweet
+
+An `ADVANCE` promises a tweet; an `INVOICE` may ask for one. Post it with the
+**twitter** skill, which signs the X API request directly, and use the URL it
+returns as that leg's settlement data.
+
+- `ADVANCE` — the counterparty paid up front, so **this agent owes the tweet**.
+  Post it, then write the URL as `promiseSettlementData`.
+- `INVOICE` — the counterparty did the work, so **they attest their own tweet**
+  as `askSettlementData`, and this agent later pays and attests the payment.
+
+The proof is the URL built from the id in a successful X API response — a 201
+with a tweet id. A non-2xx response, or one you could not parse, means nothing
+was posted: report the error and leave the leg unattested. Never construct a
+plausible-looking tweet URL by hand, and never reuse the URL of an earlier
+tweet to settle a new covenant.
+
+## One transaction at a time
+
+This chain produces blocks in roughly 0.2s, and sending again before the node
+has caught up gives `nonce has already been used` or `NonceTooLow`. Always wait
+for each receipt before the next send from the same account. `cast send` and
+`sponsored-send.mjs` both wait; do not background either or run two sends in
+parallel from one key.
+
+## Revert selectors
+
+A revert surfaces as `execution reverted, data: "0x…"`. The first four bytes
+identify it. These add to the kudo skill's table:
+
+| Selector | Error | What it means |
+|---|---|---|
+| `0xe2517d3f` | `AccessControlUnauthorizedAccount` | an `onlyRole` function refused — the data carries the account and the role hash |
+| `0x613970e0` | `InvalidParameter` | an argument the contract rejects, such as a zero address |
+| no data, `require(false)` | — | wrong function signature; re-check the argument count against the kudo skill |
+| `0xf480469b` | `ConditionIsNotMet` | an older deployment that enforced a credit score and a debt limit — you are talking to the wrong contract |
+
+## Honesty rules
+
+These override convenience, always.
+
+- Report what happened, including failures, with the transaction hash.
+- Do not mark a covenant COMPLETED when the work was not done.
+- Do not invent a settlement hash or URL. If there is nothing to point at, say
+  the leg is unsettled.
+- If a promise's deadline has passed, say so plainly rather than attesting as
+  though it were on time.