Covenants

What this page explains#

Explain covenant state, lineage, introspection, covenant IDs, and output constraints with clear implementation and proposal boundaries. This page sits in Covenants. It gives the topic a plain-language handle first, then shows the working idea, the mechanism, the source trail, and any limits that still matter. This category keeps the UTXO model visible while explaining stateful patterns. A covenant does not mutate account storage in place; it validates a spend and the successor output that carries the next state.

The writing follows a simple Kaspa documentation pattern: answer the practical question first, then link outward for details. The closest public sources for this page are DOC-TOCCATA-COVENANT-STATE, RK-COVENANTS, RK-COVENANT-ID, RK-SIGHASH, RK-TX-VALIDATION. Local notes can help choose what to explain, but public-facing references resolve to upstream websites, repositories, papers, release pages, or docs.

How to think about it#

The practical model starts by naming the layer that owns the topic: wallet use, node operation, consensus, transaction validation, Toccata script behavior, tooling, or research. From there, the page shows which public source can support the explanation and where the explanation becomes incomplete.

For Covenants, the model is built around these anchors: Covenants are taught as UTXO successor validation, not account-style mutable storage; Spent output, script context, covenant ID, successor output, and indexer head tracking are distinct review surfaces; Local dice or RollRegistry lessons can teach patterns only after upstream source cross-check; Negative cases are required before covenant design claims become stronger wording; Public pages cite covenant docs, txscript, transaction validation, and accepted-state evidence. This model is useful, but it does not encode every constant, branch, error type, or edge case. Those details belong in the source path and the source notes.

How it works#

1. Covenants are taught as UTXO successor validation, not account-style mutable storage. Covenant mechanics stay anchored in UTXOs, but the page's main question is state continuity. The current output is spent, the script inspects transaction context, and the successor output must carry the allowed next state. Covenant IDs, authorization groups, script context, and indexer head tracking are helper surfaces; they do not replace the actual successor validation rule.

2. Spent output, script context, covenant ID, successor output, and indexer head tracking are distinct review surfaces. Developer integration pages explain an interface by naming the source object behind it. API, RPC, wRPC, SDK, wallet, and indexer surfaces are useful only when they preserve the fields and evidence that the protocol layer actually defines. Accepted-state evidence, replay behavior, schema choices, and endpoint disagreement must be checked separately.

3. Local dice or RollRegistry lessons can teach patterns only after upstream source cross-check. Covenant mechanics stay anchored in UTXOs, but the page's main question is state continuity. The current output is spent, the script inspects transaction context, and the successor output must carry the allowed next state. Covenant IDs, authorization groups, script context, and indexer head tracking are helper surfaces; they do not replace the actual successor validation rule.

4. Negative cases are required before covenant design claims become stronger wording. Covenant mechanics stay anchored in UTXOs, but the page's main question is state continuity. The current output is spent, the script inspects transaction context, and the successor output must carry the allowed next state. Covenant IDs, authorization groups, script context, and indexer head tracking are helper surfaces; they do not replace the actual successor validation rule.

5. Public pages cite covenant docs, txscript, transaction validation, and accepted-state evidence. Covenant mechanics stay anchored in UTXOs, but the page's main question is state continuity. The current output is spent, the script inspects transaction context, and the successor output must carry the allowed next state. Covenant IDs, authorization groups, script context, and indexer head tracking are helper surfaces; they do not replace the actual successor validation rule.

This mechanism section keeps the covenant rule, the spent output, the successor output, covenant ID, authorization context, and indexer responsibility separate. Local case studies stay local experience unless rewritten against public sources.

How to check it#

When using this page for covenant design, verify the spent output, script context, authorization rule, successor output, state encoding, and negative cases separately. Indexer head tracking and local design notes are supporting evidence, not replacements for the covenant rule.

Expanded Category Guide#

This category carries covenant concepts and case studies. It should keep covenant state, IDs, successor outputs, introspection, indexer responsibility, local experience, and production-readiness boundaries visible.

Use this category as a curated path. Start with the category README to understand the boundary, then read the mechanism pages, then follow source-path or open-gap pages for claims that need stronger evidence. If a page contains needs checking rows, keep those claims visibly unresolved until a reader reads the cited public source directly.

The category should not be treated as final authority by folder name alone. The authority comes from page Source Notes, Source Lists, public URLs, and the status labels attached to each claim.

Related Pages#

• covenants
• covenants-and-state

Topic pages#

• Covenants And State: A covenant is taught as a script-controlled UTXO that validates a spend and the next output, not as account storage mutated in place.
• Successor Output Validation: Successor validation is the covenant safety center: the script must check what the next output is allowed to be.
• Covenant IDs And Lineage: Covenant ID is lineage evidence, not the whole app rule.
• Auth Groups Vs Covenant Groups: Auth groups and covenant groups answer different questions and must not be collapsed.
• Introspection Opcodes And Script Context: Introspection lets script logic inspect transaction context, but every inspected field needs a source-backed meaning.
• Covenant Design Patterns: Design patterns help readers recognize covenant shapes before building them.
• Covenant Head Indexer Starter: A covenant app needs a reliable way to find the current head after accepted activity and restart.
• Counter Covenant Starter: A counter covenant starter is a teaching pattern to verify, not an upstream-endorsed production recipe. It introduces successor checks, negative tests, and state encoding while keeping every concrete rule source-gated.
• Vault Covenant Starter: A vault starter is design-question guidance until a concrete upstream vault implementation, wallet flow, and accepted-evidence path are verified.
• Dice RollRegistry Case Study: The local dice/RollRegistry experience can teach reusable checks, but it is labeled local experience and cited only through public mechanisms.

Topic notes#

This category is accepted when the subpages explain the actual topics, not merely the source links. Each subpage carries public source IDs, claim labels, Open Questions, and a path from first contact into source review.