A Filecoin address is an identifier that refers to an actor in the Filecoin state. All actors (miner actors, the storage market actor, account actors) have an address. This address encodes information about the network to which an actor belongs, the specific type of address encoding, the address payload itself, and a checksum. The goal of this format is to provide a robust address format that is both easy to use and resistant to errors.
All Filecoin addresses begin with an
f to indicate the network (Filecoin), followed by any of the address prefix numbers (
4) to indicate the address type. There are five address types:
|An ID address.|
|A SECP256K1 public key address.|
|An actor address.|
|A BLS public key address.|
|Extensible, user-defined actor addresses.|
Each of the address types is described below.
All actors have a short integer assigned to them by
InitActor, a unique actor that can create new actors. This integer that gets assigned is the ID of that actor. An ID address is an actor’s ID prefixed with the network identifier and the address type.
Actor ID addresses are not robust, in the sense that they do depend on chain state, and are defined on-chain by the
InitActor. Additionally, actor IDs can change for a brief time after creation if the same ID is assigned to different actors on different forks. Actor ID addresses are similar to monotonically increasing numeric primary keys in a relational database. So, when a chain reorganization occurs (similar to a rollback in a SQL database), you can refer to the same ID for different rows. The expected consensus algorithm will resolve the conflict. Once the state that defines a new ID reaches finality, no changes can occur, and the ID is bound to that actor forever.
For example, the mainnet burn account ID address,
f099, is structured as follows:
Address type | f 0 9 9 | | | Actor ID | Network identifier
ID addresses are often referred to by their shorthand
Actors managed directly by users, like accounts, are derived from a public-private key pair. If you have access to a private key, you can sign messages sent from that actor. The public key is used to derive an address for the actor. Public key addresses are referred to as robust addresses as they do not depend on the Filecoin chain state.
Public key addresses allow devices, like hardware wallets, to derive a valid Filecoin address for your account using just the public key. The device doesn’t need to ask a remote node what your ID address is. Public key addresses provide a concise, safe, human-readable way to reference actors before the chain state is final. ID addresses are used as a space-efficient way to identify actors in the Filecoin chain state, where every byte matters.
Filecoin supports two types of public key addresses:
secp256k1addresses that begin with the prefix
- BLS addresses that begin with the prefix
For BLS addresses, Filecoin uses
curve bls12-381 for BLS signatures, which is a pair of two related curves,
G1 for public keys, as G1 allows for a smaller representation of public keys, and
G2 for signatures. This implements the same design as ETH2, but contrasts with Zcash, which has signatures on
G1 and public keys on
G2. However, unlike ETH2, which stores private keys in big-endian order, Filecoin stores and interprets private keys in little-endian order.
Public key addresses are often referred to by their shorthand,
Actor addresses provide a way to create robust addresses for actors not associated with a public key. They are generated by taking a
sha256 hash of the output of the account creation. The ZH storage provider has the actor address
f2plku564ddywnmb5b2ky7dhk4mb6uacsxuuev3pi and the ID address
Actor addresses are often referred to by their shorthand,
Extensible user-defined actors
Filecoin supports extensible, user-defined actor addresses through the
f4 address class, introduced in fip-0048. The
f4 address class provides the following benefits to the network:
- A predictable addressing scheme to support interactions with addresses that do not yet exist on-chain.
- User-defined, custom addressing systems without extensive changes and network upgrades.
- Support for native addressing schemes from foreign runtimes such as the EVM.
f4 address is structured as
<address-manager-actor-id> is the actor ID of the address manager, and
<new-actor-id> is the arbitrary actor ID chosen by that actor. An address manager is an actor that can create new actors and assign an
f4 address to the new actor.
f4addresses may only be assigned by and in association with specific, built-in actors called address managers. Once users are able to deploy custom WebAssembly actors, this restriction will likely be relaxed, in a future FIP.
As an example: suppose an address manager has an actor ID (an
123, and that address manager creates a new actor. Then, the
f4 address of the actor created by the address manager is
f4 is the address class,
123 is the actor ID of the address manager,
f is a separator, and
a3491xyz is the arbitrary
<new-actor-id> chosen by that actor.