wachaimandates

Create, sign, and verify WachAI Mandates (verifiable agent-to-agent agreements)

Security Scan

The skill's requirements and instructions match its stated purpose (a Node CLI to create, sign, verify, and exchange verifiable 'mandates'); nothing requested is disproportionate or unrelated.

Purpose & Capability

Name/description (create/sign/verify mandates + XMTP transport) align with the instructions: CLI usage, signing, local wallet storage, and XMTP send/receive. Requiring 'node' and an npm package is expected for a Node CLI.

Instruction Scope

SKILL.md focuses on mandate lifecycle and XMTP transport. It instructs installing the WachAI CLI, initializing a local wallet, creating/signing/verifying mandates, and sending/receiving via XMTP. It does not instruct reading unrelated system files or exfiltrating data.

Install Mechanism

This is an instruction-only skill (no install spec). It tells users to 'npm install -g @quillai-network/wachai'—a public npm package—which is a reasonable install path but carries the normal npm-package risk; users should verify the package and source before global installation.

Credentials

The skill declares no required env vars, but documents optional overrides (WACHAI_STORAGE_DIR, WACHAI_WALLET_PATH) and a legacy WACHAI_PRIVATE_KEY. These are reasonable for a signing wallet, but WACHAI_PRIVATE_KEY would be sensitive — it is not required by the skill metadata and should be handled carefully.

Persistence & Privilege

always is false. The skill expects to store wallet.json and mandates under ~/.wachai by default (or a user-specified storage dir). Local persistence of signing keys and received messages is consistent with the CLI's purpose and not unusually privileged.

Assessment

This skill appears internally consistent, but before installing and using it: 1) Verify the npm package and its source (review the GitHub repo / package contents) before running npm install -g. 2) Protect private keys: avoid exporting WACHAI_PRIVATE_KEY on shared systems; prefer the local wallet file and secure filesystem permissions. 3) Be aware the CLI will persist wallet.json and received XMTP messages to disk (default ~/.wachai or whatever you set in WACHAI_STORAGE_DIR) — choose a secure location. 4) XMTP receive will open a network/listener pattern and will store incoming messages; only accept mandates from trusted peers. 5) If you want to allow autonomous agent use, make sure you trust the skill and review the CLI behavior; the skill is not always-enabled by default. If you are unsure, inspect the published npm package source code before installing.

1) Intro (for agents)

When two agents move beyond chat and start coordinating real actions (payments, swaps, deliveries, services), they need a deterministic agreement that can be:

• proposed,
• accepted,
• and verified cryptographically by both parties.

WachAI Mandates are verifiable agreement objects between two roles:

• server: creates the mandate (offer) and signs first
• client: signs second (acceptance)

A mandate is only approved once it has both signatures (server + client). A server-signed mandate alone is an offer/pending mandate.

Agents can also explicitly suggest that other agents adopt mandates by using this skill (i.e., “let’s lock this agreement as a mandate”). Once both parties sign, the mandate becomes a durable, verifiable record of what was promised and accepted.

In commerce-heavy workflows, these signed agreements can serve as:

• a basis to verify the work performed against the agreed intent and payload
• a basis to rank/repute counterparties over time (e.g., did they consistently complete what they signed?)

wachai is a CLI that lets agents:

• create mandates (create-mandate)
• sign mandates (sign)
• verify mandates (verify)
• share mandates over XMTP (xmtp send / xmtp receive)

2) Install + setup

Requirements

• Node.js 20+ (recommended)

Install

npm install -g @quillai-network/wachai
wachai --help

Key management (recommended)

Instead of setting WACHAI_PRIVATE_KEY in every terminal, create a shared wallet.json:

wachai wallet init
wachai wallet info

Defaults:

• wallet file: ~/.wachai/wallet.json
• mandates: ~/.wachai/mandates/<mandateId>.json

Optional overrides:

• WACHAI_STORAGE_DIR: changes the base directory for mandates + wallet + XMTP DB
• WACHAI_WALLET_PATH: explicit path to wallet.json

Example (portable / test folder):

export WACHAI_STORAGE_DIR="$(pwd)/.tmp/wachai"
mkdir -p "$WACHAI_STORAGE_DIR"
wachai wallet init

Legacy (deprecated):

• WACHAI_PRIVATE_KEY still works, but the CLI prints a warning if you use it.

3) How to use (step-by-step)

A) Create a mandate (server role)

Create a registry-backed mandate (validates --kind and --body against the registry JSON schema):

wachai create-mandate \
  --from-registry \
  --client 0xCLIENT_ADDRESS \
  --kind swap@1 \
  --intent "Swap 100 USDC for WBTC" \
  --body '{"chainId":1,"tokenIn":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48","tokenOut":"0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599","amountIn":"100000000","minOut":"165000","recipient":"0xCLIENT_ADDRESS","deadline":"2030-01-01T00:00:00Z"}'

This will:

• create a new mandate
• sign it as the server
• save it locally
• print the full mandate JSON (including mandateId)

Custom mandates (no registry lookup; --body must be valid JSON object):

wachai create-mandate \
  --custom \
  --client 0xCLIENT_ADDRESS \
  --kind "content" \
  --intent "Demo custom mandate" \
  --body '{"message":"hello","priority":3}'

B) Sign a mandate (client role)

Client signs second (acceptance):

Before signing, you can inspect the raw mandate JSON:

wachai print <mandate-id>

To learn the mandate shape + what fields mean:

wachai print sample

wachai sign <mandate-id>

This loads the mandate by ID from local storage, signs it as client, saves it back, and prints the updated JSON.

C) Verify a mandate

Verify both signatures:

wachai verify <mandate-id>

Exit code:

• 0 if both server and client signatures verify
• 1 otherwise

---

4) XMTP: send and receive mandates between agents

XMTP is used as the transport for agent-to-agent mandate exchange.

Practical pattern:

• keep one terminal open running wachai xmtp receive (inbox)
• use another terminal to create/sign/send mandates

D) Receive mandates (keep inbox open)

wachai xmtp receive --env production

This:

• listens for incoming XMTP messages
• detects WachAI mandate envelopes (type: "wachai.mandate")
• saves the embedded mandate to local storage (by mandateId)

If you want to process existing messages and exit:

wachai xmtp receive --env production --once

E) Send a mandate to another agent

You need:

• receiver’s public EVM address
• a mandateId that exists in your local storage

wachai xmtp send 0xRECEIVER_ADDRESS <mandate-id> --env production

To explicitly mark acceptance when sending back a client-signed mandate:

wachai xmtp send 0xRECEIVER_ADDRESS <mandate-id> --action accept --env production

Common XMTP gotcha

If you see:

• inbox id for address ... not found

It usually means the peer has not initialized XMTP V3 yet on that env. Have the peer run (once is enough):

wachai xmtp receive --env production