|
| 1 | +# Accounts Database Manager |
| 2 | + |
| 3 | +The AccountsDB is a crucial component of the Magicblock Validator. It handles |
| 4 | +the storage, retrieval, and management of account data. It's highly optimized |
| 5 | +to provide efficient account search and retrieval, using memory mapped storage, |
| 6 | +while still being persisted to disk. |
| 7 | + |
| 8 | +## Features |
| 9 | + |
| 10 | +- **Account Storage**: Efficient storage of account records, with support for |
| 11 | + both owned and borrowed account data. By default accounts are read directly |
| 12 | + from memory mapping without any deserialization and/or allocation, as |
| 13 | + consequence it allows for direct memory modification in situ in the database, |
| 14 | + avoiding read modify write overhead. But this imposes a strict requirement, that |
| 15 | + no two threads have access to the same account at the same time for |
| 16 | + modification, which is naturally achieved with account locking when executing |
| 17 | + transactions. But any other way to hold onto borrowed state of account is |
| 18 | + prohibited, as it will inevitably cause an undefined behavior. |
| 19 | +- **Index Management**: Fast index-based lookups for account data. |
| 20 | + LMDB is used for the purposes of indexing, where several different mappings |
| 21 | + are maintained to support database integrity. |
| 22 | +- **Snapshot Management**: Automated snapshot creation to enable rollbacks to |
| 23 | + previous states of the database if necessary. |
| 24 | +- **Concurrency Control**: Uses a "Stop the World" lock to ensure data |
| 25 | + consistency during critical operations like snapshotting. This prevents any |
| 26 | + writes to the database while it's being manipulated at the OS level. |
| 27 | +- **Program Account Scanning**: Retrieve and filter accounts associated with a |
| 28 | + specific program, the scanning happens without deserializing anything from the |
| 29 | + database. |
| 30 | + |
| 31 | +## Main API methods |
| 32 | + |
| 33 | +- **Initialization**: Use `AccountsDb::new` to create or open an accounts |
| 34 | + database instance. |
| 35 | +- **Account Operations**: Use `get_account`, `insert_account`, |
| 36 | + `contains_account` to read, write, or check the existence of accounts. |
| 37 | +- **Snapshot Operations**: Schedule and manage snapshots with `set_slot`, which |
| 38 | + might trigger snapshot operation, which in turn involves locking everything |
| 39 | + down, thus snapshot frequency should be set to sane value. And retrieve |
| 40 | + snapshot slots using `get_latest_snapshot_slot` and |
| 41 | + `get_oldest_snapshot_slot`. |
| 42 | +- **Database Integrity**: Use `ensure_at_most` to ensure database state up to a |
| 43 | + specific slot, with rollback to previously taken snapshot if needed. |
0 commit comments