# set-channel-commitment (/docs/tx/set-channel-commitment)

`data` is UTF-8 by default or hexadecimal with `encoding='hex'`. An
empty plaintext clears this channel's commitment. With `reveal_round`,
the payload is drand-timelock-encrypted and the chain reveals it at that
round. The target is independent of the legacy commitment and other
mechanisms/channels. The signing coldkey must own the registered hotkey.
When this channel's burn is enabled, the current decayed TAO price is paid
from the coldkey; the call fails rather than exceeding `max_burn_tao`.
That maximum bounds policy spending; fees are additional. With no enabled
burn, the commitment is free apart from the normal transaction fee.

| Signer    | Origin                                 | Pallet      | Wraps                                                                             |
| --------- | -------------------------------------- | ----------- | --------------------------------------------------------------------------------- |
| `coldkey` | signed account (pallet role may apply) | Commitments | [`Commitments.set_commitment_to`](/code/pallets/commitments/src/lib.rs#L675-L742) |

## Verify [#verify]

After inclusion, confirm the effect with the
[`channel-commitment`](/docs/query/channel-commitment) read:

```bash
btcli query channel-commitment --netuid <integer> --mechid <integer> --channel <integer> --hotkey <ss58|name> --json
```

## Parameters [#parameters]

| Parameter      | Type    | Required | Description                                                          |
| -------------- | ------- | -------- | -------------------------------------------------------------------- |
| `netuid`       | integer | yes      | Subnet containing the target mechanism and hotkey.                   |
| `mechid`       | integer | no       | Mechanism whose commitment channel to use.                           |
| `channel`      | integer | no       | Independent commitment channel; separate from the legacy commitment. |
| `data`         | string  | no       | Commitment bytes as UTF-8 or hex; empty plaintext clears.            |
| `max_burn_tao` | number  | no       | Maximum current TAO burn accepted; never a tip or reserve.           |
| `hotkey_ss58`  | string  | no       | Hotkey publishing the commitment; defaults to the wallet's hotkey.   |
| `encoding`     | string  | no       | Payload encoding: 'utf8' or 'hex'.                                   |
| `reveal_round` | integer | no       | Future drand round for a timelocked commitment; omit for plaintext.  |

Address parameters (`--hotkey`, `--coldkey`, `--dest`, ...) accept a raw ss58
address, an address-book or proxy-book name, or a local wallet/hotkey name.

## CLI [#cli]

Preview with `--dry-run` (shows fee, effects, and policy result without
submitting), then submit:

```bash
btcli tx set-channel-commitment \
  --netuid <int> --dry-run
btcli tx set-channel-commitment \
  --netuid <int> -w my_coldkey
```

## Python [#python]

```python
import bittensor as bt
from bittensor.wallet import Wallet

wallet = Wallet(name="my_coldkey", hotkey="my_hotkey")
intent = bt.SetChannelCommitment(netuid=1)

sub = bt.Subtensor()
plan = sub.plan(intent, wallet)   # fee, effects, policy — no submission
result = sub.execute(intent, wallet)
if not result.success:
    print(result.error.code, result.error.remediation)
```

(`bt.Subtensor` is also the async client — `async with bt.Subtensor() as client:`
— see [The client](/docs/concepts/client).) Or build the intent by op name, as
an agent would:

```python
result = sub.execute_tool("set_channel_commitment", {...}, wallet)
```

## On-chain implementation [#on-chain-implementation]

`Commitments.set_commitment_to` — [`pallets/commitments/src/lib.rs#L683`](/code/pallets/commitments/src/lib.rs#L675-L742):

```rust
#[pallet::call_index(3)]
#[pallet::weight((
    Pallet::<T>::set_commitment_to_base_weight()
        .saturating_add(T::CommitBurn::payment_weight()),
    DispatchClass::Normal,
    Pays::Yes
))]
#[frame_support::transactional]
pub fn set_commitment_to(
    origin: OriginFor<T>,
    netuid: NetUid,
    mecid: MechId,
    channel: u8,
    hotkey: T::AccountId,
    info: Box<CommitmentInfo<T::MaxFields>>,
    max_burn: TaoBalance,
) -> DispatchResultWithPostInfo {
    let coldkey = ensure_signed(origin)?;
    T::CommitBurn::ensure_mechanism(netuid, mecid)
        .map_err(|_| Error::<T>::MechanismDoesNotExist)?;
    T::CanCommit::validate(netuid, &hotkey)
        .map_err(|_| Error::<T>::AccountNotAllowedCommit)?;
    T::CommitBurn::ensure_coldkey_hotkey(netuid, &coldkey, &hotkey)
        .map_err(|_| Error::<T>::AccountNotAuthorized)?;
    ensure!(
        !Self::channel_migration_pending(netuid, &hotkey),
        Error::<T>::ChannelMigrationPending
    );

    let burn_config = T::CommitBurn::current_price(netuid, mecid, channel);
    let (tao, alpha_recycled, new_price, seq) = if let Some(config) = burn_config {
        ensure!(config.burn <= max_burn, Error::<T>::BurnPriceLimitExceeded);
        let alpha_recycled = T::CommitBurn::pay(netuid, &coldkey, &hotkey, config.burn)
            .map_err(Into::<sp_runtime::DispatchError>::into)?;
        T::CommitBurn::bump(netuid, mecid, channel);
        let new_price = T::CommitBurn::current_price(netuid, mecid, channel)
            .map_or(TaoBalance::ZERO, |updated| updated.burn);
        let seq = CommitBurnSequence::<T>::mutate(
            (Self::target_index(netuid, mecid), channel),
            |sequence| {
                *sequence = sequence.saturating_add(1);
                *sequence
            },
        );
        (config.burn, alpha_recycled, new_price, seq)
    } else {
        (TaoBalance::ZERO, AlphaBalance::ZERO, TaoBalance::ZERO, 0)
    };

    Self::put_channel_commitment(netuid, mecid, channel, &hotkey, &coldkey, *info.clone())?;
    let content_hash = BlakeTwo256::hash(&info.encode()).to_fixed_bytes();
    Self::deposit_event(Event::CommitmentBurned {
        netuid,
        mecid,
        channel,
        hotkey,
        coldkey,
        tao,
        alpha_recycled,
        new_price,
        seq,
        content_hash,
    });
    Ok(burn_config
        .is_none()
        .then(Self::set_commitment_to_base_weight)
        .into())
}
```

Delegates to [`channel_migration_pending`](/code/pallets/commitments/src/lib.rs#L1622).

Every file is browsable under [/code](/code) exactly as built into the runtime, or as plain text under `/code/raw/<path>` (index: [`/code/index.json`](/code/index.json)).
