Guides

Channel commitments and weight delegates

Publish independent hotkey commitments with an optional floating burn and delegate weight submission for one subnet mechanism.

View as Markdown

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_hotkey

Read 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 7

The 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.

ParameterMeaningSDK/CLI value
enabledWhether paid burn appliestrue or false
min_burnLower price boundTAO decimal; converted exactly to rao
max_burnUpper price boundTAO decimal; converted exactly to rao
half_lifePrice decay intervalPositive integer blocks
increase_multPrice increase after a paid commitDecimal 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_owner

Disabling 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_hotkey

The 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_hotkey

Or 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.