proposal: ABIv2 Design Document

[Lichtso]

Now, as some time has passed since the last design (see #19191) here is the most recent draft.

TransactionContext serialization format

This serialization happens only once per transaction and is shared (via memory mapping) between SBF programs, built-in programs and the runtime. The memory layout is serialized as well (upfront) so that it can be changed and adapted without redeploying programs.

Dynamic Stride Arrays

Arrays with a dynamically configurable stride are useful to build multi-dimensional arrays or interleave arrays. Interleaved arrays can also be used to turn an array of structs (row major) into a struct of arrays (column major). This has been an undecided issue in the last draft and is now simply configurable.

Attribute Enum | Nested Value Types

• ReturnData: TransactionContext -> &[u8]
• AccountsResizeDelta: TransactionContext -> u128
• TransactionAccountCount: TransactionContext -> u16
• TransactionAccountKey: TransactionContext -> &[TransactionAccount] -> Pubkey
• TransactionAccountOwner: TransactionContext -> &[TransactionAccount] -> Pubkey
• TransactionAccountLamports: TransactionContext -> &[TransactionAccount] -> u64
• TransactionAccountData: TransactionContext -> &[TransactionAccount] -> &[u8]
• TransactionAccountIsExecutable: TransactionContext -> &[TransactionAccount] -> bool
• TransactionAccountRentEpoch: TransactionContext -> &[TransactionAccount] -> u64
• TransactionAccountTouchedFlag: TransactionContext -> &[TransactionAccount] -> bool
• InstructionStackHeight: TransactionContext -> u8
• InstructionStackCapacity: TransactionContext -> u8
• InstructionStackEntry: TransactionContext -> &[u8]
• InstructionTraceLength: TransactionContext -> u16
• InstructionTraceCapacity: TransactionContext -> u16
• InstructionTraceNestingLevel: TransactionContext -> &[InstructionContext] -> u8
• InstructionTraceLamportSum: TransactionContext -> &[InstructionContext] -> u128
• InstructionTraceInstructionData: TransactionContext -> &[InstructionContext] -> &[u8]
• InstructionTraceProgramAccount: TransactionContext -> &[InstructionContext] -> &[u16]
• InstructionAccountIndexInTransaction: TransactionContext -> &[InstructionContext] -> &[InstructionAccount] -> u16
• InstructionAccountIndexInCaller: TransactionContext -> &[InstructionContext] -> &[InstructionAccount] -> u16
• InstructionAccountIndexInCallee: TransactionContext -> &[InstructionContext] -> &[InstructionAccount] -> u16
• InstructionAccountIsSigner: TransactionContext -> &[InstructionContext] -> &[InstructionAccount] -> bool
• InstructionAccountIsWritable: TransactionContext -> &[InstructionContext] -> &[InstructionAccount] -> bool

Syscalls

The following two syscalls (CPI invoke and setting account properties) can potentially be merged into one as they often occur together. It has been that way in ABIv0/v1 as well: The CPI syscall did update the account properties in the runtime before pushing the next InstructionContext. Only the setting the data len / resizing an account is something that a user might want to do (for allocating more memory to write to) without invoking a CPI.

CPI invoke

The CPI syscall is changed so that it does not copy the fields of the InstructionContext anymore. Instead the SBF program has to fill out the last InstructionContext in the instruction_trace which is marked as writable in the memory mapping. The runtime then only verifies that and completes some of the redundant fields before doing the actual invocation. This also unifies the C and Rust CPI syscalls into one.

Set Account Properties

The account data itself is mapped directly and be writable to the SBF program (given it has the permission to write to it). All other properties of transaction_accounts like changes to the owner, lamports, is_executable or the size of the account data (resizing / reallocation) all go through one syscall. That is because they are too small to give them individual memory regions just so that we can control their writability. The SBF program passes one list / array of:

• instruction_account_index
• attribute
• value or *const value

This way one or more properties of one or more transaction_accounts could be updated in one syscall.

[Lichtso]

Closed in favor of #32154.