First draft

Author: Lichtso

proposals/0177-program-runtime-abiv2.md

@@ -0,0 +1,160 @@
+---
+simd: '0177'
+title: Program Runtime ABI v2
+authors:
+  - Alexander Meißner
+category: Standard
+type: Core
+status: Idea
+created: 2024-10-01
+feature: TBD
+extends: SIMD-0184, SIMD-0185
+---
+
+## Summary
+
+Align the layout of the virtual address space to large pages in order to
+simplify the address translation logic and allow for easy direct mapping.
+
+## Motivation
+
+At the moment all validator implementations have to copy (and compare) data in
+and out of the virtual memory of the virtual machine. There are four possible
+account data copy paths:
+
+- Serialization: Copy from program runtime (host) to virtual machine (guest)
+- CPI call edge: Copy from virtual machine (guest) to program runtime (host)
+- CPI return edge: Copy from program runtime (host) to virtual machine (guest)
+- Deserialization: Copy from virtual machine (guest) to program runtime (host)
+
+To avoid this a feature named "direct mapping" was designed which uses the
+address translation logic of the virtual machine to emulate the serialization
+and deserialization without actually performing copies.
+
+Implementing direct mapping in the current ABI v0 and v1 is very complex
+because of unaligned virtual memory regions and memory accesses overlapping
+multiple virtual memory regions. Instead the layout of the virtual address
+space should be adjusted so that all virtual memory regions are aligned to
+4 GiB.
+
+## Alternatives Considered
+
+None.
+
+## New Terminology
+
+None.
+
+## Detailed Design
+
+Programs signal their support through their SBPF version field being v4 or
+above while the program runtime signals which ABI is chosen through the
+serialized magic field.
+
+### Per Transaction Serialization
+
+At the beginning of a transaction the program runtime must prepare the
+following which is shared by all instructions running programs suporting the
+new ABI. This memory region starts at `0x400000000` and is readonly. It must be
+updated as instructions through out the transaction modify the account metadata
+and the length of the scratchpad.
+
+- The number of transaction accounts: `u64`
+- Key of the program which wrote to the scratchpad most recently: `[u8; 32]`
+- The scratchpad data: `&[u8]` which is composed of:
+  - Pointer to scratchpad data: `u64`
+  - Length of scratchpad data: `u64`
+- For each transaction account:
+  - Key: `[u8; 32]`
+  - Owner: `[u8; 32]`
+  - Lamports: `u64`
+  - Account payload: `&[u8]` which is composed of:
+    - Pointer to account payload: `u64`
+    - Account payload length: `u64`
+    - // TODO: Account payload capacity: `u64`
+
+This memory region starts at `0x500000000` and is readonly. It must be
+updated as instructions through out the transaction call TODO.
+
+### Per Instruction Serialization
+
+For each instruction the program runtime must prepare the following.
+This memory region starts at `0x600000000` and is readonly. It does not require
+any updates once serialized.
+
+- Magic: `u32`: `0x76494241` ("ABIv" encoded in ASCII)
+- ABI version `u32`: `0x00000002`
+- // TODO: Instruction trace to replace get sibling instructions syscall?
+- Program key: `[u8; 32]`
+- The instruction data: `&[u8]` which is composed of:
+  - Pointer to instruction data: `u64`
+  - Length of instruction data: `u64`
+- Number of instruction accounts: `u16`
+- For each instruction account (non interleaved):
+  - Index to transaction account: `u16`
+  - Index of first occurence (for aliasing): `u16`
+  - Flags bitfield: `u8` (bit 8 is signer, bit 16 is writable)
+
+### Per Instruction Mappings
+
+A readonly memory region starting at `0x700000000` must be mapped
+in for the instruction data. It too does not require any updates.
+
+For each unique (meaning deduplicated) instruction account the payload must
+be mapped in at `0x800000000` plus `0x100000000` times the index of the
+**transaction** account (not the index of the instruction account). Only if the
+instruction account has the writable flag set and is owned by the current
+program it is mapped in as a writable region. The writability of a region must
+be updated as programs through out the transaction modify the account metadata.
+
+### Lazy deserialization on the dApp side (inside the SDK)
+
+With this design a program SDK can (but no longer needs to) eagerly deserialize
+all account metadata at the entrypoint. Because this layout is strictly aligned
+and uses proper arrays, it is possible to directly calculate the offset of a
+single accounts metadata with only one indirect lookup and no need to scan all
+preceeding metadata. This allows a program SDK to offer a lazy interface which
+only interacts with the account metadata fields which are needed, only of the
+accounts which are of interest and only when necessary.
+
+### Changes to syscalls
+
+The `AccountInfo` parameter of the CPI syscalls will be ignored if ABI v2 is in
+use. Instead the changes to account metadata will be communicated explicitly
+through separate syscalls `set_account_owner`, `set_account_lamports` and
+`set_account_length`. Each of these must take a guest pointer to the structure
+of the transaction account (see per transaction serialization) to be updated and
+the new value as second parameter. In case of the pubkey parameter the guest
+pointer to a 32 byte slice is taken instead.
+
+### Changes to CU metering
+
+CPI will no longer charge CUs for the length of instruction data or account
+payloads. TBD CUs will be charged for every instruction account.
+
+## Impact
+
+This change is expected to drastically reduce the CU costs as the cost will no
+longer depend on the length of the instruction account payloads or instruction
+data.
+
+From the dApp devs perspective almost all changes are hidden inside the SDK.
+
+## Security Considerations
+
+What security implications/considerations come with implementing this feature?
+Are there any implementation-specific guidance or pitfalls?
+
+## Drawbacks
+
+This will require parallel code paths for serialization, deserialization, CPI
+call edges and CPI return edges. All of these will coexist with the exisiting
+ABI v0 and v1 for the forseeable future, until we decide to deprecate them.
+
+## Backwards Compatibility
+
+The magic field (`u32`) and version field (`u32`) of ABI v2 are placed at the
+beginning, where ABI v0 and v1 would otherwise indicate the number of
+instruction accounts as an `u64`. Because the older ABIs will never serialize
+more than a few hundred accounts, it is possible to differentiate the ABI
+that way without breaking the older layouts.