Actor Entrypoint Bikeshed 🎨

[Stebalien]

I'd like to bikeshed a few issues with the current Wasm-actor entrypoint so we can settle some open design discussions before we start allowing user-deployed Wasm actors and lock the existing design in-place.

Relevant reading:

• Account abstraction #388 (the validate function)
• FVM: Actor Upgrades #396 (the upgrade function)
• FVM M2.2: Replace the Constructor method with a wasm-level "constructor" entrypoint #500 (the constructor function)
• Rethink invoke signature ref-fvm#1166

Variant A

Proposal: Change the invoke Wasm actor entry point signature from:

fn invoke(param_block_id: u32) -> u32; /* return block id */

To:

fn invoke(method_number: u64, param_block_id: u32, param_codec: u64, param_len: u32) -> u32; /* return block id */

Motivation

The current Wasm actor entrypoint has a few downsides.

First, it doesn't include the method number, requiring that the user pull it from the "message context". This is both inefficient (requires a system call) and odd (we're literally invoking this method, but we're not passing it to the invoked actor).

Second, it doesn't include enough information to actually parse the parameters, requiring the user to call both block_stat(param_block_id) to learn the block's codec and size, then block_read(...) to read the block into memory.

Analysis

1. This proposal reduces the number of required syscalls to process method arguments from 3 (lookup the method number, stat the parameters block, read the parameters) to one (read the parameters block).
2. This proposal removes the method number from the environment, where it wouldn't make any sense in proposals like account abstraction, upgrades, and a separate constructor entrypoint.

Variant B

In addition to "variant A" proposed above, reserve negative method numbers for "system" entrypoints:

• -1 -- constructor (changed from its current value of 1)
• -2 -- upgrade (future upgrade)
• -3 -- validate (future account abstraction)

And use these instead of introducing new Wasm entrypoint functions.

Affects: #500, #396, #388

Motivation

At the moment, there's no reserved set of "special" method numbers that can only be invoked by the FVM, sort of.

• Method 0 is reserved for bare sends and doesn't (currently) end up invoking the called actor's code.
• Method 1 is used for actor construction, but nothing prevents anyone else from calling this method.

We have a few cases where we want actors to be able to "opt-in" to some behavior where blindly returning "ok" could be dangerous. For example, account abstraction needs some way to ask the account if a message is a valid message from the actor in question. Blindly responding with "ok" here would mean anyone would be able to send messages on behalf of this actor.

In that case, the alternative we proposed was to introduce a new validate wasm-level entrypoint. That way, actors have to "opt-in" to being abstract accounts. Unfortunately, this has a few issues:

1. It adds some complexity. There's a nice unity to always invoking actors the same way. Adding new entrypoints will add some complexity to the FVM.
2. While this entrypoint might seem like a good way to determine, e.g., "is this actor an abstract account", that's not true in practice. If, e.g., we wanted to support EVM-based abstract accounts, the EVM actor would have to implement this method everywhere.

So here I'm proposing that we do continue to use method numbers for these "methods", just out of a special reserved range (where actors would, by default, reject all calls on unhandled negative method numbers).

Alternatives & Extensions

Errors & Exit Codes

One remaining issue with the invoke entrypoint is the fact that it can't return an error. The only wait of fail with an error is to call the vm::exit syscall with an exit code.

Ideally invoke would return a tuple: (return_block_id, error_code). Unfortunately, working with multiple return values in rust+wasm is non-trivial, although doable if there's a consensus that this is the "right" approach. I assume it'll become less painful in the future, for what it's worth.

An alternative would be to say that negative return values indicate exit codes, non-negative return values are block IDs (where 0 means "success with value", as it does today). The downside of this approach is that it doesn't allow returning a value on failure, in addition to the error code.

Length & Codec

We don't have to include the length/codec in the invoke signature and this isn't a hill I plan on dying on. It just removes a pointless syscall.

[raulk]

I am confused by the "variant" terminology here. What concrete solution are these two different variants of? If I understood correctly, there are four different proposals here, which are independent from each other:

1. Glorify method numbers into the actor ABI.
2. Treat lifecycle/structural behaviours as standard methods with preallocated method numbers in the negative range.
3. Add the parameter's block codec and length to entrypoints.
4. Returning errors and exit codes from entrypoints.

On (1), method numbers are a Filecoin specificity, and the reason we didn't originally add them to the actor ABI was to keep the actor contract Filecoin-independent. In the future, we'd like FVM to work beyond Filecoin, so adopting this Filecoin convention at the ABI level just doesn't seem right. Doing this would glorify the Filecoin convention as the FVM convention. Given that the argument seems to be merely an optimization one, I'd skip doing this.

On (2), modelling lifecycle/structural behaviours as exported Wasm functions (aka. "entrypoints") has several advantages:

1. Allows us to externally detect when the actor is offering these functions. I expect there'll be several branches in ref-fvm code that will need to answer has validate?, has create?, has destruct?. Of course, we can dispatch unconditionally and assume that a well-behaved actor will return the "method not supported" exit code, but it feels like we can do better. If we go down that route, eventually we'd need to optimize and add a cache ref-fvm side to track which (frequently/recently used) actors expose which entrypoints, which will lead to variable execution times, something I'd like to avoid. Alternatively we could store this information somewhere, e.g. the Wasm bytecode itself via an exported bitflag constant that's generated with FVM build-time tooling, or the state tree, or something else. But all of this introduces complexity at different layers that wouldn't be needed if we kept these as exported Wasm functions (IMO the pragmatic solution)¨.
2. Allows to cleanly inject distinct environments depending on the entrypoint, and model dedicated entrypoint contracts. I expect each entrypoint to have a distinct "contract" / environment. You already hinted at that here: "This proposal removes the method number from the environment [object retrieved through a syscall], where it wouldn't make any sense in proposals like [...]". I'd generalise this as: "every entrypoint receives a different environment, including its own set of syscalls, and may be expected to produce different returns/exit codes". I think it's easier for a developer to understand this when viewed through the lens of static dispatch (separate functions, each with its API), than in the context of dynamic dispatch, where the explanation becomes: "if method num is -1, the interface is A, and exit codes 0, 1, 2 make sense; if method num is -2, the interface is B, any return data will be ignored, and the only valid exit codes are 0 or 78." The latter is not a design choice I'd be comfortable explaining. Also, I think we're likely to need much more divergence in available syscalls than just the one example you cited.

On (3), seems fine to me. My only hesitation is that the codec is an IPLD specific notion, but FVM is designed to be an IPLD machine, the choice seems to align with that invariant.

On (4), this doesn't seem urgent nor indispensable, as SDKs are bridging the control flow semantics of the language anyway. As you mentioned, multi-return support wasn't great in Rust the last time we looked, and we don't know about other languages. We'd need to evaluate this more carefully.

[Stebalien]

I am confused by the "variant" terminology here.

I'm making a weaker proposal, then a "stronger" proposal. But you're right that there are really 4 different proposals. However, I was trying to limit the options somewhat to focus the discussion.

On (1), method numbers are a Filecoin specificity

Method numbers have been worked in everywhere in the FVM and are likely here to stay.

• Method 0 is special at the system level.
• The send syscall expects a method number and actors are built around this assumption.
• Forks are unlikely to throw out method numbers given how widely they're used.
• Having a well-structured function selector is actually pretty convenient, especially for supporting multiple calling conventions. It provides us with a minimal "base" calling convention.

I'd love to go back and find a way to impose a "convention" on method parameters instead, but I think it's time to accept that this ship has sailed and to live with it, rather than baking it in as a second class citizen then having to live with that decision forever.

Allows us to externally detect when the actor is offering these functions. I expect there'll be several branches in ref-fvm code that will need to answer has validate?, has create?, has destruct?.

Unfortunately, that's not possible given the "hypervisor" nature of the FVM; runtimes will have to always implement these entrypoints if they want to ever support the functionality, because they can't be implemented at runtime. See the second point of my motivation for why new entrypoints aren't all that useful.

Allows to cleanly inject distinct environments depending on the entrypoint, and model dedicated entrypoint contracts.

I tried to think of a case where this might apply, and couldn't think of any (once we've removed the method number from the environment) where we'd want to inject something via the environment and not via the method parameters.

• We're already working on an upgrade entrypoint, and didn't need this.
• For account abstraction, we would need to pass the message being validated as a parameter, but we shouldn't need to pass anything else into the environment.

Of course, we may need to restrict certain parts of the environment in some cases, but that would likely be enforced in the kernel (i.e., one kernel for all contexts where the kernel makes contextual decisions on whether or not some syscall is allowed).

We never want to change which syscalls are available to the actor based on the entrypoint because the set of syscalls imported by the actor is static.

On (4), this doesn't seem urgent nor indispensable

4 is also something we can change later. I.e., we can be polymorphic over the return type, accepting both a single "block" or a block plus exit code (in the future if/when we add support for it).

[anorth]

A: more parameters to invoke
This sounds great all round. Not having method numbers here in particular is quite annoying, and adds complexity elsewhere (e.g. they need to be in the environment). It seems like Filecoin actor development would be much better with all of these additions.

I am unconcerned about how that might impact other users of FVM. This is the Filecoin protocol forum and Filecoin is the first and currently only production user of the FVM.

B: sentinel, negative method numbers for special methods
This does not sound great to me. The difference between system-level behaviour like upgrading or validating a message pre-inclusion and "normal" message execution is another level than the difference between methods. These system behaviours will probably impose expectations, limits or environmental constraints on the actor code, and having an entirely different entry point is a clear way to signal this within the code. These or future ones may pass different parameters to the actor code. If we used sentinel method numbers I expect that both the FVM and the actor could would end up with lots of if method < 0 or similar checks to invoke context-specific logic, rather than branching just once at the top. We don't need or want these entry points to be externally invokable top level, so we don't need them to be expressible in the chain's message structure.

Using method numbers would raise the possibility of an actor dynamically supporting upgrade or message validation or future behaviour, e.g. depending on state. While this is not all that difference from dynamically succeeding or failing when invoked, it still muddies the answer to "is this actor upgradeable?", which might have, e.g. security implications for users.

Errors & Exit Codes
I don't see a problem worth solving here. There is exactly one way to signal an error: great. I assume you're not proposing removing the vm::exit call when also adding support for an error return, which would then mandate plumbing? Having one way is simple. If anything we should use it more in the built-in actors (where we do in fact do much error plumbing at moderate complexity cost and little benefit).