Multi-Sig & Account Permissions

多重签名与账户权限

使用内置的协议级多重签名支持管理 TRON 原生的三层权限模型（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：使用一个工具列出、检查、共同签署并执行提案	写入

---

TRON 权限模型

每个 TRON 账户都有三个权限层级：

权限	类型	用途	默认值
Owner	0	完全控制权。唯一可以修改其他权限的权限。	账户密钥，阈值为 1
Active	2	日常操作。可限定为特定交易类型。	账户密钥，阈值为 1，所有操作
Witness	1	生成区块（仅限超级代表）。	未设置

每项权限都有密钥（地址 + 权重对）和阈值（授权所需的最低总权重）。例如：3 个密钥的权重各为 1，阈值为 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：将 Agent 限定为仅使用 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：混合签名（人工 + Agent）

review.js 脚本是一个 CLI 工具，供人工列出、检查、共同签署并执行 Agent 创建的提案。它使用 TRON_HUMAN_PRIVATE_KEY（而非 TRON_PRIVATE_KEY），以避免混淆人工和 Agent 密钥。

# 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	2-of-3 owner，1-of-1 active（所有操作）	--key1=KEY_1，--key2=KEY_2，--key3=KEY_3	标准多重签名
agent-restricted	2-of-2 owner，1-of-1 active（仅限 TriggerSmartContract）	--key1=HUMAN_KEY，--key2=BACKUP_KEY，--key3=AGENT_KEY	Agent 只能调用合约
team-tiered	3-of-5 owner，2-of-3 active（转账 + 合约）	--key1..--key5=KEY_1..KEY_5	具有分层访问权限的团队
weighted-authority	阈值为 3：主密钥（权重 2）+ 次级密钥（权重 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. 限制 Active 权限范围：不要向 Agent 授予所有操作的访问权限。使用 scope-active 将权限限制为 TriggerSmartContract。
5. 提案会过期：默认有效期为 24 小时。过期提案无法执行。
6. 明确检查签名者角色：在调用 approve.js、review.js --sign 或任何带有 Active 权限范围的 propose.js --account 前，确认已配置的私钥所推导出的地址确实出现在相应的权限块中。

---

多签提案存储

提案以 JSON 文件形式存储在本地的 ~/.clawdbot/multisig/pending/。执行后，会归档到 ~/.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 使用的私钥。推导出的地址必须与预期的所有者或 Active 签名者角色相符。
TRON_HUMAN_PRIVATE_KEY	是（review.js --sign）	review.js --sign 使用的私钥。此处应设置为人工审核者的密钥，并通过推导出的地址进行验证，不能仅凭变量名判断。
TRON_NETWORK	否（默认：mainnet）	mainnet、nile 或 shasta
TRONGRID_API_KEY	否	用于提高速率限制的 TronGrid API 密钥

---

版本 1.0.0 — 由 M2M Agent Registry 为 Bank of AI 创建