Skip to content

ADR 0033 — UTXO token vault + MÓDULO LICENSE.Art licence envelope

  • Status: Accepted (formalized 2026-05-12 with v3.7.0 — Wave 8 + 8+1 shipping)
  • Date: 2026-05-11 (locked), 2026-05-12 (formalized)
  • Deciders: TLSStress.Art project
  • Targets: v3.7.0 (vault + envelope shipping); v5.x (token economy MGMT-plane payments)
  • Patent claim family: claim #25 — UTXO note-not-balance licence accounting + cross-language signed envelope as ZTP-prem camadas 8 + 9
  • Umbrella ADR: 0026

Context

A traditional software licence is a balance — the customer has "N seats" or "M hours" and the licence checker decrements. That model loses to insider operators trivially: backup the licence state, run the seats, restore the licence state, run them again. The check happens on a number that the attacker controls.

We need an accounting model where:

  1. State is non-fungible — restoring a backup doesn't restore spend
  2. Spend is observable — every consumption is a distinct event the customer (and we) can audit
  3. Distribution is verifiable — the customer's bench can prove it received tokens from a specific signed mint event
  4. Air-gap-survivable — the customer's bench can spend tokens without round-tripping to a cloud service for every check

UTXO (Unspent Transaction Output) accounting — borrowed from Bitcoin/Cardano — solves all four:

  • Tokens are notes, each with a unique identifier
  • Spending a note destroys it and creates change notes (the change carries a new identifier; the old one cannot be re-spent because the bench enforces no-double-spend per note ID)
  • A backup-then-restore restores the spent notes' state, but the restored bench's successor notes don't validate because the chain head moved on

Bench-side, this needs to be wrapped in a tamper-resistant envelope — and the envelope has to verify offline because the customer DC may be air-gapped.

Decision

Adopt UTXO accounting with a signed licence envelope:

  • MÓDULO LICENSE.Art is the customer-visible licence façade. Every operation that costs tokens (each test run, each persona spin-up, each MGMT-plane API call in v5.x+) destroys a note + emits a change note.

  • Vault stores the unspent notes locally on the bench. It's a signed JSON document (envelope form below) wrapped in the sealed audit hash-chain (ADR 0029) so any tampering breaks the chain visibly.

  • Envelope uses the cross-language canonical encoding from ADR 0027 — RSA-4096-PSS-SHA-384 (real) + ML-DSA-65 (stub today, stdlib in Go 1.27). The Cloud HSM signs the envelope at mint time; the bench verifies offline.

  • Note format: each note carries (id, amount, mint-event-anchor, not-before, not-after, scope-tags). Bench-local accounting validates not-before/after and refuses to spend a note whose mint-event-anchor isn't in the verified chain.

  • Refill flow: bench writes a refill receipt into the sealed audit log; Cloud HSM signs a new mint envelope; envelope lands on the bench (via release-feed, OBP egress, or operator USB hand-carry for air-gap deploys); vault validates + ingests the new notes.

Tier classification: vault, envelope verifier, and the canonical encoder are Tier B (garble-obfuscated, customer never sees the source). The dashboard's licence-card surface + the audit-trail reader are Tier A (open, customer-auditable). The split is exactly the ZTP-prem story: customer audits the posture, can't recompile the enforcement.

Consequences

Pros - Restore-after-backup attack is structurally defeated, not policy- defeated - Every consumption is recorded — usage telemetry doubles as audit-of-record - Foundation for the v5.x+ token economy MGMT-plane (each cloud service is priced as a token cost; offline mints work via OBP) - Cross-language envelope (ADR 0027) means the same primitives guard the licence and the bench's own audit anchor

Cons - Operationally heavier than balance-style: customers needs to refill, not just renew. We mitigate with auto-refill in v5.x+ for cloud-connected deploys + bulk pre-minted batches for air-gap - The vault file is sensitive — its loss costs the customer their unspent notes. We cope with deterministic re-mint of the outstanding-but-unspent set against the mint-event-anchor chain (the Cloud HSM can reissue exactly the notes that haven't been reported as spent) - Token economy MGMT-plane (v5.x+) is a separate substantial product decision; this ADR commits to the accounting model, not the pricing model

Reversibility: low for the accounting model (every customer in v3.7.0+ has UTXO state in their vault). High for the pricing (token costs are configurable + not part of the patent claim).

  • dashboard/src/lib/license/ — vault + envelope verifier
  • pkg/ztp-prem-signctl/ — Cloud HSM signer
  • platform/ztp-prem/CLOUD-HSM-KEY-CUSTODY.md — Cloud HSM custody flow
  • ADR 0026 — ZTP-prem umbrella
  • ADR 0027 — cross-language signing contract (envelope substrate)
  • ADR 0028 — Tier A/B partition (vault is Tier B)
  • ADR 0029 — sealed audit hash-chain (refill + spend events)
  • Related future work: discuss_token_economy_2026_05_10 — v5.x+ MGMT-plane pricing

Last verified against shipping code: v3.7.0 (2026-05-12).