Guide
Improvement proposals (TIPs)
How to write a Tenrai Improvement Proposal. The header fields, the required sections, the review stages and the principles every proposal has to meet.
A Tenrai Improvement Proposal (TIP) describes a change to the protocol, the network or a standard API, in enough detail that others can review and implement it. Anyone may write one.
Conventions that software follows by choice, without a change to the protocol, are not TIPs. They are TCCs. How an accepted rule change reaches the network is described in Protocol upgrades.
Proposals are filed in the tenrai-tip repository, which also holds the template below as TEMPLATE.md.
Header
| Field | Content |
|---|---|
| TIP | The number, such as TIP-0001, given when the draft moves to Review |
| Title | Short, descriptive name |
| Author | The authors and contributors |
| Status | Draft, Review, Accepted, Rejected, Withdrawn or Final |
| Type | Consensus, Networking, API or Standards |
| Created | The date of the first draft |
Sections
| Section | Content |
|---|---|
| Abstract | A short summary of the proposed improvement |
| Motivation | The problem, why it matters, and why the proposed change is necessary |
| Specification | The detailed technical description: algorithms, rules, parameters, data structures and expected behavior where they apply |
| Rationale | The design decisions, the alternatives considered and the trade-offs |
| Backward compatibility | Compatibility with existing nodes, wallets, applications and earlier protocol versions, and whether a hardfork or another coordinated upgrade is required |
| Security considerations | Possible vulnerabilities, abuse scenarios and consensus risks, with the proposed mitigations |
| Implementation and testing | Implementation requirements, test cases and available reference code |
Template
# TIP-XXXX: Title
| | |
| --- | --- |
| TIP | TIP-XXXX, given when the draft moves to Review |
| Title | A short, descriptive name |
| Author | Names of the authors and contributors |
| Status | Draft |
| Type | Consensus, Networking, API or Standards |
| Created | YYYY-MM-DD |
## Abstract
## Motivation
## Specification
## Rationale
## Backward compatibility
## Security considerations
## Implementation and testingReview
| Stage | Meaning |
|---|---|
| Draft | The author publishes the proposal as tips/tip-draft-<short-name>.md in a pull request |
| Review | Developers and the community discuss it; the author revises it. The proposal gets its number |
| Accepted | Approved for implementation |
| Final | Specified in full and, where it applies, implemented and activated |
| Rejected | Not taken up |
| Withdrawn | Given up by its author, possible at any stage |
Rules
- Proposals are public and open to discussion.
- A consensus change specifies deterministic behavior and the height or condition at which it activates.
- Accepting a TIP does not change the network. A rule change takes effect only when node operators run a release that schedules it.