Building on Warda
A grant is a UTXO locked by a covenant. It names an agent key, a total budget, a per-spend cap, a rate limit, a validity window and an allowlist of payees. The agent spends from it directly — no co-signing, no relay, no custody — and consensus rejects anything outside those limits.
Steal the agent key and you inherit exactly the same limits. That is the point.
The same six checks the covenant runs, in the same order. On chain these are consensus rules, not advice: a transaction failing one is not rejected by a server, it is invalid.
Install
Compiled JavaScript with TypeScript declarations. Node 20+, no build step, no Rust toolchain and no Silverscript compiler — address derivation splices values into a compiled covenant template that ships inside the package.
# the SDK — build, sign and verify grants npm install @warda_protocol/kaspa # the MCP server — hand an agent framework a Warda tool npx @warda_protocol/mcp # the x402 adapter — pay metered APIs from a grant npm install @warda_protocol/x402
import { buildGenesis, attachGenesisSignature, signDigest, RecipientSet } from "@warda_protocol/kaspa"; import template from "@warda_protocol/kaspa/covenant-template.json" with { type: "json" }; // Who this agent may pay, committed as a Merkle root. const payees = new RecipientSet([vendorA, vendorB]); const grant = { authority: { principalKey, revocationKey }, state: { agentKey, budgetTotal: 1_000_00000000n, // 1000 KAS, ever maxPerSpend: 200_00000000n, // 200 KAS per payment epochLimit: 500_00000000n, // 500 KAS ... epochLength: 1000n, // ... per 1000 blocks recipientsRoot: payees.rootHex, notBefore, expiresAt, delegationDepth: 2n, /* accounting starts at zero */ }, }; const unsigned = buildGenesis({ template, grant, funding, changeScriptPublicKey, fee }); const tx = attachGenesisSignature(unsigned, signDigest(unsigned.sighash, principalSecret));
import { WardaPayer, wardaFetch } from "@warda_protocol/x402"; const payer = new WardaPayer({ grant: { template, authority, state, recipients }, node, sign: agentSecret, // or a remote signer function }); // A paid endpoint, called like a free one. The 402, the covenant // spend and the X-PAYMENT proof are handled underneath. const res = await wardaFetch("https://vendor.example/compute", { method: "POST", body: JSON.stringify({ prompt: "explain GHOSTDAG" }), }, { payer });
It never pays twice. A second 402 means the payment is still settling, so the same proof is re-presented rather than a new one bought — and if the server never settles, it says the money is spent instead of paying again.
import { signSpend } from "@warda_protocol/kaspa"; const { tx } = signSpend({ template, authority, state, utxo, // the grant's current coin amount: 50_00000000n, recipient: vendorA, proof: payees.proof(vendorA), // proves the payee is allowed claimedDaa, fee, computeBudget: 16, }, agentSecret); // the principal is not involved
The SDK deliberately does not decide whether a spend is allowed — the covenant does, on chain, and it is the only thing that can. If the SDK reimplemented the rules, a divergence would fail by wrongly permitting: it says yes, and a budget drains on a spend nobody authorised. Reimplementing assembly fails the other way — a mistake produces a transaction the network rejects, which is loud.
The distinction it all rests on
The usual pattern: fund a hot wallet with "only what the agent should spend", and keep a running total in the code that pays.
A real agent-payments library shipping today caps spending with an environment variable, and its own docs say the server "refuses further calls until restarted."
So the cap resets when the process does. It is bypassed by a crash, a redeploy, a second instance, or anyone who reads the key out of env. The wallet balance is the only true limit.
The budget, the caps, the window and the payee allowlist are part of the script that unlocks the coin.
A spend exceeding any of them is not refused by a server. It is an invalid transaction — no node relays it, no miner can include it.
Restarting changes nothing. Nor does compromising the agent. The limits are not enforced by the code holding the key.
Anatomy
A grant is state encoded into an address. Change any field and it is a different address — which is why a grant is never edited, only spent forward.
| Field | What it binds |
|---|---|
| budgetTotal | The most this grant can ever spend, across its life and every child it delegates to. |
| maxPerSpend | A ceiling on any single payment. Caps the blast radius of one bad decision. |
| epochLimit | A rate: how much per epochLength blocks. Bounds how fast a compromise drains. |
| notBefore / expiresAt | A validity window. After expiry the principal may sweep the remainder home. |
| recipientsRoot | A Merkle root over allowed payees. Every spend carries an inclusion proof; there is no way to pay anyone else. |
| delegationDepth | How many further levels of sub-agent this grant may create. Zero makes it a leaf. |
| Key | Power | Held by |
|---|---|---|
| agentKey | Spend within the limits; delegate to sub-agents. | The agent, online, on the machine doing the work. |
| revocationKey | Stop the grant. Sweeps the balance to the principal — it can never redirect it elsewhere. | A monitor or kill-switch you do not have to trust with the money. |
| principalKey | Receive. Reclaim the remainder after expiry. | The owner. Signs once at creation, then offline. |
That split is load-bearing, and it took two real bugs to make it true. One version let the revocation path burn the balance to fees; a later one let it sweep a delegated child anywhere it liked. Both turned a stop capability into a destroy or take one. Both are fixed, and both now have an attack test that fails if they return.
Lifecycle
Every one is an entrypoint in the covenant. The address changes at each step, because the address is the state.
Principal signs · once
An ordinary payment that happens to pay into a covenant address. From here the principal can go offline permanently.
Agent signs
Pay an allowlisted recipient within every cap. The remainder continues to a new address encoding the updated accounting.
Agent signs
Hand a sub-agent its own narrower grant, without asking the principal and without custody. The parent reserves exactly what the child receives, so authority is subdivided and never created. A child may narrow the payee list, the caps, the rate and the window — never widen any of them.
Agent + revocation key
Take a finished child back in. Its remaining coin returns to the parent and what it spent is charged against the parent's budget. Without this, delegation would be one-way: a grant that subdivided itself would shrink permanently.
Revocation key
Stop the grant at any time. The balance goes to the principal and nowhere else — the covenant checks destination and amount, so a monitor holding this key can halt an agent without being able to take or burn its money.
Principal signs
After expiry, sweep the remainder home. This is a right that opens at expiry, not a prohibition that closes: a UTXO covenant can say "not before X", never "must be spent before X".
Proof of work, in the literal sense
A real x402 endpoint priced at 0.2 KAS, paid by a covenant spend, with the vendor verifying against the UTXO set before serving. Reproduce it with x402/demo/testnet-demo.ts.
The settling retry is the part worth watching. The vendor answered 402 a second time because the coin was not yet in the UTXO set, and the client re-presented the same proof rather than buying a second call — the one failure mode in this design capable of draining a budget through nobody's fault.
The receipt was written by the process that made the payment, which is precisely the party not to take it from. So every claim in it is re-derived from the UTXO set:
node --experimental-strip-types x402/demo/verify-receipt.ts
ok the vendor was paid 20000000 sompi by 267e1bac1270fde3…
ok the address the grant spent FROM is now empty
ok the successor address holds exactly one coin
ok the coin balances: 300000000 in, 20000000 paid, 2000000 fee, 278000000 left
ok spentTotal advanced by exactly the amount paid (20000000)
ok the payment was within the per-spend cap (50000000)
the chain agrees with this receipt.
One thing the first live run taught, and the code now knows. Kaspa prices by mass, and a covenant spend carries the whole 5.7 KB redeem script in its signature script — so it is ~6 KB on the wire and costs roughly 1,511,400 sompi, not the 1,000,000 that covers a plain transfer. v3 fitted under the old default; v4 does not, because settlement and the subset witness made the script bigger. A node will accept the signature and still refuse to relay. The adapter now defaults higher and translates that rejection into the exact figure the node asked for.
Evidence
Golden vectors prove two implementations agree about a transaction meant to work. They cannot catch a covenant that permits too much. These do the other half — and every attack sits beside its nearest legitimate twin, because a covenant that refuses everything would pass a suite made only of refusals.
| Probe | Engine | What it establishes |
|---|---|---|
| epoch-rewind | refused | The agent picks the block height it claims. Claiming an earlier epoch once reset the allowance to zero, repeatably. The rate cap limited nothing at all. |
| epoch-forward | accepted | A genuinely later epoch still gets its fresh allowance. The fix must not block the honest case. |
| past-expiry | refused | Spending after the window closed. The spend path had no expiry check whatsoever. |
| revoke-burn | refused | Revoke paying 1 sompi to the principal and burning the rest to fees. The exits checked where coin went and never how much. |
| settle-steal | refused | The revocation key sweeping a delegated child to an address of its choosing — the same bug as above, in a path written after that one was fixed. |
| reabsorb-live-grandchild | refused | Settling a child that still funds grandchildren, releasing the parent's reserve while that coin sits outside anyone's accounting. |
| narrowed-pays-outside | refused | A sub-agent paying someone on its parent's allowlist but not its own. Without this, narrowing would be decoration. |
| narrowed-pays-inside | accepted | The same sub-agent paying its own vendor. The twin that proves the check discriminates. |
Eight of fourteen shown. Six vulnerabilities have been found in this covenant; none was found by reading the code, and each is now pinned by a probe that fails if it returns.
Integrations
Which makes it a drop-in wherever an agent currently needs a private key.
Available now
@warda_protocol/mcp exposes four tools over stdio: read a grant's authority, check whether a spend is permitted and why, check a delegation, and build an unsigned spend. It never holds a key and never enforces — it explains, and the covenant decides.
Available now
@warda_protocol/x402 is a drop-in fetch. Call a paid endpoint as you would a free one; the 402, the covenant spend and the proof happen underneath. x402 answers how to pay for one call; Warda answers what may be spent, and to whom — a marketplace's validated vendor list is the allowlist.
Built in
The SDK speaks wRPC directly — four calls, no proxy. It refuses to route covenant transactions through third-party REST services, which silently drop the covenant binding and produce a signature that cannot verify.
Any language
Golden genesis, spend and delegation vectors travel in the package, so a second implementation in any language can check itself against the same bytes rather than against a prose spec.
Limits
Published as prominently as the guarantees, because a limit you discover in production is a bug and a limit you read first is a design constraint.
budgetTotal — the reserve accounting is conservative — but the rate limit degrades toward the budget limit under delegation.