Agent Key:把主账户的权限,收进一把可撤销的钥匙 Agent Key: delegated authority in a key you can revoke
Agent 不应该拿着主人的私钥到处跑。Agent Key 用三个权限档位、一本统一额度账本和一笔撤销交易,把「能让 AI 做什么」变成链上可验证的边界。本文沿着注册、执行、撤销三条路径,拆开这条授权链。 An agent should never carry its owner's private key. Agent Key turns “what an AI may do” into an on-chain boundary: three permission tiers, one spend ledger, and a single revoke transaction. This essay follows the delegation chain from registration to execution to revocation.
On this page
给 Agent 一把钥匙,而不是把主账户交出去。Agent Key 的全部设计都围绕这一条:权限要小到够用,花销要有上限,收回要在一笔交易内完成。
01问题:Agent 需要行动,但不该持有主钥
当一个 AI 需要上传数据、续约存储订单、或者支付一笔费用时,最直接的做法是把主账户私钥交给它。这个做法把三种风险捆在了一起:密钥一旦泄露,攻击者可以转走全部余额;Agent 的行为没有链上记录可区分;出了问题只能换地址,不能只收回某一项能力。
Agent Key 把这个组合拆开。主账户仍然是唯一的所有者,Agent 得到的是一个独立密钥对,以及一组明确列出的消息权限。链上会记录这把 key 属于谁、能做什么、什么时候过期、已经花了多少。任何一项都不依赖调用方的自觉。
02三个档位,覆盖三种风险
权限不是按接口逐个勾选,而是按「这笔操作会带来什么后果」分成三档。当前链上只认这三个名字,其他值一律拒绝。这个表同时是执行时的消息映射和注册时的授权清单,所以两者不会漂移。
| 档位 | 解锁的消息 | 它意味着什么 |
|---|---|---|
write_data | MsgCreateIntent、MsgBatchCommit、MsgFinalizeDeal、MsgPutKeyEnvelope | 生产数据并发布读取密钥:建单、提交矿工回执、结算、写密钥信封。 |
manage_data | MsgRenewDeal、MsgTerminateDeal、MsgTransferIntent、MsgCreateCollection、MsgAppendRecord | 管理已经存在的数据:续约、终止、转交 intent、集合与记录。 |
transfer_funds | MsgSend | 从主账户转出资金。每一笔都和存储费用记在同一本额度账本上。 |
三个档位可以组合。一个只负责上传的 Agent 通常只需要 write_data;一个负责长期维护的 Agent 需要 write_data 加 manage_data;只有确实需要付款时才加上 transfer_funds。治理、参数修改、矿工管理这类消息不在任何档位里,Agent 永远发不出去。
链上还支持把权限收窄到单个 intent,例如 manage_data:intent_…。这项能力在 AuthorizeMessage 里已经生效,但当前控制台只暴露三个普通档位。需要更细的边界时,可以直接构造带 scope 的注册消息。
03注册:一笔交易写四件事
MsgRegisterAgentKey 不是只写一条 key 记录。它在同一个 handler 里完成四件事:保存 key 本身(公钥、名称、档位、过期时间、数据范围);按档位为每一种可授权消息写入一条 authz grant;为主账户给 Agent 写入 feegrant,让 Agent 发交易时由主账户付 gas;创建额度账本,记录总额度、每日额度和已用金额。
这四件事必须一起成功。只有 key 记录而没有 grant,Agent 看起来已经注册,第一次执行就会失败;只有 grant 而没有账本,费用就失去了上限。注册是创建这些授权的唯一入口,后续的续期和改额度都只修改已有状态。
数据范围与读取密钥
v4 的注册消息新增了 data_scope。留空表示主账户把 vault key 包给 Agent,Agent 可以处理该账户下的全部数据;填入 collection id 列表时,主账户改为按集合逐个包 collection key,Agent 只能解开列出的集合。两者都要求同时提交包裹后的密钥和 nonce,缺一半会被直接拒绝——半个授权比没有授权更危险,因为 Agent 会看起来配置完成,直到第一次解密才失败。
要注意,读取本身不需要 Agent Key。密钥信封在链上,任何拿到对应私钥的一方都能解密。Agent Key 管的是「以主账户名义写链」和「从主账户花钱」,不是读取的准入控制。
04执行:Agent 签名,主账户付费
Agent 不直接签一条普通 Cosmos 交易。它把要执行的消息交给网关的 POST /tx/exec,网关组装一条 authz MsgExec:外层由 Agent 账户签名,内层消息的 signer 固定为主账户,fee granter 也是主账户。这样链上的授权检查只有一条路径:authz 确认主账户确实授权过这条消息,额度账本确认这次花销没有超限。
网关返回未签名交易和 sign_doc。Agent 用自己的私钥对 keccak256(sign_doc) 做 ethsecp256k1 签名,再把 tx_bytes、签名和公钥交回 POST /tx/broadcast。签名模式是 SIGN_MODE_DIRECT,与 Cosmos EVM 的账户签名一致。
{
"agent_key_id": "key_7f3a…",
"messages": [{
"type_url": "/falari.storage.v1.MsgCreateIntent",
"value": {
"signer": "<master account>",
"file_name": "notes.md",
"file_size": 1048576,
"segment_size": 4194304,
"segment_roots": ["…"],
"erasure": { "data_shards": 4, "parity_shards": 2 },
"policy": { "duration": 2592000 }
}
}],
"gas": 400000,
"fee": "2000000000000000wei",
"memo": "agent upload"
}
内层消息的 signer 不能被 Agent 换成别的账户。网关在组装时就会用 key 记录里的 master 校验每个消息的签名者,链上还会再检查一次。因此一把 Agent Key 只能替它的主人行动,不能变成通用代签工具。
05额度:一本账,两种上限
额度账本只有一份,单位是 wei。total_limit 约束这把 key 一生可以花多少,daily_limit 约束一个 UTC 自然日内可以花多少。两者互相独立:总额度用完,日额度还有也没用;日额度用完,总额度还有也要等到次日 UTC 零点。
数值 0 表示不限,而不是「不能花」。这是一个容易读反的约定,查询接口会把它映射成 remaining = -1。调低额度时,新上限不能低于已经用掉的金额,否则会直接拒绝;已用的计数只增不减,不提供退款或回冲。
存储费用、gas 和 MsgSend 共用这一本账。这意味着「给 Agent 每天 10 FAR」是一句完整的话:不管它拿去上传、续约还是转账,合计都不会超过 10 FAR。查询入口是 GET /agent-keys/{id}/allowance,返回总额度、今日已用、剩余和下一次 UTC 日切时间。
06撤销、过期,以及撤不回的部分
MsgRevokeAgentKey 在一个 handler 里做三件清理:删掉 Agent 在主账户名下的全部 authz grant,撤销 feegrant,把额度账本标记为 revoked。重复撤销是安全的:如果上一次只改了状态、没来得及清 grant,再发一次会继续把残留清干净。撤销后,这把 key 既不能构造新交易,也不能再产生任何花费。
过期是另一条路径。key 记录带 expires_at_unix,为 0 表示不过期;到期后 /tx/exec 会拒绝,主账户可以用 MsgExtendAgentKey 把有效期往后推,并把状态从 expired 改回 active。撤销不可逆,过期可续期,这是两者最重要的区别。
2026 年的 agentkey-tiers-v1 升级把旧的逐接口权限收敛成三档。迁移没有尝试猜测每把旧 key 该映射到哪一档:它把这些 key 直接置为 revoked、清空 permissions,并同步删除授权、gas 代付与额度记录。记录本身保留下来,钱包可以告诉持有人「因权限模型升级已作废,请重新签发」,而不是让 key 从列表里悄悄消失。
撤销收回的是链上权限,不是已经发生的知识。Agent 已经解出的 Data Key、已经读进上下文的明文、已经转发出去的副本,都不会因为一笔撤销交易而消失。真正的强撤销是换 Data Key 并重新加密上传;Agent Key 的撤销只保证「从现在起不能再以主账户名义行动」。
07使用清单
- 一个任务一把 key。不要让同一个 Agent 同时拥有上传、续约和转账权限;任务结束时撤销,而不是复用。
- 先给短的过期时间。过期比撤销更容易提前规划,也更不容易忘记。
- 额度按业务上限设,不按余额设。账本的意义是限制损失,不是允许 Agent 花光账户。
- 主私钥不进提示词、不进上下文、不进日志。Agent 只需要自己的私钥;主账户的签名只在注册、续期、撤销时出现。
- 把
GET /agent-keys和额度查询接进监控。异常花费通常先体现在账本上,而不是在交易失败时。
Agent Key 不试图判断一个 Agent 是否「可信」。它只做一件更可验证的事:把主人愿意让渡的那部分权力写清楚,并保留随时收回的能力。
Give an agent a key, not the account. Every design decision in Agent Key follows from that: permissions small enough to be useful, spending with a ceiling, and revocation that finishes in one transaction.
01The problem: agents must act, not hold the master key
When an AI needs to upload data, renew a storage deal, or pay a fee, the shortest path is to hand it the master private key. That bundles three risks together: one leak exposes the entire balance; the agent's actions are indistinguishable from the owner's; and the only remedy is to rotate the account, not to withdraw a single capability.
Agent Key separates those concerns. The master account remains the only owner. The agent receives an independent key pair and an explicit list of message permissions. The chain records who the key belongs to, what it may do, when it expires, and how much it has spent. None of that depends on the caller's good behaviour.
02Three tiers for three kinds of risk
Permissions are not toggles per RPC. They are grouped by the consequence of the action. The chain recognises exactly three names; anything else is rejected. The same table drives the execution-time message map and the grants installed at registration, so the two cannot drift apart.
| Tier | Messages unlocked | What it means |
|---|---|---|
write_data | MsgCreateIntent, MsgBatchCommit, MsgFinalizeDeal, MsgPutKeyEnvelope | Produce data and publish the key to read it: create intents, commit miner receipts, finalize, write key envelopes. |
manage_data | MsgRenewDeal, MsgTerminateDeal, MsgTransferIntent, MsgCreateCollection, MsgAppendRecord | Manage data that already exists: renew, terminate, hand an intent to another account, collections and records. |
transfer_funds | MsgSend | Move money out of the master account. Every spend shares one ledger with storage fees. |
Tiers compose. An upload-only agent usually needs write_data; a long-running maintenance agent needs write_data plus manage_data; add transfer_funds only when the agent genuinely has to pay. Governance, parameter changes, and miner management are in no tier at all. An agent can never send them.
The chain also accepts a permission scoped to one intent, such as manage_data:intent_…. AuthorizeMessage already enforces it, although the current console exposes only the three plain tiers. Clients that need a narrower boundary can construct the scoped registration message directly.
03Registration writes four things in one transaction
MsgRegisterAgentKey is not just a key record. In one handler it stores the key itself (public key, name, tiers, expiry, data scope); installs one authz grant per message type the tiers cover; writes a feegrant from the master so the agent's transactions are paid for; and creates the allowance ledger with total, daily, and used amounts.
All four must succeed together. A key without grants looks registered and fails on its first action. Grants without a ledger remove the spending ceiling. Registration is the only place these authorisations are created; renewal and limit changes only modify existing state.
Data scope and read keys
The v4 registration message adds data_scope. Empty means the master wraps the vault key for the agent, which can then work with all of the account's data. A list of collection ids means the master wraps one collection key per listed collection, and the agent can open only those. Both forms require the wrapped key and its nonce together. Half a grant is worse than none: the agent would look provisioned and fail at the first decryption.
Reading does not require an Agent Key. Key envelopes live on chain, and anyone holding the matching private key can decrypt them. Agent Key governs writing to the chain as the master and spending the master's money, not read admission.
04Execution: the agent signs, the master pays
The agent does not sign an ordinary Cosmos transaction. It submits the messages to the gateway's POST /tx/exec, which builds an authz MsgExec: the outer transaction is signed by the agent account, every inner message names the master as its signer, and the fee granter is the master. On chain there is only one authorisation path: authz confirms the master granted that message, and the ledger confirms the spend is within its limits.
The gateway returns the unsigned transaction and a sign_doc. The agent signs keccak256(sign_doc) with ethsecp256k1 and sends tx_bytes, signature, and public key back to POST /tx/broadcast. The mode is SIGN_MODE_DIRECT, matching Cosmos EVM account signatures.
{
"agent_key_id": "key_7f3a…",
"messages": [{
"type_url": "/falari.storage.v1.MsgCreateIntent",
"value": {
"signer": "<master account>",
"file_name": "notes.md",
"file_size": 1048576,
"segment_size": 4194304,
"segment_roots": ["…"],
"erasure": { "data_shards": 4, "parity_shards": 2 },
"policy": { "duration": 2592000 }
}
}],
"gas": 400000,
"fee": "2000000000000000wei",
"memo": "agent upload"
}
An agent cannot redirect an inner message to another account. The gateway checks every signer against the master stored in the key record, and the chain checks again. An Agent Key can act only for its owner; it is not a general-purpose signing proxy.
05Allowance: one ledger, two ceilings
There is exactly one ledger, denominated in wei. total_limit bounds what the key may spend over its lifetime; daily_limit bounds one UTC day. They are independent: a spent-out total cannot be revived by a fresh daily allowance, and a spent-out day waits for the next UTC midnight even if the total has room.
Zero means unlimited, not “cannot spend.” That convention is easy to read backwards, so the query surface maps it to remaining = -1. A new limit below the amount already used is rejected. Usage only grows; there is no refund or credit-back.
Storage fees, gas, and MsgSend share the ledger. “Ten FAR per day for this agent” is therefore a complete sentence: whether it uploads, renews, or transfers, the combined spend stays under ten. GET /agent-keys/{id}/allowance returns the limits, today's usage, the remainder, and the next UTC reset.
06Revocation, expiry, and what cannot be taken back
MsgRevokeAgentKey performs three cleanups in one handler: it deletes every authz grant the agent holds from the master, revokes the feegrant, and marks the ledger revoked. Repeating a revoke is safe: if an earlier attempt changed the status but failed before dropping a grant, a second call finishes the cleanup. Afterwards the key can build no transaction and incur no spend.
Expiry is the other path. The key record carries expires_at_unix, where zero means no expiry. Once it passes, /tx/exec refuses the key; the master can extend it with MsgExtendAgentKey, which also moves an expired key back to active. Revocation is irreversible; expiry is renewable.
The 2026 agentkey-tiers-v1 upgrade collapsed the old per-RPC permissions into three tiers. The migration does not guess how each legacy key should map: it marks those keys revoked, clears their permissions, and removes the authz grant, fee allowance, and ledger in the same pass. The record stays so a wallet can say “retired by the tier upgrade — issue a new one” instead of letting the key vanish from the list.
Revocation withdraws on-chain authority, not knowledge. Data keys the agent already unwrapped, plaintext already in its context, and copies already forwarded do not disappear because of a revoke transaction. A hard revocation means rotating the Data Key and re-uploading encrypted data. Agent Key revocation only guarantees that the agent can no longer act as the master from that moment on.
07A short operating checklist
- One key per task. Do not give one agent upload, renewal, and transfer rights at once. Revoke when the task ends instead of reusing.
- Start with a short expiry. Expiry is easier to plan than revocation and harder to forget.
- Set limits by business ceiling, not by balance. The ledger exists to cap loss, not to let the agent drain the account.
- Keep the master key out of prompts, context, and logs. The agent needs only its own key; the master signs at registration, renewal, and revocation.
- Monitor
GET /agent-keysand the allowance. Anomalous spending usually shows up in the ledger before it shows up as a failed transaction.
Agent Key does not try to decide whether an agent is trustworthy. It does something more checkable: it writes down exactly which powers the owner is lending, and keeps the ability to take them back.
Sources
- evm/x/agentkey/types/permissions.go — tier table and message map
- evm/x/agentkey/keeper/msg_server.go — registration and revocation
- evm/x/agentkey/keeper/allowance.go — unified spend ledger
- evm/gateway/relay.go —
/tx/execand/tx/broadcast - docs/development/12-agent-keys.md · 27-agent-data-quota.md