SenditBank

Le modèle

• Comptes. Un compte est une adresse de portefeuille (ou n'importe quel contrat qui agit comme son propre compte). Les soldes sont balanceOf[account][asset], jamais indexés par une clé.
• Actifs. pUSD, l'ETH sous la forme address(0), et les jetons d'un launcher ajouté par l'opérateur (isAsset). Tout autre jeton est refusé. totalHeld[asset] est la somme exacte de tous les soldes et n'excède jamais ce que détient la banque.
• Clés. Des adresses qu'un compte a enregistrées avec une preuve signée par la clé. Une clé dépense le solde du compte auprès des venues, envoie, retire vers le propre portefeuille du compte, recharge son propre gas et révoque. Elle ne peut ni enregistrer de clés, ni changer les plafonds, ni faire un withdrawTo vers une autre adresse.
• Venues. Les contrats autorisés à débiter les comptes : le moteur, le carnet d'ordres, le coffre, la copy factory, le routeur spot, l'échange pUSD. Chacun appelle bank.pull(msg.sender, asset, amount) avec son propre appelant, si bien qu'un venue ne peut pas choisir l'argent de qui il prend. Chaque paiement revient par bank.push(account, ...), jamais vers le signataire.

Il n'y a ni receive(), ni balayage, ni modification de solde, ni mise à niveau, ni frais. L'ETH n'entre que par deposit et push.

Les comptes et accountOf

accountOf(sender) est le compte pour lequel agit un expéditeur : le propriétaire tant que sender est une clé enregistrée sous le keyEpoch actuel du compte et le globalEpoch actuel, et sender lui-même sinon. Un portefeuille se résout donc vers lui-même, et chaque venue fonctionne aussi avec une signature du portefeuille. Les positions, les parts du coffre, les comptes de copie et chaque événement désignent le compte, jamais la clé.

Une clé est périmée quand accountOf(keyOf(account)) != account. Il n'y a pas de playerOf ici : c'est le nom que la banque de l'arcade donne à la même idée.

La preuve de clé

La clé consent à servir le compte en signant un condensé :

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

La preuve est la signature EIP-191 de ces 32 octets par la clé ("\x19Ethereum Signed Message:\n32" || digest) : 65 octets, s bas, v à 27 ou 28 (0 et 1 sont acceptés). Le portefeuille l'envoie ensuite avec setKey(key, proof) ou dans deposit(pusdAmount, gasToKey, key, proof), qui peut aussi financer le gas de la clé dans la même transaction.

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 } });

Époques : ajouter ou remplacer

Une preuve est vérifiée contre l'une de deux paires d'époques, et c'est elle qui décide de ce qui se passe :

• Époques actuelles : AJOUT. La clé rejoint les clés actives du compte ; toutes les autres clés restent actives (une clé par appareil).
• keyEpoch + 1 : REMPLACEMENT. La banque révoque d'abord (l'époque avance, toutes les clés prennent fin, KeyRevoked), puis enregistre la clé sous la nouvelle époque.

revokeKey() met fin à toutes les clés du compte ; rotateKey(newKey, proof) révoque et enregistre dans une seule transaction, avec une preuve sous la nouvelle époque. invalidateAllKeys() fait avancer globalEpoch et met fin à toutes les clés de la banque. keyOf(account) n'est que la dernière clé enregistrée, celle qui reçoit le gas du dépôt.

Plafonds

Les sorties de pUSD et d'ETH d'une clé vers des tiers (send, refuel, et les prélèvements par un venue plafonné, aujourd'hui le routeur spot) s'imputent sur des plafonds quotidiens par compte, sur une fenêtre fixe de 24 heures qui démarre à la première sortie imputée. Les perps, le coffre et la copie ne sont pas plafonnés, les jetons lancés non plus, et les appels signés par le portefeuille ne sont jamais imputés. Les valeurs par défaut du contrat sont 10 000 pUSD et 5 ETH par jour ; le déploiement du testnet les a désactivées (UNCAPPED, lisez defaultCaps()). Un compte fixe les siens avec setKeyCaps depuis son portefeuille : 0 signifie la valeur par défaut.

Pause

setPaused(true) arrête le pull et le move des venues, ainsi que le send et le refuel signés par une clé. Elle n'arrête jamais withdraw, withdrawTo, push (les positions se ferment donc toujours et les paiements arrivent), les dépôts, l'enregistrement et la révocation des clés, ni le send propre d'un portefeuille ou d'un contrat (un compte de copie paie son copieur par send). L'échange pUSD respecte la pause de la banque pour ses deux portes.

Les venues et le délai de 24 heures

Un venue peut débiter n'importe quel compte via l'expéditeur qu'il transmet : les venues sont donc la racine de confiance de la banque. En ajouter un passe par proposeVenue, puis activateVenue après VENUE_DELAY (24 heures) : un événement VenueProposed laisse à chaque compte une journée pour retirer d'abord. listVenueNow saute l'attente uniquement avant le tout premier crédit de la banque. removeVenue est immédiat, et un venue retiré peut toujours faire un push.

Fonctions et événements