diff --git a/book/art/runtime.bob b/book/art/runtime.bob index b247f458b8fd40..3f56d8d145b6ea 100644 --- a/book/art/runtime.bob +++ b/book/art/runtime.bob @@ -1,9 +1,10 @@ +.------------. .-----------. .---------------. .--------------. .-----------------------. +| PoH verify +---> | sigverify +--->| lock accounts +--->| validate fee +--->| allocate new accounts +---> +| TVU | `-----------` `---------------` `--------------` `-----------------------` +`------------` -.-----------. .-------------. .--------------. .--------------------. -| sigverify +--->| lock memory +--->| validate fee +--->| allocate accounts +---> -`-----------` `-------------` `--------------` `--------------------` - - .------------. .---------. .--------. .--------------. .--------------. ---->| load data +--->| execute +--->| record +--->| commit data +-->|unlock memory | - `------------` `---------` `--------` `--------------` `--------------` + .---------------. .---------. .------------. .-----------------. .-----------------. +--->| load accounts +--->| execute +--->| PoH record +--->| commit accounts +-->| unlock accounts | + `---------------` `---------` | TPU | `-----------------` `-----------------` + `------------` diff --git a/book/src/runtime.md b/book/src/runtime.md index 417aa67a02e2bc..8165d5122c5234 100644 --- a/book/src/runtime.md +++ b/book/src/runtime.md @@ -27,58 +27,88 @@ entrypoint. ## Execution -Transactions are batched and processed in a pipeline +Transactions are batched and processed in a pipeline. The TPU and TVU follow a +slightly different path. The TPU runtime ensures that PoH record occurs before +memory is committed. +The TVU runtime ensures that PoH verification occurs before the runtime +processes any transactions. + Runtime pipeline -At the *execute* stage, the loaded pages have no data dependencies, so all the +At the *execute* stage, the loaded accounts have no data dependencies, so all the programs can be executed in parallel. The runtime enforces the following rules: 1. Only the *owner* program may modify the contents of an account. This means - that upon assignment userdata vector is guaranteed to be zero. +that upon assignment userdata vector is guaranteed to be zero. + 2. Total balances on all the accounts is equal before and after execution of a - transaction. +transaction. + 3. After the transaction is executed, balances of credit-only accounts must be - greater than or equal to the balances before the transaction. +greater than or equal to the balances before the transaction. + 4. All instructions in the transaction executed atomically. If one fails, all - account modifications are discarded. -5. Before committing the accounts, the transactions are tagged with a count - from the PoH service, indicating the time transaction processing completed. - If that time falls outside the leader's allotted slot, the transactions - are discarded. +account modifications are discarded. Execution of the program involves mapping the program's public key to an entrypoint which takes a pointer to the transaction, and an array of loaded -pages. +accounts. ## SystemProgram Interface The interface is best described by the `Instruction::userdata` that the user encodes. -* `CreateAccount` - This allows the user to create and assign an account to a - Program. -* `Assign` - allows the user to assign an existing account to a program. -* `Move` - moves tokens between accounts. +* `CreateAccount` - This allows the user to create an account with an allocated +userdata array and assign it to a Program. + +* `Assign` - Allows the user to assign an existing account to a program. + +* `Move` - Moves tokens between accounts. + +## Program State Security + +For blockchain to function correctly, the program code must be resilient to user +inputs. That is why in this design the program specific code is the only code +that can change the state of the userdata byte array in the Accounts that are +assigned to it. It is also the reason why `Assign` or `CreateAccount` must zero +out the userdata. Otherwise there would be no possible way for the program to +distinguish the recently assigned account userdata from a natively generated +state transition without some additional metadata from the runtime to indicate +that this memory is assigned instead of natively generated. + +To pass messages between programs, the receiving program must accept the message +and copy the state over. But in practice a copy isn't needed and is +undesirable. The receiving program can read the state belonging to other +Accounts without copying it, and during the read it has a guarantee of the +sender program's state. ## Notes -1. There is no dynamic memory allocation. Client's need to use `CreateAccount` +* There is no dynamic memory allocation. Client's need to use `CreateAccount` instructions to create memory before passing it to another program. This instruction can be composed into a single transaction with the call to the program itself. -2. Runtime guarantees that when memory is assigned to the program it is zero -initialized. -3. Runtime guarantees that a program's code is the only thing that can modify -memory that its assigned to -4. Runtime guarantees that the program can only spend tokens that are in -accounts that are assigned to it -5. Runtime guarantees the balances belonging to accounts are balanced before -and after the transaction -6. Runtime guarantees that multiple instructions all executed successfully when -a transaction is committed. + +* `CreateAccount` and `Assign` guarantee that when account is assigned to the +program, the Account's userdata is zero initialized. + +* Once assigned to program an Account cannot be reassigned. + +* Runtime guarantees that a program's code is the only code that can modify +Account userdata that the Account is assigned to. + +* Runtime guarantees that the program can only spend tokens that are in +accounts that are assigned to it. + +* Runtime guarantees the balances belonging to accounts are balanced before +and after the transaction. + +* Runtime guarantees that instructions all executed successfully when a +transaction is committed. # Future Work