Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[UXIT-1706] Enhance Clarity and Consistency in ‘The Blockchain’ Section #2340

Closed
wants to merge 1 commit into from
Closed

[UXIT-1706] Enhance Clarity and Consistency in ‘The Blockchain’ Section #2340

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 68 additions & 60 deletions basics/the-blockchain/actors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,133 +1,141 @@
---
description: >-
Actors are smart contracts that run on the Filecoin virtual machine (FVM) and
are used to manage, query, and update the state of the Filecoin network. Smart
contracts are small, self-executing blocks.
Actors are smart contracts that run on the Filecoin Virtual Machine (FVM). They manage, query, and update the state of the Filecoin network.
---

# Actors

For those familiar with the Ethereum virtual machine (EVM), _actors_ work similarly to [smart contracts](../../smart-contracts/fundamentals/). In the Filecoin network, there are two types of actors:
For those familiar with the Ethereum Virtual Machine (EVM), _actors_ work similarly to [smart contracts](../../smart-contracts/fundamentals/). In the Filecoin network, there are two types of actors:

* [_Built-in actors_](actors.md#built-in-actors): Hardcoded programs written ahead of time by network engineers that manage and orchestrate key subprocesses and subsystems in the Filecoin network.
* [_User actors_](actors.md#user-actors-smart-contracts): Code implemented by **any developer** that interacts with the Filecoin Virtual Machine (FVM).
- [_Built-in actors_](actors.md#built-in-actors): Hardcoded programs written ahead of time by network engineers that manage and orchestrate key subprocesses and subsystems in the Filecoin network.
- [_User actors_](actors.md#user-actors-smart-contracts): Code implemented by **any developer** that interacts with the FVM.

## Built-in actors

Built-in actors are how the Filecoin network manages and updates _global state_. The _global state_ of the network at a given epoch can be thought of as the set of blocks agreed upon via network consensus in that epoch. This global state is represented as a _state tree_, which maps an actor to an _actor state_. An _actor state_ describes the current conditions for an individual actor, such as its FIL balance and its nonce. In Filecoin, actors trigger a _state transition_ by sending a _message_. Each block in the chain can be thought of as a **proposed** global state, where the block selected by network consensus sets the **new** global state. Each block contains a series of messages and a checkpoint of the current global state after the application of those messages. The Filecoin Virtual Machine (FVM) is the Filecoin network component that is in charge of the execution of all actor code.
Built-in actors manage and update the _global state_ of the Filecoin network. The _global state_ at a given epoch is the set of blocks agreed upon via network consensus. This global state is represented as a _state tree_, mapping an actor to an _actor state_. The _actor state_ describes conditions such as the actor's FIL balance and nonce. In Filecoin, actors trigger _state transitions_ by sending _messages_. Each block in the chain represents a **proposed** global state, and the block selected by network consensus becomes the **new** global state. Each block contains a series of messages and a checkpoint of the current global state after applying those messages. The FVM executes all actor code.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Built-in actors manage and update the _global state_ of the Filecoin network. The _global state_ at a given epoch is the set of blocks agreed upon via network consensus. This global state is represented as a _state tree_, mapping an actor to an _actor state_. The _actor state_ describes conditions such as the actor's FIL balance and nonce. In Filecoin, actors trigger _state transitions_ by sending _messages_. Each block in the chain represents a **proposed** global state, and the block selected by network consensus becomes the **new** global state. Each block contains a series of messages and a checkpoint of the current global state after applying those messages. The FVM executes all actor code.
Built-in actors manage and update the _global state_ of the Filecoin network. The _global state_ at a given epoch is the set of blocks agreed upon via network consensus. This global state is represented as a _state tree_, mapping an actor to an _actor state_. The _actor state_ describes conditions such as the actor's FIL balance and nonce. In Filecoin, actors trigger _state transitions_ by sending _messages_. Each block in the chain represents a **proposed** global state, and the blocks selected by network consensus become the **new** global state. Each block contains a series of messages and a checkpoint of the current global state after applying those messages. The FVM executes all actor code.

Filecoin isn't a singular block per epoch chain. The global state for each epoch is represented by one or more blocks, with the average range being 4 to 7, see the number of IDs listed against each height aka epoch for a sense of the number of blocks per tipset: https://filfox.info/en/tipset


A basic example of how actors are used in Filecoin is the process by which storage providers prove storage and are subsequently rewarded. The process is as follows:
### Example usage of actors

1. The [`StorageMinerActor`](actors.md#storagemineractor) processes proof of storage from a storage provider.
2. The storage provider is awarded storage power based on whether the proof is valid or not.
3. The [`StoragePowerActor`](actors.md#storagepoweractor) accounts for the storage power.
4. During block validation, the [`StoragePowerActor`](actors.md#storagepoweractor) state, which includes information on storage power allocated to each storage provider, is read.
5. Using the state information, the consensus mechanism randomly awards blocks to the storage providers with the most power, and the [`RewardActor`](actors.md#rewardactor) sends FIL to storage providers.
A basic example of how actors are used in Filecoin is the process by which storage providers prove storage and are rewarded:

1. The [`StorageMinerActor`](actors.md#storagemineractor) processes proof of storage submitted by a storage provider.
2. If valid, the storage provider is awarded storage power.
3. The [`StoragePowerActor`](actors.md#storagepoweractor) records this power in the system.
4. During block validation, the state recorded by the `StoragePowerActor` is checked.
5. Using this state, the consensus mechanism rewards storage providers with the most power by awarding blocks, and the [`RewardActor`](actors.md#rewardactor) sends FIL as a reward.

### Blocks

Each block in the Filecoin chain contains the following:
Each block in the Filecoin chain contains:

* Inline data such as current block height.
* A pointer to the current state tree.
* A pointer to the set of messages that, when applied to the network, generated the current state tree.
- Inline data such as the current block height.
- A pointer to the current state tree.
- A pointer to the set of messages that, when applied to the network, generated the current state tree.

### State tree

A [Merkle Directed Acyclic Graph (Merkle DAG)](../../reference/general/glossary.md#merkle-directed-acyclic-graph) is used to map the state tree and the set of messages. Nodes in the state tree contain information on:
The _state tree_ is a [Merkle Directed Acyclic Graph (Merkle DAG)](../../reference/general/glossary.md#merkle-directed-acyclic-graph). It maps the relationships between actors and their states. Nodes in the state tree store:

- Information about actors, including FIL balances and nonces.
- Links (CIDs) pointing to actor state data.

* Actors, like FIL balance, nonce, and a pointer (CID) to actor state data.
* Messages in the current block
The state tree is updated by messages, which trigger state transitions and ensure it reflects the latest state of the network.

### Messages

Like the state tree, a Merkle Directed Acyclic Graph (Merkle DAG) is used to map the set of messages for a given block. Nodes in the messages may contain information on:
Messages are the instructions actors use to interact with each other. These are also represented in a Merkle DAG. Nodes in the messages may contain:

* The actor the message was sent to
* The actor that sent the message
* Target method to call on the actor being sent the message
* A cryptographic signature for verification
* The amount of FIL transferred between actors
- The actor the message was sent to.
- The actor sending the message.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The past tense is more accurate as the message is sent before it is accepted by the network.

- The method to call on the receiving actor.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- The method to call on the receiving actor.
- The method to call on the target actor.

Receiving suggests that there is a movement of tokens and not just that an actor may perform an action.

Think of an actor as a serverless function, you target the function of a particular serverless function not have it receive a method call.

- A cryptographic signature for verification.
- The amount of FIL transferred between actors.

### Actor code

The code that defines an actor in the Filecoin network is separated into different methods. Messages sent to an actor contain information on which method(s) to call and the input parameters for those methods. Additionally, actor code interacts with a _runtime_ object, which contains information on the general state of the network, such as the current epoch, cryptographic signatures, and proof validations. Like smart contracts in other blockchains, actors must pay a _gas fee_, which is some predetermined amount of FIL to offset the cost (network resources used, etc.) of a transaction. Every actor has a Filecoin balance attributed to it, a state pointer, a code that tells the system what type of actor it is, and a nonce, which tracks the number of messages sent by this actor.
Actor code defines what an actor does and is separated into methods. Messages specify which methods to call and any input parameters. Actor code interacts with a _runtime_ object, which provides network information like the current epoch or cryptographic validations. Actors must pay a _gas fee_ (in FIL) for executing operations. Each actor has:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Actor code defines what an actor does and is separated into methods. Messages specify which methods to call and any input parameters. Actor code interacts with a _runtime_ object, which provides network information like the current epoch or cryptographic validations. Actors must pay a _gas fee_ (in FIL) for executing operations. Each actor has:
Actor code defines what an actor does and is separated into methods. Messages specify which methods of an actor to call and any input parameters. Actor code interacts with a _runtime_ object, which provides network information like the current epoch, cryptographic signatures, and proof validations. Actors must pay a _gas fee_ (in FIL) for executing operations. Each actor has:

Clarifying whose methods and cryptographic validations seemed to be a typo.


- A balance of FIL.
- A pointer to its state.
- Code defining its type and behavior.
- A nonce tracking the number of messages it has sent.

### Types of built-in actors

The 11 different types of built-in actors are as follows:
The 11 types of built-in actors are:

* [CronActor](actors.md#cronactor)
* [InitActor](actors.md#initactor)
* [AccountActor](actors.md#accountactor)
* [RewardActor](actors.md#rewardactor)
* [StorageMarketActor](actors.md#storagemarketactor)
* [StorageMinerActor](actors.md#storagemineractor)
* [MultisigActor](actors.md#multisigactor)
* [PaymentChannelActor](actors.md#paymentchannelactor)
* [StoragePowerActor](actors.md#storagepoweractor)
* [VerifiedRegistryActor](actors.md#verifiedregistryactor)
* [SystemActor](actors.md#systemactor)
- [CronActor](actors.md#cronactor)
- [InitActor](actors.md#initactor)
- [AccountActor](actors.md#accountactor)
- [RewardActor](actors.md#rewardactor)
- [StorageMarketActor](actors.md#storagemarketactor)
- [StorageMinerActor](actors.md#storagemineractor)
- [MultisigActor](actors.md#multisigactor)
- [PaymentChannelActor](actors.md#paymentchannelactor)
- [StoragePowerActor](actors.md#storagepoweractor)
- [VerifiedRegistryActor](actors.md#verifiedregistryactor)
- [SystemActor](actors.md#systemactor)

#### CronActor

The `CronActor` sends messages to the `StoragePowerActor` and `StorageMarketActor` at the end of each epoch. The messages sent by `CronActor` indicate to StoragePowerActor and StorageMarketActor how they should maintain the internal state and process deferred events. This system actor is instantiated in the genesis block and interacts directly with the FVM.
The `CronActor` sends messages to the `StoragePowerActor` and `StorageMarketActor` at the end of each epoch. These messages ensure internal states are updated and deferred events are processed. This actor is instantiated in the genesis block and interacts directly with the FVM.

#### InitActor

The `InitActor` can initialize new actors on the Filecoin network. This system actor is instantiated in the genesis block and maintains a table resolving a public key and temporary actor addresses to their canonical ID addresses. The `InitActor` interacts directly with the FVM.
The `InitActor` initializes new actors on the Filecoin network. It maps public keys and temporary actor addresses to canonical ID addresses. This actor is instantiated in the genesis block and interacts directly with the FVM.

#### AccountActor

The `AccountActor` is responsible for user accounts. Account actors are not created by the `InitActor` but by sending a message to a public-key style address. The account actor updates the state tree with a new actor address and interacts directly with the FVM.
The `AccountActor` manages user accounts by updating the state tree with new actor addresses. It interacts directly with the FVM.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It doesn't manage user accounts, it only creates them.


#### RewardActor

The `RewardActor` manages unminted Filecoin tokens and distributes rewards directly to miner actors, where they are locked for vesting. The reward value used for the current epoch is updated at the end of an epoch. The `RewardActor` interacts directly with the FVM.
The `RewardActor` distributes rewards to miner actors based on their contributions. Rewards are locked for vesting, and values are updated at the end of each epoch. This actor interacts directly with the FVM.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `RewardActor` distributes rewards to miner actors based on their contributions. Rewards are locked for vesting, and values are updated at the end of each epoch. This actor interacts directly with the FVM.
The `RewardActor` distributes rewards to storage provider actors based on their contributions. Rewards are locked for vesting, and values are updated at the end of each epoch. This actor interacts directly with the FVM.


#### StorageMarketActor

The `StorageMarketActor` is responsible for processing and managing on-chain deals. This is also the entry point of all storage deals and data into the system. This actor keeps track of storage deals and the locked balances of both the client storing data and the storage provider. When a deal is posted on-chain through the `StorageMarketActor`, the actor will first check if both transacting parties have sufficient balances locked up and include the deal on-chain. Additionally, the `StorageMarketActor` holds _Storage Deal Collateral_ provided by the storage provider to collateralize deals. This collateral is returned to the storage provider when all deals in the sector successfully conclude. This actor does not interact directly with the FVM.
The `StorageMarketActor` processes and manages on-chain deals. It tracks storage deals and the locked balances of both clients and storage providers. When a deal is posted, it ensures both parties have sufficient collateral before including the deal on-chain. Collateral is returned when deals are successfully completed. This actor does not interact directly with the FVM.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I am aware the builtin StorageMarketActor is not used for any of the storage deals that occur on the network currently. We should figure out if it should be marked as deprecated or removed. It certainly still exists in the code base but it is not being used as described here and won't be again from my understanding.


#### StorageMinerActor

The `StorageMinerActor` is created by the `StoragePowerActor` and is responsible for storage mining operations and the collection of mining proofs. This actor is a key part of the Filecoin storage mining subsystem, which ensures a storage miner can effectively commit storage to Filecoin and handles the following:
The `StorageMinerActor` manages storage mining operations and proof collection. It ensures miners can effectively commit storage and handles:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `StorageMinerActor` manages storage mining operations and proof collection. It ensures miners can effectively commit storage and handles:
The `StorageMinerActor` manages storage provider operations and proof collection. It ensures storage providers can effectively commit storage and handles:

The actor code still contains the term Miner but it should be changed to StorageProviderActor at some point in line with FIP0018.


* Committing new storage
* Continuously proving storage
* Declaring storage faults
* Recovering from storage faults
- Committing new storage.
- Continuously proving storage.
- Declaring and recovering from storage faults.

This actor does not interact directly with the FVM.
This actor does not directly interact with the FVM.

#### MultisigActor

The `MultisigActor` is responsible for dealing with operations involving the Filecoin wallet and represents a group of transaction signers with a maximum of 256. Signers may be external users or the `MultisigActor` itself. This actor does not interact directly with the FVM.
The `MultisigActor` facilitates Filecoin wallet operations and transactions involving up to 256 signers. This actor does not directly interact with the FVM.

#### PaymentChannelActor

The `PaymentChannelActor` creates and manages _payment channels_, a mechanism for off-chain microtransactions for Filecoin dApps to be reconciled on-chain at a later time with less overhead than a standard on-chain transaction and no gas costs. Payment channels are uni-directional and can be funded by adding to their balance. To create a payment channel and deposit fund, a user calls the `PaymentChannelActor`. This actor does not interact directly with the FVM.
The `PaymentChannelActor` enables off-chain microtransactions for Filecoin dApps. It manages uni-directional payment channels, allowing transactions to be reconciled on-chain with minimal overhead. This actor does not directly interact with the FVM.

#### StoragePowerActor

The `StoragePowerActor` is responsible for keeping track of the storage power allocated to each storage miner and has the ability to create a `StorageMinerActor`. This actor does not interact directly with the FVM.
The `StoragePowerActor` tracks the storage power of miners and determines block rewards based on proportional allocations. It creates `StorageMinerActor` instances and does not directly interact with the FVM.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `StoragePowerActor` tracks the storage power of miners and determines block rewards based on proportional allocations. It creates `StorageMinerActor` instances and does not directly interact with the FVM.
The `StoragePowerActor` tracks the storage power of storage providers and determines block rewards based on proportional allocations. It creates `StorageMinerActor` instances and does not directly interact with the FVM.


#### VerifiedRegistryActor

The `VerifiedRegistryActor` is responsible for managing Filecoin Plus clients. This actor can add a verified client to the Filecoin Plus program, remove and reclaim expired DataCap allocations, and manage claims. This actor does not interact directly with the FVM.
The `VerifiedRegistryActor` manages Filecoin Plus clients and DataCap allocations, including adding verified clients and managing claims. This actor does not directly interact with the FVM.

#### SystemActor

For more information on `SystemActor`, see the [source code](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/system/system\_actor.go).
The `SystemActor` performs low-level operations essential for the network. It is instantiated in the genesis block and interacts directly with the FVM. For more details, refer to the [source code](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/system/system_actor.go).

## User actors (smart contracts)

A _user actor_ is code defined by **any developer** that can interact with the FVM, otherwise known as a _smart contract_.

A _smart contract_ is a small, self-executing block of custom code that runs on other blockchains, like Ethereum. In the Filecoin network, the term is a synonym for [_user actor_](actors.md#user-actors-smart-contracts). You may see the term _smart contract_ used in tandem with _user actor_, but there is no difference between the two.
_User actors_ (or _smart contracts_) are custom programs created by developers to define new rules and interactions within the Filecoin network. They can currently be written in Solidity, with future support planned for languages compiling to WebAssembly (Wasm). User actors can:

With the FVM, actors can be written in Solidity. In future updates, any language that compiles to WASM will be supported. With user actors, users can create and enforce custom rules for storing and accessing data on the network. The FVM is responsible for actors and ensuring that they are executed correctly and securely.
- Define rules for storing and accessing data.
- Automate workflows for data management.
- Manage transactions between users and services.

The FVM ensures these custom actors execute securely. Developers can use them to build scalable applications leveraging Filecoin’s decentralized storage.

To learn more, see [writing smart contracts](../../smart-contracts/fundamentals/).

[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill\_Page+URL=https://docs.filecoin.io/basics/the-blockchain/actors)
[Was this page helpful?](https://airtable.com/apppq4inOe4gmSSlk/pagoZHC2i1iqgphgl/form?prefill_Page+URL=https://docs.filecoin.io/basics/the-blockchain/actors)
Loading