Telcoin Network Improvement Proposals (TNIPs)

The goal for TNIPs is to standardize and provide high-quality documentation for Telcoin Network itself and conventions built upon it. This repository tracks past and ongoing improvements to Telcoin Network in the form of Telcoin Network Improvement Proposals (TNIPs). TNIP-1 governs how TNIPs are published.

Telcoin Network is still under heavy development. The proposals outlined here guide and document the progress towards mainnet.

The status page tracks and lists TNIPs, which can be divided into the following categories:

Before you write a TNIP, ideas MUST be thoroughly discussed on Telcoin Network Forum. Once consensus is reached in the community, thoroughly read and review TNIP-1, which describes the TNIP process.

Please note that this repository is for documenting standards and not for help implementing them. These types of inquiries should be directed to the Telcoin Network Discord Channel. For specific questions and concerns regarding TNIPs, it’s best to comment on the relevant discussion thread of the TNIP denoted by the discussions-to tag in the TNIP’s preamble.

Preferred Citation Format

The canonical URL for a TNIP that has achieved draft status at any point is at https://tnips.telcoin.network/. For example, the canonical URL for TNIP-1 is https://tnips.telcoin.network/TNIPS/tnip-1.

Consider any document not published at https://tnips.telcoin.network/ as a working paper. Additionally, consider published TNIPs with a status of “draft”, “review”, or “last call” to be incomplete drafts, and note that their specification is likely subject to change.

Validation and Automerging

The CI is incomplete, but included here to document future ambitions.

All pull requests in this repository must pass automated checks before they can be automatically merged:

  • TNIP-1 rules are enforced using tnipv1
  • Spelling is enforced with CodeSpell1
    • False positives sometimes occur. When this happens, please submit a PR editing .codespell-whitelist and ONLY .codespell-whitelist
  • Markdown best practices are checked using markdownlint1

It is possible to run the TNIP validator locally:

cargo install tnipv
tnipv <INPUT FILE / DIRECTORY>

Build the status page locally

The TNIP book is built using rust.

The mdbook compiles the binary in process-frontmatter. This preprocessor looks parses content between “—” to create the preamble for each TNIP.

Install prerequisites

  1. Open Terminal.

  2. Check whether you have mdbook installed (requires rust).

    mdbook --version

  3. If you don’t have mdbook installed, install mdbook. If you don’t have rust, it’s recommended to install using rustup.

  4. Install mdbook with cargo (shipped with rust):

    cargo install mdbook

Build the book locally

  1. Compile the markdown, start the server, and open the page:

    mdbook serve --open

More information on mdbook here.

This document was derived heavily from Ethereum’s EIP repo.

1

https://github.com/telcoin-network/TNIPs/blob/main/.github/workflows/ci.yml

TNIPs

Telcoin Network Improvement Proposals are designed for transparent community discourse surround Telcoin Network’s protocol.

titleTNIP Purpose and Guidelines
descriptionGuidelines for TNIP process.
authorgrant (@grantkee) <grant@telcoin.org>, et al.
statusLiving
created2024-07-30

Guidelines for TNIP Process

What is a TNIP?

TNIP stands for Telcoin Network Improvement Proposal. A TNIP is a design document providing information to the Telcoin Network community, or describing a new feature for Telcoin Network or its processes or environment. The TNIP should provide a concise technical specification of the feature and a rationale for the feature. The TNIP author is responsible for building consensus within the community and documenting dissenting opinions.

TNIP Rationale

creating change to trigger CI

TNIPs are intended to be the primary mechanism for proposing new features, for collecting community technical input on an issue, and for documenting the design decisions that have gone into Telcoin Network. TNIPs are maintained as text files in a versioned repository, so their revision history is the historical record of the feature proposal.

For Telcoin Network implementers, TNIPs are a convenient way to track the progress of their implementation. Ideally each implementation maintainer would list the TNIPs that they have implemented. This will give end users a convenient way to know the current status of a given implementation or library.

TNIP Types

There are three types of TNIP:

  • A Standards Track TNIP describes any change that affects most or all Telcoin Network implementations, such as: a change to the network protocol, a change in block or transaction validity rules, proposed application standards/conventions, or any change or addition that affects the interoperability of applications using Telcoin Network. Furthermore, Standards Track TNIPs are broken down into the following categories:

    • Core: improvements requiring a consensus fork, as well as changes that are not necessarily consensus critical but may be relevant to “core dev” discussions.
    • Networking: includes improvements around devp2p and Light Telcoin Network Subprotocol, as well as proposed improvements to network protocol specifications.
    • Interface: includes improvements around around client API/RPC specifications and standards, as well as language-level standards like method names and contract ABIs.

  • A Meta EIP describes a process surrounding Telcoin Network or proposes a change to (or an event in) a process. Process TNIPs are like Standards Track TNIPs but apply to areas other than the Telcoin Network protocol itself. They may propose an implementation, but not to Telcoin Network’s codebase; they often require community consensus; unlike Informational TNIPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Telcoin Network development. Any meta-TNIP is also considered a Process TNIP.

  • An Informational TNIP describes an Telcoin Network design issue, or provides general guidelines or information to the Telcoin Network community, but does not propose a new feature. Informational TNIPs do not necessarily represent Telcoin Network community consensus or a recommendation, so users and implementers are free to ignore Informational TNIPs.

It is highly recommended that a single TNIP contain a single key proposal or new idea. TNIPs that focus on a pariticular issue are more likely to become integrated into the protocol.

A TNIP must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. The enhancement must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate the protocol unduly.

TNIP Work Flow

Creating a TNIP

Before you begin writing a formal TNIP, you should vet your idea. Ask the Telcoin Network community first if an idea is original to avoid wasting time on something that will be rejected based on prior research. It is thus recommended to open a discussion thread on the Telcoin Network forum to do this.

Once the idea has been vetted, your next responsibility is to present (by means of a TNIP) the idea to the reviewers and all interested parties, invite editors, developers, and the community to give feedback on the aforementioned channels. You should try and gauge whether the interest in your TNIP is commensurate with both the work involved in implementing it and how many parties will have to conform to it. The work required for implementing a core TNIP is significant and the TNIP will need sufficient interest from the Telcoin Network protocol team. Negative community feedback is taken into consideration and may prevent your TNIP from moving past the Draft stage.

TNIP Process

The following is the standardization process for all TNIPs in all tracks:

Idea - An idea that is pre-draft. This is not tracked within the TNIP Repository.

Draft - The first formally tracked stage of a TNIP in development. A TNIP is merged by a TNIP Editor into the TNIP repository when properly formatted.

Review - A TNIP Author marks a TNIP as ready for and requesting Peer Review.

Last Call - This is the final review window for a TNIP before moving to Final. A TNIP editor will assign Last Call status and set a review end date (last-call-deadline), typically 14 days later.

If this period results in necessary normative changes it will revert the TNIP to Review.

Final - This TNIP represents the final standard. A Final TNIP exists in a state of finality and should only be updated to correct errata and add non-normative clarifications.

A PR moving a TNIP from Last Call to Final SHOULD contain no changes other than the status update. Any content or editorial proposed change SHOULD be separate from this status-updating PR and committed prior to it.

Stagnant - Any TNIP in Draft or Review or Last Call if inactive for a period of 6 months or greater is moved to Stagnant. A TNIP may be resurrected from this state by Authors or TNIP Editors through moving it back to Draft or its earlier status. If not resurrected, a proposal may stay forever in this status.

TNIP Authors are notified of any algorithmic change to the status of their TNIP

Withdrawn - The TNIP Author(s) have withdrawn the proposed TNIP. This state has finality and can no longer be resurrected using this TNIP number. If the idea is pursued at later date it is considered a new proposal.

Living - A special status for TNIPs that are designed to be continually updated and not reach a state of finality. This includes most notably TNIP-1.

What belongs in a successful TNIP?

Each TNIP should have the following parts:

  • Preamble - RFC 822 style headers containing metadata about the TNIP, including the TNIP number, a short descriptive title (limited to a maximum of 44 characters), a description (limited to a maximum of 140 characters), and the author details. Irrespective of the category, the title and description should not include TNIP number.
  • Abstract - Abstract is a multi-sentence (short paragraph) technical summary. This should be a very terse and human-readable version of the specification section. Someone should be able to read the abstract and get the gist of what this specification does.
  • Motivation - The motivation section is critical for TNIPs that want to change the Telcoin Network protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the TNIP solves. This section may be brief if the motivation is evident.
  • Specification - The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed.
  • Rationale - The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other protocols. The rationale should discuss important objections or concerns raised during discussion around the TNIP.
  • Backwards Compatibility (optional) - All TNIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their consequences. The TNIP must explain how the author proposes to deal with these incompatibilities. This section may be omitted if the proposal does not introduce any backwards incompatibilities, but this section must be included if backward incompatibilities exist.
  • Test Cases - Test cases for an implementation are mandatory for TNIPs. Tests should either be inlined in the TNIP as data (such as input/expected output pairs) or listed as test cases with outcomes.
  • Reference Implementation (optional) - An optional section that contains a reference/example implementation that facilitates deeper understanding. This section may be omitted for all TNIPs.
  • Security Considerations - All TNIPs must contain a section that discusses the security implications/considerations relevant to the proposed change. Include information that might be important for security discussions, surfaces risks and can be used throughout the life-cycle of the proposal. E.g. include security-relevant design decisions, concerns, important discussions, implementation-specific guidance and pitfalls, an outline of threats and risks and how they are being addressed. TNIP submissions missing the “Security Considerations” section will be rejected. A TNIP cannot proceed to status “Final” without a Security Considerations discussion deemed sufficient by the reviewers.
  • Copyright Waiver - All TNIPs must be in the public domain. The copyright waiver MUST link to the license file and use the following wording: Copyright and related rights waived via [CC0](../LICENSE.md).

TNIP Formats and Templates

TNIPs should be written in markdown format. There is a template to follow.

TNIP Header Preamble

Each TNIP must begin with an RFC 822 style header preamble. The header information must appear in the following order.

tnip: TNIP number

title: The TNIP title is a few words, not a complete sentence

description: Description is one full (short) sentence

author: The list of the author’s or authors’ name(s) and/or username(s), or name(s) and email(s). Details are below.

discussions-to: The url pointing to the official discussion thread

status: Draft, Review, Last Call, Final, Stagnant, Withdrawn, Living

last-call-deadline: The date last call period ends on (Optional field, only needed when status is Last Call)

created: Date the TNIP was created on

requires: TNIP number(s) (Optional field)

withdrawal-reason: A sentence explaining why the TNIP was withdrawn. (Optional field, only needed when status is Withdrawn)

Headers that permit lists must separate elements with commas.

Headers requiring dates will always do so in the format of ISO 8601 (yyyy-mm-dd).

author header

The author header lists the names, email addresses and/or usernames of the authors/owners of the TNIP. Those who prefer anonymity may use a username only, or a first name and a username. The format of the author header value must be:

name + github username

Another E. User (@username)

or

name + email

Random T. User <address@dom.ain>

or

name + username + email

Some L. User (@username) <address@dom.ain>

or

just name

Mystery S. User

Note: At least one author must use a GitHub username, in order to get notified on change requests and have the capability to approve or reject them.

discussions-to header

While a TNIP is a draft, a discussions-to header will indicate the URL where the TNIP is being discussed.

The preferred discussion URL is a topic on Telcoin Network Forum. The URL cannot point to Github pull requests, any URL which is ephemeral, and any URL which can get locked over time (i.e. Reddit topics).

created header

The created header records the date that the TNIP was assigned a number. Both headers should be in yyyy-mm-dd format, e.g. 2001-08-14.

requires header

TNIPs may have a requires header, indicating the TNIP numbers that this TNIP depends on. If such a dependency exists, this field is required.

A requires dependency is created when the current TNIP cannot be understood or implemented without a concept or technical element from another TNIP. Merely mentioning another TNIP does not necessarily create such a dependency.

Linking to other TNIPs

References to other TNIPs should follow the format TNIP-N where N is the TNIP number you are referring to. Each TNIP that is referenced in a TNIP MUST be accompanied by a relative markdown link the first time it is referenced, and MAY be accompanied by a link on subsequent references. The link MUST always be done via relative paths so that the links work in this GitHub repository, forks of this repository, the main TNIPs site, mirrors of the main TNIP site, etc. For example, you would link to this TNIP as ./tnip-1.md.

Auxiliary Files

Images, diagrams and auxiliary files should be included in a subdirectory of the assets folder for that TNIP as follows: assets/tnip-N (where N is to be replaced with the TNIP number). When linking to an image in the TNIP, use relative links such as ../assets/tnip-1/image.png.

Transferring TNIP Ownership

It occasionally becomes necessary to transfer ownership of TNIPs to a new developer. In general, we’d like to retain the original author as a co-author of the transferred TNIP, but that’s really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the TNIP process, or has fallen off the face of the ’net (i.e. is unreachable or isn’t responding to email). A bad reason to transfer ownership is because you don’t agree with the direction of the TNIP. We try to build consensus around a TNIP, but if that’s not possible, you can always submit a competing TNIP.

If you are interested in assuming ownership of a TNIP, send a message asking to take over, addressed to both the original author and the TNIP editor.

TNIP Editors

The current TNIP editors are

  • Grant Kee (@grantkee)
  • Steven Stanfield (@sstanfield)
  • Markus Osterlund (@robriks)

TNIP Editor Responsibilities

For each new TNIP that comes in, an editor does the following:

  • Read the TNIP to check if it is ready: sound and complete. The ideas must make technical sense, even if they don’t seem likely to get to final status.
  • The title should accurately describe the content.
  • Check the TNIP for language (spelling, grammar, sentence structure, etc.), markup (GitHub flavored Markdown), code style

If the TNIP isn’t ready, the editor will send it back to the author for revision, with specific instructions.

Once the TNIP is ready for the repository, the TNIP editor will:

  • Assign a TNIP number (generally incremental; editors can reassign if number sniping is suspected)
  • Merge the corresponding pull request
  • Send a message back to the TNIP author with the next step.

Many TNIPs are written and maintained by developers with write access to the Telcoin Network codebase. The TNIP editors monitor TNIP changes, and correct any structure, grammar, spelling, or markup mistakes we see.

The editors don’t pass judgment on TNIPs. We merely do the administrative & editorial part.

Style Guide

Titles

The title field in the preamble:

  • Should not include the word “standard” or any variation thereof; and
  • Should not include the TNIP’s number.

Descriptions

The description field in the preamble:

  • Should not include the word “standard” or any variation thereof; and
  • Should not include the TNIP’s number.

TNIP numbers

TNIPs must be written in the hyphenated form TNIP-X where X is that TNIP’s assigned number.

RFC 2119 and RFC 8174

TNIPs are encouraged to follow RFC 2119 and RFC 8174 for terminology and to insert the following at the beginning of the Specification section:

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

History

This document was derived heavily from Ethereum’s EIP-1, which was derived heavily from Bitcoin’s BIP-0001 written by Amir Taaki which in turn was derived from Python’s PEP-0001. In many places text was simply copied and modified. Although the PEP-0001 text was written by Barry Warsaw, Jeremy Hylton, and David Goodger, they are not responsible for its use in the Telcoin Network Improvement Process, and should not be bothered with technical questions specific to Telcoin Network or the TNIP. Please direct all comments to the TNIP editors.

Copyright and related rights waived via CC0.

Creative Commons Legal Code

CC0 1.0 Universal

CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
HEREUNDER.

Statement of Purpose

The laws of most jurisdictions throughout the world automatically confer exclusive Copyright and Related Rights (defined below) upon the creator and subsequent owner(s) (each and all, an “owner”) of an original work of authorship and/or a database (each, a “Work”).

Certain owners wish to permanently relinquish those rights to a Work for the purpose of contributing to a commons of creative, cultural and scientific works (“Commons”) that the public can reliably and without fear of later claims of infringement build upon, modify, incorporate in other works, reuse and redistribute as freely as possible in any form whatsoever and for any purposes, including without limitation commercial purposes. These owners may contribute to the Commons to promote the ideal of a free culture and the further production of creative, cultural and scientific works, or to gain reputation or greater distribution for their Work in part through the use and efforts of others.

For these and/or other purposes and motivations, and without any expectation of additional consideration or compensation, the person associating CC0 with a Work (the “Affirmer”), to the extent that he or she is an owner of Copyright and Related Rights in the Work, voluntarily elects to apply CC0 to the Work and publicly distribute the Work under its terms, with knowledge of his or her Copyright and Related Rights in the Work and the meaning and intended legal effect of CC0 on those rights.

  1. Copyright and Related Rights. A Work made available under CC0 may be protected by copyright and related or neighboring rights (“Copyright and Related Rights”). Copyright and Related Rights include, but are not limited to, the following:

i. the right to reproduce, adapt, distribute, perform, display, communicate, and translate a Work; ii. moral rights retained by the original author(s) and/or performer(s); iii. publicity and privacy rights pertaining to a person’s image or likeness depicted in a Work; iv. rights protecting against unfair competition in regards to a Work, subject to the limitations in paragraph 4(a), below; v. rights protecting the extraction, dissemination, use and reuse of data in a Work; vi. database rights (such as those arising under Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, and under any national implementation thereof, including any amended or successor version of such directive); and vii. other similar, equivalent or corresponding rights throughout the world based on applicable law or treaty, and any national implementations thereof.

  1. Waiver. To the greatest extent permitted by, but not in contravention of, applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and unconditionally waives, abandons, and surrenders all of Affirmer’s Copyright and Related Rights and associated claims and causes of action, whether now known or unknown (including existing as well as future claims and causes of action), in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the “Waiver”). Affirmer makes the Waiver for the benefit of each member of the public at large and to the detriment of Affirmer’s heirs and successors, fully intending that such Waiver shall not be subject to revocation, rescission, cancellation, termination, or any other legal or equitable action to disrupt the quiet enjoyment of the Work by the public as contemplated by Affirmer’s express Statement of Purpose.

  2. Public License Fallback. Should any part of the Waiver for any reason be judged legally invalid or ineffective under applicable law, then the Waiver shall be preserved to the maximum extent permitted taking into account Affirmer’s express Statement of Purpose. In addition, to the extent the Waiver is so judged Affirmer hereby grants to each affected person a royalty-free, non transferable, non sublicensable, non exclusive, irrevocable and unconditional license to exercise Affirmer’s Copyright and Related Rights in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the “License”). The License shall be deemed effective as of the date CC0 was applied by Affirmer to the Work. Should any part of the License for any reason be judged legally invalid or ineffective under applicable law, such partial invalidity or ineffectiveness shall not invalidate the remainder of the License, and in such case Affirmer hereby affirms that he or she will not (i) exercise any of his or her remaining Copyright and Related Rights in the Work or (ii) assert any associated claims and causes of action with respect to the Work, in either case contrary to Affirmer’s express Statement of Purpose.

  3. Limitations and Disclaimers.

a. No trademark or patent rights held by Affirmer are waived, abandoned, surrendered, licensed or otherwise affected by this document. b. Affirmer offers the Work as-is and makes no representations or warranties of any kind concerning the Work, express, implied, statutory or otherwise, including without limitation warranties of title, merchantability, fitness for a particular purpose, non infringement, or the absence of latent or other defects, accuracy, or the present or absence of errors, whether or not discoverable, all to the greatest extent permissible under applicable law. c. Affirmer disclaims responsibility for clearing rights of other persons that may apply to the Work or any use thereof, including without limitation any person’s Copyright and Related Rights in the Work. Further, Affirmer disclaims responsibility for obtaining any necessary consents, permissions or other rights required for any use of the Work. d. Affirmer understands and acknowledges that Creative Commons is not a party to this document and has no duty or obligation with respect to this CC0 or use of the Work.