doc: add account spec pages #5489
Conversation
Adds information to guide account database and cache design. This information is not reviewed, YMMV. May be useful in a real spec later.
| ### Program executions | ||
|
|
||
| A *program execution* is a type of account access that results from | ||
| transaction execution. The *program account* to execute is specified |
There was a problem hiding this comment.
| transaction execution. The *program account* to execute is specified | |
| transaction execution. The *program accounts* to execute are specified |
| ### Sysvar reads | ||
|
|
||
| Certain accounts can be read at any time during runtime execution. This | ||
| includes the slot transition, native programs, and syscall handlers. |
There was a problem hiding this comment.
Should define what a "slot transition" is or rephrase
| When executing a slot, the runtime alternates between transaction | ||
| execution and miscellaneous system processing. The latter includes any | ||
| slot execution phase during which transactions are not executed. These | ||
| steps perform various writes to [*stored accounts*](#stored-accounts). |
There was a problem hiding this comment.
Clarify that system accesses only happen in this aforementioned "miscellaneous system processing". (Or use a proper term to define that sort of system processing, like "slot freeze")
| 8. [Incinerator](#incinerator) | ||
| 2. [System managed accounts](#system-managed-accounts) | ||
| 1. [Slot sysvars](#slot-sysvars) | ||
| 2. [Builtin accounts](#builtin-accounts) |
There was a problem hiding this comment.
I'm unsure about where we draw the distinction between "user writable accounts" and "system managed accounts". Perhaps, there is none ...
| 1. [Slot sysvars](#slot-sysvars) | ||
| 2. [Builtin accounts](#builtin-accounts) | ||
|
|
||
| ### Transparent Accounts |
There was a problem hiding this comment.
"Virtual account" sounds better
| non-existent account when trying to read *transparent accounts*. | ||
|
|
||
| [*System writes*](#system-writes) to transparent accounts are inherently | ||
| undefined, since the written data would not persist. |
There was a problem hiding this comment.
Reflink is broken (system-accesses instead), also clarify that these accesses don't exist because they are undefined
| Ephemeral sysvars are transparent accounts that are accessible through | ||
| *sysvar reads*. | ||
|
|
||
| For more information, see [sysvars.md](./sysvars.md#slot-sysvars) |
There was a problem hiding this comment.
Reflink should say txn-sysvars
| Most modifications are subject to permission checks. Increasing the | ||
| lamport value of an account always passes the permission checks of a | ||
| *user writable account*. |
There was a problem hiding this comment.
These permission checks are specific to the access type (transaction account access), not the account type.
|
|
||
| ### BPF program accounts | ||
|
|
||
| There are two type of *BPF program accounts*: *User BPF programs* and |
There was a problem hiding this comment.
| There are two type of *BPF program accounts*: *User BPF programs* and | |
| There are two types of *BPF program accounts*: *User BPF programs* and |
| - Transitioning a program between immutable/executable, and | ||
| mutable/non-executable incurs a one slot delay. | ||
|
|
||
| ### Core BPF programs |
There was a problem hiding this comment.
This shouldn't be a separate section
|
|
||
| Firedancer uses a **write-through** cache policy for these sysvars. | ||
|
|
||
| All writes to the above sysvars use the `fd_slot_sysvar_write` API, which: |
There was a problem hiding this comment.
Probably going to be called fd_sysvar_XXX_write
| (FIXME clarify what happens when this is attempted) | ||
| - Never written to the account database | ||
| - Account reads via user transactions are redirected to a custom | ||
| callback (does not access the account database) |
There was a problem hiding this comment.
Should add reference to account.md "virtual accounts", and add a rough summary what virtual accounts do
ripatel-fd
requested review from
mmcgee-jump,
topointon-jump and
ibhatt-jumptrading
There was a problem hiding this comment.
- Document cache behavior of "rent" bank field vs rent sysvar
Adds information to guide account database and cache design.
This information is not reviewed, YMMV. May be useful in a real
spec later.