FVM: Actor Upgrades

[Stebalien]

(This design is a collaboration from everyone on the FVM team)

The FVM would like to support atomically (and safely) upgrading actor code. This will allow actors to update themselves without having to rely on proxy patterns.

The general proposal is to add a sself::become_actor syscall that atomically switches to some new code CID, executing an upgrade endpoint on the new code giving it a chance to upgrade the state, reject the upgrade, etc.

Concretely, we're proposing:

1. Two new syscalls: sself::become_actor and sself::get_old_code_cid.
2. A new optional upgrade WASM entrypoint (in addition to the invoke entrypoint). Deployed actor code would only be a valid upgrade target if it defines this entrypoint.

New WASM Entrypoint

When upgrading actor code, the new actor code needs an opportunity to:

1. Upgrade the state tree.
2. Reject the upgrade.

Furthermore, upgrades must be opt-in. Otherwise, a malicious actor could upgrade to a "trusted" actor, leaving the trusted actor in a compromised state (either by seeding the trusted actor's state-tree, or by kicking off some chain of events that the trusted actor will later blindly complete).

To do this, we're proposing introducing a new WASM entrypoint. This entrypoint is defined as follows:

/// Called when an actor "upgrades" to this module's code.
///
/// # Parameters
///
/// `params` is an IPLD block handle for the upgrade params, if any.
///
/// # Returns
///
/// The return value is an IPLD block handle 
#[no_mangle]
pub fn upgrade(params: u32) -> u32;

New Syscalls

We're proposing two new syscalls:

1. A sself::become_actor syscall to atomically switch to a new code CID.
2. A sself::get_old_code_cid syscall to get the previous actor's code CID.

sself::become_actor

/// Atomically transition to the new actor code. On success, this syscall does not return to the
/// current actor. Instead, the target actor "replaces" the invocation.
///
/// # Parameters
///
/// - `new_code_cid_off` is the offset (in wasm memory) of the code CID to upgrade _to_.
/// - `params` is the IPLD block handle passed to the new code's `upgrade` wasm endpoint.
///
/// # Returns
///
/// On success, this syscall will not return. Instead, the current invocation will "complete" and
/// the return value will be the block returned by the new code's `upgrade` endpoint.
///
/// If the new code rejects the upgrade (aborts) or performs an illegal operation, this syscall will
/// return the exit code of the `upgrade` endpoint.
///
/// Finally, the syscall will return an error if it fails to call the upgrade endpoint entirely.
///
/// # Errors
///
/// | Error                 | Reason                                               |
/// |-----------------------|------------------------------------------------------|
/// | [`NotFound`]          | there's no actor deployed with the target code cid.  |
/// | [`InvalidHandle`]     | parameters block not found.                          |
/// | [`LimitExceeded`]     | recursion limit reached.                             |
/// | [`IllegalArgument`]   | invalid code cid buffer.                             |
/// | [`Forbidden`]         | target actor doesn't have an upgrade endpoint.       |
fn become_actor(new_code_cid_off: *const u8, params: u32) -> SyscallResult<u32>;

Internally, this syscall would:

1. Lookup the target code CID in the code registry.
2. Load it and validate that it has an upgrade method.
3. Update the actor's code CID to this new code CID.
4. Create a new invocation container for this actor.
5. Seed this invocation container with the params block.
6. Invoke the upgrade entrypoint.
7. On success, return from the original invocation container with the block ID returned by upgrade.
8. On failure, return to the actor that called sself::become_actor.

Note: sself::become_actor may be invoked recursively as follows:

1. Actor A1 invokes actor A2 with send(A2).
2. Actor A2 has code C1.
3. Actor A1:C1 calls become_actor(C2).
4. Actor A1:C2 calls become_actor(C3).
5. Actor A1:C3 returns some block B.
6. Actor A1 receives B as the return result from the send in step 1.

sself::get_old_code_cid

/// Gets the code CID of the code that upgraded _to_ this actor, if any.
///
/// # Parameters
///
/// - `cid_off` and `cid_len` are the offset and length of the output CID buffer in wasm memory.
///
/// # Returns
///
/// The length of the returned CID.
///
/// # Errors
///
/// | Error                 | Reason                                               |
/// |-----------------------|------------------------------------------------------|
/// | [`IllegalArgument`]   | invalid cid pointer/length.                          |
/// | [`IllegalOperation`]  | actor is not currently being upgraded.               |
/// | [`BufferTooSmall`]    | the cid buffer is too small to fit the code cid.     |
fn get_old_code_cid(cid_off: *mut u8, cid_len: u32) -> SyscallResult<u32>;

Open Questions

• Q: Having to define a new syscall just to get the old code CID is very unfortunate. But we can't easily pass it into the upgrade method as we can only pass numbers.
• Q: The upgrade entrypoint's signature is identical to send, so it's a bit unfortunate that we need a new endpoint.
• Q: What do we put in the InvocationContext (returned by vm::context)? I assume we just leave everything as-is (caller, received value, etc.).

[anorth]

Thanks for writing this up, @Stebalien .

• Could you explain the "opt-in" concern a little more? Opt in by whom?
• For NotFound "no actor deployed", I think we mean that the code was not found, but the message seems to be saying the only way it could be found is if an actor was previously deployed with it? Can we make the code available without deploying an actor with it? How did the first actor get deployed with that code? Or maybe I'm confused between actor (has state, nonce, etc) and code (just code).
• Why would we want to support the recursive upgrade calls?

I think the get_old_code_cid syscall is the right tradeoff.

I think a new entry point is also appropriate. This would also align with discussion about a separate constructor endpoint (https://github.com/filecoin-project/fvm-specs/issues/71), and if we were going to use this pattern again here I'd more or less shelve my points against it. If we're going to do it, let's make the most of it.

[Stebalien]

Could you explain the "opt-in" concern a little more? Opt in by whom?

Opt-in by both the current code, and the new code.

1. The actor upgrading (it has to explicitly call the sself::become_actor syscall.
2. The actor code being upgraded to (it has to provide an upgrade entrypoint and said entrypoint must "accept" the upgrade).

The first case is pretty straightforward.

In the second case...

1. My first concern is just state poisoning (which can be fixed through careful programming).
   1. Some malicious actor A upgrades to a trusted actor.
   2. In the constructor, before setting the state, the new trusted actor makes a send to some other actor.
   3. Eventually, some actor makes a re-entrant call back into A.
   4. Said trusted actor acts on the untrusted state.
2. My second concern is more complicated and is harder to fix.

Let's say that we have three actor types (codes) A (good actor code 1), B (good actor code 2) and M (evil actor code). Let's say that code A and code B implicitly trust each other. Let's also define some "callback" actor Ci, where all actors in the system trust that the callback actor will only perform a callback on an actor that requested one.

• Mallory creates some actor Mi with code M.
• Mi registers a callabck with Ci.
• Mallory upgrades Mi to code A. Let's now call this actor Ai for clarity.
• Eventually, Ci calls back into Ai, triggering a call from Ai to some Bi (an instantiation of B).

Basically, for actor upgrades to be "safe", actor code A needs to be very sure that it doesn't respond to implicitly trusted callbacks like this. Hence the reverse opt-in.

For NotFound "no actor deployed", I think we mean that the code was not found, but the message seems to be saying the only way it could be found is if an actor was previously deployed with it? Can we make the code available without deploying an actor with it? How did the first actor get deployed with that code? Or maybe I'm confused between actor (has state, nonce, etc) and code (just code).

I can't remember the terms we settled on here. We have two phases:

1. Deploy, or maybe we're calling it load now? The phase where we upload code and register it with the init actor.
2. Instantiate when we actually create a new actor.

I'm just saying that the code must exist on-chain, and must be loaded with the init actor.

Why would we want to support the recursive upgrade calls?

E.g., if an actor tries to upgrade to an old version of an actor, that old version may want to immediate upgrade again. The important part is to at least handle this case, but I'd prefer to support it as well.

[Stebalien]

@vyzo suggested passing an upgrade "metadata" IPLD block instead of adding a new syscall. Basically:

/// Called when an actor "upgrades" to this module's code.
///
/// # Parameters
///
/// `params` is an IPLD block handle for the upgrade params, if any.
///
/// # Returns
///
/// The return value is an IPLD block handle 
#[no_mangle]
pub fn upgrade(params: u32, upgrade_info: u32) -> u32;

#[derive(Serialize_tuple, Deserialize_tuple)] // IPLD Block
pub struct UpgradeInfo {
    old_code: Cid,
    // maybe more properties?
}

• Pro: No new context-specific syscall.
• Con: This diverges from our current conventions. Given this upgrade signature, I'd expect invoke to take an ID of an InvocationContext block, or something like that (which would be interesting, but that's not what we currently do).

[Stebalien]

@fridrik01 pointed out an additional issue: re-entrant upgrades. I.e.

1. Actor A (depth=1) calls actor B (2) calls actor A (3).
2. Actor A (depth=3) upgrades itself to some new code CID.
3. Actor A returns, actor B returns.
4. Now we're running actor A but with the wrong code CID.

This is a potential security issue as the old code running as actor A could try to mutate the state after the upgrade. I believe the answer here is to abort. That is:

1. When actor A calls actor B, record actor A's code CID on the stack.
2. When actor B returns to actor A, check if actor A's code CID has changed. If so, revert.

[anorth]

I see a draft in progress for this. I'm a bit confused about the motivation though. What's the use case for upgradeable actors when users can't deploy any actors themselves anyway (#779)?

[Stebalien]

It's a dependency of #473 (comment) and won't actually have any consensus implications until used.

[fridrik01]

Support for actor upgrades was added in filecoin-project/ref-fvm#1866 and the FIP draft is #873. It follows the proposal in this discussion almost exactly, with the following minor changes:

• The new syscall was referred to as sself::become_actor but we renamed it to actor::upgrade_actor to better reflect its meaning
• We decided to not create a separate syscall to get the code cid of the actor initiating the upgrade, but instead the actor::upgrade_actor syscall takes a second UpgradeInfo parameter to pass in metadata IPLD block (as proposed in the discussion above)

[kaitlin-beegle]

A curiosity for @jennijuju, @Stebalien, and @lemmih -

Do Lotus/Venus/Forest currently support features that ought to exist in network actors, but don't because of the burden of migrating actor state for small changes? If/when upgradeable actors are implemented, are there implementation features that ought to be migrated into the actors codebase?

[lemmih]

We don't have anything in Forest that I want to migrate to the actors.

[Stebalien]

So, the feature here doesn't really replace network upgrades (yet). It moves us one step closer to on-chain network upgrades in the future, but that's way into the distant future.

The immediate motivation is smaller: we need a way for an actor to become another actor without a network upgrade. Specifically, #473 (comment). We want to replace our "placeholder" actors with "regular" actors that can upgrade themselves into fully-fledged EVM smart contracts.