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, 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, withdrawal, etc), as well as the balance agreement item (balance agreement must be successful or the transaction will be rejected.)

---

The INBOX is a LEDGER. (Used for receiving incoming transfers and receipts.)
The OUTBOX is a LEDGER. (Used for outgoing transfers.)
The NYMBOX is a LEDGER. (Used for receiving messages and for receiving new transaction numbers.)

A ledger is also constructed by the wallet, to send to the server, whenever you need to signal acceptance or rejection of specific transactions that are sitting in your inbox.

---

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) will contain a LEDGER, which will contain a “DEPOSIT” TRANSACTION, which contains a “BALANCE AGREEMENT” TRANSACTION ITEM and 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 increment with each message, and normally they stay in sync automatically. If they go out of sync, your messages to that server will start failing (there is an API call to 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.

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, then the server will remove #14 from my RESPONSIBLE FOR list (I no longer have to sign for that number; I’m free of it.) Once my wallet receives the successful server reply regarding this, my wallet will then also remove #14 from my RESPONSIBLE FOR list.

---