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.

titleCommittee Shuffle at Epoch Boundary
descriptionPeriodically create new committees to reach consensus by randomly selecting from a group of eligible validators that have stake.
authorGrant Kee (@grantkee)
discussions-tohttps://forum.telcoin.org/t/epoch-boundary-validator-shuffle/343
statusReview
created2024-10-29

Rotating Committees

Abstract

This TNIP specifies a Validator Shuffle Protocol designed to enhance network security and decentralization by introducing a robust, cryptographic mechanism for randomizing validator committee selection at defined intervals, termed “epochs”. Eligible validators stake enough TEL to a contract and participate in consensus. Periodically, the protocol randomly selects a group of validators to form a new committee. The new committee is responsible for verifying, settling, and executing transactions for the next epoch.

Motivation

The foundational security of blockchain protocols relies heavily on the decentralization and unpredictability of consensus participants. A deterministic or predictable pattern in validator selection leads to vulnerabilities, such as targeted attacks and collusion, ultimately compromising the integrity and security of the network.

In Ethereum, validators are randomly shuffled into different committees responsible for validating specific portions of transactions and proposing new blocks. This randomness is critical as it prevents bad actors from predicting their assignments and colluding to influence the network unfairly. By leveraging a similar random committee selection mechanism, Telcoin Network can enhance its robustness against such attacks. Randomly shuffling validators into consensus committees not only minimizes the risks of collusion, it ensures a fair representation of the validator pool and increases the difficulty for any adversarial entities aiming to control the committee selection process.

Introducing a process to rotate eligible validators provides fresh opportunities for new nodes to participate in consensus as voting committee members. Randomly shuffling validators underpins both network security and community growth, aligning with the broader goals of decentralized security and equitable participation.

Specification

Committees

Consensus is managed by nodes that staked TEL. These nodes form committees and cast votes to reach a quorum. Committees are only valid for the epoch in which they are current.

Committee Voting Validators (CVVs)

Validators currently in the committee, responsible for casting votes, extending the canonical chain, and reaching consensus on transactions and finality.

Non-Voting Validators (NVVs)

Validators that track and execute consensus but do not vote for every block in the epoch. They participate by receiving consensus through a gossip network consisting of both CVVs and NVVs. NVVs only vote on the latest execution result to support new committees during epoch transitions.

Observing Validators (OVs)

Validators that track and execute consensus but never vote. OVs are primarily used as clients that want to independently verify execution results.

On-chain Committee Information

Committee information is stored on-chain to support client verification. The “Consensus Registry” contract is located at 0x07e17e17e17e17e17e17e17e17e17e17e17e17e1 and includes the following committee types:

  • C: The current committee which votes to reach consensus and extend the canonical tip.
  • Cp: The committee from the previous epoch.
  • Cn: The committee in the next epoch.
  • Cn+1: The committee after the next epoch, which is 2 epochs ahead of the current epoch.
Committee Transition

At each epoch boundary, the outgoing committee signs and broadcasts the last sealed execution result. The incoming committee waits for a quorum of signed execution results to establish the genesis certificate for the new epoch.

Epochs

An epoch is defined as a 24-hour time period. The transition is triggered by the first commit to the consensus Directed Acyclic Graph (DAG) after the 24-hour interval.

Epoch Boundary (e)

The last round of consensus committed to the DAG within an epoch, serving as the trigger for the next committee to advance. The timestamp for e must be greater-than or equal-to the 24-hour interval, but it cannot exceed 30 seconds past.

  • e : The epoch boundary.
  • et : “Epoch boundary time” is the UNIX timestamp used to quantify the epoch boundary (currently expected to be 24-hours after the epoch starts).
  • er : “Epoch boundary round” is the last round of consensus committed by all CVVs in the current epoch.
  • en : “Epoch boundary number” is the number of epochs, starting at 0 and incrementing +1 with every new epoch.
  • em : “Epoch boundary max” is the maximum amount of time (in seconds) that the pending committee should wait before falling back to a previous execution result to include in their genesis certificate.

NOTE: The timestamp for er must be within [et , et + em).

Closing Epoch Responsibilities

CVVs must perform closing epoch responsibilities to facilitate a successful transfer of consensus voting privileges to the next committee.

Signed Execution Result

The sealed header of the last block produced while executing er. The header’s hash is signed by the node’s BLS12-381 private key. The signed execution result includes the sealed header and the signed hash of the sealed header. Peers verify signed execution results by taking the SHA-256 hash of the header and comparing it to the signature.

Executing the last output

CVVs reach consensus and commit rounds to a local DAG until a certain UNIX timestamp is reached (et). The timestamp comes from consensus and is immutable based on the leader’s certificate for the committed subdag.

Once et is reached, CVVs stop accepting new transactions and do not propose any more batches. Primaries continue proposing headers to advance the round until all of their outstanding certificates with batches are committed to the DAG. Once a Primary’s outstanding certificates are committed to the DAG, the primary includes a system message in it’s header to CloseEpoch. Primaries continue to propose headers until a quourm of CVVs include CloseEpoch in their certificates.

The committee has up to 60 seconds (or enough time to ensure a reasonable attempt to commit all certified blocks) to reach a quorum of CloseEpoch system messages. The last committed round with a quorum of CloseEpoch system messages is er. While executing er, CVVs must update the consensus registry contract with committee’s updates using a system call to concludeEpoch on the consensus registry contract at 0x07e17e17e17e17e17e17e17e17e17e17e17e17e1. The required committee updates are:

  1. The current committee must become the previous committee.

Cp = C

  1. The next committee must become the current committee to ensure clients following the canonical tip always read the correct current committee from state.

C = Cn

  1. The committee after the next committee must become the next committee.

Cn = Cn+1

  1. The committee after the next committee must be deterministically decided using the Fisher-Yates shuffle algorithm for all eligible validators from the staking contract in the current epoch that is closing. The source of randomness for shuffling must be the aggregate BLS12-381 signature from the leader certificate. TODO: specify eligible validator requirements in previous section

Cn+1 = new committee from a deterministic shuffle

The final execution result is signed by the validator’s BLS12-381 private key and unreliably broadcast to all known validators (CVVs and NVVs) through the gossip network.

NVVs must also sign and vote on execution results at e. All validators continue to gossip signed execution results at e until the committee taking over for the next epoch (updated C) reaches a quorum of signatures (2f+1) from all eligible validators. These votes comprise a quorum from all staked validator nodes on the network, completing the epoch. Pending CVVs reliably forward all signed execution results to their fellow committee members to support a successful transition.

Shuffle Mechanism

The Fisher-Yates shuffle algorithm is used to randomly reorder validators. This shuffle occurs once per epoch, and uses the aggregate BLS signature from the leader certificate from the last committed consensus round mixed with the accumulated randomness during the epoch as the source of entropy.

The probability of a node being selected during the shuffle is influenced by the node’s effective stake. “Effective stake” in this context simply means the amount of stake that affects the node’s probability of being selected during the shuffle process. See staking section for more details.

Recovering from failed execution at e

Byzantine nodes must not prevent the network from closing an epoch or a new committee from taking over consensus. If the (pending) current committee C fails to receive a quorum of signed execution results at e to start the epoch, then the certified block in the last DAG commit is used to start the epoch. The new committee C must use this leader certificate’s aggregate signatures to generate Cn+1 since the closing committee failed to propose this committee. Nodes must be penalized in the first round of the new epoch by slashing stake if they failed to attest the epoch boundary. The penalty must be applied in addition to the node’s other opening epoch responsibilities. The amount of stake to deduct from the validator’s staked balance is yet to be determined. Social governance must participate in this decision.

Beginning a new epoch

CVVs must perform opening epoch responsibilities to facilitate a successful beginning to the new epoch.

Epoch genesis

Epochs are conceptually new chains that begin with the closing state from the previous epoch. The pending committee C collects signed execution results for the last block of the last executed round of consensus until a quorum of all eligible validator nodes is reached (2f+1) or time expires after em, whichever happens first.

The first round committed to the DAG must apply rewards and penalties for the previous epoch for all validators through a system call to the staking contract at 0x07e17e17e17e17e17e17e17e17e17e17e17e17e1. The method on the staking contract is applyIncentives.

Protocol implementation must include a new RPC endpoint called tn_epochGenesis that returns the quorum of signatures and the sealed header of the execution result used by the current committee to start the current epoch.

Recovering from different execution results at genesis

Because the asynchronous nature of the protocol could cause some nodes to miss the signed execution result at e, CVVs must verify signatures and use the latest, signed, canonical tip in the event that the proposed genesis certificates include different execution results. Consider the scenario that some nodes have the correct signed execution result and others used the fallback tip because they did not receive a quorum of votes in time. This could happen if em expires while a node has only broadcast its signed execution results to some of its peers.

During epoch genesis, CVVs that receive unexpected execution results must consider the most recent result. If a CVV receives an outdated execution result from a peer’s genesis certificate, then it responds with the correct execution results, including all signatures that formed a quorum. The CVV that included the fallback execution result must then verify all signatures of the more-recently signed execution result and reissue their genesis certificate to start the next epoch.

This ensures that the closing executing result from the previous epoch will start the next epoch as long as at least one committee member receives the signed execution result in time.

Preparing for the next epoch

Validators that are in the next committee (Cn) must update their peer lists to include all future committee members by making a request on the gossipsub peer network for peers matching the peer’s BLS12-381 public keys. Nodes should drop peers in preference of their future committee members to ensure they have network information for all committee members by the start of the next epoch.

Eligible Nodes

Telcoin Network is a proof-of-stake network (PoS) that requires proof of authority to stake. Authorities are GSMA full-members.

Syncing

New nodes synchronize by downloading all consensus output and executing the data up to the current epoch. The Telcoin Association’s TAO manages snapshots of execution and consensus data to facilitate this process. Syncing must be permissionless and verifiable through independent execution.

Staking Contract

Validators must stake 1 million TEL to the designated staking contract at 0x07e17e17e17e17e17e17e17e17e17e17e17e17e1. The locking period for stake is 10 epochs, after which a validator may withdraw their funds and exit the protocol entirely.

NFT Requirement

Validator wallets require an NFT issued by Telcoin Association for staking. The NFT issuance process involves a human, real-world review by the Telcoin Association and is exclusive to GSMA members.

Validators must first obtain an NFT through Telcoin Association’s decentralized governance and have a fully synced node online. The validator NFT allows wallets to deposit TEL to the staking contract located at 0x07e17e17e17e17e17e17e17e17e17e17e17e17e1.

Once a node has completed the staking process, the validator’s status is updated to “active” after one full epoch. Once the validator status is “active” on-chain, it is eligible to become a CVV. The newly eligible validator will be included in the next shuffle that determines Cn+1. The node’s effective stake is considered during the shuffle process.

Network Discovery

Validators must support a trustless and permissionless exchange of peer information. CVVs need to know the ports and IP addresses of all other CVVs in order to effectively participate in consensus. However, publicly exposing this information introduces attack vectors for DOS attacks.

The public RPC must add a new endpoint called tn_validatorHandshake that verifies and acknowledges new peers that have staked TEL and joined the network.

NVVs initiate contact with known validators through their RPC endpoints, allowing them to subscribe to the latest consensus. The node initiates a “handshake” protocol with an existing node. The initial handshake from a new node attempting to join the consensus network includes the following information:

  • Primary network address
  • Worker network address
  • BLS12-381 signature of the ECDSA secp256k1 public key used to stake
  • The chain id of the network the node is trying to join

Protocol implementations should support node operators to manually specify an IP address to initiate the handshake. Well-known beacons must be supported by the Telcoin Autonomous Operations (TAO) to facilitate peer discovery.

“Friendly” network

Once a validator has verified a new node joining the network, the new peer’s information is forwarded to all peers. Nodes must store this information in a persistent way to ensure all known, eligible nodes have network addresses for closing epochs.

If a node needs to update network information, it must initiate another handshake sequence. Nodes must update the peer’s stored information.

In the early stages, the core protocol team is responsible for assisting node operators joining the network. Eventually, the protocol will be open-source so anyone can run a node and execute consensus output. Only GSMA full members are eligible to become CVVs.

Transition from NVV to CVV

NVVs become eligible to transition to CVVs after participating for one full epoch. The epoch boundary marks the transition, with validators signing and broadcasting their final execution results to form a new committee based on a quorum of signatures.

Future considerations

Small pool of validators

The protocol’s current strategy is for a small network of robust nodes to participate in consensus. Once the network has a larger number of staked nodes, there will be more eligible NVVs available to attest to the current committee’s proposed state changes. At that time, it is beneficial to reconsider how NVVs participate in securing the network. One idea is having NVVs take random samples of execution results throughout an epoch to ensure validators aren’t being lazy. Lazy validators might subscribe to a peer’s execution results and including it in their own proposed headers as if they performed the execution result. See the security discussion for lazy validators for more information.

Maintaining peers

The number of validating peers maintained by a CVV is not a concern at this time because the number of eligible validators is small. However, as the network grows in size, it may be necessary to implement a limit to the number of peers a CVV maintains for consensus gossip. It’s critical that consensus maintains smooth operation with maximum bandwidth prioritized for committee messages. Handshakes and gossipping consensus data may influence performance as the network grows.

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.

Rationale

Permissionless NVVs

The network’s security is reinforced with permissionless clients that independently execute consensus output. The network should further enhance its security by allowing these nodes, once staked, to perform attestations against CVV consensus output. However, this is outside the scope of this proposal.

Furthermore, node operators may need time to setup their environment and optimize performance (NAT, firewall, latency, etc). The protocol could be designed so operators submit a 2nd transaction to update their status to “active” after staking, but this is inconvenient. Node operators are encouraged to use state-of-the-art security best practices for managing private keys. A second transaction after staking introduces friction to join the network and requires additional gas. Instead, the system is designed so operators can simply stake after they’ve ensured their node is ready to participate in consensus.

Permissionless access to consensus output accentuates the need for trustless peer communication.

Initiating Handshakes

Nodes joining the network must initiate handshakes to exchange network information so existing nodes can find them. Initiating handshakes through public RPC methods allows any node operator to join the network as easily as submitting a transaction and reduces the challenge of discovering peers. This approach also allows nodes to easily update their network information.

CVV Gossip

Committee nodes must limit the number and prioritize the type of peers they maintain. Consensus output must be gossipped outside the committee so non-voting clients can track the canonical tip. However, it’s critical that CVVs prioritize inner-committee communication above all else to ensure consensus is successful.

Stake

The amount of stake needs to be further evaluated, but is assumed to be sufficient in the early stages of the network. Stake is only effective if the amount is substantial enough to economically disincentivize nodes from becoming Byzantine. Revenue varies significantly between different tiers of Mobile Network Operators (MNO), so the financial impact could vary between staked nodes. Social governance should still play a role in revoking validator NFTs for bad actors on the network if losing stake is insufficient. The current target is expected to be a minimum amount of appropriate stake for the lowest tier MNO.

Governance should review and provide feedback on how validators withdraw and exit the network. Further evaluation is needed to identify appropriate penalties for slashable offenses.

The concept of “effective stake” is not clearly defined at this time. As penalties and rewards are applied to validator stake, their balance will fluctuate. If the amount staked is above the minimum requirement, it may or may not influence the node’s chances of being selected in the shuffle. Governance should review and provide feedback if validators should be considered more favorably during the shuffle process if their stake is higher than other nodes.

Committees On-Chain

Storing committees on-chain ensures any clients following the canonical tip have the latest committee information. Validating execution results ensures consensus is reached for committee selections. Previous committee information supports clients trying to sync. Selecting committees in advance allows the protocol to ensure stable withdrawals for validators exiting the network.

Closing Epoch Leftover Certificates

Transactions are executed if they’re included in the consensus DAG commit, so inevitably there will be transactions that were certified within one epoch but unsettled and executed before e is reached. The new committee should not rely on a previous committee’s certificates and must reach consensus again before executing any transactions leftover from a previous epoch because validators cannot securely propose on behalf of other nodes. To ensure the best possible user experience, exiting CVVs must track and reliably forward any remaining transactions to pending CVVs. CVVs in the new epoch must reverify and prioritize these transactions in the early rounds of the new epoch.

CVVs must track their certified batches and continue advancing rounds until all their batches are executed. At et, validators must stop proposing batches. Primaries only propose empty headers to advance rounds and ensure additional commits to the DAG. Once all batches for a primary are settled, the primary includes a system message in their proposed headers to indicate the epoch should close. A quorum of these system messages triggers the epoch transition.

On the happy path, this seems more efficient. Considerable effort, measured in both computation and network bandwidth, is used to reach consensus for batches of transactions. The network already spent computation and bandwidth to certify these transactions, and the additional overhead to propose empty blocks to reach consensus seems trivial compared to forwarding certified transactions to the next committee. The next committee would still need to re-verify all transactions, so the computation and bandwidth costs are duplicated for the next committee.

Network latency could cause issues if a certificate is delayed or never committed to the DAG.

The protocol could enforce a strict cutoff without any delay to close the epoch, but any certificates containing batches cannot be considered certified by the next committee. All certified transactions would need to be forwarded to a new CVV, reproposed, reverified, and resequenced by the new committee.

Instead, a best effort is made to reduce waste and execute any transactions that were included in certificates by C. Primaries still propose headers to advance the round, but empty headers utilize much less resources.

Specifying a timeout ensures the protocol advances, even in the event of a faulty leader or asynchronous network conditions.

Gossip vs Reliable Broadcasting Execution Results at e

Reliable broadcast is unnecessary at e with a robust gossip network. All nodes gossip signed execution results to support a successful committee transition.

Backwards Compatibility

No backward compatibility issues.

Test Cases

N/A

Reference Implementation

N/A

Security Considerations

Limited Decentralization (Early Stages)

GSMA full-members hold the exclusive right to validate transactions and participate in consensus. The members are decentralized within the context of Mobile Network Operators (MNOs), but eligible committee members are more limited than other protocols because of this requirement. It is beneficial for the protocol and the network at large for GSMA members to stake and operate multiple nodes. However, it will take time for validator numbers to reach a critical point of diversity where the protocol can tolerate more byzantine nodes without significant consequences.

Denial of Service (DoS)

Validators must share network information with peers and maintain constant communication. It’s also important that NVVs are permissionless and trustless. As the network continues to grow, validator numbers are expected to be limited in the early stages which increases the effectiveness of flooding validators with bogus requests. Spamming ports dedicated to consensus messages between CVVs is especially detrimental to network progress.

Additional consideration is needed to enhance the network’s robustness against these types of attacks. Currently, the network uses virtual private networks for committees messages. Redundant proxies may also be effective in preventing this type of attack. MNOs have significant experience mitigating these types of attacks and should provide direction towards refining network security.

Lazy Validators

Lazy validators might subscribe to a peer’s execution results through a public RPC and use the data as their own, as if they computed the output individually. Right now, there is some level of trust that validators won’t be lazy and skip execution. Stake and knowledge is a reasonable deterrent in the early stages, but more work is needed to remove this trust assumption as the network grows larger. One idea is to have staked NVVs randomly sample CVV execution results throughout each epoch, but that is outside the scope of this proposal.

Randomness

Unpredictable values are critical for maintining the integrity and security of the chain. Randomness is obtained through BLS aggregate signatures from the leader certificate for a round and mixed with the accumulated randomness from the previous consensus output.

The random bytes generated from aggregate BLS signatures are theoretically impossible to predict and easy to verify.

As certificates are issued, it’s possible for a bad actor to look ahead and anticipate the future accumulated random value by considering all possible certificates as leaders. However, such a maneuver doesn’t yield any advantage because the signatures are already accumulated.

In order for an adversary to take advantage of knowing the random value, they would need to influence the aggregate signature bytes themselves. If an adversary were able to affect the outcome of the aggregate signature or predict its value, they could take action before the signature is generated to manipulate events in their favor. This is largely understood to be impossible as long as private keys remain private.

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.