Multi-Sig & Account Permissions

マルチシグとアカウント権限

TRON のネイティブな 3 階層の権限モデル（Owner、Active、Witness）を、プロトコルレベルに組み込まれたマルチシグ対応で管理します。外部コントラクトは不要です。キー、しきい値、操作範囲を設定し、提案 → 承認 → 実行のフローで複数署名トランザクションを調整します。

---

クイックスタート

ウォレットが必要です： まず agent-wallet list を実行してください。
ウォレットが存在しない場合は、先に bankofai-guide（セクション C — Wallet Guard）を呼び出してください。

cd multisig-permissions && npm install
export TRON_PRIVATE_KEY="<your-private-key>"
export TRON_NETWORK="mainnet"

署名者固有のコマンドを使用する前に、設定済みのキーからアドレスを導出し、そのアドレスがオンチェーン上の意図した owner / active ロールと一致することを確認してください。TRON_PRIVATE_KEY や TRON_HUMAN_PRIVATE_KEY のような変数名は単なるラベルです。実際の署名者ロールは、現在のアカウント権限セットにおける導出済みアドレスによって決まります。

注意

owner 権限の設定を誤ると、復旧手段がなく、アカウントが永久にロックされるおそれがあります。必ず最初に --dry-run を使用し、新しいしきい値を満たすだけのキーを管理していることを確認してください。

---

利用可能なスクリプト

スクリプト	目的	読み取り／書き込み
status.js	現在の権限設定を表示	読み取り専用
update.js	アカウント権限を変更（キー、しきい値、範囲の追加・削除）	書き込み
propose.js	マルチシグトランザクションの提案を作成	書き込み
approve.js	保留中の提案に署名を追加	書き込み
execute.js	署名がそろったトランザクションをブロードキャスト	書き込み
pending.js	保留中のマルチシグ提案を一覧表示	読み取り専用
review.js	人間向け CLI：1 つのツールで提案の一覧表示、確認、共同署名、実行を行う	書き込み

---

TRON の権限モデル

すべての TRON アカウントには、次の 3 つの権限階層があります。

権限	種類	目的	デフォルト
Owner	0	全権限。ほかの権限を変更できる唯一の権限です。	アカウントキー、しきい値 1
Active	2	日常的な操作。特定のトランザクション種別に範囲を限定できます。	アカウントキー、しきい値 1、すべての操作
Witness	1	ブロック生成（スーパー代表者のみ）。	未設定

各権限には、キー（アドレスとウェイトのペア）としきい値（承認に必要なウェイトの合計最小値）があります。例：各ウェイトが 1 のキー 3 つとしきい値 2 の組み合わせは、2-of-3 マルチシグです。

---

使用パターン

パターン 1：アカウントのセキュリティを確認する

# Check your own account
node scripts/status.js

# Check any account
node scripts/status.js TXk8rQSAvPvBBNtqSoY3UkFdpMTMbqRMKU

パターン 2：マルチシグを設定する（2-of-3）

# Step 1: Preview changes (always dry-run first!)
node scripts/update.js add-key TKey2Address... --permission owner --weight 1 --dry-run
node scripts/update.js add-key TKey3Address... --permission owner --weight 1 --dry-run
node scripts/update.js set-threshold 2 --permission owner --dry-run

# Step 2: Or use a template for all at once
node scripts/update.js from-template basic-2of3 \
  --key1 TKey1... --key2 TKey2... --key3 TKey3... --dry-run

# Step 3: Execute when satisfied
node scripts/update.js from-template basic-2of3 \
  --key1 TKey1... --key2 TKey2... --key3 TKey3...

パターン 3：エージェントを DeFi のみに制限する

# Preview the restricted owner + active configuration
node scripts/update.js from-template agent-restricted \
  --key1 THumanKey... --key2 TBackupKey... --key3 TAgentKey... --dry-run

# Apply it from a single-owner account
node scripts/update.js from-template agent-restricted \
  --key1 THumanKey... --key2 TBackupKey... --key3 TAgentKey...

# If the current owner is already multi-sig, update.js creates a pending owner
# proposal instead of broadcasting directly. Finish it through the normal flow.
node scripts/approve.js prop_xxxxx_xxxx
node scripts/execute.js prop_xxxxx_xxxx

パターン 4：マルチシグトランザクションのフロー

# Signer 1: Propose a transfer
node scripts/propose.js transfer TRecipient... 10000 --memo "Q1 budget"

# Signer 2: Review and approve
node scripts/approve.js prop_1709312400_a3f2

# Any signer: Execute when threshold is met
node scripts/execute.js prop_1709312400_a3f2

# Check all pending proposals
node scripts/pending.js

パターン 5：ハイブリッド署名（人間 + エージェント）

review.js スクリプトは、人間がエージェント作成の提案を一覧表示、確認、共同署名、実行するための単一の CLI ツールです。人間用とエージェント用のキーを混同しないよう、TRON_PRIVATE_KEY ではなく TRON_HUMAN_PRIVATE_KEY を使用します。

# Agent (Key B) proposes a transfer from its own account (uses TRON_PRIVATE_KEY):
node scripts/propose.js transfer TRecipient... 500 --memo "Q1 vendor payment"
# → Outputs proposal ID: prop_1710345600_b7e4

# Agent (Key B) proposes an active-scoped contract call for a controlled
# multi-sig account. --account identifies the controlled account.
node scripts/propose.js contract-call TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj \
  "approve(address,uint256)" '["TSpender...","1000000"]' \
  --permission active \
  --account TControlledMultisig...

# Human (Key A) reviews all pending proposals (no key needed):
node scripts/review.js

# Human inspects a specific proposal (read-only, no key needed):
node scripts/review.js prop_1710345600_b7e4

# Human co-signs after verifying details (uses TRON_HUMAN_PRIVATE_KEY):
export TRON_HUMAN_PRIVATE_KEY="<human-key>"
node scripts/review.js prop_1710345600_b7e4 --sign

# Human co-signs AND broadcasts in one step:
node scripts/review.js prop_1710345600_b7e4 --sign --execute

パターン 6：Active 権限の操作範囲を設定する

# Restrict active permission to only TRX transfers and smart contract calls
node scripts/update.js scope-active --id 2 \
  --operations TransferContract,TriggerSmartContract --dry-run

---

権限テンプレート

テンプレートでは --keyN フラグを使用して、アドレスを名前付きロールに割り当てます。キー番号は owner と active のロール全体で（重複を除き、owner を先に）順番に割り当てられます。--role_name を直接使用することもできます（例：--agent_key TAddr...）。

テンプレート	設定	キーの対応	説明
basic-2of3	owner は 2-of-3、active は 1-of-1（すべての操作）	--key1=KEY_1、--key2=KEY_2、--key3=KEY_3	標準的なマルチシグ
agent-restricted	owner は 2-of-2、active は 1-of-1（TriggerSmartContract のみ）	--key1=HUMAN_KEY、--key2=BACKUP_KEY、--key3=AGENT_KEY	エージェントはコントラクトの呼び出しのみ可能
team-tiered	owner は 3-of-5、active は 2-of-3（送金 + コントラクト）	--key1..--key5=KEY_1..KEY_5	階層型アクセス権を持つチーム
weighted-authority	しきい値 3：primary（ウェイト 2）+ secondary（ウェイト 1）	--key1=PRIMARY_KEY、--key2=SECONDARY_1、--key3=SECONDARY_2	ウェイト付きキー権限

---

トランザクションの種類（操作）

scope-active --operations で使用します。

操作	説明
TransferContract	TRX を送金します
TransferAssetContract	TRC10 トークンを送金します
TriggerSmartContract	任意のスマートコントラクトを呼び出します（DeFi、トークンなど）
FreezeBalanceV2Contract	エネルギー／帯域幅を得るために TRX をステーキングします
UnfreezeBalanceV2Contract	TRX のステーキングを解除します
DelegateResourceContract	エネルギー／帯域幅を委任します
VoteWitnessContract	スーパー代表に投票します
AccountPermissionUpdateContract	権限を変更します（Active では非常に危険です）

全リストについては、resources/permission_config.json を参照してください。

---

セキュリティルール

警告

ロックアウトの防止：新しいしきい値がキーの合計ウェイトを超える場合、update.js スクリプトは実行を拒否します。ただし、実際にキーを制御できることを必ず確認してください。スクリプトでは確認できません。

1. 必ず最初にドライランを実行してください：すべての書き込み操作で --dry-run を使用できます。
2. オーナーの変更は取り消せません：権限を変更できるのはオーナーキーセットだけです。自分をロックアウトすると、アカウントは永久に失われます。
3. キーを制御できることを確認してください：オーナー権限を変更する前に、新しいしきい値を満たすのに十分なキーにアクセスできることを確認してください。
4. アクティブ権限の範囲を限定してください：エージェントにすべての操作へのアクセス権を与えないでください。scope-active を使って TriggerSmartContract に限定してください。
5. 提案には有効期限があります：デフォルトの有効期限は 24 時間です。期限切れの提案は実行できません。
6. 署名者の役割を明示的に確認してください：approve.js、review.js --sign、またはアクティブ権限の範囲を指定した propose.js --account の呼び出しを行う前に、設定された秘密鍵から導出されるアドレスが、対象の権限ブロックに実際に含まれていることを確認してください。

---

マルチシグ提案の保存

提案はローカルの ~/.clawdbot/multisig/pending/ に JSON ファイルとして保存されます。実行後は ~/.clawdbot/multisig/executed/ にアーカイブされます。

複数人で利用する場合は、同じファイルシステムにアクセスできる共同署名者と提案 ID を共有するか、提案の JSON ファイルをコピーして渡してください。

---

よくある問題

「LOCKOUT DANGER: threshold exceeds total key weight」

スクリプトが危険な権限変更を防止しました。しきい値を下げるか、キーを追加してください。

「Account not found or not activated」

そのアドレスにはオンチェーンアカウントがありません。アカウントを有効化するには、少なくとも 0.1 TRX を送金してください。

「Proposal has expired」

提案の 24 時間の有効期間が過ぎています。propose.js で新しい提案を作成してください。

「Threshold not met」

提案にはさらに署名が必要です。pending.js で必要な残りのウェイトを確認してください。

---

環境変数

変数	必須	説明
TRON_PRIVATE_KEY	はい（書き込みスクリプト）	propose.js、approve.js、execute.js、update.js が使用する秘密鍵です。導出されたアドレスは、対象のオーナーまたはアクティブな署名者の役割と一致する必要があります。
TRON_HUMAN_PRIVATE_KEY	はい（review.js --sign）	review.js --sign が使用する秘密鍵です。変数名だけで判断せず、人間のレビュー担当者のキーを設定し、導出されたアドレスで検証してください。
TRON_NETWORK	いいえ（デフォルト：mainnet）	mainnet、nile、または shasta
TRONGRID_API_KEY	いいえ	レート制限を緩和するための TronGrid API キー

---

バージョン 1.0.0 — Bank of AI 向けに M2M Agent Registry が作成