@keymaster/connect / ProtocolFeePoolRecord

Interface: ProtocolFeePoolRecord

费用池持久化记录。

设计缘由（V4 收口 + 施工单 2026-06-28 002 硬切换）：feepool 真实模型是两笔 tx：

• A-Tx（base tx，建池时定）：client P2PKH UTXO → 2-of-2 multisig output， 池大小 = multisig output 总额 = feePoolDefaultFundSatoshis。
• B-Tx（draft 草稿，持续协商）：multisig output → server + client change。 每次 transfer 不再独立发一笔新 draftTx，而是在同一个 B-Tx 草稿上 更新 serverAmount 字段；只有 close 时把草稿切到 FINAL_LOCKTIME 最终版本，broadcast 后真正生效。

totalAmount vs serverAmount 语义（V4 明确）：

• totalAmount = 池大小 = base tx multisig output 总额。
• serverAmount = 当前已累计分配给 server 的金额 （prior.serverAmount + amountSatoshis 的累加结果）；永远 <= totalAmount。
• 决策：若 prior.serverAmount + amountSatoshis <= prior.totalAmount → spend（在旧 B-Tx 草稿上 update）；否则 close_and_recreate。
• key 必须包含 ownerPublicKeyHex + counterpartyPublicKeyHex： 同一 origin 不同 owner 不能串池（不同 connect session 是不同 owner）； 同一 origin 同一 owner 但对端公钥切换 → 新池。
• key 格式： ${origin}::${ownerPublicKeyHex}::${counterpartyPublicKeyHex}； :: 不可能出现在 origin / publicKeyHex 字符串里，碰撞风险极低。

Properties overview

Property	Type	Required	Description
poolKey	string	Yes	复合 key。
origin	string	Yes	—
ownerPublicKeyHex	string	Yes	绑定该池的 connect session owner 的公钥 hex。
counterpartyPublicKeyHex	string	Yes	—
baseTxid	string	Yes	base tx txid（2-of-2 multisig output 在这里）。
baseTxHex	string	Yes	base tx raw hex。
totalAmount	number	Yes	池大小（satoshis）= base tx multisig output 总额 = feePoolDefaultFundSatoshis。
serverAmount	number	Yes	累计已分配给 server 的金额（satoshis）。
draftSpendTxHex	string	Yes	当前 B-Tx 草稿 hex（site 与 server 持续协商的对象；当前草稿，不是真广播）。
draftClientSignBytes	BinaryField	Yes	当前 B-Tx 草稿上的 client 部分签名。
lastOperationId	string	Yes	产生这条记录的最后一次 operation id。
updatedAt	number	Yes	—

Properties

poolKey

poolKey: string

复合 key。施工单 2026-06-28 002 硬切换：补 ownerPublicKeyHex 维度， 不再仅按 origin + counterpartyPublicKeyHex 归档。 格式：${origin}::${ownerPublicKeyHex}::${counterpartyPublicKeyHex}。

---

origin

origin: string

---

ownerPublicKeyHex

ownerPublicKeyHex: string

绑定该池的 connect session owner 的公钥 hex。

---

counterpartyPublicKeyHex

counterpartyPublicKeyHex: string

---

baseTxid

baseTxid: string

base tx txid（2-of-2 multisig output 在这里）。

---

baseTxHex

baseTxHex: string

base tx raw hex。

---

totalAmount

totalAmount: number

池大小（satoshis）= base tx multisig output 总额 = feePoolDefaultFundSatoshis。

---

serverAmount

serverAmount: number

累计已分配给 server 的金额（satoshis）。

• create：第一次 transfer 后 = amountSatoshis。
• spend：每次在 prior 基础上累加（prior.serverAmount + amountSatoshis）。
• close_and_recreate：旧池被关时 = prior.serverAmount + amountSatoshis； 新池被建时 = amountSatoshis（新池重新从 0 开始累计）。

---

draftSpendTxHex

draftSpendTxHex: string

当前 B-Tx 草稿 hex（site 与 server 持续协商的对象；当前草稿，不是真广播）。

---

draftClientSignBytes

draftClientSignBytes: BinaryField

当前 B-Tx 草稿上的 client 部分签名。

---

lastOperationId

lastOperationId: string

产生这条记录的最后一次 operation id。

---

updatedAt

updatedAt: number