Attenuate a Macaroon
proof.attenuateAttenuate an authentic, unexpired L402 parent macaroon by appending strictly formatted first-party caveats. expiresAt (UTC instant) or ttlSeconds adds time < YYYY-MM-DDTHH:MM:SS.sssZ: redemption at or after that instant is rejected with HTTP 401. tools adds rpc = tool[,tool...]: any tool not listed exactly is rejected with HTTP 403, and every listed tool must already be authorized by the parent. caveats accepts those forms plus max_target, max_requests, allowed_path, and legacy time_before or allowed_tools restrictions. At least one restriction is required. Requires its own L402 authorization; the parent's payment proof remains required for child redemption. Delegation cannot widen authority or reset an inherited quota. Live L402 Satoshi settlement: a configured NWC wallet issues the exact-priced Lightning invoice; paid execution requires confirmed incoming settlement and an invoice-bound payment proof. Handle HTTP 402, pay explicitly, then retry the identical request with Authorization: L402 :. Invoice creation alone is not payment; unavailable verification does not authorize execution.
Example tool call
This call uses example arguments supplied in the tool’s input schema.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"tools": [
"stratigraphy.get_diff"
],
"caveats": [
"max_target = 870000"
],
"macaroon": "base64url-parent-macaroon",
"expiresAt": "2026-12-31T23:59:59Z"
},
"name": "proof.attenuate"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tools | No | Optional exact MCP tool targets (1-16 unique names). Appends one `rpc = tool[,tool...]` caveat; the child is refused for every other tool. Matching is exact, so a legacy alias is a different name. Each tool must already be authorized by the parent: an MCP L402 credential authorizes the single tool named in its allowed_path. Constraints: minItems: 1; maxItems: 16. Example: ["stratigraphy.get_diff"]. | |
| caveats | No | Optional restriction caveats to append, normalized to canonical form: 'time < 2026-12-31T23:59:59Z', 'rpc = stratigraphy.get_diff', 'max_target = 870000', 'max_requests = 1', 'allowed_path = /mcp/tools/stratigraphy.get_diff', and legacy 'time_before = 2026-12-31' or 'allowed_tools = stratigraphy.get,stratigraphy.get_digest'. Constraints: maxItems: 16. Example: ["max_target = 870000"]. | |
| macaroon | Yes | Required authentic, unexpired parent L402 macaroon (1-8192 characters); added restrictions can only narrow its scope. Constraints: minLength: 1; maxLength: 8192. Example: "base64url-parent-macaroon". | |
| expiresAt | No | Optional absolute expiration boundary as a future UTC instant (YYYY-MM-DDTHH:MM:SSZ, optionally with .sss milliseconds). Appends `time < YYYY-MM-DDTHH:MM:SS.sssZ`; it cannot extend the parent's expiry. Mutually exclusive with ttlSeconds. Constraints: format: date-time; pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$. Example: "2026-12-31T23:59:59Z". | |
| ttlSeconds | No | Optional positive integer TTL of 1-2592000 seconds (e.g. 3600). Appends `time <` at the current time plus ttlSeconds; it cannot extend the parent's expiry. Mutually exclusive with expiresAt. Constraints: minimum: 1; maximum: 2592000. Example: 3600. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | Successful attenuation status. Example: "attenuated". | |
| issuedAt | Yes | UTC issuance timestamp. Constraints: format: date-time. Example: "2026-09-27T21:00:00.000Z". | |
| appliedCaveats | Yes | New canonical caveats appended to the parent; inherited caveats are preserved inside the token. Example: ["max_target=870000","time < 2026-12-31T23:59:59.000Z","rpc = stratigraphy.get_diff"]. | |
| attenuatedMacaroon | Yes | Encoded child subscription macaroon. Treat as a bearer credential. Example: "base64url-child-macaroon". | |
| _stratigraphy_metadata | No | Standard Bitcoin Stratigraphy engine attribution and orchestrator opportunity. |