Record predictable addresses in actor roots

[Stebalien]

Deprecated: This proposal has been merged into FIP0048 in #572.

Proposal: Record an actor's predictable¹ address (f1/f3/f4) (if any) in the actor's state-root object.

Depends on #474.

Motivation

We call f1, f3, and f4 addresses "predictable" because, unlike f0 and f2 addresses, they address types can (sometimes) be predicted before an actor is deployed on chain. Specifically:

• f1/f3 addresses are always predictable as they're derived from the account's public key.
• An f4 address may be predictable, depending on responsible the address manager.

These addresses may be useful to know because:

• The address may be computed and stored on-chain before the actor is actually deployed. In this case, it can be useful to resolve the caller's actor ID to the caller's "predictable" address. We usually resolve addresses actor IDs before recording them on-chain, but this may not always be desirable (e.g., to save gas if the addressed actor may not ever be deployed on chain).
• The address may be a part of some...

At the moment, the only predictable addresses on-chain (f1 and f3) are stored inside account state and can be accessed by calling the PubkeyAddress method on the target account actor. However:

1. This inefficient. It requires a syscall to resolve the actors code ID and a full inter-actor send to actually lookup the public key.
2. The f4 address class further complicates the issue:
   1. An f4 actor wouldn't even be able to learn its predictable address unless it's passed into the constructor.
   2. Worse, the constructor is called by-proxy by an address management actor (UserActor -> AddressManager -> Constructor) where the user's actor specifies the constructor parameters but the address manager chooses the f4 address.
3. FEVM (EVM on the FVM) will need to know the "Ethereum" address of the calling actor. This means we either need to:
   1. Pass and validate the Ethereum address on every call.
   2. Lookup the Ethereum address on every call.

Proposal

Extend the ActorState object as follows:

pub struct ActorState {
    /// Link to code for the actor.
    pub code: Cid,
    /// Link to the state of the actor.
    pub state: Cid,
    /// Sequence of the actor.
    pub sequence: u64,
    /// Tokens available to the actor.
    pub balance: TokenAmount,

    /// NEW: Predictable address.
    pub address: Option<Address>,
}

When an actor object is first created, the address would be set if specified. Actors created through Init.Exec would not have this field set because these actors would only have f2 addresses.

Additionally, extend the create_actor syscall to take an optional "predictable" address:

/// Creates a new actor in the state-tree with the specified actor ID, recording the specified
/// "predictable" address in the actor root if non-empty, and returning a new stable address.
///
/// **Privileged:** May only be called by the init actor.
pub fn create_actor(
    actor_id: u64,
    typ_off: *const u8,
    predictable_addr_off: *const u8, // new
    predictable_addr_len: u32, // new. Pass 0 to ignore.
) -> Result<()>;

Finally, add a new lookup_address syscall for looking up an actor's "predictable" address by ID:

/// Looks up the "predictable" address of the target actor.
///
/// # Arguments
///
/// `addr_buf_off` and `addr_buf_len` specify the location and length of the output buffer in
/// which to store the address.
///
/// # Returns
///
/// The length of the address written to the output buffer, or 0 if the target actor has no
/// predictable address.
///
/// # Errors
///
/// | Error               | Reason                                                           |
/// |---------------------|------------------------------------------------------------------|
/// | [`NotFound`]        | if the target actor does not exist                               |
/// | [`BufferTooSmall`]  | if the output buffer isn't large enough to fit the address       |
/// | [`IllegalArgument`] | if the output buffer isn't valid, in memory, etc.                |
pub fn lookup_address(
    actor_id: u64,
    addr_buf_off: *mut u8,
    addr_buf_len: u32,
) -> Result<u32>;

Analysis

The benefits of this approach are:

1. There's a single source of truth for all actor-related information.
2. In most cases, this information will be cached (both reads and writes).

The downside is that we're making all actor objects slightly bigger, and paying that cost on every actor invocation and every time an actor updates their balance, state, etc. However:

1. Given that we buffer writes to the actor state-tree, the write amplification should be amortized.
2. Given that we store multiple actor objects next to each other in the stat-tree, this isn't going to be the most significant source of write amplification anyways.

Alternatives

Userspace

We could continue to implement this feature in userspace. This would require:

1. Creating a convention for passing an actor's "predictable" address into actors on construction.
2. Defining a conventional method for retrieving such addresses (e.g., with FRC-0042) and validating said address.

Separate Table

Alternatively, we could create a new map (or even an AMT) in the init actor mapping ID addresses to stable addresses.

• This table is small and likely easy to cache, especially because it's write once.
• This extra state would not bloat every single actor update.

The downside is that this we'd need to maintain this separate table along with a separate cache for performance (handling reverts, etc.). Really, there's little benefit over storing this information in the actor state object itself.

Footnotes

1. This isn't a great name, but I can't think of a better one other than "not randomly chosen" or "useful" or "meaningful". ↩

[Stebalien]

Extension: remove addresses from account state (now redundant)?

[anorth]

The main reason I see not to is that external tools that use state inspection might rely on it. I'm not sure how entrenched the assumption of that state might be. Otherwise 👍 .

[anorth]

Thanks @Stebalien, I think this is a good proposal.

[anorth]

You haven't address on-chain access of these addresses, which I think we need. I propose a new syscall that returns the optional address of any actor ID.

[Stebalien]

You haven't address on-chain access of these addresses, which I think we need. I propose a new syscall that returns the optional address of any actor ID.

Yeah:

mod actor {
    fn lookup_address(actor_id: ActorID, addr_out_off: *mut u8, addr_out_len: u32) -> u32; // returns the length, or 0 if not found.
}

[Stebalien]

Added.

[ZenGround0]

This isn't a great name, but I can't think of a better one other than "not randomly chosen" or "useful" or "meaningful".

chosen address?

[anorth]

How about "external address", highlighting the differentation from ActorIDs?

[Stebalien]

• Chosen: it includes f1/f3.
• External: what about f2? I'm not including f2 here.

Although chosen address seems like the best option so far. I'm also happy to exclude f1/f3 if we feel that's a good idea...

[Stebalien]

Planned extension: use this address as the source of truth in the verify_signature and new_actor_address syscalls to save some gas.

[anorth]

This proposal seems to be missing description of what create_actor does with the provided address. By omission, I assumed that it just accepts and sets the address. However this seems to be more intimately tied with FIP-0048. In prototype code I'm examining, you have create_actor making the check that the provided predictable address matches an address previously set when establishing an embryo. FIP-0048 suggests that that check happens in the Init actor (which would make the VM simpler – generally good but sometimes less important than tight-loop performance).

Perhaps this should be merged into FIP-0048? If not, the proposals probably need to refer to each other and clearly describe interactions, in order to function as a spec.

[Stebalien]

I'll reference this FIP in 0048.

NOTE: that check should just be a sanity check. It means that the the init actor thinks that there's already an actor deployed there with the given f4 address.