Data models
This page is about clarifying the Data Model
WALLETS HAVE: any number of NYMS (Pseudonyms) any number of SERVER CONTRACTS (transaction servers) any number of ASSET CONTRACTS (asset types) any number of ASSET ACCOUNTS (where funds go) a CASH PURSE for each ASSET TYPE
A NYM may be registered at any SERVER, and will have the same NYM ID (and public key) on every server.
An ASSET CONTRACT may be registered at any SERVER, and will have the same ASSET TYPE ID on every server.
A NYM may create many ASSET ACCOUNTS on any SERVER. An Asset Account lives on a single server. (A "smart wallet" will abstract a single "account" in the user's interface across an actual LIST of accounts that reside on multiple servers.)
Each ASSET ACCOUNT has 1 ASSET TYPE (the currency contract), 1 SERVER (the server contract), and 1 Nym (the owner/signer). Even BASKET CURRENCIES have 1 ASSET TYPE: the basket contract. Within that basket contract, multiple asset types are listed, with their IDs and their ratios, based on the formula:
(x * Basket_Currency) == (y * Member_CurrencyA) + (z * Member_CurrencyB) + ...
A LEDGER stores a list of TRANSACTIONS.
A TRANSACTION stores a list of TRANSACTION ITEMS. Currently any transaction has two items: the transaction's main item (deposit item, withdrawal item, etc), as well as the "balance agreement" item (The balance agreement must be successful, otherwise the transaction will be rejected by the server.)
The server includes a copy of your request in its receipt. (Whether success or fail.) As long as you keep that last signed receipt, then you don't have to store any other transaction history, and the receipt will prove your current account balance, as well as prove which instruments are authorized, and which transactions have closed. (This is also what prevents the server from forging transactions, or changing balances, without permission.)
In practice, whenever you download a copy of your intermediary files, a "smart wallet" will verify them against the last receipt and make sure none of them are invalid (which would disable the wallet's ability to submit any new transactions, since of course it wouldn't sign any false balance agreements, and would set up a dispute with the server.) The current "Moneychanger" test GUI has a "Verify" button, if you want to test calling the API function for verifying the last receipt. (Note: this function always fails until the first transaction has been performed, since a new account has no receipts.)
The INBOX is a LEDGER. (Used for receiving INCOMING TRANSFERS, as well as RECEIPTS.) The OUTBOX is a LEDGER. (Used for storing my PENDING OUTGOING TRANSFERS, as they await signed acceptance by the recipient.) The NYMBOX is a LEDGER. (Used for receiving MESSAGES and for receiving NEW TRANSACTION NUMBERS, which must be signed for.)
Ledger objects are also used inside the OT messages, whenever you need to signal acceptance or rejection of specific transactions that are sitting in your inbox. Transactions are always stored as a list, inside a ledger.
A PURSE contains a specified amount of cash, stored as a list of TOKENS of various denominations.
If you want to deposit some cash, your MESSAGE (a "deposit" transaction request message) will contain a LEDGER, which will contain a "DEPOSIT" TRANSACTION, which contains a "BALANCE AGREEMENT" TRANSACTION ITEM as well as the actual "DEPOSIT" TRANSACTION ITEM, which contains a PURSE, which contains the list of TOKENS.
A NYM has a list of REQUEST NUMBERS. (ONE for EACH SERVER that the Nym is registered at.) These request numbers must stay in sync, and they increment with each message sent. Normally, they stay in sync automatically. If they go out of sync, your messages to that server will start to fail (there is an API call that will re-sync them.) This prevents replay attacks (where an attacker intercepts the message and sends it multiple times.)
FOR EACH SERVER A NYM IS REGISTERED AT: A NYM has a list of TRANSACTION NUMBERS available, as well as a list of TRANSACTION NUMBERS still responsible for. (Two lists for each server.) A Nym must "sign out" specific transaction numbers beforehand, and store a supply of them, and attach one to each transaction request.
For example, if I'm responsible for transaction #14, then I have to sign for it in every balance agreement. So Transaction #14 will appear on my AVAILABLE list, as well as my RESPONSIBLE FOR list, ON EVERY "balance agreement" thereafter...
But once I actually write a cheque using #14, my wallet will remove #14 from my AVAILABLE list. (It's still in my RESPONSIBLE FOR list.) Then once the cheque is deposited by the recipient, the OT Server will also remove #14 from my AVAILABLE list. (It's still on my RESPONSIBLE FOR list on the server side at this point as well.)
Once I process my inbox and accept the CHEQUE RECEIPT for #14 (accepting the new balance), then the server will remove #14 from my RESPONSIBLE FOR list (I no longer have to sign for that number, as far as the server is concerned) Once my wallet receives the SUCCESS server reply regarding this, my wallet will then also remove #14 from my RESPONSIBLE FOR list (now I'm free of it; I will no longer sign for that number on any future balance agreements.)
