SenditBank

模型

• 账户。账户是一个钱包地址（或任何作为自身账户行事的合约）。余额是 balanceOf[account][asset]，从不以密钥为键。
• 资产。pUSD、以 address(0) 表示的 ETH，以及运营者添加的发行器所发行的代币（isAsset）。其他任何代币都会被拒绝。totalHeld[asset] 是所有余额的精确总和，从不超过银行实际持有的数量。
• 密钥。账户用一份由密钥签名的证明登记的地址。密钥可以在场所花费账户的余额、转账、提取到账户自己的钱包、为自己补充 gas 以及撤销。它不能登记密钥、修改上限，也不能 withdrawTo 另一个地址。
• 场所。被允许从账户扣款的合约：引擎、订单簿、金库、跟单工厂、现货路由器、pUSD 兑换合约。每个场所都以自己的调用者调用 bank.pull(msg.sender, asset, amount)，所以场所无法指定拿谁的钱。每一笔支付都通过 bank.push(account, ...) 返回，从不付给签名者。

没有 receive()，没有清扫，没有余额修改，不可升级，也不收费。ETH 只通过 deposit 和 push 进入。

账户与 accountOf

accountOf(sender) 是发送者所代表的账户：当 sender 是在该账户当前 keyEpoch 和当前 globalEpoch 下登记的密钥时，返回所有者；否则返回 sender 本身。所以钱包解析为它自己，每个场所也都能用钱包签名来使用。仓位、金库份额、跟单账户以及每一个事件记录的都是账户，从不是密钥。

当 accountOf(keyOf(account)) != account 时，密钥已失效。这里没有 playerOf：那是街机银行合约对同一概念的称呼。

密钥证明

密钥通过签署一个摘要，表示同意为该账户服务：

keyDigest(account, key) = keccak256(abi.encode(
  "SENDIT/key-proof/v1", block.chainid, address(bank), account, key,
  keyEpoch[account], globalEpoch))

证明是密钥对这 32 字节的 EIP-191 签名（"\x19Ethereum Signed Message:\n32" || digest）：65 字节，low s，v 为 27 或 28（也接受 0 和 1）。随后钱包用 setKey(key, proof) 发送它，或放在 deposit(pusdAmount, gasToKey, key, proof) 中发送，后者还能在同一笔交易里为密钥注入 gas。

import { encodeAbiParameters, parseAbiParameters, keccak256 } from "viem";
import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";

const key = privateKeyToAccount(generatePrivateKey()); // keep the private key safe

// ADD a key under the epochs in force: the bank computes the digest for you.
const digest = await client.readContract({
  address: bank, abi: bankAbi, functionName: "keyDigest", args: [account, key.address],
});
const proof = await key.signMessage({ message: { raw: digest } }); // EIP-191, 32 bytes

// REPLACE every key of the account: the same digest under keyEpoch + 1.
const [epoch, global] = await Promise.all([
  client.readContract({ address: bank, abi: bankAbi, functionName: "keyEpoch", args: [account] }),
  client.readContract({ address: bank, abi: bankAbi, functionName: "globalEpoch" }),
]);
const nextDigest = keccak256(encodeAbiParameters(
  parseAbiParameters("string, uint256, address, address, address, uint64, uint64"),
  ["SENDIT/key-proof/v1", 78270n, bank, account, key.address, epoch + 1n, global],
));
const replaceProof = await key.signMessage({ message: { raw: nextDigest } });

纪元：添加或替换

证明会对照两组纪元之一进行校验，校验所用的那一组决定会发生什么：

• 当前纪元：添加（ADD）。该密钥加入账户的有效密钥；其他每把密钥仍然有效（每台设备一把密钥）。
• keyEpoch + 1：替换（REPLACE）。银行先撤销（纪元前进，每把密钥都终止，发出 KeyRevoked），然后在新纪元下登记该密钥。

revokeKey() 终止账户的所有密钥；rotateKey(newKey, proof) 在一笔交易中撤销并登记，所用证明须基于新纪元。invalidateAllKeys() 推进 globalEpoch，终止银行上的所有密钥。keyOf(account) 只是最后登记的那把密钥，存入时附带的 gas 就发给它。

上限

密钥向第三方流出的 pUSD 和 ETH（send、refuel，以及受上限约束的场所发起的 pull，目前只有现货路由器）计入每个账户的每日上限，窗口为从第一笔计费流出开始的固定 24 小时。永续合约、金库和跟单不受上限约束，发行的代币也不受约束，钱包签名的调用从不计费。合约默认值为每天 10,000 pUSD 和 5 ETH；测试网部署把它们关闭了（UNCAPPED，读取 defaultCaps()）。账户可以从自己的钱包用 setKeyCaps 设置自己的上限：0 表示使用默认值。

暂停

setPaused(true) 会停止场所的 pull 和 move，以及密钥签名的 send 和 refuel。它从不停止 withdraw、withdrawTo、push（所以仓位仍能平仓，支付仍能到账）、存入、密钥的登记与撤销，也不停止钱包或合约自己发起的 send（跟单账户通过 send 向跟单者付款）。pUSD 兑换合约的两个入口都遵从银行的暂停。

场所与 24 小时延迟

场所可以通过它传入的发送者从任何账户扣款，所以场所是银行的信任根。添加一个场所先调用 proposeVenue，经过 VENUE_DELAY（24 小时）之后再调用 activateVenue：VenueProposed 事件给每个账户一天时间先行提取。listVenueNow 只在银行第一次入账之前可以跳过等待。removeVenue 立即生效，被移除的场所仍然可以 push。

函数与事件