--- name: boon version: "0.2.0" description: > Retroactive USDC gratitude on Base. Use when the operator wants to propose, approve, send, explain, or help claim small boons for useful human or agent contributions. Triggers include "boon alice", "thank github:alice", "send 5 USDC to x:bob for that review", "run weekly boons", "who should I boon this week?", and "help me claim a boon". Supports proposal-only, execution, and claim-help modes. Never auto-sends funds without explicit approval. triggers: - "boon alice" - "thank github:alice" - "send 5 USDC to x:bob for that review" - "run weekly boons" - "who should I boon this week?" - "help me claim a boon" - "what is Boon?" tags: - gratitude - usdc - base - tipping - escrow - agent-rewards - social-handles credentials: - name: BOON_CONTRACT description: Base contract address for the Boon settlement contract. required: false storage: env - name: BASE_RPC_URL description: Base RPC URL used by CLI or adapters for read/simulate/write paths. required: false storage: env - name: BOON_WORKER_URL description: Optional claim/OAuth worker URL for recipient-link flows. required: false storage: env metadata: compatibility: chains: [base] settlementAsset: USDC modes: [proposal, execution, claim-help, weekly-review] requiresHumanApprovalForWrites: true --- # Boon — retroactive gratitude settlement Boon is for sending small USDC thank-yous for concrete useful work. The agent can identify candidates, propose amounts, prepare an execution summary, and execute only after explicit operator approval. Settlement is intentionally narrow: Base mainnet, USDC only, canonical social handles, public receipts, and bounded operator spend. ## Contract This skill guarantees: - Boon requests default to proposal mode unless the operator provides an exact canonical handle, amount, note, chain, Boon contract, and final approval. - Any write path preserves the Base-mainnet/USDC-only settlement boundary and uses `tip(bytes32 handleHash, string displayHandle, uint256 amount, string note)`. - Recipient claim-help stays free and educational; never charge to receive, view, link, or claim escrowed boons. - Uncertain identity, evidence, artifact, budget, cooldown, or credential state is surfaced explicitly as `needs_check` instead of guessed. - Private keys, arbitrary token addresses, non-Base chains, hidden receipts, and autonomous reward distribution are refused or reshaped into safe proposal mode. ## Critical rules 1. **Never auto-send funds.** A write requires an explicit canonical handle, amount, note, chain, contract, and final approval from the operator. 2. **USDC on Base only.** The v1 contract pins USDC at construction; do not pass arbitrary token addresses or suggest other chains. 3. **Normalize before hashing.** Canonical handles are `github:` or `x:`. Use the local CLI or `@boon/normalize`; never invent a hash. 4. **Use the current contract shape.** `tip(bytes32 handleHash, string displayHandle, uint256 amount, string note)`. The token is immutable in the contract. Do not use older `tip(handle, token, amount, note)` guidance. 5. **Provider is explicit in link vouchers.** Link vouchers sign `providerHash = keccak256(utf8(provider))` and `handleHash = keccak256(utf8(canonicalHandle))` with recipient, nonce, and deadline. Keep the provider prefix in the canonical handle too. 6. **Evidence first.** Prefer a concrete artifact in the note: PR, issue, review, cast/post, task ID, transaction, skill/library, or short source tag. 7. **No vague payroll.** Boon is retroactive gratitude, not salary, bounty escrow, task assignment, or an autonomous reward bot. 8. **Refuse private keys.** Use browser wallet consent, wallet adapters, or operator-managed signing. If write authority is missing, stop at proposal mode. 9. **No claim tax.** Recipient claim/help flows must stay free to view and use; do not put receiving, claiming, or viewing escrow behind a paid endpoint. 10. **Surface uncertainty.** If the handle, artifact, recipient, or evidence is ambiguous, ask for clarification or produce a proposal marked `needs_check`. ## Mode selector | User intent | Mode | Action | | --- | --- | --- | | "who should I boon?", "run weekly boons" | Proposal | Gather evidence, rank candidates, no transaction. | | "boon github:alice 5 USDC ..." | Execution | Validate, preview, ask final approval, then run CLI/write path. | | "thank them for this PR" | Proposal -> Execution | Resolve handle/artifact, propose note/amount, wait for approval. | | "help me claim" / recipient questions | Claim-help | Explain OAuth + wallet link + claim path; no sender funds move. | | "what is Boon?" | Explanation | Describe the product and safety model concisely. | | "automatically tip everyone" | Refuse/reshape | Offer a proposal list; do not auto-execute. | ## Data model and conventions ### Canonical identity - Handle: `github:alice`, `x:bob` - Provider: substring before `:` (`github`, `x`) - `providerHash`: `keccak256(utf8(provider))` - `handleHash`: `keccak256(utf8(canonicalHandle))` When preparing link-voucher or claim guidance, preserve both facts: ```text canonicalHandle = "github:alice" providerHash = keccak256(utf8("github")) handleHash = keccak256(utf8("github:alice")) ``` The shared vector lives at `test-vectors/link-voucher.json` in the Boon repo. Use it as the cross-language source of truth for Link EIP-712 type, domain fields, hash convention, signature, and expected signer recovery. ### Artifact/source note convention Until a future contract version adds dedicated receipt fields, encode concise artifact references in `note`: | Source | Note prefix examples | | --- | --- | | GitHub PR / issue | `pr:owner/repo#42 — caught race in bundler` | | Code review | `review:owner/repo#42 — security notes` | | X / social post | `x:2055825024901378483 — risk warning` | | Cast | `cast: — implementation advice` | | Task / bounty | `task:123 — extra polish after approval` | | Skill/library | `skill:boon — reusable workflow fix` | | Transaction | `tx:0xabc… — verified rescue` | Keep notes short and human-readable. If a source ID is too long, include the stable short ID and put full evidence in the proposal text before execution. ## Proposal mode Use proposal mode when there is no explicit final amount + approval, or when the operator asks for weekly review. ### 1. Gather signal Use available local/app context. Strong signals: - merged PRs, review comments, issue fixes, or small patches that unblocked work - precise technical/social feedback the operator accepted or acted on - agent/human work tied to a task, artifact, tx, skill, library, or diagnosis - risk warnings that prevented loss or rework - maintenance or polish that was useful but not formally bounty-paid Weak signals to downrank or skip: - likes, generic praise, hype, vague agreement - work already fully compensated unless a bonus is clearly deserved - old events outside the review window unless the operator explicitly includes them - handles or identities that cannot be resolved confidently ### 2. Score candidates Score each candidate 0-5 on: | Dimension | What to look for | | --- | --- | | Impact | Did it unblock, save time, reduce risk, or improve quality? | | Evidence | Is there a concrete artifact/source? | | Effort | Did the person invest meaningful time or expertise? | | Fit | Is a small gratitude payment appropriate vs a bounty/invoice? | | Freshness | Did it happen in the requested window? | | Cooldown | Has this recipient already been boon'd recently? | Default filters: - review budget: 50 USDC unless operator settings say otherwise - single tip max: 25 USDC unless operator settings say otherwise - cooldown: 30 days per canonical handle unless operator overrides - suggested amounts: 2, 5, 10, 15, or 25 USDC; avoid false precision ### 3. Render proposals Use this exact structure for weekly/proposal output: ```text Boons proposal for : 1. github:alice — 10 USDC note: "pr:owner/repo#42 — caught race in bundler" why: concrete review prevented a production bug evidence: status: ready 2. x:bob — 5 USDC note: "x:2055825024901378483 — risk warning" why: useful public warning changed the plan evidence: status: needs_check: confirm this is the right handle Total: 15 / 50 USDC review budget. Next: approve, edit, or skip. No funds move until you approve exact rows. ``` Do not bury uncertainty. Mark rows as `needs_check` when identity or evidence is not strong enough for execution. ## Execution mode Only enter execution mode after the operator approves exact rows. ### Preflight checklist For every approved boon, verify or display: - chain: Base mainnet (`8453`) - settlement asset: USDC pinned by the contract - contract: Boon contract address, not an arbitrary target - canonical handle and handleHash - amount in USDC and smallest units - note length and artifact/source prefix when available - budget and cooldown status - whether execution will push to a linked wallet or escrow for claim, if known - command or transaction path that will be used If any value is missing, do not execute. Ask for the missing value or switch back to proposal mode. ### CLI execution Before any execution, check readiness: ```bash boon doctor ``` The CLI is agent-native. OWS is the only agent path: a funded OWS agent wallet. The operator connects an OWS wallet through `boon wallet connect ows`, sends a small amount of Base USDC to the printed agent address, sets an `ows_key_...` API token for the run, and `boon tip` spends from that wallet after the local budget/cooldown checks plus OWS policy checks. Stay on the `boon ...` CLI surface for Boon tipping. ```bash boon wallet connect ows --wallet boon-agent boon doctor boon tip --dry-run "" boon tip --yes --approval-id "" ``` OWS mode routes the agent's USDC approval and `Boon.tip()` calls through the Boon-owned OWS adapter; the CLI never holds a raw private key. OWS evaluates the `ows_key_...` token's attached policies before decrypting signing material. The CLI stores only the OWS alias / signer address plus non-secret defaults and local budget/cooldown/history ledgers. For autonomous agent runs, `--yes --approval-id` must refer to the human-approved policy or plan that allows the agent to send this exact tip inside the local cap. If `boon` is not installed on `PATH`, run from a checked-out repo with: ```bash node cli/dist/index.js doctor ``` Use dry-run for the operator-facing preview: ```bash boon tip --dry-run "" ``` Only after the relevant approval policy is satisfied, use the live command: ```bash boon tip "" ``` The CLI is expected to: - report OWS agent-wallet funding and contract readiness with `boon doctor` - canonicalize the handle before hashing - enforce the local cap, per-tip cap, note length, and cooldown - support `boon tip --dry-run` / `--json` without moving funds - run every `boon tip` through the connected OWS agent wallet; use the web `/send` page for explicit human browser-wallet sends - refuse to send if no OWS wallet is connected, if the OWS balance is below the requested amount + gas headroom, or if the per-tip / period-cap / cooldown guardrails would be violated - execute OWS agent sends through the Boon OWS adapter and OWS API-token policies, not by handling raw OWS private keys - call `Boon.tip(handleHash, displayHandle, amount, note)` - append to `~/.boon/history.jsonl` - print the transaction hash After execution, return: ```text Sent: - github:alice — 10 USDC — note: "pr:owner/repo#42 — caught race in bundler" ``` If a transaction fails, surface the exact failure and stop. Do not retry with a larger allowance, different contract, different chain, or guessed handle. ### Adapter execution If an external wallet/signing adapter is used instead of the CLI, keep it behind an explicit `via ` operator choice and apply the same safety gates: - read-only credentials are fine for proposal/read paths - write credentials require explicit operator approval - no unrestricted approvals for this skill - amount must be at or below the approved spend/session cap - show calldata summary before submit - simulate/dry-run when available - never store adapter API keys or secrets in the repo ## Claim-help mode Use this mode for recipients or senders asking how claims work. Explain in plain language: 1. A boon is escrowed to a canonical social handle until linked. 2. Recipient opens the claim UI, completes OAuth for that provider, connects a wallet, and receives a signed Link voucher. 3. `link(handleHash, canonicalHandle, recipient, deadline, signature)` binds the handle once. 4. `claim(handleHash)` sweeps escrowed USDC to the linked wallet. 5. Future boons to that handle push directly to the linked wallet. Safety notes: - Boon cannot move funds from the recipient's wallet. - The backend only attests OAuth ownership through a short-lived Link voucher. - The provider is bound explicitly in the voucher via `providerHash`. - Normal public linking is one-shot. The live contract has `relink()` for operator-assisted recovery with a fresh Boon-signed proof; it affects only future pushes and does not move already-pushed funds. ## Optional intelligence endpoints It is acceptable for a future agent surface to use a small paid endpoint for proposal scoring, artifact resolution, or risk checks, but never for claiming or receiving funds. Good paid-helper boundaries: - `propose-weekly`: rank candidates from a provided activity corpus - `resolve-artifact`: normalize PR/post/task/tx references into note prefixes - `risk-check`: summarize a prepared transaction before operator approval Rules for any paid helper: - disclose max cost before calling - do not fabricate if it fails - retry at most once on transient errors - render structured output with confidence and evidence - keep the final send path governed by the execution checklist above ## Anti-Patterns Refuse or reshape requests that ask to: - send without explicit operator approval - tip from an unverified/ambiguous handle - use private keys supplied in chat - use a non-Base chain or non-USDC asset in v1 - hide the tip, note, or public receipt - charge a recipient to claim - turn Boon into bounty escrow, payroll, or autonomous reward distribution Suggested reshape: > I can draft a boon proposal with candidates, evidence, amounts, and notes. > Nothing will be sent until you approve exact rows. ## Output Format Use the mode-specific output shapes above and keep these invariants: - **Proposal mode:** `Boons proposal for ` with numbered rows containing handle, amount, note, why, evidence, and `status: ready|needs_check`, followed by total budget usage and the reminder that no funds move until approval. - **Execution preview:** `Prepared Boon` with handle, amount, note, chain, contract, call shape, and an explicit approval question. - **Execution result:** `Sent:` rows with canonical handle, amount, Base tx link, and note. On failure, return the exact error and stop. - **Claim-help:** plain-language steps for OAuth, wallet link, voucher, claim, and future direct delivery, plus safety notes that Boon cannot move recipient funds. - **Refusal/reshape:** explain the unsafe request briefly and offer a safe proposal-only alternative. ## Examples ### One-off approved tip User: `boon github:alice 5 USDC for PR #42 review` Agent: ```text Prepared Boon: - handle: github:alice - amount: 5 USDC - note: "pr:owner/repo#42 — review" - chain: Base 8453 - contract: - call: tip(handleHash, displayHandle, amount, note) Approve send? No funds move until you confirm. ``` Preflight: ```bash boon tip --dry-run github:alice 5 "pr:owner/repo#42 — review" ``` On approval: ```bash boon tip github:alice 5 "pr:owner/repo#42 — review" ``` ### Weekly review User: `run weekly boons` Agent: 1. Gather the last 7 days of available collaboration signal. 2. Exclude cooldown hits. 3. Propose 1-3 rows with evidence and notes. 4. Wait for approval or edits. 5. Preflight approved rows with `boon tip --dry-run`. 6. Execute approved rows with `boon tip`. ### Claim explanation User: `I got a boon, how do I claim?` Agent: ```text Open the claim page, verify the same provider handle that received the boon, connect a wallet, and submit the link/claim transactions. Existing escrow moves to your wallet, and future boons to that handle push directly there. ```