Contractless-Proposals/README.md

Contractless Proposals

Contractless Proposals, or CLPs, provide a public process for describing ideas, approving consensus proposals, and activating completed implementations.

Not every CLP requires a network vote. A CLP may document a wallet standard, application convention, recommended practice, or other idea that does not change consensus. Only proposals that require network approval need an on-chain ProposalKey and a matching .id file.

The repository document explains the proposal. The blockchain records whether eligible node operators approve it.

Proposal Files

Each proposal uses a numbered Markdown file:

CLP-0001.md

When a proposal is submitted for an on-chain vote, it also receives an ID file:

CLP-0001.id

The Markdown document and ID file serve different purposes:

• CLP-0001.md contains the proposal.
• CLP-0001.id contains the confirmed ProposalKey transaction ID used for voting and the document hash committed by that transaction.

A CLP without an .id file is informational and has not been submitted for an on-chain vote.

A CLP with an .id file has been committed on-chain. Its Markdown file must not be changed. A revised proposal requires a new CLP document and a new ProposalKey.

Creating a Proposal

Write the complete proposal before creating its ProposalKey.

The document should clearly describe:

• The problem being addressed.
• The proposed behavior.
• Whether consensus rules would change.
• Compatibility and migration concerns.
• Expected effects on nodes, wallets, applications, and historical validation.

The ProposalKey commits to the exact bytes of the document. Even changes that do not visibly alter its meaning can produce a different hash. Changing line endings, spacing, punctuation, or the final newline changes the document hash.

Finalize the document before continuing.

Creating the ProposalKey

Use create_proposal_key_tx with the finalized Markdown file:

./create_proposal_key_tx ./CLPs/CLP-0001.md

An optional transaction fee may be supplied:

./create_proposal_key_tx ./CLPs/CLP-0001.md 1

The minimum fee is currently 1 CLC or CLTC.

The tool:

1. Reads the exact raw bytes of the proposal document.
2. Creates a Skein-256 hash of those bytes.
3. Loads the selected wallet.
4. Creates and signs transaction type 200.
5. Saves the transaction under ./transactions/<transaction_hash>.json.

Proposal creators must use a registered wallet address and must have enough confirmed balance to pay the transaction fee. Proposal creation does not require the wallet to operate an eligible mining node.

Creating the transaction file does not submit it to the network. Broadcast it separately:

./broadcast_transaction ./transactions/<transaction_hash>.json

Wait for the transaction to be included in a confirmed block before publishing its ID as active.

Creating the ID File

The ProposalKey is the hash field in the generated transaction JSON. It is also the filename created by create_proposal_key_tx.

It is not the proposal_hash field:

• hash is the ProposalKey transaction ID used when voting.
• proposal_hash proves which exact proposal document was submitted.

Create CLP-0001.id after the ProposalKey has been confirmed:

proposal_key=<ProposalKey transaction hash>
document_hash=<proposal_hash committed by the transaction>

For example:

proposal_key=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
document_hash=abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789

The .id file is intentionally separate from the Markdown document. Adding the ProposalKey to the proposal itself would change the document bytes and invalidate the document hash.

Checking a Proposal

Use the ProposalKey from the .id file:

./lookup_governance_proposal <proposal_key>

The lookup reports:

• The ProposalKey.
• The committed proposal document hash.
• The proposal creator.
• The creation timestamp.
• Whether proposal voting is open or approved.
• Current yes and no votes.
• The number of eligible nodes used for the calculation.
• Which recorded votes are currently counted.
• Final vote totals and finalization block, when approved.
• Implementation candidates and their activation votes.
• Any scheduled activation block.

Anyone reviewing a CLP should verify that the hash of the published Markdown document matches proposal_document_hash in this result.

Voting on a Proposal

Proposal voting uses transaction type 201:

./create_proposal_vote_tx <proposal_key> <yes|no>

Examples:

./create_proposal_vote_tx 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef yes

./create_proposal_vote_tx 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef no

An optional transaction fee may be supplied as the final argument:

./create_proposal_vote_tx <proposal_key> yes 1

Broadcast the generated transaction:

./broadcast_transaction ./transactions/<transaction_hash>.json

Before voting, verify the proposal document, its document hash, and the ProposalKey. A vote approves or rejects the exact document committed by that ProposalKey.

Who Can Vote?

A proposal or activation vote is valid only when the voting wallet:

• Is a registered Contractless wallet.
• Belongs to a network node.
• Has been active for at least 60 minutes.
• Has mined at least 100 blocks.
• Is active when casting the vote.
• Can pay the required 1 CLC or CLTC transaction fee.

Each eligible node wallet may vote only once on a particular proposal. A vote cannot be replaced after it has been accepted.

Governance is based on eligible nodes, not coin balances. Holding more currency does not create more votes.

An active replacement wallet on the same IP supersedes the older wallet for unfinished governance decisions. This prevents one physical node from being counted more than once after changing wallets.

Vote Counting and Approval

A proposal is approved when yes votes reach at least 85 percent of currently countable eligible nodes.

Votes are recalculated when blocks are accepted. This allows a proposal to become approved after the eligible network changes, even if the latest block does not contain another governance vote.

An otherwise eligible node remains part of the eligible-node calculation while active and for 5,760 blocks after being marked offline. If it already voted, that vote remains countable during the same period. After the grace period, the node leaves the denominator and its vote stops contributing to the current calculation. If the same wallet returns, its existing vote becomes countable again while the proposal remains open.

A proposal has no voting deadline. It remains open unless and until it reaches the required approval.

Once approval reaches 85 percent, the result is finalized at that block. Later changes to the eligible-node population do not reopen the proposal or change the recorded result.

Implementation Voting

Approving a proposal does not activate code.

Developers must create an implementation and an implementation document. That document should identify the relevant source changes, commits, compatibility requirements, and the exact behavior being presented for activation.

Eligible nodes vote on that specific implementation using transaction type 202:

./create_activation_vote_tx <proposal_key> <implementation_file> <development_location> <yes|no>

Example:

./create_activation_vote_tx \
  <proposal_key> \
  ./CLPs/CLP-0001-IMPLEMENTATION.md \
  CLPs/CLP-0001-IMPLEMENTATION.md \
  yes

The arguments are:

• proposal_key: The approved ProposalKey transaction ID.
• implementation_file: The local document whose exact bytes will be hashed.
• development_location: The repository location where others can find that document. It must be ASCII and no longer than 100 bytes.
• yes|no: Whether the node approves activating that implementation.
• txfee: An optional fee argument. The minimum is currently 1 CLC or CLTC.

The tool saves a signed activation-vote transaction under ./transactions/. Broadcast it with broadcast_transaction.

Different implementation documents produce different development hashes and are counted as separate activation candidates. Voting for one implementation does not count as voting for another. The ProposalKey and development-document hash identify the candidate; voters should also use the same canonical document location so the recorded location remains unambiguous.

Activation voting can begin only after the proposal itself has been approved.

Activation

When one implementation reaches 85 percent approval:

1. The activation vote is finalized.
2. Its development hash and document location are recorded.
3. An activation block is scheduled exactly 5,760 blocks after the finalization block.
4. The implementation becomes active at that scheduled block.

Node operators must install compatible candidate software before activation. The candidate software must preserve the old rules for blocks before the activation height and apply the approved rules beginning at the activation height.

Governance records approval and the activation boundary. It does not download, compile, or execute source code automatically.

See DEVELOPERS.md for implementation requirements.

Important Rules

• Never change a CLP document after creating its ProposalKey.
• Never confuse the proposal document hash with the ProposalKey transaction ID.
• Never vote without independently verifying the document hash.
• Never treat repository inclusion as proposal approval.
• Never activate consensus behavior merely because code was published.
• Preserve historical validation rules before every activation height.
• Use a new CLP and ProposalKey when revising an existing proposal.