diff --git a/documentation/en/WIP-arch-complementary-notes.md b/documentation/en/WIP-arch-complementary-notes.md index 013a7bbac..85403cbc1 100644 --- a/documentation/en/WIP-arch-complementary-notes.md +++ b/documentation/en/WIP-arch-complementary-notes.md @@ -1,14 +1,14 @@ # Genesis block -Seems a good way to start exploring the VM state though the instantiation of its different actors like the storage power. +Seems a good way to start exploring the VM state through the instantiation of its different actors like the storage power. -Explain where do we load the genesis block, the CAR entries, and we set the root of the state. Follow the daemon command option, `chain.LoadGenesis()` saves all the blocks of the CAR file into the store provided by `ChainBlockstore` (this should already be explained in the previous section). The CAR root (MT root?) of those blocks is decoded into the `BlockHeader` that will be the Filecoin (genesis) block of the chain, but most of the information was stored in the raw data (non-Filecoin, what's the correct term?) blocks forwarded directly to the chain, the block header just has a pointer to it. +Explain where we load the genesis block, the CAR entries, and we set the root of the state. Follow the daemon command option, `chain.LoadGenesis()` saves all the blocks of the CAR file into the store provided by `ChainBlockstore` (this should already be explained in the previous section). The CAR root (MT root?) of those blocks is decoded into the `BlockHeader` that will be the Filecoin (genesis) block of the chain, but most of the information was stored in the raw data (non-Filecoin, what's the correct term?) blocks forwarded directly to the chain, the block header just has a pointer to it. `SetGenesis` block with name 0. `(ChainStore).SetGenesis()` stores it there. `MakeInitialStateTree` (`chain/gen/genesis/genesis.go`, used to construct the genesis block (`MakeGenesisBlock()`), constructs the state tree (`NewStateTree`) which is just a "pointer" (root node in the HAMT) to the different actors. It will be continuously used in `(*StateTree).SetActor()` an `types.Actor` structure under a certain `Address` (in the HAMT). (How does the `stateSnaps` work? It has no comments.) -From this point we can follow different setup function like: +From this point we can follow different setup functions like: * `SetupInitActor()`: see the `AddressMap`. @@ -40,7 +40,7 @@ List what are the main directories we should be looking at (e.g., `chain/`) and # Tests -Run a few messages and observe state changes. What is the easiest test that also let's us "interact" with it (modify something and observe the difference). +Run a few messages and observe state changes. What is the easiest test that also lets us "interact" with it (modify something and observe the difference). ### Filecoin blocks vs IPFS blocks @@ -84,7 +84,7 @@ func (b *BlockHeader) ToStorageBlock() (block.Block, error) { These edited extracts from the `BlockHeader` show how it's treated as an IPFS block, `github.com/ipfs/go-block-format.block.BasicBlock`, to be both stored and referenced by its block storage CID. -This duality permeates the code (and the Filecoin spec for that matter) but it is usually clear within the context to which block we are referring to. Normally the unqualified *block* is reserved for the Filecoin block and we won't usually refer to the IPFS one but only implicitly through the concept of its CID. With enough understanding of both stack's architecture the two definitions can coexist without much confusion as we will abstract away the IPFS layer and just use the CID as an identifier that we now its unique for two sequences of different *raw* byte strings. +This duality permeates the code (and the Filecoin spec for that matter) but it is usually clear within the context to which block we are referring to. Normally the unqualified *block* is reserved for the Filecoin block and we won't usually refer to the IPFS one but only implicitly through the concept of its CID. With enough understanding of both stack's architecture the two definitions can coexist without much confusion as we will abstract away the IPFS layer and just use the CID as an identifier that we know is unique for two sequences of different *raw* byte strings. (FIXME: We use to do this presentation when talking about `gossipsub` topics and incoming blocks, and had to deal with, besides the block ambiguity, a similar confusion with the *message* term, used in libp2p to name anything that comes through the network, needing to present the extremely confusing hierarchy of a libp2p message containing a Filecoin block, identified by a IPFS block CID, containing Filecoin messages.) @@ -150,4 +150,4 @@ Because we rely heavily on reflection for this part of the code the call chain i This means that when we are tracking the logic of a CLI command we will eventually find this bifurcation and need to study the code of the server-side implementation in `node/impl/full` (mostly in the `common/` and `full/` directories). If we understand this architecture going directly to that part of the code abstracts away the JSON-RPC client/server logic and we can think that the CLI is actually running the node's logic. -FIXME: Explain that "*the* node" is actually an API structure like `impl.FullNodeAPI` with the different API subcomponents like `full.SyncAPI`. We won't see a *single* node structure, each API (full node, minder, etc) will gather the necessary subcomponents it needs to service its calls. \ No newline at end of file +FIXME: Explain that "*the* node" is actually an API structure like `impl.FullNodeAPI` with the different API subcomponents like `full.SyncAPI`. We won't see a *single* node structure, each API (full node, minder, etc) will gather the necessary subcomponents it needs to service its calls. diff --git a/documentation/en/about.md b/documentation/en/about.md index de2bb4c37..210f920b7 100644 --- a/documentation/en/about.md +++ b/documentation/en/about.md @@ -5,7 +5,7 @@ Lotus is an implementation of the **Filecoin Distributed Storage Network**. It is written in Go and provides a suite of command-line applications: - Lotus Node (`lotus`): a Filecoin Node: validates network transactions, manages a FIL wallet, can perform storage and retrieval deals. -- Lotus Miner (`lotus-miner`): a Filecoin miner. See the the respective Lotus Miner section in the Mine documentation. +- Lotus Miner (`lotus-miner`): a Filecoin miner. See the respective Lotus Miner section in the Mine documentation. - Lotus Worker (`lotus-worker`): a worker that assists miners to perform mining-related tasks. See its respective guide for more information. The [Lotus user documentation](https://lotus.filecoin.io/lotus/get-started/what-is-lotus/) is part of the [Filecoin documentation site](https://lotus.filecoin.io): diff --git a/documentation/en/architecture/architecture.md b/documentation/en/architecture/architecture.md index 64914d539..9e78fa650 100644 --- a/documentation/en/architecture/architecture.md +++ b/documentation/en/architecture/architecture.md @@ -81,7 +81,7 @@ Note: The API refers to these stages as `StageHeaders` and `StagePersistHeaders` We proceed in the sync process by requesting block headers from the peer, moving back from their head, until we reach a tipset that we have in common -(such a common tipset must exist, thought it may simply be the genesis block). +(such a common tipset must exist, though it may simply be the genesis block). The functionality can be found in `Syncer::collectHeaders()`. If the common tipset is our head, we treat the sync as a "fast-forward", else we must @@ -126,7 +126,7 @@ If all validations pass we will now set that head as our heaviest tipset in We already have the full state, since we calculated it during the sync process. -FIXME (aayush) I don't fuilly understand the next 2 paragraphs, but it seems important. Confirm and polish. +FIXME (aayush) I don't fully understand the next 2 paragraphs, but it seems important. Confirm and polish. Relevant issue in IPFS: https://github.com/ipfs/ipfs-docs/issues/264 It is important to note at this point that similar to the IPFS architecture of addressing by content and not by location/address (FIXME: check and link to IPFS docs) the "actual" chain stored in the node repo is *relative* to which CID we look for. We always have stored a series of Filecoin blocks pointing to other blocks, each a potential chain in itself by following its parent's reference, and its parent's parent, and so on up to the genesis block. (FIXME: We need a diagram here, one of the Filecoin blog entries might have something similar to what we are describing here.) It only depends on *where* (location) do we start to look for. The *only* address/location reference we hold of the chain, a relative reference, is the `heaviest` pointer. This is reflected by the fact that we don't store it in the `Blockstore` by a fixed, *absolute*, CID that reflects its contents, as this will change each time we sync to a new head (FIXME: link to the immutability IPFS doc that I need to write). @@ -149,7 +149,7 @@ encapsulated in the [`StateTree`](https://github.com/filecoin-project/lotus/blob and accessed through the [`StateManager`](https://github.com/filecoin-project/lotus/blob/master/chain/stmgr/stmgr.go). The state at the chain's head is thus easily tracked and updated in a state root CID. -(FIXME: Talk about CIDs somewhere, we might want to explain some of the modify/flush/update-root mechanism here.)) +(FIXME: Talk about CIDs somewhere, we might want to explain some of the modify/flush/update-root mechanism here.) ## Calculating a Tipset State diff --git a/documentation/en/block-validation.md b/documentation/en/block-validation.md index ccd83a904..d178a0667 100644 --- a/documentation/en/block-validation.md +++ b/documentation/en/block-validation.md @@ -34,7 +34,7 @@ Assemble a `FullTipSet` populated with the single block received earlier. `(*Syncer).collectHeaders()`: we retrieve all tipsets from the received block down to our chain. Validation now is expanded to *every* block inside these tipsets. -`V`: Beacon entires are ordered by their round number. +`V`: Beacon entries are ordered by their round number. `V:` Tipset `Parents` CIDs match the fetched parent tipset through block sync. (This check is not enforced correctly at the moment, see [issue](https://github.com/filecoin-project/lotus/issues/1918).) diff --git a/documentation/en/create-miner.md b/documentation/en/create-miner.md index 7b3b81765..254d70f86 100644 --- a/documentation/en/create-miner.md +++ b/documentation/en/create-miner.md @@ -2,7 +2,7 @@ This document explains the code flow of the [storage miner](https://filecoin-project.github.io/specs/#systems__filecoin_mining) creation process. It describes the flow on two dimensions: at the network level, from the local node to the rest of the Filecoin network, and at the VM level, from the CLI commands to the new chain state. It assumes the reader is already familiar with the general Lotus [architecture](architecture-2.md), relying especially on the descriptions of the CLI/API interface and the VM chain state. -Note we are not following the [Storage Mining](https://lotu.sh/en+mining) user documentation where the miner is created along with the owner through the faucet, but we do those in separate stages try to exercise what will be the closest code path to Mainnet, using the `createStorageMiner()` call in the CLI (when `--actor` is not provided). +Note we are not following the [Storage Mining](https://lotu.sh/en+mining) user documentation where the miner is created along with the owner through the faucet, but we do those in separate stages to try to exercise what will be the closest code path to Mainnet, using the `createStorageMiner()` call in the CLI (when `--actor` is not provided). FIXME: Check that all the information it assumes throughout this document is actually present in the main architecture doc. diff --git a/documentation/en/dev-tools-pond-ui.md b/documentation/en/dev-tools-pond-ui.md index 7d110890b..f20dad44a 100644 --- a/documentation/en/dev-tools-pond-ui.md +++ b/documentation/en/dev-tools-pond-ui.md @@ -19,7 +19,7 @@ Now go to `http://127.0.0.1:2222`. ## What can I test? - The `Spawn Node` button starts a new **Lotus Node** in a new draggable window. -- Click `[Spawn Miner]` to start a **Lotus Miner**. This require's the node's wallet to have funds. +- Click `[Spawn Miner]` to start a **Lotus Miner**. This requires the node's wallet to have funds. - Click on `[Client]` to open the **Lotus Node**'s client interface and propose a deal with an existing Miner. If successful you'll see a payment channel open up with that Miner. Don't leave Pond unattended for more than 10 hours, the web client will eventually consume all available RAM. diff --git a/documentation/en/jaeger-tracing.md b/documentation/en/jaeger-tracing.md index ec9351d53..2c0cf566b 100644 --- a/documentation/en/jaeger-tracing.md +++ b/documentation/en/jaeger-tracing.md @@ -19,7 +19,7 @@ export LOTUS_JAEGER_AGENT_ENDPOINT=127.0.0.1:6831 lotus daemon ``` -Alternatively, the agent endpoint can also be configured by a pair of environemnt variables to provide the host and port. The following snipit is functionally equivilent to the previous. +Alternatively, the agent endpoint can also be configured by a pair of environment variables to provide the host and port. The following snippet is functionally equivalent to the previous. ```bash export LOTUS_JAEGER_AGENT_HOST=127.0.0.1