{"id":"75340894a67306e89e04e76c2ada238f7ad2b42afc9cfbcf09e2c9324e42afd7","pubkey":"da19f1cd34beca44be74da4b306d9d1dd86b6343cef94ce22c49c6f59816e5bd","created_at":1774618397,"kind":30817,"tags":[["title","NIP-SLA: Service Level Agreements (Composition Guide)"],["k","composition-guide"],["d","nip-sla"]],"content":"NIP-SLA\n=======\n\nService Level Agreements (Composition Guide)\n-----------------------------------------------\n\n`draft` `optional` `composition-guide`\n\n> **Standalone.** This NIP works independently on any Nostr application. It does not depend on any particular protocol ecosystem or application framework.\n\n> **Composition guide, not a new kind.** This document describes how [NIP-EVIDENCE](NIP-EVIDENCE.md), [NIP-APPROVAL](NIP-APPROVAL.md), and [NIP-DISPUTES](NIP-DISPUTES.md) can be combined to model Service Level Agreements on Nostr. No new event kinds are defined. These three NIPs are currently drafts. This guide will be most useful once its component NIPs are accepted, but it is written so that each component contributes independently -- you do not need all three to get value from this pattern.\n\n---\n\n## How to Read This Guide\n\nEach section of this guide maps to one component NIP. You can adopt them incrementally:\n\n| If you only adopt...   | You get...                                                                 |\n|------------------------|----------------------------------------------------------------------------|\n| **NIP-EVIDENCE alone** | Publishable SLA templates and machine-readable breach reports              |\n| **+ NIP-APPROVAL**     | Multi-party agreement workflows binding templates to specific engagements  |\n| **+ NIP-DISPUTES**     | Formal escalation and mediation when breach reports are contested          |\n\nThe full pattern uses all three, but a team that only needs to publish SLA terms (templates) or record threshold violations (breach reports) can start with NIP-EVIDENCE alone and layer in agreement and dispute workflows later.\n\n---\n\n## Motivation\n\nNostr has mechanisms for conditional payment coordination (NIP-ESCROW) and structured billing (NIP-INVOICING), but no standard pattern for **declaring and enforcing performance commitments**. Many service relationships benefit from measurable quality guarantees:\n\n- **API providers** commit to 99.9% uptime with penalty credits for downtime exceeding the threshold\n- **SaaS platforms** guarantee response time targets (e.g. < 200ms p95) with automated breach detection\n- **Consultants** promise first-contact response within 4 hours and resolution within 48 hours, with refunds for missed deadlines\n- **Freelancers** agree to milestone delivery deadlines with penalty clauses for late completion\n- **Managed infrastructure providers** offer availability guarantees with tiered severity levels and escalating penalties\n\nThese are all variations of the same pattern: a provider publishes commitments, both parties agree, measurements are taken, and breaches are resolved. This guide shows how to model that pattern using existing Nostr primitives.\n\n### Why composition over dedicated kinds?\n\nSLA management decomposes into three operations that already have NIP support:\n\n1. **Publishing a reference document** (the SLA template) -- this is evidence: a signed, timestamped record of commitments. NIP-EVIDENCE (`kind:30578`) handles this directly.\n2. **Multi-party agreement** to those terms -- this is an approval workflow. NIP-APPROVAL (`kind:30570` + `kind:30571`) handles this directly.\n3. **Recording a threshold violation** (a breach) -- this is evidence of a measured fact. NIP-EVIDENCE handles this directly.\n4. **Disputing a contested breach** -- this is a dispute. NIP-DISPUTES (`kind:7543` + `kind:30545`) handles this directly.\n\nDedicated SLA kinds would duplicate semantics already available in these NIPs. Composition keeps the kind space lean and lets implementers reuse existing parsers, builders, and relay filters.\n\n### Why not NIP-78 (Arbitrary Custom App Data)?\n\nNIP-78 (`kind:30078`) provides generic application-specific data storage. While you could encode SLA terms in a `kind:30078` event, you would lose the structured semantics that NIP-EVIDENCE provides: evidence typing, captured-at timestamps, file hashes for supporting documents, and integration with relay filters that already understand evidence records. SLA templates are a specific category of evidence, not arbitrary app data.\n\n### Why not plain kind:1 notes?\n\nYou could announce SLA terms in a regular note, but notes lack addressable event semantics (no `d` tag for updates), no structured tag format for machine parsing, and no integration with approval or dispute workflows. An SLA that cannot be programmatically queried, agreed to, or enforced is just a promise in a timeline.\n\n---\n\n## Terminology\n\n| Term                    | Description                                                                                     |\n|-------------------------|-------------------------------------------------------------------------------------------------|\n| **SLA template**        | A `kind:30578` evidence record declaring a provider's standard performance commitments           |\n| **SLA agreement**       | A `kind:30570` approval gate + `kind:30571` responses binding SLA terms to a specific engagement |\n| **SLA breach**          | A `kind:30578` evidence record documenting that an SLA threshold was violated                    |\n| **Response time**       | The maximum permitted time between engagement start and first provider action                    |\n| **Resolution time**     | The maximum permitted time between engagement start and completion                              |\n| **Availability**        | The percentage of time a service must be operational within a measurement period                 |\n| **First contact**       | The maximum permitted time between request creation and first provider response                  |\n| **On-time rate**        | The minimum percentage of engagements completed by their agreed deadline                        |\n| **Threshold**           | The numeric limit that defines SLA compliance (e.g. 240 minutes, 99.5 percent)                  |\n| **Penalty**             | The consequence triggered by an SLA breach -- applications define their own penalty structures   |\n| **Severity**            | The classification of a breach: `minor`, `major`, or `critical`                                 |\n\n---\n\n## SLA Metric Conventions\n\nAll SLA events in this guide use consistent tag conventions for metrics, thresholds, and penalties. Applications MAY extend these conventions with additional metric types, units, or penalty structures to suit their needs.\n\n### SLA Metric Types\n\nThese are the standard metric types. Applications MAY define additional types using the same tag format.\n\n| Type              | Description                                                                      |\n|-------------------|----------------------------------------------------------------------------------|\n| `response_time`   | Maximum time from engagement start to first provider action or acknowledgement   |\n| `resolution_time` | Maximum time from engagement start to completion                                 |\n| `availability`    | Minimum percentage of uptime within the measurement period                       |\n| `first_contact`   | Maximum time from request creation to first provider response                    |\n| `on_time_rate`    | Minimum percentage of engagements completed by their agreed deadline             |\n\n### Threshold Units\n\n| Unit         | Description                                                         |\n|--------------|---------------------------------------------------------------------|\n| `minutes`    | Elapsed minutes (e.g. 240 = 4 hours)                               |\n| `hours`      | Elapsed hours (e.g. 24 = 1 day)                                    |\n| `days`       | Elapsed days (e.g. 14 = 2 weeks)                                   |\n| `percentage` | Percentage value (e.g. 99.5 = 99.5% uptime or on-time rate)        |\n\n### Penalty Types\n\nApplications define their own penalty structures. The following types are suggested starting points:\n\n| Type              | Description                                                          |\n|-------------------|----------------------------------------------------------------------|\n| `refund`          | Direct payment from provider to consumer                             |\n| `credit`          | Credit issued against a future invoice or billing cycle              |\n| `stake_forfeit`   | Forfeiture of a locked stake or deposit held in escrow               |\n\n### Measurement Periods\n\n| Period       | Description                              |\n|--------------|------------------------------------------|\n| `monthly`    | Calendar month                           |\n| `quarterly`  | Calendar quarter (3 months)              |\n| `yearly`     | Calendar year                            |\n\n---\n\n## Component 1: SLA Templates with NIP-EVIDENCE\n\n> **Independent value.** Even without NIP-APPROVAL or NIP-DISPUTES, publishing SLA templates as evidence records gives providers a verifiable, timestamped, machine-readable way to advertise their service commitments. Clients can query relay filters to discover and compare SLA offerings across providers.\n\nAn SLA template is a published reference document declaring a provider's standard performance commitments. Because templates are signed, timestamped records of fact, they map directly to NIP-EVIDENCE (`kind:30578`) with `evidence_type: sla_template`.\n\nEach template defines one or more service level objectives via repeatable `sla_metric` tags. Structured SLA tags (`sla_threshold`, `sla_penalty`, `sla_measurement_window`) provide machine-parseable parameters alongside each metric.\n\n### SLA Metric Tag Format\n\nEach `sla_metric` tag uses a structured multi-value format:\n\n```\n[\"sla_metric\", \"<sla_type>\", \"<threshold_value>\", \"<threshold_unit>\", \"<penalty_amount>\", \"<penalty_type>\"]\n```\n\n| Position | Field | Description |\n|----------|-------|-------------|\n| 1 | `sla_type` | Metric type (see SLA Metric Types table above) |\n| 2 | `threshold_value` | Numeric threshold as a string |\n| 3 | `threshold_unit` | Unit of measurement |\n| 4 | `penalty_amount` | Penalty amount in smallest currency unit (cents for USD, satoshis for SAT, etc.) |\n| 5 | `penalty_type` | Penalty category (e.g. `refund`, `credit`, or `stake_forfeit`) |\n\n### Example: API Hosting SLA Template\n\nA cloud API provider advertising availability and response time guarantees:\n\n```json\n{\n  \"kind\": 30578,\n  \"pubkey\": \"<provider-hex-pubkey>\",\n  \"created_at\": 1698780000,\n  \"tags\": [\n    [\"d\", \"api-hosting:sla_template:premium\"],\n    [\"t\", \"evidence-record\"],\n    [\"alt\", \"SLA template: API hosting premium tier\"],\n    [\"evidence_type\", \"sla_template\"],\n    [\"sla_metric\", \"availability\", \"99.9\", \"percentage\", \"10000\", \"credit\"],\n    [\"sla_metric\", \"response_time\", \"200\", \"minutes\", \"5000\", \"refund\"],\n    [\"sla_threshold\", \"availability\", \"99.9\", \"percentage\"],\n    [\"sla_threshold\", \"response_time\", \"200\", \"minutes\"],\n    [\"sla_penalty\", \"availability\", \"10000\", \"credit\"],\n    [\"sla_penalty\", \"response_time\", \"5000\", \"refund\"],\n    [\"sla_measurement_window\", \"monthly\"],\n    [\"p\", \"<provider-hex-pubkey>\"],\n    [\"currency\", \"USD\"],\n    [\"captured_at\", \"1698780000\"]\n  ],\n  \"content\": \"\",\n  \"id\": \"<32-byte-hex>\",\n  \"sig\": \"<64-byte-hex>\"\n}\n```\n\n### Example: Freelance Project SLA Template\n\nA freelance developer advertising milestone delivery and revision guarantees:\n\n```json\n{\n  \"kind\": 30578,\n  \"pubkey\": \"<freelancer-hex-pubkey>\",\n  \"created_at\": 1698780000,\n  \"tags\": [\n    [\"d\", \"freelance-dev:sla_template:standard\"],\n    [\"t\", \"evidence-record\"],\n    [\"alt\", \"SLA template: freelance development standard tier\"],\n    [\"evidence_type\", \"sla_template\"],\n    [\"sla_metric\", \"resolution_time\", \"14\", \"days\", \"50000\", \"refund\"],\n    [\"sla_metric\", \"first_contact\", \"24\", \"hours\", \"0\", \"credit\"],\n    [\"sla_threshold\", \"resolution_time\", \"14\", \"days\"],\n    [\"sla_threshold\", \"first_contact\", \"24\", \"hours\"],\n    [\"sla_penalty\", \"resolution_time\", \"50000\", \"refund\"],\n    [\"sla_measurement_window\", \"monthly\"],\n    [\"p\", \"<freelancer-hex-pubkey>\"],\n    [\"currency\", \"USD\"],\n    [\"captured_at\", \"1698780000\"]\n  ],\n  \"content\": \"Milestone delivery within 14 days of acceptance. First response to queries within 24 hours on business days. Up to 2 revision rounds included.\",\n  \"id\": \"<32-byte-hex>\",\n  \"sig\": \"<64-byte-hex>\"\n}\n```\n\n### Example: SaaS Uptime SLA Template\n\nA SaaS provider advertising tiered uptime and latency guarantees:\n\n```json\n{\n  \"kind\": 30578,\n  \"pubkey\": \"<saas-provider-hex-pubkey>\",\n  \"created_at\": 1698780000,\n  \"tags\": [\n    [\"d\", \"saas-crm:sla_template:enterprise\"],\n    [\"t\", \"evidence-record\"],\n    [\"alt\", \"SLA template: CRM platform enterprise tier\"],\n    [\"evidence_type\", \"sla_template\"],\n    [\"sla_metric\", \"availability\", \"99.95\", \"percentage\", \"500000\", \"credit\"],\n    [\"sla_metric\", \"response_time\", \"500\", \"minutes\", \"100000\", \"credit\"],\n    [\"sla_threshold\", \"availability\", \"99.95\", \"percentage\"],\n    [\"sla_threshold\", \"response_time\", \"500\", \"minutes\"],\n    [\"sla_penalty\", \"availability\", \"500000\", \"credit\"],\n    [\"sla_penalty\", \"response_time\", \"100000\", \"credit\"],\n    [\"sla_measurement_window\", \"monthly\"],\n    [\"p\", \"<saas-provider-hex-pubkey>\"],\n    [\"currency\", \"USD\"],\n    [\"captured_at\", \"1698780000\"]\n  ],\n  \"content\": \"Enterprise SLA: 99.95% monthly availability, 500ms p95 API response time. Penalties as account credits against next billing cycle. Scheduled maintenance windows excluded.\",\n  \"id\": \"<32-byte-hex>\",\n  \"sig\": \"<64-byte-hex>\"\n}\n```\n\n### Tag Reference (SLA Template)\n\n| Tag                        | Required | Multiple | Description                                          |\n|----------------------------|----------|----------|------------------------------------------------------|\n| `d`                        | MUST     | No       | Addressable event identifier                         |\n| `t`                        | MUST     | No       | MUST be `\"evidence-record\"`                          |\n| `evidence_type`            | MUST     | No       | MUST be `\"sla_template\"`                             |\n| `sla_metric`               | MUST     | Yes      | Service level objective: `[\"sla_metric\", \"<type>\", \"<threshold>\", \"<unit>\", \"<penalty_amount>\", \"<penalty_type>\"]` |\n| `sla_threshold`            | SHOULD   | Yes      | Machine-parseable threshold: metric, value, unit     |\n| `sla_penalty`              | SHOULD   | Yes      | Machine-parseable penalty: metric, amount, type      |\n| `sla_measurement_window`   | SHOULD   | No       | Measurement period (`monthly`, `quarterly`, `yearly`)|\n| `p`                        | SHOULD   | No       | Provider pubkey                                      |\n| `currency`                 | SHOULD   | No       | Currency for penalty amounts                         |\n| `captured_at`              | SHOULD   | No       | When the template was authored                       |\n| `ref`                      | MAY      | No       | External reference (service tier code)               |\n| `expiration`               | MAY      | No       | Template validity period (NIP-40)                    |\n\n**Content:** Empty string, plain text describing additional terms, or NIP-44 encrypted JSON with extended SLA terms such as exclusion periods, force majeure clauses, or escalation procedures.\n\n---\n\n## Component 2: SLA Agreements with NIP-APPROVAL\n\n> **Independent value.** Even without NIP-DISPUTES, adding NIP-APPROVAL to the pattern gives you verifiable multi-party sign-off on SLA terms. Both parties have a cryptographically signed record that they agreed to specific thresholds, which is valuable for accountability regardless of whether formal dispute resolution exists.\n\nAgreeing to an SLA is a multi-party approval workflow. The proposer creates an Approval Gate (`kind:30570`) referencing the SLA template evidence record and listing the parties. Each party then responds with an Approval Response (`kind:30571`). The agreed SLA is the combination of the template plus all approval responses.\n\n### Step 1: Proposer Creates Approval Gate\n\nThe consumer (or provider) publishes an approval gate referencing the SLA template. The gate lists all parties who need to sign off.\n\n```json\n{\n  \"kind\": 30570,\n  \"pubkey\": \"<consumer-hex-pubkey>\",\n  \"created_at\": 1698780000,\n  \"tags\": [\n    [\"d\", \"engagement_api_hosting_007:gate:sla_agreement\"],\n    [\"t\", \"approval-gate\"],\n    [\"alt\", \"SLA agreement gate: API hosting engagement\"],\n    [\"gate_type\", \"approval\"],\n    [\"gate_authority\", \"<provider-hex-pubkey>\"],\n    [\"gate_authority\", \"<consumer-hex-pubkey>\"],\n    [\"gate_status\", \"pending\"],\n    [\"e\", \"<sla-template-event-id>\", \"wss://relay.example.com\"],\n    [\"sla_template_ref\", \"api-hosting:sla_template:premium\"],\n    [\"p\", \"<provider-hex-pubkey>\"],\n    [\"p\", \"<consumer-hex-pubkey>\"],\n    [\"effective_from\", \"1698780000\"],\n    [\"effective_until\", \"1730316000\"],\n    [\"expiration\", \"1699370000\"]\n  ],\n  \"content\": \"Proposing SLA agreement for API hosting engagement. Terms per premium SLA template.\",\n  \"id\": \"<32-byte-hex>\",\n  \"sig\": \"<64-byte-hex>\"\n}\n```\n\nThe `sla_template_ref` tag records the `d` tag value of the referenced `kind:30578` SLA template. The `e` tag points to the template's event ID for direct lookup. The `effective_from` and `effective_until` tags define the SLA validity window.\n\n### Step 2: Each Party Responds\n\nEach listed `gate_authority` publishes an approval response. The SLA is considered agreed once all required parties have responded with approval.\n\n```json\n{\n  \"kind\": 30571,\n  \"pubkey\": \"<provider-hex-pubkey>\",\n  \"created_at\": 1698781000,\n  \"tags\": [\n    [\"d\", \"engagement_api_hosting_007:gate:sla_agreement:response:<provider-hex-pubkey>\"],\n    [\"t\", \"approval-response\"],\n    [\"alt\", \"SLA agreement response: provider accepts terms\"],\n    [\"e\", \"<gate-event-id>\", \"wss://relay.example.com\"],\n    [\"decision\", \"approved\"],\n    [\"p\", \"<consumer-hex-pubkey>\"]\n  ],\n  \"content\": \"SLA terms accepted. Monitoring will commence from the effective date.\",\n  \"id\": \"<32-byte-hex>\",\n  \"sig\": \"<64-byte-hex>\"\n}\n```\n\n### Negotiating Modified Terms\n\nIf a party wants to negotiate different thresholds, they respond with `decision: revise` and include override metrics:\n\n```json\n{\n  \"kind\": 30571,\n  \"pubkey\": \"<provider-hex-pubkey>\",\n  \"created_at\": 1698781000,\n  \"tags\": [\n    [\"d\", \"engagement_api_hosting_007:gate:sla_agreement:response:<provider-hex-pubkey>\"],\n    [\"t\", \"approval-response\"],\n    [\"alt\", \"SLA agreement response: provider requests revision\"],\n    [\"e\", \"<gate-event-id>\", \"wss://relay.example.com\"],\n    [\"decision\", \"revise\"],\n    [\"sla_metric\", \"resolution_time\", \"72\", \"hours\", \"25000\", \"refund\"],\n    [\"revision_notes\", \"Requesting extended resolution time of 72 hours given scope\"],\n    [\"p\", \"<consumer-hex-pubkey>\"]\n  ],\n  \"content\": \"Resolution time of 48 hours is too tight for this engagement scope. Proposing 72 hours instead.\",\n  \"id\": \"<32-byte-hex>\",\n  \"sig\": \"<64-byte-hex>\"\n}\n```\n\nThe proposer then updates the gate (republishing `kind:30570` with the same `d` tag) incorporating the negotiated terms, and the approval cycle repeats until all parties approve.\n\n### Effective Metric Resolution\n\nWhen override `sla_metric` tags appear in the final approved gate, the effective metrics are resolved as:\n\n1. Start with all metrics from the referenced SLA template (`kind:30578`)\n2. For each override metric in the gate, replace the matching `sla_type` metric\n3. The resulting merged set is the effective SLA for the engagement\n\n```\neffective_metrics = template_metrics\nfor each override in gate.sla_metric:\n    effective_metrics[override.sla_type] = override\n```\n\n---\n\n## SLA Breach Reporting with NIP-EVIDENCE\n\n> **Uses the same component as templates.** Breach reports are also NIP-EVIDENCE records. If you have adopted NIP-EVIDENCE for SLA templates, you already have everything needed to record breaches -- no additional NIP required.\n\nAn SLA breach is evidence of a threshold violation. When a metric is breached, either party (or an automated monitoring system) publishes a `kind:30578` evidence record with `evidence_type: sla_breach`. This captures the specific metric violated, the expected threshold, the actual measured value, and the measurement timestamp.\n\n### Example: SaaS Availability Breach\n\n```json\n{\n  \"kind\": 30578,\n  \"pubkey\": \"<consumer-hex-pubkey>\",\n  \"created_at\": 1698795780,\n  \"tags\": [\n    [\"d\", \"engagement_saas_crm_012:evidence:sla_breach_001\"],\n    [\"t\", \"evidence-record\"],\n    [\"alt\", \"SLA breach: availability dropped to 99.2%\"],\n    [\"evidence_type\", \"sla_breach\"],\n    [\"sla_metric\", \"availability\"],\n    [\"sla_threshold\", \"availability\", \"99.95\", \"percentage\"],\n    [\"sla_actual_value\", \"99.2\"],\n    [\"sla_measurement_timestamp\", \"1698794400\"],\n    [\"severity\", \"major\"],\n    [\"e\", \"<gate-event-id>\", \"wss://relay.example.com\"],\n    [\"sla_template_ref\", \"saas-crm:sla_template:enterprise\"],\n    [\"p\", \"<provider-hex-pubkey>\"],\n    [\"p\", \"<consumer-hex-pubkey>\"],\n    [\"captured_at\", \"1698795780\"]\n  ],\n  \"content\": \"Availability dropped to 99.2% during March. 43 minutes of unplanned downtime recorded by monitoring system.\",\n  \"id\": \"<32-byte-hex>\",\n  \"sig\": \"<64-byte-hex>\"\n}\n```\n\n### Example: API Latency Breach\n\n```json\n{\n  \"kind\": 30578,\n  \"pubkey\": \"<consumer-hex-pubkey>\",\n  \"created_at\": 1698795780,\n  \"tags\": [\n    [\"d\", \"engagement_api_hosting_007:evidence:sla_breach_001\"],\n    [\"t\", \"evidence-record\"],\n    [\"alt\", \"SLA breach: p95 latency exceeded 500ms target\"],\n    [\"evidence_type\", \"sla_breach\"],\n    [\"sla_metric\", \"response_time\"],\n    [\"sla_threshold\", \"response_time\", \"500\", \"minutes\"],\n    [\"sla_actual_value\", \"847\"],\n    [\"sla_measurement_timestamp\", \"1698795780\"],\n    [\"severity\", \"major\"],\n    [\"e\", \"<gate-event-id>\", \"wss://relay.example.com\"],\n    [\"sla_template_ref\", \"api-hosting:sla_template:premium\"],\n    [\"p\", \"<provider-hex-pubkey>\"],\n    [\"p\", \"<consumer-hex-pubkey>\"],\n    [\"captured_at\", \"1698795780\"],\n    [\"ref\", \"INCIDENT-2026-0042\"]\n  ],\n  \"content\": \"API p95 latency measured at 847ms, exceeding the 500ms threshold. Measurement period: 1-31 March 2026.\",\n  \"id\": \"<32-byte-hex>\",\n  \"sig\": \"<64-byte-hex>\"\n}\n```\n\n### Example: Freelance Deadline Breach\n\n```json\n{\n  \"kind\": 30578,\n  \"pubkey\": \"<client-hex-pubkey>\",\n  \"created_at\": 1698795780,\n  \"tags\": [\n    [\"d\", \"engagement_freelance_029:evidence:sla_breach_001\"],\n    [\"t\", \"evidence-record\"],\n    [\"alt\", \"SLA breach: milestone delivery 3 days late\"],\n    [\"evidence_type\", \"sla_breach\"],\n    [\"sla_metric\", \"resolution_time\"],\n    [\"sla_threshold\", \"resolution_time\", \"14\", \"days\"],\n    [\"sla_actual_value\", \"17\"],\n    [\"sla_measurement_timestamp\", \"1698795780\"],\n    [\"severity\", \"minor\"],\n    [\"e\", \"<gate-event-id>\", \"wss://relay.example.com\"],\n    [\"p\", \"<freelancer-hex-pubkey>\"],\n    [\"p\", \"<client-hex-pubkey>\"],\n    [\"captured_at\", \"1698795780\"]\n  ],\n  \"content\": \"Milestone 2 (frontend prototype) delivered 3 days past the agreed 14-day deadline.\",\n  \"id\": \"<32-byte-hex>\",\n  \"sig\": \"<64-byte-hex>\"\n}\n```\n\n### Severity Levels\n\nApplications define their own severity thresholds. The following classifications are suggested starting points:\n\n| Severity   | Description                                                                      |\n|------------|----------------------------------------------------------------------------------|\n| `minor`    | Threshold exceeded by a small margin (e.g. response time 5% over limit)          |\n| `major`    | Significant breach (e.g. response time 50% over limit, or repeated minor breach) |\n| `critical` | Severe breach (e.g. complete service failure, extended outage)                    |\n\n### Tag Reference (SLA Breach)\n\n| Tag                          | Required | Multiple | Description                                           |\n|------------------------------|----------|----------|-------------------------------------------------------|\n| `d`                          | MUST     | No       | Unique per breach (append-only)                       |\n| `t`                          | MUST     | No       | MUST be `\"evidence-record\"`                           |\n| `evidence_type`              | MUST     | No       | MUST be `\"sla_breach\"`                                |\n| `sla_metric`                 | MUST     | No       | The breached metric type                              |\n| `sla_threshold`              | MUST     | No       | Expected threshold: metric, value, unit               |\n| `sla_actual_value`           | MUST     | No       | The actual measured value                             |\n| `sla_measurement_timestamp`  | MUST     | No       | Unix timestamp of the measurement or deadline         |\n| `severity`                   | MUST     | No       | `minor`, `major`, or `critical`                       |\n| `e`                          | SHOULD   | No       | Reference to the SLA agreement gate event             |\n| `sla_template_ref`           | SHOULD   | No       | `d` tag value of the referenced SLA template          |\n| `p`                          | SHOULD   | Yes      | Parties to notify                                     |\n| `captured_at`                | SHOULD   | No       | When the breach was detected                          |\n| `ref`                        | MAY      | No       | External reference (incident ticket, alert ID)        |\n| `file_hash`                  | MAY      | No       | Hash of supporting evidence file                      |\n\n**Content:** Plain text or NIP-44 encrypted JSON with breach details such as monitoring system output, timeline reconstruction, or supporting documentation.\n\n---\n\n## Component 3: Escalating Breaches with NIP-DISPUTES\n\n> **Independent value.** NIP-DISPUTES provides a structured mediation workflow for any contested claim. In the SLA context, it adds formal escalation when a breach report is disputed. Without it, breach resolution is left to the parties' own informal process, which may be perfectly adequate for many use cases.\n\nWhen a breach report is contested, either party can escalate by filing a Dispute Claim (`kind:7543`) from NIP-DISPUTES. The claim references both the breach evidence and the SLA agreement gate, enabling a mediator to review the full context.\n\n### Filing a Dispute Claim\n\n```json\n{\n  \"kind\": 7543,\n  \"pubkey\": \"<provider-hex-pubkey>\",\n  \"created_at\": 1698800000,\n  \"tags\": [\n    [\"p\", \"<consumer-hex-pubkey>\"],\n    [\"e\", \"<breach-evidence-event-id>\"],\n    [\"alt\", \"Dispute claim: contesting SLA availability breach\"],\n    [\"dispute_type\", \"quality\"],\n    [\"resolution_model\", \"mediator\"],\n    [\"mediator\", \"<mediator-pubkey>\"],\n    [\"amount_disputed\", \"10000\"],\n    [\"currency\", \"USD\"],\n    [\"ref\", \"engagement_api_hosting_007\"]\n  ],\n  \"content\": \"Disputing the availability breach report. Downtime was caused by a scheduled maintenance window that was communicated in advance and excluded under the SLA terms.\"\n}\n```\n\n### Supporting Evidence\n\nBoth parties submit additional evidence as `kind:30578` records referencing the dispute claim:\n\n```json\n{\n  \"kind\": 30578,\n  \"pubkey\": \"<provider-hex-pubkey>\",\n  \"created_at\": 1698801000,\n  \"tags\": [\n    [\"d\", \"engagement_api_hosting_007:evidence:dispute_support_001\"],\n    [\"t\", \"evidence-record\"],\n    [\"alt\", \"Dispute evidence: scheduled maintenance notification\"],\n    [\"evidence_type\", \"document\"],\n    [\"e\", \"<dispute-claim-event-id>\"],\n    [\"file_hash\", \"sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2\"],\n    [\"captured_at\", \"1698780000\"],\n    [\"p\", \"<consumer-hex-pubkey>\"]\n  ],\n  \"content\": \"Scheduled maintenance notification sent 7 days prior. See attached communication log.\"\n}\n```\n\n### Resolution\n\nThe mediator resolves the dispute via `kind:30545` (Dispute Resolution), ruling on whether the breach was valid and what penalty (if any) applies. Settlement can then proceed through whatever payment mechanism the parties have agreed on (e.g. NIP-ESCROW, NIP-INVOICING, or direct Lightning payment).\n\n---\n\n## SLA Monitoring Workflow\n\nThe following diagram shows the complete SLA lifecycle from template publication through breach detection and optional dispute escalation.\n\n\n![SLA Monitoring Workflow](https://raw.githubusercontent.com/forgesworn/nip-drafts/main/images/sla-1.png)\n\n```mermaid\nsequenceDiagram\n    participant Provider\n    participant Relay\n    participant Consumer\n    participant Monitor\n    participant Mediator\n\n    Note over Provider: Publish SLA Template\n    Provider->>Relay: kind:30578 (evidence_type: sla_template)\n\n    Note over Consumer: Propose SLA Agreement\n    Consumer->>Relay: kind:30570 (approval gate, refs template)\n    Relay->>Provider: notification\n\n    Note over Provider: Accept SLA Terms\n    Provider->>Relay: kind:30571 (decision: approved)\n    Relay->>Consumer: notification\n\n    Note over Provider,Consumer: SLA is now agreed\n\n    rect rgb(27, 45, 61)\n        Note over Monitor: Continuous Monitoring\n        Monitor->>Monitor: Track metrics against thresholds\n    end\n\n    alt Threshold Violated\n        Monitor->>Relay: kind:30578 (evidence_type: sla_breach)\n        Relay->>Provider: notification\n        Relay->>Consumer: notification\n\n        alt Breach Accepted\n            Note over Provider: Provider acknowledges breach\n            Note over Provider: Penalty settled per agreed terms\n        else Breach Contested\n            Provider->>Relay: kind:7543 (dispute claim)\n            Relay->>Consumer: notification\n            Relay->>Mediator: notification\n\n            Provider->>Relay: kind:30578 (dispute evidence)\n            Consumer->>Relay: kind:30578 (dispute evidence)\n\n            Mediator->>Relay: kind:30545 (resolution)\n            Relay->>Provider: notification\n            Relay->>Consumer: notification\n        end\n    end\n```\n\n---\n\n## REQ Filters\n\n> **Note:** Tags such as `evidence_type`, `sla_template_ref`, `gate_authority`, `gate_type`, and `gate_status` are multi-letter tags and therefore not relay-indexed per NIP-01. The filters below show the intended query semantics; clients MUST post-filter results client-side for multi-letter tag matches.\n\n### Discovering SLA Templates\n\nFind all SLA templates published by a specific provider:\n\n```json\n{\n  \"kinds\": [30578],\n  \"authors\": [\"<provider-hex-pubkey>\"],\n  \"#evidence_type\": [\"sla_template\"]\n}\n```\n\nFind all SLA templates for a specific service type by `d` tag prefix:\n\n```json\n{\n  \"kinds\": [30578],\n  \"#evidence_type\": [\"sla_template\"],\n  \"#d\": [\"api-hosting:sla_template:premium\"]\n}\n```\n\n### Discovering SLA Agreements\n\nFind all pending SLA approval gates for a party:\n\n```json\n{\n  \"kinds\": [30570],\n  \"#gate_authority\": [\"<party-hex-pubkey>\"],\n  \"#sla_template_ref\": [\"api-hosting:sla_template:premium\"]\n}\n```\n\nFind approval responses for a specific SLA gate:\n\n```json\n{\n  \"kinds\": [30571],\n  \"#e\": [\"<gate-event-id>\"]\n}\n```\n\n### Discovering SLA Breaches\n\nFind all breach reports for an engagement:\n\n```json\n{\n  \"kinds\": [30578],\n  \"#evidence_type\": [\"sla_breach\"],\n  \"#e\": [\"<gate-event-id>\"]\n}\n```\n\nFind all breach reports against a provider:\n\n```json\n{\n  \"kinds\": [30578],\n  \"#evidence_type\": [\"sla_breach\"],\n  \"#p\": [\"<provider-hex-pubkey>\"]\n}\n```\n\n### Discovering Related Disputes\n\nFind dispute claims referencing a breach:\n\n```json\n{\n  \"kinds\": [7543],\n  \"#e\": [\"<breach-evidence-event-id>\"]\n}\n```\n\n---\n\n## Validation Rules\n\nImplementations SHOULD enforce these rules when processing SLA-composed events. The rules use MUST to indicate what a conforming event looks like; applications decide how strictly to enforce them.\n\n### SLA Template Validation (kind:30578, evidence_type: sla_template)\n\n| Rule      | Requirement                                                                                    |\n|-----------|------------------------------------------------------------------------------------------------|\n| V-SLA-01  | MUST include at least one `sla_metric` tag                                                     |\n| V-SLA-02  | Each `sla_metric` tag MUST contain six elements: tag name, `sla_type`, `threshold_value`, `threshold_unit`, `penalty_amount`, and `penalty_type` |\n| V-SLA-03  | `sla_type` SHOULD be one of the defined metric types (applications MAY extend)                 |\n| V-SLA-04  | `threshold_unit` MUST be one of `minutes`, `hours`, `days`, or `percentage`                    |\n| V-SLA-05  | `penalty_type` SHOULD be one of `refund`, `credit`, or `stake_forfeit` (applications MAY extend) |\n| V-SLA-06  | `threshold_value` MUST be a positive numeric string                                            |\n| V-SLA-07  | `penalty_amount` MUST be a non-negative integer string                                         |\n| V-SLA-08  | `evidence_type` MUST be `\"sla_template\"`                                                       |\n\n### SLA Agreement Validation (kind:30570 + kind:30571)\n\n| Rule      | Requirement                                                                                    |\n|-----------|------------------------------------------------------------------------------------------------|\n| V-SLA-09  | Gate MUST include an `sla_template_ref` tag referencing a valid SLA template `d` tag           |\n| V-SLA-10  | Gate MUST include an `e` tag referencing the SLA template event                                |\n| V-SLA-11  | Override `sla_metric` tags MUST follow the same format as template metrics                     |\n| V-SLA-12  | `effective_from` MUST be a valid Unix timestamp when present                                   |\n| V-SLA-13  | `effective_until` MUST be greater than `effective_from` when both are present                   |\n| V-SLA-14  | All listed `gate_authority` pubkeys SHOULD respond with `decision: approved` for the SLA to be considered agreed |\n\n### SLA Breach Validation (kind:30578, evidence_type: sla_breach)\n\n| Rule      | Requirement                                                                                    |\n|-----------|------------------------------------------------------------------------------------------------|\n| V-SLA-15  | `evidence_type` MUST be `\"sla_breach\"`                                                         |\n| V-SLA-16  | `sla_metric` tag SHOULD match an `sla_type` defined in the referenced template                 |\n| V-SLA-17  | `sla_threshold` tag MUST be present with metric name, value, and unit                          |\n| V-SLA-18  | `sla_actual_value` MUST be present                                                             |\n| V-SLA-19  | `sla_measurement_timestamp` MUST be a valid Unix timestamp                                     |\n| V-SLA-20  | `severity` MUST be one of `minor`, `major`, or `critical`                                      |\n\n---\n\n## Security Considerations\n\n### Fraudulent Breach Claims\n\nA consumer could publish fraudulent breach evidence to trigger unwarranted penalties. Applications SHOULD validate breach claims against objective evidence before executing penalties. Implementations SHOULD require `file_hash` tags on breach evidence and verify that the evidence supports the claimed breach. For automated monitoring, the monitoring system's pubkey SHOULD be pre-authorised in the SLA agreement gate.\n\n### SLA Template Manipulation\n\nA provider could publish a revised SLA template after an agreement gate is approved, weakening the committed thresholds. The approval gate records the specific `sla_template_ref` at the time of agreement. Clients MUST evaluate SLA compliance against the template version that was in effect when the approval gate was approved, not the current version. Implementations SHOULD cache the template state at agreement time.\n\n### Automated Monitor Trust\n\nAutomated monitoring systems that publish breach evidence SHOULD be identified by a recognised pubkey that both parties have agreed to trust. The approval gate content MAY designate the authorised monitoring system pubkey. Clients SHOULD treat breach evidence from unrecognised publishers with caution.\n\n### Collusion Between Parties\n\nIn peer-to-peer engagements, parties could collude to manufacture breach evidence for accounting fraud. Relay operators MAY apply rate limiting on SLA breach evidence events and flag patterns of frequent breaches between the same party pairs.\n\n### Breach Timing Disputes\n\nDisagreements over whether a deadline was actually missed depend on accurate timestamps. All breach evidence carries `sla_measurement_timestamp` and `captured_at` tags for transparency. Applications SHOULD cross-reference these against objective sources (monitoring systems, relay `created_at` timestamps) to validate timing claims.\n\n---\n\n## Use Cases\n\n### API Hosting and Infrastructure\n\nA cloud hosting provider publishes a `kind:30578` SLA template advertising 99.9% availability and < 500ms response time guarantees. A client subscribing to the service proposes a `kind:30570` approval gate referencing the template. When automated monitoring detects downtime exceeding the threshold, a `kind:30578` breach evidence record is published. The provider acknowledges the breach and issues account credits per the agreed penalty terms.\n\n### SaaS Uptime Guarantees\n\nA SaaS application provider commits to tiered availability (99.95% for enterprise, 99.5% for standard). Each tier is a separate `kind:30578` SLA template. Enterprise customers bind approval gates referencing the premium template. Monthly availability calculations drive automated breach detection. Penalties are applied as credits against the next billing cycle.\n\n### Freelance Milestone Contracts\n\nA freelancer commits to delivering project milestones by agreed dates. Each milestone deadline is encoded as a `resolution_time` metric in the SLA template. The client proposes an approval gate with the specific milestones and dates. Late delivery triggers a breach evidence record, and the agreed penalty (e.g. a percentage discount on the final invoice) is settled between the parties.\n\n### API Service Rate Limits and Latency\n\nAn API provider guarantees rate limits (10,000 requests/minute) and latency targets (p95 < 200ms) to paying consumers. The SLA template encodes these as `availability` and `response_time` metrics. Automated monitoring publishes breach evidence when thresholds are exceeded. The consumer can present the signed breach record when requesting penalty credits.\n\n### Consulting and Professional Services\n\nA consultant commits to 4-hour first-contact response and 48-hour resolution for client queries. The SLA template encodes these as `first_contact` and `resolution_time` metrics. When the consultant misses a response window, the client publishes breach evidence. If the consultant disputes the timing (e.g. the query was sent outside business hours), they escalate via NIP-DISPUTES and a mediator rules on the claim.\n\n---\n\n## Implementation Notes\n\n### SLA Compliance Tracking\n\nClients tracking SLA compliance SHOULD:\n\n1. Subscribe to `kind:30570` gates with `sla_template_ref` tags for active engagements\n2. Resolve the referenced `kind:30578` SLA template to obtain the full metric set\n3. Apply any override `sla_metric` tags from the approval gate\n4. Monitor service metrics against SLA thresholds\n5. Alert when thresholds approach (e.g. 80% of response time elapsed)\n6. Publish `kind:30578` breach evidence when thresholds are violated\n\n### Automated SLA Monitoring\n\nImplementations MAY deploy automated monitoring systems that:\n\n- Subscribe to relevant events for engagements with approved SLA gates\n- Track elapsed time against response time and resolution time thresholds\n- Calculate rolling availability and on-time rate metrics per measurement period\n- Automatically publish `kind:30578` breach evidence when thresholds are violated\n- The monitoring system SHOULD use a dedicated keypair identified in the SLA approval gate\n\n### Filing Deadlines and Escalation\n\nThis guide does not prescribe specific filing deadlines or escalation timeframes. Applications define their own rules for:\n\n- How long after a threshold violation a breach report may be filed\n- Whether escalation to NIP-DISPUTES is automatic or manual\n- What penalty calculations apply for different severity levels\n- Whether penalties compound for repeated breaches within a measurement period\n\nThese decisions depend on the specific service context and the agreement between parties.\n\n---\n\n## Test Vectors\n\n### Minimal Valid SLA Template\n\n```json\n{\n  \"kind\": 30578,\n  \"pubkey\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2\",\n  \"created_at\": 1698780000,\n  \"tags\": [\n    [\"d\", \"test:sla_template:minimal\"],\n    [\"t\", \"evidence-record\"],\n    [\"evidence_type\", \"sla_template\"],\n    [\"sla_metric\", \"availability\", \"99.9\", \"percentage\", \"1000\", \"credit\"]\n  ],\n  \"content\": \"\"\n}\n```\n\nThis is valid because it includes the three required tags (`d`, `t` with `evidence-record`, `evidence_type` with `sla_template`) and at least one `sla_metric` with all six elements.\n\n### Invalid: Missing sla_metric\n\n```json\n{\n  \"kind\": 30578,\n  \"pubkey\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2\",\n  \"created_at\": 1698780000,\n  \"tags\": [\n    [\"d\", \"test:sla_template:invalid\"],\n    [\"t\", \"evidence-record\"],\n    [\"evidence_type\", \"sla_template\"]\n  ],\n  \"content\": \"\"\n}\n```\n\nInvalid: violates V-SLA-01 (no `sla_metric` tag).\n\n### Invalid: Incomplete sla_metric\n\n```json\n{\n  \"kind\": 30578,\n  \"pubkey\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2\",\n  \"created_at\": 1698780000,\n  \"tags\": [\n    [\"d\", \"test:sla_template:invalid_metric\"],\n    [\"t\", \"evidence-record\"],\n    [\"evidence_type\", \"sla_template\"],\n    [\"sla_metric\", \"availability\", \"99.9\"]\n  ],\n  \"content\": \"\"\n}\n```\n\nInvalid: violates V-SLA-02 (`sla_metric` has 3 elements instead of 6).\n\n### Minimal Valid SLA Breach\n\n```json\n{\n  \"kind\": 30578,\n  \"pubkey\": \"b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3\",\n  \"created_at\": 1698795780,\n  \"tags\": [\n    [\"d\", \"test:evidence:sla_breach_001\"],\n    [\"t\", \"evidence-record\"],\n    [\"evidence_type\", \"sla_breach\"],\n    [\"sla_metric\", \"availability\"],\n    [\"sla_threshold\", \"availability\", \"99.9\", \"percentage\"],\n    [\"sla_actual_value\", \"98.5\"],\n    [\"sla_measurement_timestamp\", \"1698794400\"],\n    [\"severity\", \"major\"]\n  ],\n  \"content\": \"\"\n}\n```\n\nThis is valid because it includes all required breach tags: `evidence_type`, `sla_metric`, `sla_threshold`, `sla_actual_value`, `sla_measurement_timestamp`, and `severity`.\n\n---\n\n## Composing NIPs\n\n| SLA Function          | Composed From                                      | Kind(s)          |\n|-----------------------|----------------------------------------------------|------------------|\n| SLA Template          | NIP-EVIDENCE (`evidence_type: sla_template`)       | `kind:30578`     |\n| SLA Agreement         | NIP-APPROVAL (gate + responses)                    | `kind:30570` + `kind:30571` |\n| SLA Breach Report     | NIP-EVIDENCE (`evidence_type: sla_breach`)         | `kind:30578`     |\n| Breach Dispute        | NIP-DISPUTES (claim + resolution)                  | `kind:7543` + `kind:30545` |\n| Dispute Evidence      | NIP-EVIDENCE (`evidence_type: document`, etc.)     | `kind:30578`     |\n| Penalty Settlement    | Application-specific (e.g. NIP-ESCROW, NIP-INVOICING, Lightning) | (see those NIPs) |\n\n---\n\n## Dependencies\n\n* [NIP-EVIDENCE](NIP-EVIDENCE.md): Timestamped evidence recording (`kind:30578`) for SLA templates and breach reports\n* [NIP-APPROVAL](NIP-APPROVAL.md): Multi-party approval gates (`kind:30570` + `kind:30571`) for SLA agreements\n* [NIP-DISPUTES](NIP-DISPUTES.md): Dispute resolution (`kind:7543` + `kind:30545`) for contested breaches\n* [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md): Basic protocol flow, addressable events\n* [NIP-40](https://github.com/nostr-protocol/nips/blob/master/40.md): Expiration timestamps (template and agreement validity)\n* [NIP-44](https://github.com/nostr-protocol/nips/blob/master/44.md): Versioned encrypted payloads (private SLA terms)\n\n> **Note on draft dependencies.** NIP-EVIDENCE, NIP-APPROVAL, and NIP-DISPUTES are currently draft NIPs. This composition guide describes the intended interaction pattern. Implementers should track the status of these component NIPs and adjust their implementations as those specifications evolve.\n\n## Informative References\n\n* [ITIL 4 -- Service Level Management](https://www.axelos.com/best-practice-solutions/itil): ITIL SLA framework; the industry standard for service level management taxonomy. NIP-SLA metric types (`response_time`, `resolution_time`, `availability`, `first_contact`, `on_time_rate`) align with ITIL service level objective categories. Implementations targeting enterprise compatibility MAY map NIP-SLA metrics to ITIL SLO definitions.\n\n## Reference Implementation\n\nNo public reference implementation exists yet. Implementors SHOULD refer to the kind definitions and tag conventions above.\n\nA minimal implementation requires:\n\n1. A Nostr client that supports addressable event publishing.\n2. SLA template rendering logic: parsing `sla_metric` tags from `kind:30578` evidence records with `evidence_type: sla_template`.\n3. Agreement management (optional): creating `kind:30570` approval gates referencing templates, collecting `kind:30571` responses, and resolving effective metrics (template + overrides).\n4. Breach detection (optional): monitoring service metrics against SLA thresholds and publishing `kind:30578` breach evidence when thresholds are violated.\n5. Dispute escalation (optional): filing `kind:7543` dispute claims when breaches are contested and resolving via `kind:30545`.","sig":"412720d116a018047482ad4568ed5e2419fd29dcb335e345cd2c75e2f2b717c3513c07b7baac666575ec868671a9e1e43d986ef7f37141fe1f644cd122fef5a4"}