[UXIT-1706] Enhance Clarity and Consistency in ‘The Blockchain’ Section #2340
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mirhamasala
force-pushed
the
mm/copy-edits-the-blockchain
branch
from
f1c3823 to
4d3f6f2
Compare
mirhamasala
force-pushed
the
mm/copy-edits-the-blockchain
branch
from
4d3f6f2 to
bef1722
Compare
lanzafame
reviewed
Dec 9, 2024
There was a problem hiding this comment.
@mirhamasala Not sure if you were ready for a review considering the PR was still in draft but since it has been sitting here for 3 weeks I would run an eye over it anyway. Is there anything in particular that you are waiting for to move this PR forward?
|
|
||
| ## 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. |
There was a problem hiding this comment.
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 cryptographic signature for verification | ||
| * The amount of FIL transferred between actors | ||
| - The actor the message was sent to. | ||
| - The actor sending the message. |
There was a problem hiding this comment.
The past tense is more accurate as the message is sent before it is accepted by the network.
| * The amount of FIL transferred between actors | ||
| - The actor the message was sent to. | ||
| - The actor sending the message. | ||
| - The method to call on the receiving actor. |
There was a problem hiding this comment.
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.
|
|
||
| ### 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: |
There was a problem hiding this comment.
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.
|
|
||
| #### 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. |
There was a problem hiding this comment.
It doesn't manage user accounts, it only creates them.
|
|
||
| #### 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. |
There was a problem hiding this comment.
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: |
There was a problem hiding this comment.
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.
|
|
||
| #### 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. |
There was a problem hiding this comment.
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. |
|
|
||
| #### 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. |
There was a problem hiding this comment.
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. |
|
@lanzafame - Thank you for the review. Quite enjoyed learning from your suggestions. We can close this PR without merging, though! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR improves readability and consistency in The Blockchain section of the Filecoin documentation, including updates to language flow, terminology alignment, and clearer explanations.