Guides
Channel commitments and weight delegates
Publish independent hotkey commitments with an optional floating burn and delegate weight submission for one subnet mechanism.
Channel commitments and mechanism weight delegates separate operational keys from the accounts that own a validator or its commitments. Channels let a coldkey publish distinct payloads for its hotkeys. Weight delegates let a registered validator hotkey authorize another hotkey to submit weights without sharing the validator's private key.
Publish a channel commitment
A channel is identified by netuid, mechanism, and channel number. Each
hotkey has an independent commitment at that target; publishing there does not
replace the legacy Commitments.set_commitment record or another channel's
payload. The signing coldkey must own the registered hotkey and pays the normal
transaction fee. The channel's commitment deposit, if configured, is reserved
from the coldkey rather than the hotkey; reducing the deposit releases the
unused reserve. Deregistration follows the existing deposit release convention,
but burned TAO is never refunded.
After a coldkey swap, the new owner funds the full deposit on its next rewrite before the previous owner's reserve is released. Hotkey swaps and deregistration move or release channel state through bounded idle-work queues; new writes wait while a hotkey's migration is pending. Burn configuration and receipt sequences are scoped to the channel, not the hotkey, and are not migrated.
The write budget resets each subnet epoch for each hotkey, mechanism, and channel. A hotkey can retain state on all 256 channels of a mechanism, with up to 10 revealed entries per channel. Storage deposits are zero by default. Retained records add to the cleanup work when a hotkey or mechanism is retired.
The SDK constructs the same CommitmentInfo shape used by set_commitment,
including length-tagged plaintext fields and drand timelocked fields. Pass
max_burn_tao as an exact decimal TAO amount: the call fails if the current
burn exceeds that limit. It is a price limit, not an extra payment. The
runtime charges only the current burn; fees are additional. If burn is
disabled, publishing is free apart from fees.
import bittensor as bt
# Plaintext, with at most 0.25 TAO of burn accepted.
intent = bt.SetChannelCommitment(
netuid=1,
mechid=1,
channel=7,
data="model endpoint and metadata",
max_burn_tao="0.25",
)
result = await client.execute(intent, wallet)
# Timelocked plaintext; the chain reveals it at the supplied future drand round.
sealed = bt.SetChannelCommitment(
netuid=1,
mechid=1,
channel=7,
data="embargoed announcement",
reveal_round=12_345_678,
max_burn_tao="0.25",
)Use encoding="hex" when data is a hexadecimal byte string. An empty
plaintext payload writes an empty commitment, replacing this channel's previous
contents; it does not delete the channel's storage entry. Raw plaintext is
limited to 512 bytes; a timelocked payload cannot be empty. The execution result
includes the actual timelock reveal round.
The dedicated CLI command uses UTF-8 text by default, --hex for hexadecimal,
and --reveal-round for timelock encryption:
btcli commitments commit \
--netuid 1 --mechid 1 --channel 7 \
--data "model endpoint and metadata" --max-burn 0.25 \
-w my_coldkey -H my_hotkeyRead the payload with btcli commitments show or the registered SDK read:
commitment = await client.identity.channel_commitment(
netuid=1, mechid=1, channel=7, hotkey_ss58=hotkey,
)The v2 runtime API returns the SCALE-encoded commitment registration. The SDK decodes it against the connected runtime's metadata, including the channel's plaintext field variants. It does not return an opaque blob.
Burn price and owner configuration
Each channel has its own optional floating burn. Successful paid commits raise
the price; it decays toward its configured minimum according to the half-life.
Prices are lazily decayed. The burn stored in Commitments.CommitBurnConfig
can be old, so use the runtime API or the registered commit_burn read for the
current price rather than treating raw storage as a live quote.
price = await client.identity.commit_burn(netuid=1, mechid=1, channel=7)
print(price["burn"], price["price_is_decayed"])price_is_decayed=True means burn came from the live runtime quote. The API
returns no price when burn is disabled or unconfigured, so the read also shows
the stored configuration with price_is_decayed=False and burn=None; its
possibly stale amount is labeled stored_burn. That distinction makes
stored-versus-live pricing explicit.
btcli commitments price --netuid 1 --mechid 1 --channel 7The subnet owner coldkey (or root) configures five parameters independently for each mechanism and channel. Updates respect the subnet-owner rate-limit and admin-window rules.
For a new channel, set the ceiling before setting a positive floor. Enable
burn after configuring the price. On mechanism 0, channel 0, enabling burn
also disables new writes through the legacy Commitments.set_commitment call.
Switch publishers on that target to Commitments.set_commitment_to first.
| Parameter | Meaning | SDK/CLI value |
|---|---|---|
enabled | Whether paid burn applies | true or false |
min_burn | Lower price bound | TAO decimal; converted exactly to rao |
max_burn | Upper price bound | TAO decimal; converted exactly to rao |
half_life | Price decay interval | Positive integer blocks |
increase_mult | Price increase after a paid commit | Decimal 1..3 in the CLI or SDK. The Python SDK also accepts raw U64F64 bits as an integer. |
btcli commitments burn-config --netuid 1 --mechid 1 --channel 7 \
--name max_burn --value 10 -w subnet_owner
btcli commitments burn-config --netuid 1 --mechid 1 --channel 7 \
--name min_burn --value 0.1 -w subnet_owner
btcli commitments burn-config --netuid 1 --mechid 1 --channel 7 \
--name half_life --value 360 -w subnet_owner
btcli commitments burn-config --netuid 1 --mechid 1 --channel 7 \
--name increase_mult --value 1.26 -w subnet_owner
btcli commitments burn-config --netuid 1 --mechid 1 --channel 7 \
--name enabled --value true -w subnet_ownerDisabling burn makes subsequent channel commitments free apart from fees; it
does not refund earlier payments. The min_burn and max_burn bounds must
remain ordered, and the runtime enforces its own multiplier and half-life
limits.
Delegate weights for one mechanism
A registered validator hotkey can authorize one account as its mechanism weight delegate. Authorization is scoped to exactly one netuid/mechanism pair. It does not transfer stake, ownership, validator status, or control of other mechanisms. The validator hotkey signs the grant and revocation:
btcli weights delegate set --netuid 1 --mechid 1 --delegate OPERATOR_HOTKEY \
-w validator_coldkey -H validator_hotkey
btcli weights delegate show --netuid 1 --mechid 1 --hotkey VALIDATOR_HOTKEY
btcli weights delegate revoke --netuid 1 --mechid 1 \
-w validator_coldkey -H validator_hotkeyThe equivalent SDK mutation is SetMechWeightDelegate; set delegate=None to
revoke. Inspect the current grant with the mech_weight_delegate read.
Swapping a validator hotkey revokes its grants on the affected subnets. Once
cleanup finishes, the new hotkey can explicitly appoint a delegate again.
To submit as the delegate, sign with the authorized hotkey and identify the
validator with --for-hotkey. This works for automatic plaintext/timelocked
submission, forced timelock commits, and legacy reveals. The explicit legacy
hash commit is available as weights hash:
btcli weights set --netuid 1 --mechid 1 --for-hotkey VALIDATOR_HOTKEY \
--uids 0,1,2 --weights 0.5,0.3,0.2 -w operator_coldkey -H operator_hotkey
btcli weights commit --netuid 1 --mechid 1 --for-hotkey VALIDATOR_HOTKEY \
--uids 0,1,2 --weights 0.5,0.3,0.2 -w operator_coldkey -H operator_hotkey
btcli weights reveal --netuid 1 --mechid 1 --for-hotkey VALIDATOR_HOTKEY \
--uids 0,1,2 --weights 0.5,0.3,0.2 --salt 1,2,3 \
-w operator_coldkey -H operator_hotkeyOr use the same intents from Python:
intent = bt.SetWeights(
netuid=1,
mechid=1,
weights={0: 0.5, 1: 0.3, 2: 0.2},
for_hotkey=validator_hotkey,
)
result = await client.execute(intent, operator_wallet)The validator's identity is used for registration, rate-limit, and timelock encryption checks—not the delegate's. Registration, stake, permit, version, rate-limit, and weight-conformance rules still apply to the validator. The chain verifies that the signer is currently authorized for that mechanism. After a hotkey swap, bounded idle work moves the grant only when the destination owns the validator's former UID. A reverse swap before that work completes restores the grant on the hotkey that currently owns the UID.
These delegated calls charge a normal transaction fee to the signing
delegate, unlike hotkey weight calls whose fee is routed to the validator's
owning coldkey. The SDK deliberately does not classify the new *_for calls
as owner-paid. For low-level legacy flows, CommitWeightHash wraps
commit_mechanism_weights_for; the other intents select the appropriate
*_for call automatically.