archetech · hexdaemon · Feb 14, 2026
diff --git a/credentials/escrow/v1/README.md 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
@@ -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
@@ -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
@@ -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
@@ -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