diff --git a/credentials/escrow/v1/README.md b/credentials/escrow/v1/README.md new file mode 100644 index 0000000..9b48e22 --- /dev/null +++ b/credentials/escrow/v1/README.md @@ -0,0 +1,51 @@ +# Escrow Receipt Schema + +Signed proof-of-completion credential for conditional task escrow using Cashu ecash tokens. + +## Schema + +### [escrow-receipt.json](escrow-receipt.json) + +Record the outcome of a delegated task executed under escrow conditions, including whether payment was released. + +**Use case:** A Lightning node executes a rebalancing task requested by an AI advisor. The node issues an escrow receipt recording success, the HTLC preimage revelation (releasing payment), and metrics like the amount rebalanced and routing fees paid. + +**Core fields:** +- `taskId` — Unique task identifier +- `taskSchema` — Schema of the executed task (e.g., `hive:rebalance/v1`) +- `executor` — DID of the agent that performed the task +- `verifier` — DID of the node/oracle that verified completion +- `completedAt` — Completion timestamp +- `result` — Outcome: `success`, `partial`, or `failed` +- `preimageRevealed` — Whether the HTLC preimage was revealed (payment released) +- `metrics` — Domain-specific quality measurements +- `stateHashBefore` / `stateHashAfter` — State integrity proofs +- `evidence` — Supporting attestations and receipts + +## Escrow Flow + +1. **Operator** mints a Cashu escrow ticket (P2PK + HTLC + timelock) +2. **Agent** presents ticket + credential + task command to the node +3. **Node** executes the task and issues this receipt +4. On **success**: receipt includes the HTLC preimage; agent redeems the token +5. On **failure**: no preimage; operator reclaims via timelock refund + +The receipt serves as verifiable evidence for [Reputation Credentials](../reputation/v1/) — completed escrow receipts prove an agent's track record. + +## Design + +- **W3C VC 2.0** compliant +- **Domain-agnostic** — works for any task schema, not just Lightning operations +- **Evidence-backed** — links to signed receipts, metric snapshots, and audit logs +- **Composable** with [Service Credentials](../service/v1/) for delegation scope and [L402 Access Credentials](../l402/v1/) for payment proof + +## Design Document + +- [DID + Cashu Task Escrow Protocol](https://github.com/lightning-goats/cl-hive/blob/main/docs/planning/DID-CASHU-TASK-ESCROW.md) — Full specification for conditional Cashu ecash tokens as task escrow tickets + +## Contributing + +When using escrow receipts with new task domains: +- Define meaningful `metrics` keys for the domain +- Document what constitutes `success` vs `partial` vs `failed` for the task schema +- Ensure the verifier is an objective party (or document the trust assumption) diff --git a/credentials/escrow/v1/escrow-receipt.json b/credentials/escrow/v1/escrow-receipt.json new file mode 100644 index 0000000..9ade88c --- /dev/null +++ b/credentials/escrow/v1/escrow-receipt.json @@ -0,0 +1,90 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$credentialContext": [ + "https://www.w3.org/ns/credentials/v2", + "https://schemas.archetech.com/credentials/escrow/v1" + ], + "$credentialType": [ + "VerifiableCredential", + "DIDTaskEscrowReceipt" + ], + "title": "DID Task Escrow Receipt", + "description": "Signed proof-of-completion credential for task escrow. Records the outcome of a delegated task, including whether the HTLC preimage was revealed (payment released) and domain-specific metrics measuring task quality. Used as evidence in reputation credentials.", + "type": "object", + "properties": { + "taskId": { + "type": "string", + "description": "Unique identifier for the task that was executed." + }, + "taskSchema": { + "type": "string", + "description": "Schema identifier of the task that was executed (e.g., 'hive:fee-policy/v1', 'agent:code-review/v1')." + }, + "executor": { + "type": "string", + "description": "DID of the agent or service that executed the task." + }, + "verifier": { + "type": "string", + "description": "DID of the node or oracle that verified task completion and controls the HTLC secret." + }, + "completedAt": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was completed or evaluated (ISO 8601)." + }, + "result": { + "type": "string", + "enum": ["success", "partial", "failed"], + "description": "Task outcome. 'success' = fully completed, 'partial' = some milestones achieved, 'failed' = task did not meet completion criteria." + }, + "preimageRevealed": { + "type": "boolean", + "description": "Whether the HTLC preimage was revealed, indicating payment was released to the executor." + }, + "metrics": { + "type": "object", + "description": "Domain-specific measurements of task outcome quality. Keys and semantics depend on the task schema.", + "additionalProperties": { + "oneOf": [ + { "type": "number" }, + { "type": "string" }, + { "type": "integer" }, + { "type": "boolean" } + ] + } + }, + "stateHashBefore": { + "type": "string", + "description": "Hash of the verifier's state before task execution, enabling before/after comparison." + }, + "stateHashAfter": { + "type": "string", + "description": "Hash of the verifier's state after task execution, proving the task changed (or preserved) state." + }, + "evidence": { + "type": "array", + "description": "Supporting attestations, receipts, or snapshots backing the receipt.", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["SignedReceipt", "MetricSnapshot", "Attestation", "AuditLog", "EscrowTicket"], + "description": "Category of evidence." + }, + "id": { + "type": "string", + "description": "DID or URI referencing the evidence credential." + }, + "description": { + "type": "string", + "description": "Human-readable description of the evidence." + } + }, + "required": ["type", "id"] + } + } + }, + "required": ["taskId", "taskSchema", "executor", "verifier", "completedAt", "result", "preimageRevealed"] +} diff --git a/credentials/l402/v1/README.md b/credentials/l402/v1/README.md new file mode 100644 index 0000000..2e31cf4 --- /dev/null +++ b/credentials/l402/v1/README.md @@ -0,0 +1,55 @@ +# L402 Access Credential Schema + +Binds DID identity with payment proof and scoped access authorization for payment-gated services. + +## Schema + +### [l402-access.json](l402-access.json) + +Express that a DID holder has paid for and is authorized to access specific services within defined scope and rate limits. + +**Use case:** An AI advisor pays a Lightning invoice to subscribe to a node's management API. The node issues an L402 Access Credential binding the advisor's DID to the payment proof and a scoped set of allowed actions with rate limits. + +**Core fields:** +- `accessType` — Access domain identifier (e.g., `hive:management`, `api:read`) +- `paymentProof` — Payment method (`lightning` or `cashu`), preimage hash, macaroon, token reference, amount, and timestamp +- `scope` — Allowed schemas, maximum actions, and rate limits +- `macaroonCaveats` — L402 macaroon caveats binding access to specific conditions (DID, tier, expiration, etc.) + +## Payment Models + +| Model | Payment Proof | Scope | Use Case | +|-------|--------------|-------|----------| +| **Per-action (Cashu)** | Cashu token hash + mint URL | Single action | Low-volume, pay-as-you-go | +| **Subscription (L402)** | Lightning preimage hash + macaroon | N actions over time window | High-volume, predictable access | +| **Hybrid** | Both methods accepted | Varies | Flexible access patterns | + +## Macaroon Caveats + +L402 macaroons support attenuation via caveats. Common caveats for service access: + +| Caveat | Example Value | Purpose | +|--------|--------------|---------| +| `did` | `did:cid:bagaaiera...` | Bind to specific DID holder | +| `tier` | `standard` | Permission tier | +| `expires` | `2026-03-14T00:00:00Z` | Expiration timestamp | +| `max_actions` | `1000` | Action budget | +| `service` | `hive:management` | Service domain restriction | + +## Design + +- **W3C VC 2.0** compliant +- **Domain-agnostic** — works for any payment-gated service, not just Lightning management +- **Composable** with [Service Credentials](../service/v1/) for delegation scope and [Escrow Receipts](../escrow/v1/) for conditional payment proof + +## Related + +- [Archon Issue #75](https://github.com/nicholasgasior/gatekeeper/issues/75) — L402 integration with Archon Gatekeeper +- [DID + L402 Remote Fleet Management](https://github.com/lightning-goats/cl-hive/blob/main/docs/planning/DID-L402-FLEET-MANAGEMENT.md) — Full specification for authenticated, paid remote node management + +## Contributing + +When using L402 access credentials with new service domains: +- Define the `accessType` namespace:type identifier +- Document which `macaroonCaveats` are meaningful for the domain +- Specify rate limiting expectations for the service diff --git a/credentials/l402/v1/l402-access.json b/credentials/l402/v1/l402-access.json new file mode 100644 index 0000000..206c5ee --- /dev/null +++ b/credentials/l402/v1/l402-access.json @@ -0,0 +1,111 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$credentialContext": [ + "https://www.w3.org/ns/credentials/v2", + "https://schemas.archetech.com/credentials/l402/v1" + ], + "$credentialType": [ + "VerifiableCredential", + "L402AccessCredential" + ], + "title": "L402 Access Credential", + "description": "Binds DID identity with payment proof and scoped access authorization. Enables payment-gated access to services where the credential holder has paid via Lightning or Cashu and is authorized for specific actions within defined rate limits.", + "type": "object", + "properties": { + "accessType": { + "type": "string", + "description": "Access domain identifier following namespace:type pattern (e.g., 'hive:management', 'api:read', 'content:premium').", + "pattern": "^[a-z]+:[a-z][a-z0-9_-]*$" + }, + "paymentProof": { + "type": "object", + "description": "Proof of payment authorizing this access credential.", + "properties": { + "method": { + "type": "string", + "enum": ["lightning", "cashu"], + "description": "Payment method used to obtain access." + }, + "preimageHash": { + "type": "string", + "description": "SHA-256 hash of the payment preimage (for Lightning payments)." + }, + "macaroon": { + "type": "string", + "description": "Serialized L402 macaroon token (for Lightning subscription payments)." + }, + "tokenHash": { + "type": "string", + "description": "Hash of the Cashu token used for payment (for Cashu payments)." + }, + "mint": { + "type": "string", + "format": "uri", + "description": "Cashu mint URL where the payment token was issued." + }, + "amountSats": { + "type": "integer", + "minimum": 0, + "description": "Amount paid in satoshis." + }, + "paidAt": { + "type": "string", + "format": "date-time", + "description": "Timestamp when payment was made (ISO 8601)." + } + }, + "required": ["method"] + }, + "scope": { + "type": "object", + "description": "Defines what the credential holder is authorized to access.", + "properties": { + "allowedSchemas": { + "type": "array", + "items": { "type": "string" }, + "description": "Schema identifiers the holder may invoke (supports glob patterns)." + }, + "maxActions": { + "type": "integer", + "minimum": 0, + "description": "Maximum number of actions authorized under this credential." + }, + "rateLimit": { + "type": "object", + "description": "Rate limiting parameters for access.", + "properties": { + "maxPerHour": { + "type": "integer", + "minimum": 0, + "description": "Maximum actions per hour." + }, + "maxPerDay": { + "type": "integer", + "minimum": 0, + "description": "Maximum actions per day." + } + } + } + } + }, + "macaroonCaveats": { + "type": "array", + "description": "L402 macaroon caveats binding the access credential to specific conditions.", + "items": { + "type": "object", + "properties": { + "condition": { + "type": "string", + "description": "Caveat condition key (e.g., 'did', 'tier', 'expires', 'max_actions', 'service')." + }, + "value": { + "type": "string", + "description": "Caveat condition value." + } + }, + "required": ["condition", "value"] + } + } + }, + "required": ["accessType", "paymentProof", "scope"] +} diff --git a/credentials/service/v1/README.md b/credentials/service/v1/README.md new file mode 100644 index 0000000..4e1e118 --- /dev/null +++ b/credentials/service/v1/README.md @@ -0,0 +1,69 @@ +# Service Credential Schemas + +General-purpose schemas for delegated service relationships between DIDs — scoped authorization and service advertising. + +## Schemas + +### [service-credential.json](service-credential.json) + +Express a scoped delegation of authority from one DID to another within a specific service domain. + +**Use case:** A Lightning node operator issues a service credential to an AI advisor, granting permission to adjust fees and rebalance channels within defined constraints and compensation terms. + +**Core fields:** +- `serviceType` — Domain identifier (e.g., `hive:management`, `agent:code-review`) +- `delegator` — DID granting authority (issuer) +- `delegate` — DID receiving authority (subject) +- `permissions` — Boolean flags for authorized actions +- `constraints` — Quantitative limits (rate limits, amount caps, allowed schemas) +- `tier` — Named permission level +- `compensation` — Payment model, rate, currency, and escrow terms +- `scope` — Additional metadata (allowed schemas, target resources, daily action limits) + +### [service-profile.json](service-profile.json) + +Advertise service capabilities, pricing, and availability. Self-issued by service providers to enable marketplace discovery. + +**Use case:** An AI fleet advisor publishes a service profile describing their routing optimization capabilities, pricing models, current availability, and links to reputation credentials from past clients. + +**Core fields:** +- `serviceType` — Service domain identifier +- `capabilities` — What the provider can do +- `supportedSchemas` — Which command schemas the provider supports +- `pricing` — Available compensation models with rates +- `availability` — Capacity, current load, acceptance status +- `specializations` — Areas of particular expertise +- `reputation` — References to third-party reputation credentials +- `contact` — DID and endpoints for communication + +## Service Types + +Service type identifiers follow the `namespace:type` pattern: + +| Service Type | Description | Example Use | +|-------------|-------------|-------------| +| `hive:management` | Lightning fleet management | AI advisor managing node fees, rebalancing, channels | +| `hive:monitoring` | Node health monitoring | Dashboard service tracking uptime and metrics | +| `agent:code-review` | Code review service | AI agent reviewing pull requests | +| `infra:monitoring` | Infrastructure monitoring | Service monitoring uptime and alerting | + +New service types are created organically — any issuer can define a new `namespace:type` pair. + +## Design + +- **W3C VC 2.0** compliant (`validFrom`/`validUntil`, standard context) +- **Domain-agnostic** — the same schema works for Lightning fleet management, code review, or any delegated service +- **Composable** with [Reputation Credentials](../reputation/v1/) for trust evaluation and [Escrow Receipts](../escrow/v1/) for payment conditionality + +## Design Documents + +- [DID + L402 Remote Fleet Management](https://github.com/lightning-goats/cl-hive/blob/main/docs/planning/DID-L402-FLEET-MANAGEMENT.md) — Full specification for authenticated, paid remote node management +- [DID Hive Marketplace Protocol](https://github.com/lightning-goats/cl-hive/blob/main/docs/planning/DID-HIVE-MARKETPLACE.md) — Marketplace layer for service discovery, negotiation, and contracting + +## Contributing + +When proposing new service types: +- Follow the `namespace:type` naming convention +- Define clear permission semantics for the domain +- Document expected constraint keys and their units +- Specify which compensation models are appropriate diff --git a/credentials/service/v1/service-credential.json b/credentials/service/v1/service-credential.json new file mode 100644 index 0000000..df9f43a --- /dev/null +++ b/credentials/service/v1/service-credential.json @@ -0,0 +1,107 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$credentialContext": [ + "https://www.w3.org/ns/credentials/v2", + "https://schemas.archetech.com/credentials/service/v1" + ], + "$credentialType": [ + "VerifiableCredential", + "DIDServiceCredential" + ], + "title": "DID Service Credential", + "description": "General-purpose scoped delegation credential for service relationships between DIDs. Defines what a delegate is authorized to do, within what constraints, and how they are compensated. Domain-agnostic — applicable to fleet management, code review, monitoring, or any delegated service.", + "type": "object", + "properties": { + "serviceType": { + "type": "string", + "description": "Service domain identifier following namespace:type pattern (e.g., 'hive:management', 'agent:code-review', 'infra:monitoring').", + "pattern": "^[a-z]+:[a-z][a-z0-9_-]*$" + }, + "delegator": { + "type": "string", + "description": "DID of the party granting authority (the credential issuer)." + }, + "delegate": { + "type": "string", + "description": "DID of the party receiving delegated authority (the credential subject)." + }, + "permissions": { + "type": "object", + "description": "Boolean flags defining what the delegate is authorized to do. Keys are domain-specific permission names.", + "additionalProperties": { + "type": "boolean" + } + }, + "constraints": { + "type": "object", + "description": "Quantitative limits on delegated authority. Keys are domain-specific constraint names; values are numbers or strings defining upper bounds, allowed lists, or rate limits.", + "additionalProperties": { + "oneOf": [ + { "type": "number" }, + { "type": "string" }, + { + "type": "array", + "items": { "type": "string" } + } + ] + } + }, + "tier": { + "type": "string", + "description": "Named permission tier summarizing the delegation level (e.g., 'monitor', 'standard', 'advanced', 'admin'). Semantics are domain-specific." + }, + "compensation": { + "type": "object", + "description": "How the delegate is compensated for service.", + "properties": { + "model": { + "type": "string", + "enum": ["per_action", "subscription", "performance", "escrow", "flat_fee"], + "description": "Compensation model governing payment timing and conditions." + }, + "rate": { + "type": "number", + "description": "Compensation rate in the specified currency (e.g., sats per action, sats per month)." + }, + "currency": { + "type": "string", + "description": "Payment currency or method (e.g., 'sats', 'L402', 'cashu')." + }, + "performanceSharePct": { + "type": "number", + "minimum": 0, + "maximum": 100, + "description": "Percentage of performance-based bonus (for 'performance' model)." + }, + "acceptableMints": { + "type": "array", + "items": { "type": "string", "format": "uri" }, + "description": "Acceptable Cashu mint URLs for escrow ticket redemption." + } + }, + "required": ["model", "currency"] + }, + "scope": { + "type": "object", + "description": "Additional metadata bounding the delegation scope.", + "properties": { + "allowedSchemas": { + "type": "array", + "items": { "type": "string" }, + "description": "Schema identifiers the delegate is authorized to execute (supports glob patterns)." + }, + "targetResources": { + "type": "array", + "items": { "type": "string" }, + "description": "Identifiers of resources the delegate may act upon (e.g., node IDs, service endpoints)." + }, + "maxDailyActions": { + "type": "integer", + "minimum": 0, + "description": "Maximum number of actions the delegate may perform per day." + } + } + } + }, + "required": ["serviceType", "delegator", "delegate", "permissions", "tier", "compensation"] +} diff --git a/credentials/service/v1/service-profile.json b/credentials/service/v1/service-profile.json new file mode 100644 index 0000000..1040c2c --- /dev/null +++ b/credentials/service/v1/service-profile.json @@ -0,0 +1,131 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$credentialContext": [ + "https://www.w3.org/ns/credentials/v2", + "https://schemas.archetech.com/credentials/service/v1" + ], + "$credentialType": [ + "VerifiableCredential", + "DIDServiceProfile" + ], + "title": "DID Service Profile", + "description": "Service advertising credential for any DID offering delegated services. Describes capabilities, pricing, availability, and reputation references. Self-issued by the service provider to enable marketplace discovery.", + "type": "object", + "properties": { + "serviceType": { + "type": "string", + "description": "Service domain identifier following namespace:type pattern (e.g., 'hive:advisor', 'agent:code-review').", + "pattern": "^[a-z]+:[a-z][a-z0-9_-]*$" + }, + "capabilities": { + "type": "array", + "items": { "type": "string" }, + "description": "List of capability identifiers this service provider offers (e.g., 'fee-optimization', 'rebalancing', 'emergency-response')." + }, + "supportedSchemas": { + "type": "array", + "items": { "type": "string" }, + "description": "Schema URIs or identifiers this provider can execute (e.g., 'hive:fee-policy/v1', 'hive:rebalance/v1')." + }, + "pricing": { + "type": "array", + "description": "Available pricing models offered by this provider.", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["per_action", "subscription", "performance", "escrow", "flat_fee"], + "description": "Pricing model type." + }, + "rate": { + "type": "number", + "description": "Base rate in the specified currency." + }, + "currency": { + "type": "string", + "description": "Payment currency or method (e.g., 'sats', 'L402', 'cashu')." + }, + "description": { + "type": "string", + "description": "Human-readable description of this pricing model." + } + }, + "required": ["type", "currency"] + } + }, + "availability": { + "type": "object", + "description": "Current availability and capacity of the service provider.", + "properties": { + "maxClients": { + "type": "integer", + "minimum": 0, + "description": "Maximum number of concurrent clients this provider can serve." + }, + "currentLoad": { + "type": "integer", + "minimum": 0, + "description": "Number of clients currently being served." + }, + "acceptingNewClients": { + "type": "boolean", + "description": "Whether the provider is currently accepting new clients." + }, + "responseTimeSla": { + "type": "string", + "description": "Advertised response time SLA (e.g., '5m', '1h', '24h')." + } + } + }, + "specializations": { + "type": "array", + "items": { "type": "string" }, + "description": "Areas of particular expertise (e.g., 'high-volume-routing', 'fee-optimization', 'emergency-response')." + }, + "reputation": { + "type": "array", + "description": "References to DIDReputationCredential instances attesting to this provider's track record.", + "items": { + "type": "object", + "properties": { + "credentialRef": { + "type": "string", + "description": "DID or URI of the reputation credential." + }, + "issuer": { + "type": "string", + "description": "DID of the reputation credential issuer (the client who evaluated)." + }, + "domain": { + "type": "string", + "description": "Reputation domain (e.g., 'hive:advisor').", + "pattern": "^[a-z]+:[a-z][a-z0-9_-]*$" + }, + "outcome": { + "type": "string", + "enum": ["renew", "revoke", "neutral"], + "description": "Outcome of the referenced reputation credential." + } + }, + "required": ["credentialRef"] + } + }, + "contact": { + "type": "object", + "description": "Contact information for reaching this service provider.", + "properties": { + "did": { + "type": "string", + "description": "Primary DID for communication." + }, + "endpoints": { + "type": "array", + "items": { "type": "string" }, + "description": "Reachable endpoints (e.g., Nostr relays, Lightning node pubkeys, Dmail addresses)." + } + } + } + }, + "required": ["serviceType", "capabilities", "supportedSchemas", "pricing", "availability"] +}