You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -7,6 +7,12 @@ This page describes the **commit reveal** feature: a configurable waiting period
7
7
8
8
This feature was designed to address the issue of _weight copying_ by validators.
9
9
10
+
## Overview
11
+
12
+
Commit reveal uses **[Drand time-lock encryption](https://drand.love/docs/timelock-encryption/)** to automatically reveal validator weights after a concealment period. When a validator sets weights, they are cryptographically encrypted and can only be decrypted after the configured number of tempos has passed. This automation eliminates the need for manual reveals and prevents selective revelation attacks.
13
+
14
+
**For validators**: The commit reveal process is completely transparent. You continue to call [`set_weights`](pathname:///python-api/html/autoapi/bittensor/core/extrinsics/set_weights/index.html) exactly as you always have. All commit-reveal logic happens behind the scenes at the chain level.
15
+
10
16
## Weight copying
11
17
12
18
In each Bittensor subnet, each validator scores—or _'weights'_—each miner, producing what is referred to as a [weight vector](../resources/glossary.md#weight-vector). The weight vectors for each validator in a subnet are combined into a weight matrix. This matrix determines emissions to miners in the subnet based on the consensus evaluation of their performance, according to [Yuma Consensus](../resources/glossary.md#yuma-consensus).
@@ -27,70 +33,137 @@ new_immunity_period = (new_commit_reveal_period x tempo - old_commit_reveal_peri
27
33
28
34
See [Subnet Hyperparameters](../subnets/subnet-hyperparameters.md).
29
35
30
-
## Commit reveal in detail
36
+
## How commit reveal works
37
+
38
+
When commit reveal is enabled for a subnet, the following process occurs automatically:
39
+
40
+
### 1. Validator Sets Weights
31
41
32
-
When commit reveal is enabled, it works as follows:
42
+
A subnet validator calls [`set_weights`](pathname:///python-api/html/autoapi/bittensor/core/extrinsics/set_weights/index.html) exactly as they normally would. No code changes are required.
33
43
34
-
1. A subnet validator sets the weights normally by using [`set_weights`](pathname:///python-api/html/autoapi/bittensor/core/extrinsics/set_weights/index.html).
44
+
### 2. Automatic Commit with Time-Lock Encryption
35
45
36
-
2. Instead of publishing weights openly, an encrypted copy of these weights is committed to the blockchain, using an internal method called [`commit_weights`](pathname:///python-api/html/autoapi/bittensor/core/extrinsics/commit_weights/index.html).
46
+
Instead of publishing weights openly, the chain automatically:
47
+
- Encrypts the weights using **[Drand time-lock encryption](https://drand.love/docs/timelock-encryption/)**
48
+
- Commits the encrypted weights to the blockchain via an internal method called [`commit_weights`](pathname:///python-api/html/autoapi/bittensor/core/extrinsics/commit_weights/index.html)
49
+
- Calculates the target Drand round based on the current block and `commit_reveal_period`
37
50
38
-
3. A waiting interval, specified as a number of tempos, elapses. Subnet owners configure this interval with the subnet hyperparameter `commit_reveal_period`.
51
+
The encrypted weights cannot be decrypted by anyone—including the validator who submitted them—until the designated Drand round is reached.
39
52
40
53
:::tip Tempo is a hyperparameter
41
54
The subnet's tempo is a hyperparameter. Subnet owners cannot modify this parameter, which defaults to `360` blocks.
42
55
:::
43
56
44
-
4. After this interval has elapsed, the unencrypted weights are automatically revealed by the chain, using [Drand time-lock encryption](https://drand.love/docs/timelock-encryption/).
57
+
### 3. Concealment Period
58
+
59
+
A waiting interval, specified as a number of tempos, elapses. Subnet owners configure this interval with the `commit_reveal_period` hyperparameter. During this time:
60
+
- The weights remain encrypted on-chain
61
+
- No one can view or copy the weights
62
+
- The validator does not need to take any action
63
+
64
+
### 4. Automatic Reveal
65
+
66
+
After the `commit_reveal_period` has elapsed, the chain automatically decrypts and reveals the weights at the beginning of the next tempo. This happens when the corresponding Drand randomness beacon pulse becomes available, providing the cryptographic key needed to unlock the time-locked encryption.
67
+
68
+
**Key security property**: The reveal timing is cryptographically guaranteed by the Drand network—a decentralized randomness beacon. No single party can prevent or delay the reveal once weights are committed.
69
+
70
+
### 5. Consensus Processing
45
71
46
-
5.The weights are now input to Yuma Consensus.
72
+
The revealed weights are now publicly visible and input into Yuma Consensus for the next epoch calculation, just as if they had been submitted without commit reveal.
47
73
48
74
<br />
49
-
:::tip Commit reveal works behind the scenes
50
-
After the subnet owner turns ON the commit reveal feature, everything happens behind the scenes. A subnet validator will continue to set weights normally by using [`set_weights`](pathname:///python-api/html/autoapi/bittensor/core/extrinsics/set_weights/index.html).
75
+
:::tip Completely transparent to validators
76
+
After a subnet owner enables commit reveal, validators don't need to change anything. They continue calling [`set_weights`](pathname:///python-api/html/autoapi/bittensor/core/extrinsics/set_weights/index.html) as always. All encryption, time-locking, and automatic revealing happens at the chain level.
51
77
:::
52
78
79
+
## Benefits of automatic commit reveal
80
+
81
+
The Drand-based automatic reveal system provides several important benefits:
82
+
83
+
1.**No manual reveals required**: Validators don't need to remember to reveal weights or maintain uptime for reveals
84
+
2.**Eliminates selective revelation**: Validators cannot choose not to reveal if they see unfavorable consensus forming
85
+
3.**Cryptographic guarantees**: Time-lock encryption ensures weights are revealed on schedule
86
+
4.**Reduced transaction costs**: No separate reveal transaction is needed
87
+
5.**Trustless operation**: Drand is a decentralized network; no single party controls reveal timing
As a subnet owner, set the below hyperparameters to use the commit reveal feature:
102
+
This detailed sequence diagram shows the CRv4 process across three tempos. Key observations:
103
+
-**Drand pulse** triggers automatic reveals at block 1005, 1105, 1205 (shortly after each tempo starts)
104
+
-**Commit window** is blocks 1090-1099 of each tempo (last 10 blocks)
105
+
-**Concealment period** protects weights during the tempo
106
+
-**Epoch calculation** uses revealed weights at block 1100, 1200, etc.
67
107
68
-
1.`commit_reveal_weights_enabled` (boolean): Set this to `True` to activate the commit reveal feature for the subnet. Default value is `False`.
69
-
2.`commit_reveal_period` (int): Set this to an integer number. This is the number of subnet tempos to elapse before revealing the weights by submitting them again to the blockchain, but now openly for everyone to see. Default value is `1`.
108
+
## Configuring commit reveal
70
109
71
-
See [Setting subnet hyperparameters](../subnets/subnet-hyperparameters.md#set-hyperparameters).
110
+
As a subnet owner, you can enable and configure commit reveal using two hyperparameters:
72
111
73
-
:::danger Ensure that the commit reveal interval is less than your immunity period to avoid unintended miner de-registration!
74
-
See [Commit Reveal and Immunity Period](#commit-reveal-and-immunity-period).
75
-
:::
112
+
### Hyperparameters
76
113
77
-
Weights will be revealed immediately at the beginning of the tempo after the `commit_reveal_period`. For example, if `commit_reveal_period` value is set to `3`, then the reveal will occur at the beginning of the fourth tempo from the current tempo. The current tempo is counted as the first tempo. See the below diagram for this example:
114
+
1.**`commit_reveal_weights_enabled`** (boolean)
115
+
- Set to `True` to activate commit reveal for your subnet
116
+
- Default: `False` (disabled)
117
+
- When enabled, all validator weights are automatically committed with time-lock encryption
- The number of tempos that must elapse before weights are revealed
121
+
- Default: `1` (weights revealed after 1 tempo)
122
+
- Example: If set to `3`, weights committed in tempo 10 will be revealed at the start of tempo 13
123
+
124
+
See [Setting subnet hyperparameters](../subnets/subnet-hyperparameters.md#set-hyperparameters) for how to update these values.
125
+
126
+
### Reveal timing example
127
+
128
+
Weights will be revealed at the beginning of the tempo after the `commit_reveal_period` has elapsed. The Drand pulse triggers the automatic decryption shortly after the new tempo begins.
129
+
130
+
**Example**: If `commit_reveal_period` is set to `3`:
-**Tempo 13**: Weights automatically revealed at tempo start
135
+
136
+
The current tempo when committing counts as tempo 1 in the calculation. Refer to the detailed sequence diagram above for a visual representation of this timing.
137
+
138
+
:::tip Validator experience
139
+
Validators don't see any of this timing complexity. They simply call `set_weights()` whenever they want to update their weights. The chain handles all commit-reveal timing automatically.
140
+
:::
141
+
142
+
:::danger Critical: Immunity period must be longer than commit reveal interval
143
+
Ensure that your immunity period is **longer** than your commit reveal interval to avoid unintended miner deregistration. If the immunity period expires before weights are revealed, newly registered miners may be deregistered without having their performance evaluated. See [Commit Reveal and Immunity Period](#commit-reveal-and-immunity-period).
144
+
:::
89
145
90
146
<br />
91
147
148
+
## What is Drand?
149
+
150
+
[Drand](https://drand.love) (pronounced "dee-rand") is a distributed randomness beacon network that provides publicly verifiable, unpredictable, and unbiased random numbers. It is operated by the [League of Entropy](https://drand.love/league-of-entropy/), a consortium of independent organizations running Drand nodes.
151
+
152
+
**Time-lock encryption** is a cryptographic technique where data is encrypted such that it can only be decrypted after a specific time has passed. Drand provides this capability by regularly producing randomness "pulses" at fixed intervals. Data encrypted for a future Drand round cannot be decrypted until that round's randomness is published—even by the person who encrypted it.
153
+
154
+
Key properties that make Drand suitable for Bittensor:
155
+
-**Decentralized**: No single entity controls the randomness generation
156
+
-**Verifiable**: Anyone can verify that randomness was generated correctly
157
+
-**Predictable timing**: Pulses are produced at regular intervals
158
+
-**Industry adoption**: Used by multiple blockchain and cryptographic protocols
0 commit comments