/build/rpc / assets / governance_rotation

prepare_rotation

prepare_rotation "asset_id" Prepare a quorum-gated governance Creates a template with the new IssuerReg Holders can then sign ballots independently Arguments: 1. asset_id 2. options { "icu_payload_plain": "hex", "icu_payload": "hex", "icu_ctxt_commit": "hex", "icu_plain_commit": "hex", "kdf_salt": "hex", "icu_visibility": n, "icu_compressed": bool, "policy_quorum_bps": n, "issuance_cap_units": n, "issuance_cap": "str", "unlock_fee_bump": amount, } Result: { "psbt" : "str", "proposal_hash" : "hex", "summary" : { "issuance_cap" : "str", "quorum" : "str", "icu_visibility" : "str", "icu_text" : "str", "kdf_salt" : "str", "kyc_required" : "str", "unlock_fee_bump" : "str", "policy_epoch" : "str" }, "settled_supply" : n, "required_units" : n, "policy_quorum_bps" : n, "asset_id" : "hex" } Examples: > bitcoin-cli prepare_rotation {"icu_payload_plain":"hex","icu_payload":"hex","icu_ctxt_commit":"hex","icu_plain_commit":"hex","kdf_salt":"hex","icu_visibility":n,"icu_compressed":bool,"policy_quorum_bps":n,"issuance_cap_units":n,"issuance_cap":"str","unlock_fee_bump":amount} rotation PSBT template. and placeholder ballot outputs. using the 'ballot' RPC. (string, required) Asset ID to rotate (json object, required) Rotation parameters (string, optional) Canonical ICU plaintext bytes (will be encrypted automatically using existing DEK/salt). Preferred method for updating governance text. (string, optional) Pre-encrypted ICU payload bytes (advanced use only) (string, optional) 32-byte ciphertext commitment (string, optional) 32-byte plaintext commitment (string, optional) 16-byte encryption salt (numeric, optional) ICU visibility (0=public, 1=holder_only) (boolean, optional) Use zstd compression for ICU payload (numeric, optional) Governance quorum in basis points (numeric, optional) Issuance cap in base units (0=unlimited) (string, optional) Issuance cap expressed in asset units (e.g., "50.0"). Overrides issuance_cap_units. (numeric or string, optional, default=0.5) BTC to add to unlock_fees_base (min 0.5) (json object) (string) Base64-encoded PSBT template (string) Proposal hash binding for ballot validation (json object) Human-readable summary of IssuerReg changes (string) Issuance cap change (e.g., '100 units → 200 units' or 'unlimited (unchanged)') (string) Quorum change (e.g., '55.00% → 60.00%' or '55.00% (unchanged)') (string) ICU visibility change (e.g., 'public → holder_only' or 'public (unchanged)') (string) ICU text/commit update status (e.g., 'Updated (95.2 KB)', 'Updated (commits only)', or 'No changes') (string, optional) KDF salt update status (only shown if changed) (string, optional) KYC requirement change (only shown if changed) (string) Unlock fee increase (e.g., '+0.50 BTC') (string) Policy epoch increment (e.g., '5 → 6') (numeric) Current settled supply (issued - burned) (numeric) Minimum ballot units needed for quorum (numeric) Governance quorum threshold (string) Asset ID being rotated "asset_id" '{"icu_visibility": 1, "unlock_fee_bump": 0.5}'

Signature

prepare_rotation(asset_id: string, options: object) → any

Code samples

curl --user "$RPC_USER:$RPC_PASS" \
  --data-binary '{"jsonrpc":"1.0","id":"docs","method":"prepare_rotation","params":["\"<asset_id>\"",{}]}' \
  -H 'content-type: text/plain;' \
  http://127.0.0.1:8332/

bitcoin-cli prepare_rotation "asset_id" '{"icu_visibility": 1, "unlock_fee_bump": 0.5}'

import requests
r = requests.post(
    "http://127.0.0.1:8332/",
    auth=("$RPC_USER", "$RPC_PASS"),
    json={
        "jsonrpc": "1.0",
        "id": "docs",
        "method": "prepare_rotation",
        "params": ["\"<asset_id>\"", {}],
    },
    timeout=30,
)
print(r.json())

const res = await fetch("http://127.0.0.1:8332/", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "authorization": "Basic " + btoa(`${process.env.RPC_USER}:${process.env.RPC_PASS}`),
  },
  body: JSON.stringify({
    jsonrpc: "1.0",
    id: "docs",
    method: "prepare_rotation",
    params: ["\"<asset_id>\"",{}],
  }),
});
console.log(await res.json());

Parameters

Name	Type	Req.	Description
asset_id	`string`	yes	Asset ID to rotate
options	`object`	yes	Rotation parameters { "icu_payload_plain": "hex", (string, optional) Canonical ICU plaintext bytes (will be encrypted automatically using existing DEK/salt). Preferred method for updating governance text. "icu_payload": "hex", (string, optional) Pre-encrypted ICU payload bytes (advanced use only) "icu_ctxt_commit": "hex", (string, optional) 32-byte ciphertext commitment "icu_plain_commit": "hex", (string, optional) 32-byte plaintext commitment "kdf_salt": "hex", (string, optional) 16-byte encryption salt "icu_visibility": n, (numeric, optional) ICU visibility (0=public, 1=holder_only) "icu_compressed": bool, (boolean, optional) Use zstd compression for ICU payload "policy_quorum_bps": n, (numeric, optional) Governance quorum in basis points "issuance_cap_units": n, (numeric, optional) Issuance cap in base units (0=unlimited) "issuance_cap": "str", (string, optional) Issuance cap expressed in asset units (e.g., "50.0"). Overrides issuance_cap_units. "unlock_fee_bump": amount, (numeric or string, optional, default=0.5) BTC to add to unlock_fees_base (min 0.5) }

Result

Type: any

{ (json object) "psbt" : "str", (string) Base64-encoded PSBT template "proposal_hash" : "hex", (string) Proposal hash binding for ballot validation "summary" : { (json object) Human-readable summary of IssuerReg changes "issuance_cap" : "str", (string) Issuance cap change (e.g., '100 units → 200 units' or 'unlimited (unchanged)') "quorum" : "str", (string) Quorum change (e.g., '55.00% → 60.00%' or '55.00% (unchanged)') "icu_visibility" : "str", (string) ICU visibility change (e.g., 'public → holder_only' or 'public (unchanged)') "icu_text" : "str", (string) ICU text/commit update status (e.g., 'Updated (95.2 KB)', 'Updated (commits only)', or 'No changes') "kdf_salt" : "str", (string, optional) KDF salt update status (only shown if changed) "kyc_required" : "str", (string, optional) KYC requirement change (only shown if changed) "unlock_fee_bump" : "str", (string) Unlock fee increase (e.g., '+0.50 BTC') "policy_epoch" : "str" (string) Policy epoch increment (e.g., '5 → 6') }, "settled_supply" : n, (numeric) Current settled supply (issued - burned) "required_units" : n, (numeric) Minimum ballot units needed for quorum "policy_quorum_bps" : n, (numeric) Governance quorum threshold "asset_id" : "hex" (string) Asset ID being rotated }

Source: services/core-node/bcore/src/wallet/rpc/assets.cpp:6804

C++ symbol: prepare_rotation

Code samples

curl --user "$RPC_USER:$RPC_PASS" \
  --data-binary '{"jsonrpc":"1.0","id":"docs","method":"prepare_rotation","params":["\"<asset_id>\"",{}]}' \
  -H 'content-type: text/plain;' \
  http://127.0.0.1:8332/

bitcoin-cli prepare_rotation "asset_id" '{"icu_visibility": 1, "unlock_fee_bump": 0.5}'

import requests
r = requests.post(
    "http://127.0.0.1:8332/",
    auth=("$RPC_USER", "$RPC_PASS"),
    json={
        "jsonrpc": "1.0",
        "id": "docs",
        "method": "prepare_rotation",
        "params": ["\"<asset_id>\"", {}],
    },
    timeout=30,
)
print(r.json())

const res = await fetch("http://127.0.0.1:8332/", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "authorization": "Basic " + btoa(`${process.env.RPC_USER}:${process.env.RPC_PASS}`),
  },
  body: JSON.stringify({
    jsonrpc: "1.0",
    id: "docs",
    method: "prepare_rotation",
    params: ["\"<asset_id>\"",{}],
  }),
});
console.log(await res.json());