Syscall Refactor

[Stebalien]

Depends on:

• Compute circulating supply in cron #777
• Support BLS Aggregate Signatures in FVM (FIP-0079) #841
• Actor Entrypoint Bikeshed :art: #792

Abstract

• Reorganize the FVM syscalls to aid in layering/composition with the goal to eventually generalize the FVM beyond Filecoin. This will, e.g., improve FVM/IPC integration.
• Version FVM syscall "modules".
• Move static contextual information into globals to:
  • Improve forwards compatibility.
  • Reduce actor startup overhead.

Motivation

Currently, the FVM exposes all system information through syscalls
organized into 11 "modules":

• debug
• ipld
• crypto
• self
• vm
• actor
• event
• send
• rand
• network
• gas

However:

1. We will definitely need to restrict some of these syscalls to "privileged" actors before allowing arbitrary user-deployed Wasm actors. Sometimes this is because the syscall is an implementation detail we want to change later, sometimes it's just dangerous and, e.g., should only be called by the init actor.
2. Some of these syscalls simply "fetch" static information from the system and there's a significant overhead to doing so (the cost of exiting/entering Wasm). We've grouped them into two syscalls (`network::context` and `message::context`) that return all contextual information in one structure however, this means we can't add additional contextual information without breaking changes.
3. The module organization is logical, but doesn't really lend itself towards composition & layering. E.g., I'd like to isolate all functions related to the FVM's "actor" model in case we ever want a lower-level process-based abstraction.

Syscall Changes

I'm proposing that we refactor these syscalls into the following 6 public modules:

1. debug – debugging syscalls
2. ipld1 – ipld block syscalls, kept as a separate module to be shared with the IPVM (versioned)
3. crypto1 – general-purpose module for cryptographic functions (versioned)
4. fvm1 – universal FVM features/syscalls.
5. fvm_actor1 – functions related to the FVM's actor model (versioned)
6. fvm_chain1 – functions related to the chain state (versioned)

And a single private module.

Versions

I'm currently proposing that we version entire "namespaces". Alternatively, we could let actors export some kind of runtime version constant and use that to decide the environment.

Debug

The debug syscalls are not versioned. Instead, the idea is to:

1. Define that there must exist a single debug::enabled global variable, regardless of the version.
2. Define that calling any debug syscall when debugging is not enabled traps (aborts).

Syscall Changes

Old	New	Permission/Comment
debug::enabled	removed	replaced by globals
debug::*	traps at runtime
ipld::*	ipld1::*
crypto::hash	crypto1::hash
crypto::recover_secp_public_key	crypto1::recover_secp_public_key
crypto::verify_bls_aggregate	crypto1::verify_bls_aggregate
self::root	fvm_actor1::get_state_root
self::set_root	fvm_actor1::set_state_root
vm::exit	fvm_actor1::exit
self::current_balance	fvm_actor1::current_balance
self::self_destruct	fvm_actor1::self_destruct
actor::resolve_address	fvm_actor1::resolve_address
actor::lookup_delegated_address	fvm_actor1::lookup_delegated_address
actor::get_actor_code_cid	fvm_actor1::get_actor_code_cid
actor::balance_of	fvm_actor1::balance_of
event::emit_event	fvm_actor1::emit_event
send::send	fvm_actor1::send
rand::get_chain_randomness	fvm_chain1::get_chain_randomness
rand::get_beacon_randomness	fvm_chain1::get_beacon_randomness
network::tipset_cid	fvm_chain1::tipset_cid
actor::next_actor_address	private::next_actor_address	init actor only
actor::create_actor	private::create_actor	init actor only
actor::get_builtin_actor_type	private::get_builtin_actor_type	builtin actors
actor::get_code_cid_for_type	private::get_code_cid_for_type	builtin actors
gas::charge	private::charge_gas	power actor
crypto::verify_post	private::verify_post	miner actor
crypto::verify_consensus_fault	private::verify_consensus_fault	miner actor
crypto::verify_aggregate_seals	private::verify_aggregate_seals	miner actor
crypto::verify_replica_update	private::verify_replica_update	miner actor
crypto::batch_verify_seals	private::batch_verify_seals	miner & cron actor
network::total_circ_supply	removed
gas::available	removed	replaced by globals
vm::message_context	removed	replaced by globals
network::context	removed	replaced by globals

New Globals

All globals are constants, except fvm1::gas_available. However, user code is not allowed to modify fvm1::gas_available.

Global	Comment
fvm1::gas_available (u64)	The remaining gas available (immutable).
fvm_chain1::epoch (u64)	Network epoch (maybe rename to height?).
fvm_chain1::timestamp (u64)	Unix time of the currently executing tipset.
fvm_chain1::base_fee (u64)	The base-fee in attoFIL
fvm_chain1::chain_id (u64)	The chain ID of the network.
fvm_chain1::network_version (u64)	The network version as specified by the client.
fvm_chain1::message_origin (u64)	The ID of the top-level sender.
fvm_chain1::message_nonce (u64)	The nonce of the top-level message.
fvm_chain1::gas_premium (u64)	The gas premium (in attoFIL).
fvm_actor1::caller (u64)	The ID of the immediate caller.
fvm_actor1::self (u64)	The ID of the immediate executing actor.
fvm_actor1::value_received_lo (u64)	The low-order bits of the value received from the caller (in attoFIL).
fvm_actor1::value_received_hi (u64)	The high-order bits of the value received from the caller (in attoFIL)
fvm_actor1::flags (u64)	Invocation flags.

If the actor imports fvm1::gas_available, we will validate that the import is immutable. Then, we will make it mutable so we can use it for gas instrumentation. This means the initial validation (before gas instrumentation) will statically reject any mutations to this global variable from user-provided code.

At the moment, accessing wasm globals is difficult from most languages. However, we can provide tiny wasm "shims" that can be linked (with ldd) to actors before deployment that export small functions for reading these globals. E.g.:

(module
 (global $messageOrigin (import "fvm_chain1" "message_origin") i64)
 (func (export "get_origin") () (result i64)
       (global.get $messageOrigin)))

NOTE: This assumes that the method number is passed via the wasm entrypoint as described in #792.

Upgrades

When an FVM upgrade introduces breaking changes in some WASM API, we'll:

1. Bump the API's wasm module name from, e.g., fvm1 to fvm2.
2. Create a special "shim" wasm module to the init actor that translates calls from fvm1 to fvm2.
3. Link (think ld) this "shim" to all deployed actors importing fvm1. I.e. ld(actor_wasm_module_imports_fvm1, shim_wasm_module) -> new_actor_wasm_module_imports_fvm2
4. Add the shim to a set of wasm modules implicitly linked to all newly deployed actors (maybe?).

This means that the FVM can continue to support exactly one API version while maintaining perfect backwards compatibility on-chain.

[Stebalien]

Revisiting these layers, I've changed my mind on a few things:

1. fvm_actor1 may mix too many things together:
   1. "self" operations (set_root, self_destruct, etc.) and "inter-actor" (balance_of, send, etc.) operations may want to live in separate namespaces. E.g., some systems may support "async" sends but not synchronous sends.
   2. Events may want to remain separate as not all actor systems will want to emit events.
2. I'm really unsure of fvm_chain1. The way it handles randomness is pretty Filecoin specific, and network_version also seems network specific.