diff --git a/.vscode/settings.json b/.vscode/settings.json index 2accb736..2282049d 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,6 +1,7 @@ { "cSpell.words": [ "smesher", + "smeshers", "Smeshing", "Spacemesh" ] diff --git a/docs/learn/blocks.md b/docs/learn/blocks.md index d21b01d2..c44351b4 100644 --- a/docs/learn/blocks.md +++ b/docs/learn/blocks.md @@ -5,13 +5,13 @@ title: Blocks and Transactions In traditional blockchains such as Bitcoin or Ethereum each block contains a "backwards pointer" to the previous known block (i.e., the previous chain head). In this way it's not possible to replace a single, historical block without replacing every block that came after. -Due to its mesh design, Spacemesh doesn't work this way. Spacemesh blocks are freestanding, i.e., each individual block is deemed valid or invalid on its own right by the consensus mechanisms, Tortoise and Hare. The protocol allows for zero or more valid blocks in a given layer. The vast majority of layers are expected to have a single valid, effective block. Empty layers may occur from time to time when certain assumptions are violated, e.g., when many miners are offline and the Hare consensus mechanism fails. +Due to its mesh design, Spacemesh doesn't work this way. Spacemesh blocks are freestanding, i.e., each individual block is deemed valid or invalid on its own right by the consensus mechanisms, Tortoise and Hare. The protocol allows for zero or more valid blocks in a given layer. The vast majority of layers are expected to have a single valid, effective block. Empty layers may occur from time to time when certain assumptions are violated, e.g., when many smeshers are offline and the Hare consensus mechanism fails. -There can only be multiple valid blocks in a given layer when security assumptions are temporarily violated, e.g., when the network temporarily loses synchrony or > 1/3 of miners act dishonestly. In this case the protocol dictates that a single block be deterministically chosen as the only _effective_ block for the layer. Over time the network's self-healing mechanism ensures that all honest nodes reach consensus on the canonical set of valid, effective blocks, zero or one per layer. +There can only be multiple valid blocks in a given layer when security assumptions are temporarily violated, e.g., when the network temporarily loses synchrony or > 1/3 of smeshers act dishonestly. In this case the protocol dictates that a single block be deterministically chosen as the only _effective_ block for the layer. Over time the network's self-healing mechanism ensures that all honest nodes reach consensus on the canonical set of valid, effective blocks, zero or one per layer. In practice this means that a _single historical block_ and its contents may be reorg'ed in or out of the canonical chain. When a historical change occurs, the state rolls back (i.e., reorgs) to the point of change and all subsequent canonical state (i.e., all transactions in the new canonical chain) is replayed from that point forward. This could mean that transactions in the canonical chain that were previously effective now become ineffective, or vice versa. It may also mean that the same transaction (uniquely identified by its transaction ID) may appear in multiple blocks, in the same layer or in multiple layers. When this happens, only the first instance of the transaction in the canonical chain is considered effective; later instances are ignored. -A layer contains zero or more blocks. Most layers contain exactly one block, but it's possible for a layer to have zero blocks (when the network is under attack, or during times when many miners were offline or otherwise acting Byzantine) or more than one block (e.g., after a network partition-and-rejoin). In rare cases of multiple blocks, the network will establish consensus on a single block as canonical; transactions in other blocks will not be included in the canonical mesh nor processed. A block may thus be _valid_ or _invalid_ and there may only be one _valid_ block per layer. +A layer contains zero or more blocks. Most layers contain exactly one block, but it's possible for a layer to have zero blocks (when the network is under attack, or during times when many smeshers were offline or otherwise acting Byzantine) or more than one block (e.g., after a network partition-and-rejoin). In rare cases of multiple blocks, the network will establish consensus on a single block as canonical; transactions in other blocks will not be included in the canonical mesh nor processed. A block may thus be _valid_ or _invalid_ and there may only be one _valid_ block per layer. Blocks contain zero or more transactions. Blocks are uniquely indexed by their block hash. diff --git a/docs/learn/economics.md b/docs/learn/economics.md index fff7bab7..fd2e3ca6 100644 --- a/docs/learn/economics.md +++ b/docs/learn/economics.md @@ -3,10 +3,10 @@ id: economics title: Economics --- -The primary goal of Spacemesh is to make mining from home easy and economically sustainable over the long term. This means that home miners should not be "priced out" by large-scale, industrial "whale" mining operations with large economies of scale. While we cannot perfectly eliminate economies of scale--for instance, large scale operations will likely be able to acquire data storage more cheaply on a per-TB basis, and will likely have access to cheaper power--what we can do (and, indeed, have done) is level the playing field by introducing _diseconomies of scale_ that favor home miners. +The primary goal of Spacemesh is to make mining (called "smeshing" in Spacemesh) from home easy and economically sustainable over the long term. This means that home miners (called "smeshers" in Spacemesh) should not be "priced out" by large-scale, industrial "whale" mining operations with large economies of scale. While we cannot perfectly eliminate economies of scale--for instance, large scale operations will likely be able to acquire data storage more cheaply on a per-TB basis, and will likely have access to cheaper power--what we can do (and, indeed, have done) is level the playing field by introducing _diseconomies of scale_ that favor home smeshers. -To understand how this works it's necessary to consider [marginal cost](https://en.wikipedia.org/wiki/Marginal_cost). For a miner running her node on a computer that she already owns and uses every day, on a home Internet connection that she already has, the marginal cost is effectively zero. More precisely, the marginal cost is the cost of the GPU-based PoST initialization (which amortizes to zero over time), and the cost of keeping the computer turned on and online all the time rather than during the hours she'd normally use it. For the average home miner with an unmetered broadband Internet connection this works out to around $10-20 annually. Such a miner simply needs to earn more than this per year from mining for it to be worthwhile. +To understand how this works it's necessary to consider [marginal cost](https://en.wikipedia.org/wiki/Marginal_cost). For a smesher running her node on a computer that she already owns and uses every day, on a home Internet connection that she already has, the marginal cost is effectively zero. More precisely, the marginal cost is the cost of the GPU-based PoST initialization (which amortizes to zero over time), and the cost of keeping the computer turned on and online all the time rather than during the hours she'd normally use it. For the average home smesher with an unmetered broadband Internet connection this works out to around $10-20 annually. Such a smesher simply needs to earn more than this per year from mining for it to be worthwhile. -By contrast, a hobbyist miner investing time and money into building a custom mining setup has both a higher startup cost and a higher ongoing cost. An industrial miner has an even larger, more complex cost structure. The cost of mining at scale--factoring in power, bandwidth, redundancy, fixing drive failures, devops, etc.--means that large scale mining operations are not able to compete on a marginal cost basis with home miners. +By contrast, a hobbyist smesher investing time and money into building a custom mining setup has both a higher startup cost and a higher ongoing cost. An industrial smesher has an even larger, more complex cost structure. The cost of mining at scale--factoring in power, bandwidth, redundancy, fixing drive failures, devops, etc.--means that large scale mining operations are not able to compete on a marginal cost basis with home smeshers. -In short, if you're spending money to mine Spacemesh you're very likely to lose money and this is by design. +In short, if you're spending money to smesh, you're very likely to lose money - and this is by design. diff --git a/docs/learn/rewards.md b/docs/learn/rewards.md index 681b292e..5d214947 100644 --- a/docs/learn/rewards.md +++ b/docs/learn/rewards.md @@ -13,7 +13,7 @@ Rewards are added to a smesher's coinbase account (the one registered in its ATX ## Punishment -Every robust system of incentives must include sanctions as well as rewards. In the case of Spacemesh and other permissionless, public blockchains, block producers (miners) must be punished for violating the rules of the protocol or failing to contribute to consensus. +Every robust system of incentives must include sanctions as well as rewards. In the case of Spacemesh and other permissionless, public blockchains, block producers (i.e., miners, or smeshers in the case of Spacemesh) must be punished for violating the rules of the protocol or failing to contribute to consensus. In Spacemesh Smeshers are _not_ punished for failing to contribute, e.g., for failing to publish proposals in their eligible slots. However, they do fail to receive rewards in this case which amounts to the same thing economically. @@ -21,4 +21,4 @@ The only sanctionable offense in Spacemesh is equivocation, otherwise known as d Note that, unlike in proof of stake networks, **there is no slashing in Spacemesh.** In other words the coins earned by a smesher will not be reduced, and all coins earned prior to the moment of malfeasance are still valid and spendable. -However, once a malfeasance proof has been generated and broadcast for that smesher, its identity is effectively burnt. The only option is to delete the PoST files and generate them again from scratch using a new identity. Therefore it's essential that miners use caution when moving identities, and they must **never run two nodes attached to the same identity at the same time.** There's more information on how to avoid this in [our Advanced Smeshing Guide](../start/smeshing/smeshing_adv/equivocation.md). +However, once a malfeasance proof has been generated and broadcast for that smesher, its identity is effectively burnt. The only option is to delete the PoST files and generate them again from scratch using a new identity. Therefore it's essential that smeshers use caution when moving identities, and they must **never run two nodes attached to the same identity at the same time.** There's more information on how to avoid this in [our Advanced Smeshing Guide](../start/smeshing/smeshing_adv/equivocation.md). diff --git a/docs/learn/smeshing.md b/docs/learn/smeshing.md index 15c04367..02eb3b84 100644 --- a/docs/learn/smeshing.md +++ b/docs/learn/smeshing.md @@ -5,4 +5,4 @@ title: What is Smeshing? In short, smeshing is mining. Similar to Bitcoin and other public blockchains, smeshing is the process of dedicating scarce resources to the Spacemesh network in exchange for eligibility to produce proposals and earn rewards. At a high level, mining in Spacemesh works like it does in other blockchains: smeshers provably spend scarce resources in order to obtain eligibilities to participate in block production at certain points in time, are rewarded with coins for following the rules of the protocol and contributing to block production, and are punished for violating these rules. -However, unlike in other blockchains, the scarce resource committed to the protocol is _spacetime_ (as opposed to hashing power in proof of work, or staked capital and time value of money in proof of stake), and multiple miners participate in the creation of each block. +However, unlike in other blockchains, the scarce resource committed to the protocol is _spacetime_ (as opposed to hashing power in proof of work, or staked capital and time value of money in proof of stake), and multiple smeshers participate in the creation of each block. diff --git a/docs/learn/spacemesh.md b/docs/learn/spacemesh.md index f33f708a..27dea348 100644 --- a/docs/learn/spacemesh.md +++ b/docs/learn/spacemesh.md @@ -11,7 +11,7 @@ Consider, for instance, Bitcoin. Industrial grade, specialized machines are a pr It can be argued that Ethereum, with its Proof of Stake consensus algorithm, is also “green” and inclusive: one only needs to stake ETH in order to participate in consensus and block production. However, a validator must first acquire ETH to stake. While ETH is a liquid asset that can be purchased easily enough, it still requires access to an exchange which usually means having a bank account, passing a KYC/AML process, etc. Strictly speaking this process is not permissionless; by contrast, mining Spacemesh coins simply requires running the mining software and is thus 100% permissionless! -Furthermore, it’s possible for any proof of stake network, including Ethereum, to be effectively and invisibly captured by a small number of colluding actors that collectively control a substantial portion of the stake. This casts a shadow of concern over the security and censorship resistance of the network. However, Spacemesh, with its Proof of Spacetime consensus algorithm, allows anyone to participate in the smeshing process simply by allocating at least 256 GiB hard drive space. Like proof of work, honest miners in Spacemesh can always permissionlessly add more weight to their votes in the consensus mechanism, effectively routing around any such attempts at capture or censorship. +Furthermore, it’s possible for any proof of stake network, including Ethereum, to be effectively and invisibly captured by a small number of colluding actors that collectively control a substantial portion of the stake. This casts a shadow of concern over the security and censorship resistance of the network. However, Spacemesh, with its Proof of Spacetime consensus algorithm, allows anyone to participate in the smeshing process simply by allocating at least 256 GiB hard drive space. Like proof of work, honest smeshers in Spacemesh can always permissionlessly add more weight to their votes in the consensus mechanism, effectively routing around any such attempts at capture or censorship. As such, the Spacemesh approach to securing the network and distributing rewards to the honest participants is not only environmentally-friendly, but also far more decentralized, and censorship resistant. With just some storage space and a stable internet connection, one can earn guaranteed rewards while also contributing to the security of the network. diff --git a/docs/start/rewards.md b/docs/start/rewards.md index 6f3ce3af..101793c4 100644 --- a/docs/start/rewards.md +++ b/docs/start/rewards.md @@ -3,21 +3,21 @@ id: rewards title: How Rewards Work --- -In Spacemesh, miners earn rewards for successfully proving eligibility and submitting valid block proposals to the network in their designated eligibility slots. Note that, at present, the only behavior that's rewarded is submission of block proposals, but in the future we intend to additionally incentivize other useful behavior such as participating in Hare consensus. +In Spacemesh, smeshers earn rewards for successfully proving eligibility and submitting valid block proposals to the network in their designated eligibility slots. Note that, at present, the only behavior that's rewarded is submission of block proposals, but in the future we intend to additionally incentivize other useful behavior such as participating in Hare consensus. As with many other blockchain networks, rewards consist of two components: block subsidy, i.e., coins newly minted by the protocol; and transaction fees. While we expect transaction fees to increase and form a larger percentage of rewards over time, at this early stage in the network lifecycle the vast majority of rewards (more than 99.99%) derive from block subsidies. As such the remainder of this analysis will ignore transaction fees for the purpose of estimating rewards. ## Estimated Rewards -Three factors are necessary to calculate a miner's estimated rewards: the miner's **weight** in a given epoch, the **total network weight** in the epoch, and the **per-layer subsidy.** +Three factors are necessary to calculate a smesher's estimated rewards: the smesher's **weight** in a given epoch, the **total network weight** in the epoch, and the **per-layer subsidy.** -As described above, a miner's weight in a given epoch (as encoded in the ATX they submitted to establish eligibility for the epoch) is simply the number of storage units proven times the number of PoET ticks. For instance, a miner with 4 SU (the minimum) and a PoET proof with 100k ticks would have a weight of 400k. +As described above, a smesher's weight in a given epoch (as encoded in the ATX they submitted to establish eligibility for the epoch) is simply the number of storage units proven times the number of PoET ticks. For instance, a smesher with 4 SU (the minimum) and a PoET proof with 100k ticks would have a weight of 400k. -The total network weight is (as the name suggests) the weight of _all_ eligible miners in the same epoch. A miner's **relative weight** is the weight of their ATX in a given epoch divided by the total network weight in that epoch. There isn't currently an easy way to retrieve total network weight but, given that at present nearly all miners are using the same PoET proof or a PoET proof with a similar number of ticks, it can be estimated by dividing the miner's total committed storage by the total network storage (as displayed on the [Network Dashboard](https://dash.spacemesh.io/)). For instance, a miner with 1TiB of storage of a network that's 18PiB has 1/18000 = 5.6e-5 of the total network space. +The total network weight is (as the name suggests) the weight of _all_ eligible smeshers in the same epoch. A smesher's **relative weight** is the weight of their ATX in a given epoch divided by the total network weight in that epoch. There isn't currently an easy way to retrieve total network weight but, given that at present nearly all smeshers are using the same PoET proof or a PoET proof with a similar number of ticks, it can be estimated by dividing the smesher's total committed storage by the total network storage (as displayed on the [Network Dashboard](https://dash.spacemesh.io/)). For instance, a smesher with 1TiB of storage of a network that's 18PiB has 1/18000 = 5.6e-5 of the total network space. The final piece of the puzzle is the per-layer reward. This decays gradually from layer to layer. The simplest way to see the current value is to check [LAYERS](https://explorer.spacemesh.io/layers) in the Explorer. As of [layer 17980](https://explorer.spacemesh.io/layers/17980), 476.614 SMH are being minted as a subsidy each layer. Multiply this by the number of layers per epoch, 4032, to get the approximate total new issuance per epoch: for epoch 4 this is roughly 4032 * 476.614 = 1,921,707 SMH. -Finally, to calculate a miner's estimated rewards for a given epoch simply multiply its relative weight by the total epoch issuance. A miner with 5.6e-5 of the total weight would be expected to earn around 5.6e-5*1921707 = 107 SMH in this epoch. +Finally, to calculate a smesher's estimated rewards for a given epoch simply multiply its relative weight by the total epoch issuance. A smesher with 5.6e-5 of the total weight would be expected to earn around 5.6e-5*1921707 = 107 SMH in this epoch. Note: It is possible to read more precise values from a node's state database (see below). This sample SQL query will give you the total weight for an epoch: @@ -26,7 +26,7 @@ SELECT SUM(effective_num_units*tick_count) FROM atxs WHERE epoch=2; 781394721 ``` -And this query will give an individual miner's relative weight: +And this query will give an individual smesher's relative weight: ```sql SELECT 1.0*atxs.effective_num_units*atxs.tick_count/total_weight.weight @@ -36,13 +36,13 @@ SELECT 1.0*atxs.effective_num_units*atxs.tick_count/total_weight.weight 0.000519591429387197 ``` -Some miners may find community-run tools like [Spacemesh Calculator](https://www.spacemeshcalculator.com/) helpful in doing this math, but we cannot vouch for their correctness. +Some smeshers may find community-run tools like [Spacemesh Calculator](https://www.spacemeshcalculator.com/) helpful in doing this math, but we cannot vouch for their correctness. ## Eligibility Slots -Every eligible miner has one or more slots per epoch where they're eligible to produce a proposal (and thus earn a reward). Every miner with at least the minimum storage (4 storage units) is guaranteed at least one slot per epoch. There are 50 slots per layer (i.e., on average 50 proposals per layer) or 201,600 slots per epoch. The slots are assigned randomly and unpredictably at the start of the epoch so that even the miner itself doesn't know its own eligibility slots before the epoch starts. You can calculate the estimated number of slots for a given miner using similar math to the above: multiply the miner's relative epoch weight by 201,600 with floor=1. +Every eligible smesher has one or more slots per epoch where they're eligible to produce a proposal (and thus earn a reward). Every smesher with at least the minimum storage (4 storage units) is guaranteed at least one slot per epoch. There are 50 slots per layer (i.e., on average 50 proposals per layer) or 201,600 slots per epoch. The slots are assigned randomly and unpredictably at the start of the epoch so that even the smesher itself doesn't know its own eligibility slots before the epoch starts. You can calculate the estimated number of slots for a given smesher using similar math to the above: multiply the smesher's relative epoch weight by 201,600 with floor=1. -There are several ways to see a miner's actual eligibility slots for a given epoch. The node prints its eligibilities in the log at the beginning of an epoch, e.g.: +There are several ways to see a smesher's actual eligibility slots for a given epoch. The node prints its eligibilities in the log at the beginning of an epoch, e.g.: ``` 2023-08-11T13:45:00.622-0400 INFO abcde.proposalBuilder proposal eligibility for an epoch {"node_id": "abcde", "module": "proposalBuilder", "epoch_id": 2, "beacon": "e3e3389e", "weight": 141435, "min activeset weight": 5000000, "total weight": 305096691, "total num slots": 93, "num layers eligible": 93, "layers to num proposals": [{"layer": 8091, "slots": 1}, {"layer": 8179, "slots": 1}, {"layer": 8212, "slots": 1}, {"layer": 8215, "slots": 1}, {"layer": 8248, "slots": 1}, {"layer": 8306, "slots": 1}, {"layer": 8382, "slots": 1}, {"layer": 8389, "slots": 1}, {"layer": 8411, "slots": 1}, {"layer": 8432, "slots": 1}, {"layer": 8454, "slots": 1}...], "name": "proposalBuilder"} @@ -80,7 +80,7 @@ In Smapp the same thing looks like this: ![image](https://github.com/spacemeshos/wiki/assets/3316532/be77ccd8-ab5f-4763-8a98-8c37f606241e) -In order to successfully earn a reward for a given eligibility slot, a miner has to be running up to date software, has to be online and fully synced, and has to successfully generate and broadcast a proposal during the slot. The actual, final reward that's earned in a given slot depends upon the behavior of other eligible miners in the same slot. If an eligible miner fails to submit a proposal, that miner's portion of the reward is distributed to the eligible miners that successfully publish proposals. +In order to successfully earn a reward for a given eligibility slot, a smesher has to be running up to date software, has to be online and fully synced, and has to successfully generate and broadcast a proposal during the slot. The actual, final reward that's earned in a given slot depends upon the behavior of other eligible smeshers in the same slot. If an eligible smesher fails to submit a proposal, that smesher's portion of the reward is distributed to the eligible smeshers that successfully publish proposals. ## Earned Rewards @@ -136,24 +136,24 @@ You may also find this community-run [SpaceMesh Lamba Chunks](http://fcmx.net/sm ## Missed Rewards -If your node is offline or not fully synced when an eligible slot arrives, it may fail to produce a proposal and thus miss a reward for the slot. If a proposal is produced or gossiped too late, or not received by enough other nodes in time, it may also not be included in the canonical block and thus the slot reward may be missed. Note that this has no bearing whatsoever upon future eligibilities, and note also that the protocol does not allow a miner to subsequently "earn back" lost rewards. In this scenario, the coins that the miner would've received will instead be allocated proportionally (i.e., by weight) to the other eligible miners that successfully produced proposals in the same slot. By far the most common cause of missed rewards is node updates. We strongly encourage you to closely track your node eligibilities and not restart or upgrade within 2-3 layers before an upcoming eligibility (so that the node has a chance to fully initialize and sync in time). +If your node is offline or not fully synced when an eligible slot arrives, it may fail to produce a proposal and thus miss a reward for the slot. If a proposal is produced or gossiped too late, or not received by enough other nodes in time, it may also not be included in the canonical block and thus the slot reward may be missed. Note that this has no bearing whatsoever upon future eligibilities, and note also that the protocol does not allow a smesher to subsequently "earn back" lost rewards. In this scenario, the coins that the smesher would've received will instead be allocated proportionally (i.e., by weight) to the other eligible smeshers that successfully produced proposals in the same slot. By far the most common cause of missed rewards is node updates. We strongly encourage you to closely track your node eligibilities and not restart or upgrade within 2-3 layers before an upcoming eligibility (so that the node has a chance to fully initialize and sync in time). -There are also rare scenarios when no proposals are produced at all for a given layer, e.g., when the [Hare](#hare) fails due to a network issue such as many miners temporarily being offline. In these scenarios, which are usually short-lived, no proposals are produced at all, a layer will have no block and no transactions, and no rewards will be issued. In this case, the coins that would've been issued as part of the layer subsidy simply fail to get minted, i.e., they will never exist, will never enter circulation, and for all intents and purposes may be considered burnt. +There are also rare scenarios when no proposals are produced at all for a given layer, e.g., when the [Hare](#hare) fails due to a network issue such as many smeshers temporarily being offline. In these scenarios, which are usually short-lived, no proposals are produced at all, a layer will have no block and no transactions, and no rewards will be issued. In this case, the coins that would've been issued as part of the layer subsidy simply fail to get minted, i.e., they will never exist, will never enter circulation, and for all intents and purposes may be considered burnt. ## Reward Lifecycle The end to end reward lifecycle works as follows: -1. Mining node performs [PoST initialization](#post-initialization-2) -1. Mining node generates its initial [proof of spacetime](#proof-generation) -1. Mining node registers with the [PoET](#poet) -1. Mining node receives proof from PoET server and uses it to generate another proof of spacetime (proving that it still has the data) -1. Mining node bundles this proof into an ATX and submits it to the network to establish eligibility in the following epoch -1. The new epoch begins. The mining node calculates its eligibilities for the new epoch (based on active set and random beacon). -1. Mining node participates in gossip normally and follows the network, remaining in sync, periodically joining a Hare committee, etc. -1. When an eligibility slot (layer) arrives, the miner generates a block proposal based on its view of the network (which valid transactions it's collected into its mempool, signs it, and broadcasts it to the rest of the network -1. A few seconds later the [Hare protocol](./../learn/hare.md) runs for the layer. A random committee of nodes is picked to come to consensus on the canonical set of valid proposals for the layer (i.e., those received on time and with valid eligibility proofs) and they're collated into a new block. Assuming the mining node's proposal is valid and it was received on time, it should be included in the new block. -1. A few minutes later the new block is confirmed by the [Tortoise](./../learn/tortoise.md) and its contents become a part of the canonical mesh. Rewards are paid to all miners that participated in the construction of the block by submitting valid, on time proposals. +1. Smeshing node performs [PoST initialization](#post-initialization-2) +1. Smeshing node generates its initial [proof of spacetime](#proof-generation) +1. Smeshing node registers with the [PoET](#poet) +1. Smeshing node receives proof from PoET server and uses it to generate another proof of spacetime (proving that it still has the data) +1. Smeshing node bundles this proof into an ATX and submits it to the network to establish eligibility in the following epoch +1. The new epoch begins. The smeshing node calculates its eligibilities for the new epoch (based on active set and random beacon). +1. Smeshing node participates in gossip normally and follows the network, remaining in sync, periodically joining a Hare committee, etc. +1. When an eligibility slot (layer) arrives, the smesher generates a block proposal based on its view of the network (which valid transactions it's collected into its mempool, signs it, and broadcasts it to the rest of the network +1. A few seconds later the [Hare protocol](./../learn/hare.md) runs for the layer. A random committee of nodes is picked to come to consensus on the canonical set of valid proposals for the layer (i.e., those received on time and with valid eligibility proofs) and they're collated into a new block. Assuming the smeshing node's proposal is valid and it was received on time, it should be included in the new block. +1. A few minutes later the new block is confirmed by the [Tortoise](./../learn/tortoise.md) and its contents become a part of the canonical mesh. Rewards are paid to all smeshers that participated in the construction of the block by submitting valid, timely proposals. Note that this describes the happy flow. Many things can happen to interfere with this process or slow it down. Proposals may not be gossiped or received on time, in which case a block still be created from the valid proposals that were received on time. If not enough nodes are online to select a Hare committee, Hare may fail, which would temporarily result in empty layers (i.e., layers without blocks), until nodes come back online and a Hare quorum can be re-established. diff --git a/docs/start/smeshing/smeshing_adv/advanced.md b/docs/start/smeshing/smeshing_adv/advanced.md index 0ae349aa..a683c5ec 100644 --- a/docs/start/smeshing/smeshing_adv/advanced.md +++ b/docs/start/smeshing/smeshing_adv/advanced.md @@ -5,7 +5,7 @@ title: Additional Advanced Topics ## Monitoring -The simplest and most straightforward way to monitor any running node, including a mining node, is using the [gRPC API](#api). You can use the `spacemesh.v1.NodeService.Status` to see the current status (number of connected peers, sync status, layer status), and you can use the `spacemesh.v1.AdminService.EventsStream` to follow events (such as proof creation and broadcast, eligibilities, etc.) (see [API](#api) for example commands). +The simplest and most straightforward way to monitor any running node, including a smeshing node, is using the [gRPC API](#api). You can use the `spacemesh.v1.NodeService.Status` to see the current status (number of connected peers, sync status, layer status), and you can use the `spacemesh.v1.AdminService.EventsStream` to follow events (such as proof creation and broadcast, eligibilities, etc.) (see [API](#api) for example commands). It's also possible to do more sophisticated monitoring using [Prometheus and Grafana](https://prometheus.io/docs/visualization/grafana/). You can configure your own Prometheus data model, or use the out of the box model that `go-spacemesh` already supports. If you run the node with the `--metrics` flag (or set this in the [config](#config)), and optionally `--metrics-port`, then Prometheus can scrape metrics from the running node. @@ -17,29 +17,29 @@ This topic is covered in the [PoST Initialization](./post_init#resizing-post) se ## Very Large Identities -In general a miner is free to initialize as much or as little storage as she likes. However, miners with especially large identities may run into problems with [PoST proof generation](#proof-generation) as this requires sequentially reading all of the PoST data and additionally doing proof of work over the data. In the worst case, if the user selects a relatively low number of nonces (see next section), the node may get unlucky and need to perform this sequential read multiple times. All of this needs to fit into the PoET [cycle gap](#timing) (12 hours for mainnet) or else the miner risks being ineligible for an entire epoch and missing all epoch rewards. +In general a smesher is free to initialize as much or as little storage as she likes. However, smeshers with especially large identities may run into problems with [PoST proof generation](#proof-generation) as this requires sequentially reading all of the PoST data and additionally doing proof of work over the data. In the worst case, if the user selects a relatively low number of nonces (see next section), the node may get unlucky and need to perform this sequential read multiple times. All of this needs to fit into the PoET [cycle gap](#timing) (12 hours for mainnet) or else the smesher risks being ineligible for an entire epoch and missing all epoch rewards. -Precisely calculating the maximum identity size that a system can support depends upon a number of variables: drive read speed, CPU power, the other applications running on the system, and the configured parameters (see next section). As a rule of thumb, we recommend that miners not use identities larger than about 4 TiB (i.e., 64 storage units). Given the average hard drive read speed, and assuming the miner is running on a reasonably powerful system, a miner with a 4 TiB identity should have ample time to read that identity twice, if necessary, and successfully generate a proof during the cycle gap in the vast majority of cases. It should also be noted that advanced miners have reported achieving significantly higher throughput speeds and, thus, being able to manage much larger identities using, e.g., large NVMe SSD drives and/or [RAID5](https://en.wikipedia.org/wiki/Standard_RAID_levels#RAID_5) configurations. +Precisely calculating the maximum identity size that a system can support depends upon a number of variables: drive read speed, CPU power, the other applications running on the system, and the configured parameters (see next section). As a rule of thumb, we recommend that smeshers not use identities larger than about 4 TiB (i.e., 64 space units). Given the average hard drive read speed, and assuming the smesher is running on a reasonably powerful system, a smesher with a 4 TiB identity should have ample time to read that identity twice, if necessary, and successfully generate a proof during the cycle gap in the vast majority of cases. It should also be noted that advanced smeshers have reported achieving significantly higher throughput speeds and, thus, being able to manage much larger identities using, e.g., large NVMe SSD drives and/or [RAID5](https://en.wikipedia.org/wiki/Standard_RAID_levels#RAID_5) configurations. -For very large identities, it probably makes sense to split the identity into multiple smaller identities (again, 4 TiB is a good starting point, although the exact amount will depend upon the system and the miner's needs). Assuming these identities are stored on physically separate disks, and assuming the miner has a system that's powerful enough to run multiple nodes (i.e., the system resources are a multiple of the [required resources](#requirements) for a single node), she should have no trouble running multiple identities on a single system. +For very large identities, it probably makes sense to split the identity into multiple smaller identities (again, 4 TiB is a good starting point, although the exact amount will depend upon the system and the smesher's needs). Assuming these identities are stored on physically separate disks, and assuming the smesher has a system that's powerful enough to run multiple nodes (i.e., the system resources are a multiple of the [required resources](#requirements) for a single node), she should have no trouble running multiple identities on a single system. You may find math such as the following helpful: assuming you know the throughput (based on drive read speed and CPU hash throughput), it should take [a little over eight hours](https://www.wolframalpha.com/input?i=4TiB%2F%5B150MB%2Fsec%5D) to create a proof serially for a single 4TiB identity assuming a throughput of 150MB/s (normal for a modern HDD). Note that in this case, if the number of nonces isn't high enough (see next section) and the proof generation fails in the first pass, there won't be enough time to perform a second pass during the 12 hour cycle gap! -Such a miner should pay close attention to the contents of the [Fine-tuning Proving](#fine-tuning-proving) and [Identity Management](#identity-management) sections, as she'll need to generate and manage multiple identities, being sure to keep them separate and distinct and to [avoid equivocation](#avoiding-equivocation), and also to pick the appropriate proving parameters for her setup. +Such a smesher should pay close attention to the contents of the [Fine-tuning Proving](#fine-tuning-proving) and [Identity Management](#identity-management) sections, as she'll need to generate and manage multiple identities, being sure to keep them separate and distinct and to [avoid equivocation](#avoiding-equivocation), and also to pick the appropriate proving parameters for her setup. ## Fine-tuning Proving -As a refresher, there are two stages to the process of proving storage so that a miner will be eligible for rewards on an ongoing basis: the [PoST initialization](#post-initialization-2), which only needs to be performed once, and the ongoing, regular [proofs of spacetime](#proofs-of-spacetime) that miners need to generate and broadcast each epoch. Generating a proof of spacetime requires that the miner perform a sequential read of all of their PoST data. Since it would be infeasible to transmit _all_ of the PoST data as a proof, in order to make the proofs succinct, Spacemesh instead requires miners to do a small proof of work each epoch by hashing their PoST data and looking for elements (known as **labels**) that pass a certain proof of work threshold. The proof itself consists of just the indices of the labels that pass the threshold. +As a refresher, there are two stages to the process of proving storage so that a smesher will be eligible for rewards on an ongoing basis: the [PoST initialization](#post-initialization-2), which only needs to be performed once, and the ongoing, regular [proofs of spacetime](#proofs-of-spacetime) that smeshers need to generate and broadcast each epoch. Generating a proof of spacetime requires that the smesher perform a sequential read of all of their PoST data. Since it would be infeasible to transmit _all_ of the PoST data as a proof, in order to make the proofs succinct, Spacemesh instead requires smeshers to do a small proof of work each epoch by hashing their PoST data and looking for elements (known as **labels**) that pass a certain proof of work threshold. The proof itself consists of just the indices of the labels that pass the threshold. The user may specify the number of CPU threads and nonces that are used in the proving process. The process itself is probabilistic: with 64 nonces the probability of creating a successful proof in a single pass is 79.39%; with 128 nonces it's 95.75%; and with 288 nonces it's 99.9%. Moreover the number of CPU threads must be set to balance disk read speed. For more information on this process, see [Proof of work and PoST proof generation](https://community.spacemesh.io/t/proof-of-work-and-post-proof-generation/361) in the Spacemesh research forum. -As described in the [Config](#config) section above, these parameters can be passed to `postcli` (as command-line arguments) and `go-spacemesh` (command-line arguments or via the config file). Advanced miners will need to run some benchmarks to determine the best values for their particular system. See the documentation for [the profiler tool](https://github.com/spacemeshos/post-rs/blob/main/docs/profiler.md) for more information. +As described in the [Config](#config) section above, these parameters can be passed to `postcli` (as command-line arguments) and `go-spacemesh` (command-line arguments or via the config file). Advanced smeshers will need to run some benchmarks to determine the best values for their particular system. See the documentation for [the profiler tool](https://github.com/spacemeshos/post-rs/blob/main/docs/profiler.md) for more information. ## Identity Management -Each miner in Spacemesh has an identity, known as a miner ID or smesher ID. The ID is simply a 32-byte Ed25519 public key, which is commonly displayed in hexidecimal or base64 format. It should look something like `0x91b8db4fecd9cd5db953275fdefb0b8cdfb08954e9186d9dc6f86b2a81980d40` (hex) or `kbjbT+zZzV25Uydf3vsLjN+wiVTpGG2dxvhrKoGYDUA=` (base64). +Each smesher in Spacemesh has an identity, known as a smesher ID or smesher ID. The ID is simply a 32-byte Ed25519 public key, which is commonly displayed in hexidecimal or base64 format. It should look something like `0x91b8db4fecd9cd5db953275fdefb0b8cdfb08954e9186d9dc6f86b2a81980d40` (hex) or `kbjbT+zZzV25Uydf3vsLjN+wiVTpGG2dxvhrKoGYDUA=` (base64). -Note: Miner identities have absolutely nothing to do with accounts or wallet addresses. Both are based on Ed25519 keypairs, but that's all they have in common. A miner also needs to specify a coinbase account to receive its rewards, but that coinbase account is not derived from the miner identity nor connected to it in any way. It can also be changed at any time. The miner identity **is connected** to its PoST data, however. PoST data generated for a given miner ID can never be used by another miner. Moreover, if a miner identity is lost or invalidated for equivocation, the associated PoST data becomes useless. +Note: smesher identities have absolutely nothing to do with accounts or wallet addresses. Both are based on Ed25519 keypairs, but that's all they have in common. A smesher also needs to specify a coinbase account to receive its rewards, but that coinbase account is not derived from the smesher identity nor connected to it in any way. It can also be changed at any time. The smesher identity **is connected** to its PoST data, however. PoST data generated for a given smesher ID can never be used by another smesher. Moreover, if a smesher identity is lost or invalidated for equivocation, the associated PoST data becomes useless. Tip: You can convert between these two formats using two simple command-line tools: @@ -50,9 +50,9 @@ kbjbT+zZzV25Uydf3vsLjN+wiVTpGG2dxvhrKoGYDUA= 91b8db4fecd9cd5db953275fdefb0b8cdfb08954e9186d9dc6f86b2a81980d40 ``` -The first time the node runs it will create a new miner identity (if it doesn't see an existing one), which it stores in a file `/identities/local.key`, by default `~/spacemesh/identities/local.key`. This file contains both the miner public and private keys. The private key is used to sign messages on behalf of the miner. It's critical both that this file be kept private (its contents should never be revealed or sent to anyone) and that it not be lost. If it's lost, just like a lost wallet there's absolutely no way to restore it, and the associated PoST data would become useless. +The first time the node runs it will create a new smesher identity (if it doesn't see an existing one), which it stores in a file `/identities/local.key`, by default `~/spacemesh/identities/local.key`. This file contains both the smesher public and private keys. The private key is used to sign messages on behalf of the smesher. It's critical both that this file be kept private (its contents should never be revealed or sent to anyone) and that it not be lost. If it's lost, just like a lost wallet there's absolutely no way to restore it, and the associated PoST data would become useless. -You can read the public key portion of the key file, i.e., the hexidecimal miner identity, as follows: +You can read the public key portion of the key file, i.e., the hexidecimal smesher identity, as follows: ```bash > cut -c 65-128 local.key @@ -68,13 +68,13 @@ You can also read the identity from a running node via the API: } ``` -A miner identity can be transferred from one system to another simply by moving the `local.key` file. However, it's essential that the same identity never be attached to two running miners at the same time in order to avoid equivocation (see next section). +A smesher identity can be transferred from one system to another simply by moving the `local.key` file. However, it's essential that the same identity never be attached to two running smeshers at the same time in order to avoid equivocation (see the next section). A new identity can be generated by deleting or moving the `local.key` file and starting the node again, at which point a new identity will be created. `postcli` can be used to do the same thing. ## Moving PoST files -You can safely move PoST data from one directory to another, or from one system to another, as long as the data remain intact and you're careful to avoid equivocation (see next point). The miner identity used to create the PoST data is bound with the data and, thus, you must move the `local.key` file along with the rest of the data; the data is useless without the `local.key` identity file, and any attempt to use the same PoST data with a different miner identity will fail. There's nothing about the data that ties it to a particular system, architecture, or operating system; thus, it's also safe to move the data across systems. +You can safely move PoST data from one directory to another, or from one system to another, as long as the data remain intact and you're careful to avoid equivocation (see next point). The smesher identity used to create the PoST data is bound with the data and, thus, you must move the `local.key` file along with the rest of the data; the data is useless without the `local.key` identity file, and any attempt to use the same PoST data with a different smesher identity will fail. There's nothing about the data that ties it to a particular system, architecture, or operating system; thus, it's also safe to move the data across systems. We strongly recommend using a tool like [rsync](https://www.digitalocean.com/community/tutorials/how-to-use-rsync-to-sync-local-and-remote-directories), which has built-in error checking and can resume a partial transfer, to move data both locally and remotely. You can use a command like the following to move data locally: @@ -92,7 +92,7 @@ You can use a command like the following to copy data from a remote host: ## Multiple Drives -At present it's not possible to naively split a single identity across multiple drives or filesystems. We hope to add this feature soon. In the meantime you have two possibilities: run multiple identities, or join multiple filesystems into a single logical filesystem at the hardware or OS level. +At present it's not possible to naively split a single identity across multiple drives or filesystems. We hope to add this feature soon. In the meantime you have two possibilities: run multiple identities, or join multiple file systems into a single logical filesystem at the hardware or OS level. ### Multiple Identities @@ -100,9 +100,9 @@ Running multiple identities is explained in [Identity Management](#identity-mana ### Joining Filesystems -There are many ways to combine multiple, physical filesystems into a single "logical" filesystem and the best way to do this will depend on your hardware, your operating systems, you degree of technical expertise, and your needs. Some miners have had success with [RAID5](https://en.wikipedia.org/wiki/Standard_RAID_levels#RAID_5); bear in mind that it's possible to run RAID in either [hardware or software](https://www.techtarget.com/searchstorage/tip/Key-differences-in-software-RAID-vs-hardware-RAID), with various tradeoffs. Linux users can rely on [LVM](https://en.wikipedia.org/wiki/Logical_Volume_Manager_(Linux)), which has wide support in modern distributions. +There are many ways to combine multiple, physical filesystems into a single "logical" filesystem and the best way to do this will depend on your hardware, your operating systems, you degree of technical expertise, and your needs. Some smeshers have had success with [RAID5](https://en.wikipedia.org/wiki/Standard_RAID_levels#RAID_5); bear in mind that it's possible to run RAID in either [hardware or software](https://www.techtarget.com/searchstorage/tip/Key-differences-in-software-RAID-vs-hardware-RAID), with various tradeoffs. Linux users can rely on [LVM](https://en.wikipedia.org/wiki/Logical_Volume_Manager_(Linux)), which has wide support in modern distributions. -This has the advantage that you can run a single node, rather than many, and that, if configured correctly, you may achieve much faster read speed (see [Very Large Identities](#very-large-identities)) than you can with a single drive. It has the disadvantage of requiring more configuring at the operating system and filesystem level; miners who aren't comfortable doing so may prefer to instead run multiple identities. +This has the advantage that you can run a single node, rather than many, and that, if configured correctly, you may achieve much faster read speed (see [Very Large Identities](#very-large-identities)) than you can with a single drive. It has the disadvantage of requiring more configuring at the operating system and filesystem level; smeshers who aren't comfortable doing so may prefer to instead run multiple identities. ## State Managament @@ -119,7 +119,7 @@ It's possible to explore the contents of this database to understand a node's vi **Note 1: Unlike the API, we make no guarantees that the state database schema will remain the same.** It will likely evolve over time. Thus, while it's perfectly okay to explore the state database for troubleshooting, we strongly recommend against building or deploying any production applications that rely on it. -**Note 2: Never, under any circumstances, modify the state of a running node.** Making even a small change runs the risk of totally corrupting the state database, which in the worst case would require that a node be resynced from scratch, a process that can take a long time (and during which time a miner node isn't eligible for rewards). As such, before even opening the state database, **make a copy of the file** and work with the copy only to make sure you don't accidentally modify the live database. +**Note 2: Never, under any circumstances, modify the state of a running node.** Making even a small change runs the risk of totally corrupting the state database, which in the worst case would require that a node be resynced from scratch, a process that can take a long time (and during which time a smeshing node isn't eligible for rewards). As such, before even opening the state database, **make a copy of the file** and work with the copy only to make sure you don't accidentally modify the live database. ### Reading the State Database @@ -154,7 +154,7 @@ From time to time, such as if the state database becomes corrupt or if you simpl ### Copying State -There's no "private" data, i.e., data that's specific to one miner or one node, in the state database. This means that you can copy one trusted node's database to another node as a quick-and-dirty "quick sync" option, rather than letting the nodes sync the old fashioned way. To do this: +There's no "private" data, i.e., data that's specific to one smesher or one node, in the state database. This means that you can copy one trusted node's database to another node as a quick-and-dirty "quick sync" option, rather than letting the nodes sync the old fashioned way. To do this: 1. Make sure both nodes are running the same version of go-spacemesh. 1. Stop **both nodes.** Ensure that they've exited cleanly and completely. @@ -217,7 +217,7 @@ The PoST data directory contains a file called postdata_metadata.json that conta In general you should never touch this file or change any of these values, other than when combining data from a [parallel initialization](#parallel-initialization), which requires manually finding the lowest nonce. -It's _never safe_ to change the `NodeId`, `CommitmentAtxId`, `LabelsPerUnit`, or `MaxFileSize` values. If you increase `MaxUnits` and run `postcli` or `go-spacemesh`, it'll continue PoST initialization and generate more files; this is safe to do unless/until your miner has already generated and broadcast an ATX, after which it cannot be changed. If you decrease `MaxUnits` and run `postcli` or `go-spacemesh`, they will delete existing files to match the config value. +It's _never safe_ to change the `NodeId`, `CommitmentAtxId`, `LabelsPerUnit`, or `MaxFileSize` values. If you increase `MaxUnits` and run `postcli` or `go-spacemesh`, it'll continue PoST initialization and generate more files. This is safe to do unless/until your smeshing node has already generated and broadcast an ATX, after which it cannot be changed. If you decrease `MaxUnits` and run `postcli` or `go-spacemesh`, they will delete existing files to match the config value. It's always safe to change the `Nonce` and `NonceValue` to any valid values, even after generating and broadcasting an ATX. If, for instance, you discover that you hadn't configured the lowest nonce, you can add it later. Note that this will have no impact upon rewards; it's just future-proofing in case you change the PoST size in future (once this is allowed). See [Searching for a lost VRF nonce](https://github.com/spacemeshos/post/tree/develop/cmd/postcli#searching-for-a-lost-vrf-nonce). @@ -225,7 +225,7 @@ Note that this nonce value, known as a VRF Nonce, has nothing to do with the non ## Cloud GPU -Miners without local access to a GPU may choose to instead perform GPU initialization remotely using one or multiple (see next section) GPUs. This can be done using the infrastructure of any cloud compute provider that offers a modern GPU platform. Note that cloud providers that specialize in GPUs and other types of high-performance computing will often offer better prices and tooling than general-purpose cloud compute platforms like Azure, AWS, or GCP. While we cannot vouch for any particular provider and have no affiliation with any such provider, in our testing we've had particular luck with [Runpod](https://www.runpod.io/) and have also heard good things about [Coreweave](https://www.coreweave.com/) and [Vast](https://vast.ai/). +Smeshers without local access to a GPU may choose to instead perform GPU initialization remotely using one or multiple (see next section) GPUs. This can be done using the infrastructure of any cloud compute provider that offers a modern GPU platform. Note that cloud providers that specialize in GPUs and other types of high-performance computing will often offer better prices and tooling than general-purpose cloud compute platforms like Azure, AWS, or GCP. While we cannot vouch for any particular provider and have no affiliation with any such provider, in our testing we've had particular luck with [Runpod](https://www.runpod.io/) and have also heard good things about [Coreweave](https://www.coreweave.com/) and [Vast](https://vast.ai/). As a rule of thumb, you'll want access to an instance that: diff --git a/docs/start/smeshing/smeshing_adv/api.md b/docs/start/smeshing/smeshing_adv/api.md index fb31fcca..8fb6a452 100644 --- a/docs/start/smeshing/smeshing_adv/api.md +++ b/docs/start/smeshing/smeshing_adv/api.md @@ -204,7 +204,7 @@ The Spacemesh node gRPC API lives in the [api repository](https://github.com/spa The Spacemesh team regularly releases updates to GUI and CLI node software. Smapp has a feature that monitors new releases and notifies the user when a new release is available, with a one-click update mechanism (Linux users who installed Smapp using the .deb file will need to manually check for and install updates due to [this issue](https://github.com/spacemeshos/smapp/issues/1299)). Note that, at present, go-spacemesh updates are bundled into Smapp updates, though this may change in the future; and go-spacemesh and Smapp use independent version numbering (e.g., Smapp [v1.0.18](https://github.com/spacemeshos/smapp/releases/tag/v1.0.18) bundles go-spacemesh v1.0.19). -No such notify or update mechanism is built into `go-spacemesh`, so CLI node operators will need to manually keep their software up to date. Node updates vary in severity and, while it's generally safe to be one or two patch releases behind, this isn't always the case and some bigger updates may need to be installed right away in order to keep one's node online and mining, and in order not to receive rewards. Releases are announced on several channels including: +No such notify or update mechanism is built into `go-spacemesh`, so CLI node operators will need to manually keep their software up to date. Node updates vary in severity and, while it's generally safe to be one or two patch releases behind, this isn't always the case and some bigger updates may need to be installed right away in order to keep one's node online and smeshing, and in order not to receive rewards. Releases are announced on several channels including: - [go-spacemesh releases](https://github.com/spacemeshos/go-spacemesh/releases) on GitHub - the [#announcements channel](https://discord.com/channels/623195163510046732/691258865861394432) on the Spacemesh Discord diff --git a/docs/start/smeshing/smeshing_adv/equivocation.md b/docs/start/smeshing/smeshing_adv/equivocation.md index 6d686d0a..ddb4ec63 100644 --- a/docs/start/smeshing/smeshing_adv/equivocation.md +++ b/docs/start/smeshing/smeshing_adv/equivocation.md @@ -3,40 +3,21 @@ id: equivocation title: Avoiding Equivocation --- -There's a very small set of behaviors that a miner in Spacemesh is punished for. If a miner simply goes offline or fails -to publish a proposal when they're eligible to do so they'll miss some rewards but they're not punished per se. However, -if a miner double votes, otherwise known as equivocation, their miner identity is permanently disqualified from -participation in consensus and from earning rewards in the future. In a permissionless blockchain like Spacemesh, -equivocation is a serious offense that can have severe negative ramifications for the entire network, so this behavior -cannot go unsanctioned. Once a miner's identity has been cancelled their PoST data is effectively useless. They must -generate a new identity and reinitialize their PoST data. For more information, see -[Community Clarification: Equivocation](https://spacemesh.io/blog/community-clarification-equivocation/). +There's a very small set of behaviors that a smesher in Spacemesh is punished for. If a smesher simply goes offline or fails to publish a proposal when they're eligible to do so they'll miss some rewards but they're not punished per se. However, if a smesher double votes, otherwise known as equivocation, their smesher identity is permanently disqualified from participation in consensus and from earning rewards in the future. In a permissionless blockchain like Spacemesh, equivocation is a serious offense that can have severe negative ramifications for the entire network, so this behavior +cannot go unsanctioned. Once a smesher's identity has been cancelled their PoST data is effectively useless. They must generate a new identity and reinitialize their PoST data. For more information, see [Community Clarification: Equivocation](https://spacemesh.io/blog/community-clarification-equivocation/). -It's not difficult to avoid equivocation: simply make sure that the same identity is never attached to two running nodes -at the same time. Extra care must be taken any time a miner identity or its PoST data are copied or moved -(since the miner identity lives in the PoST data directory). +It's not difficult to avoid equivocation: simply make sure that the same identity is never attached to two running nodes at the same time. Extra care must be taken any time a smesher identity or its PoST data are copied or moved (since the smesher identity lives in the PoST data directory). ### Moving an Identity -When moving a miner identity from one place to another, **perform the following steps in the following order:** +When moving a smesher identity from one place to another, **perform the following steps in the following order:** -1. **Shut down the miner** in the source location +1. **Shut down the smeshing node** in the source location 1. Copy the files to the new location (see previous section) -1. **Double-check that the old miner was shut down.** Check again one more time to make sure. If you get this part - wrong, you risk permanently disqualifying the miner identity for equivalence and invalidation of the PoST data. -1. Make sure the `local.key` file is intact in the new location. Compare it to the `local.key` file in the old - location and make sure the contents are the same. Delete the old `local.key` file, or at the very least, rename it - or move it to ensure that you don't accidentally run the same identity again on the old system. -1. Start the miner in the new location. Make sure that you specify the correct `smeshing-opts-datadir` in the config, - and make sure that the other `smeshing-opts` are the same as they were in the old system, and that they match the - contents of the `postdata_metadata.json` file in the PoST datadir. Make sure that the miner found the data and was - able to read it. (You should see the messages `post setup completed`, `loaded the initial post from disk`, and - `verifying the initial post` in the log.) +1. **Double-check that the old smeshing node was shut down.** Check again one more time to make sure. If you get this part wrong, you risk permanently disqualifying the smesher identity for equivalence and invalidation of the PoST data. +1. Make sure the `local.key` file is intact in the new location. Compare it to the `local.key` file in the old location and make sure the contents are the same. Delete the old `local.key` file, or at the very least, rename it or move it to ensure that you don't accidentally run the same identity again on the old system. +1. Start the smesher in the new location. Make sure that you specify the correct `smeshing-opts-datadir` in the config, and make sure that the other `smeshing-opts` are the same as they were in the old system, and that they match the contents of the `postdata_metadata.json` file in the PoST datadir. Make sure that the smesher found the data and was able to read it. (You should see the messages `post setup completed`, `loaded the initial post from disk`, and `verifying the initial post` in the log.) ### Generating Multiple Identities -You can use one system to generate multiple PoST identities - this is a common usage pattern for a user who wants to, -e.g., generate multiple identities on a system with a GPU, then transfer them to other systems. However, once you've -moved the PoST data files (`postdata_*.bin`) to their new location, and copied the associated `local.key` as well, -**make absolutely certain that `local.key` has been removed** in the source location. If the file still exists, the -next PoST identity you generate will be identical to the prior one and equivocation may occur as a result. +You can use one system to generate multiple PoST identities - this is a common usage pattern for a user who wants to, e.g., generate multiple identities on a system with a GPU, then transfer them to other systems. However, once you've moved the PoST data files (`postdata_*.bin`) to their new location, and copied the associated `local.key` as well, **make absolutely certain that `local.key` has been removed** in the source location. If the file still exists, the next PoST identity you generate will be identical to the prior one and equivocation may occur as a result. diff --git a/docs/start/smeshing/smeshing_adv/multipleGPUinit.md b/docs/start/smeshing/smeshing_adv/multipleGPUinit.md index bd3d8c27..119f398f 100644 --- a/docs/start/smeshing/smeshing_adv/multipleGPUinit.md +++ b/docs/start/smeshing/smeshing_adv/multipleGPUinit.md @@ -15,7 +15,7 @@ title: Initializing a Subset of PoST Data With postcli 3.**Network Bandwidth Constraints** : In environments where network bandwidth is limited or costly, transferring large volumes of data between machines or data centers can be impractical. Initializing data in subsets locally on machines where it will be used can mitigate this issue. -4.**Parallel Processing** : When you have access to multiple machines or compute nodes, you can leverage parallel processing to expedite the initialization process. This is particularly beneficial for a still young network, where speed is of the essence, as the amount of rewards to distribute is lower wich each epoch and the number of miners constantly grows. +4.**Parallel Processing** : When you have access to multiple machines or compute nodes, you can leverage parallel processing to expedite the initialization process. This is particularly beneficial for a still young network, where speed is of the essence, as the amount of rewards to distribute is lower wich each epoch and the number of smeshers constantly grows. ### When Not to Use It diff --git a/docs/start/smeshing/smeshing_adv/networking.md b/docs/start/smeshing/smeshing_adv/networking.md index 6b138216..c49cf905 100644 --- a/docs/start/smeshing/smeshing_adv/networking.md +++ b/docs/start/smeshing/smeshing_adv/networking.md @@ -3,7 +3,7 @@ id: networking title: Networking --- -Most miners should never need to think much about their network settings. The Spacemesh node software ships with a reasonable default set of parameters that should work well for most node operators and most miners, and the software is built on top of the popular [libp2p network stack](https://libp2p.io/) which includes many useful features and support for things like peer discovery and NAT traversal. +Most smeshers should never need to think much about their network settings. The Spacemesh node software ships with a reasonable default set of parameters that should work well for most node operators and most smeshers, and the software is built on top of the popular [libp2p network stack](https://libp2p.io/) which includes many useful features and support for things like peer discovery and NAT traversal. ### NAT Traversal @@ -20,7 +20,7 @@ You can disable NAT traversal with the `--disable-natport` commandline flag or c ### Number of Connections -By default the node attempts to maintain 20-100 peer connections, including both inbound and outbound. The number of inbound and outbound connections is governed by the [p2p config](https://github.com/spacemeshos/go-spacemesh/blob/475b05b6a8900424bedf5b9086881920ed035b8b/p2p/host.go#L75-L106). Miners wishing to manage the details of their node's participation in the p2p network may wish to tweak the following settings: +By default the node attempts to maintain 20-100 peer connections, including both inbound and outbound. The number of inbound and outbound connections is governed by the [p2p config](https://github.com/spacemeshos/go-spacemesh/blob/475b05b6a8900424bedf5b9086881920ed035b8b/p2p/host.go#L75-L106). Smeshers wishing to manage the details of their node's participation in the p2p network may wish to tweak the following settings: - `listen`: as mentioned above, this is the inbound connection port - `disable-natport` and `p2p-holepunching`: as mentioned above, these features can be used for NAT traversal. See [What are NATs](https://docs.libp2p.io/concepts/nat/overview/) for more information. @@ -36,6 +36,6 @@ Even more settings are available. See the [p2p config](https://github.com/spacem ### Private Nodes -A miner running [multiple nodes](./setup.md#multiple-nodes) or [multiple identities](./advanced.md#identity-management) may wish to manually configure how the nodes peer with and communicate with one another. In other words, miners can configure a custom network topology among their own nodes. One very common configuration is to have one or more public "gateway" nodes that are publicly accessible and responsible for communicating with the outside world that relay information from the public p2p network to many private nodes. Such a configuration can save an enormous amount of bandwidth compared to each of several nodes joining the public p2p network directly. +A smesher running [multiple nodes](./setup.md#multiple-nodes) or [multiple identities](./advanced.md#identity-management) may wish to manually configure how the nodes peer with and communicate with one another. In other words, smeshers can configure a custom network topology among their own nodes. One very common configuration is to have one or more public "gateway" nodes that are publicly accessible and responsible for communicating with the outside world that relay information from the public p2p network to many private nodes. Such a configuration can save an enormous amount of bandwidth compared to each of several nodes joining the public p2p network directly. Such a configuration is achieved through the use of the `bootnodes` and `direct` parameters in the `p2p` config. The process is fully documented in the [go-spacemesh p2p README](https://github.com/spacemeshos/go-spacemesh/blob/develop/p2p/README.md). diff --git a/docs/start/smeshing/smeshing_adv/post_init.md b/docs/start/smeshing/smeshing_adv/post_init.md index 29943184..a28d8234 100644 --- a/docs/start/smeshing/smeshing_adv/post_init.md +++ b/docs/start/smeshing/smeshing_adv/post_init.md @@ -7,7 +7,7 @@ title: PoST Initialization Once an epoch, after the node has received a PoET proof and during the PoET cycle gap, the node will generate a [proof of spacetime](#proof-generation), which requires that it sequentially read all of the PoST data. The details -aren't something most miners need to worry about as the node will handle the process for you; see +aren't something most smeshers need to worry about as the node will handle the process for you. See [Fine-tuning Node Performance](./performance.md) for information on benchmarks and parameters that can be tweaked. The first part of the proving process is an initial proof of work phase called **k2pow** that uses a proof of work @@ -33,7 +33,7 @@ invalidation of a smesher ID, which invalidates all of the PoST data associated to be costly, performing PoST initialization and generating PoST data must also be costly. Note that initialization can theoretically be performed using a CPU (as opposed to a GPU), but it will take so long that -this option isn't viable for the vast majority of miners. +this option isn't viable for the vast majority of smeshers. ### OpenCL @@ -117,10 +117,7 @@ things in mind when choosing a filesystem. the disk. In our personal experience, we've found that exFAT is more efficient than EXT4, and may allow one extra storage unit to be placed on the same physical disk. -We also recommend that you _not encrypt_ the drive or partition used to store the PoST data. You should of course -protect the `local.key` file (which contains a miner's private key and is located in the `node_data/identities` -folder) and not allow it to fall into anyone else's hands, but full drive encryption feels like overkill and could slow -down [proof generation](#proof-generation). +We also recommend that you _not encrypt_ the drive or partition used to store the PoST data. You should of course protect the `local.key` file (which contains a smesher's private key and is located in the `node_data/identities` folder) and not allow it to fall into anyone else's hands, but full drive encryption feels like overkill and could slow down [proof generation](#proof-generation). ## Number of Units diff --git a/docs/start/smeshing/smeshing_adv/setup.md b/docs/start/smeshing/smeshing_adv/setup.md index a716c929..fa748665 100644 --- a/docs/start/smeshing/smeshing_adv/setup.md +++ b/docs/start/smeshing/smeshing_adv/setup.md @@ -4,7 +4,7 @@ title: Advanced Setup --- Now that you have the necessary resources ready, it is time to start smeshing! This section will walk you through how to do that. First, a couple of quick notes: -- This guide is intended as an advanced smeshing guide, covering cases such as parallel init, cloud GPUs, and transferring and managing multiple identities. In particular it does not cover the baseline case of using Smapp to initialize a single smesher. That process is straightforward and mostly automated in Smapp, and the steps are outlined in this explainer video. The guide does explain the differences between mining using Smapp or the CLI where appropriate. +- This guide is intended as an advanced smeshing guide, covering cases such as parallel init, cloud GPUs, and transferring and managing multiple identities. In particular it does not cover the baseline case of using Smapp to initialize a single smesher. That process is straightforward and mostly automated in Smapp, and the steps are outlined in this explainer video. The guide does explain the differences between smeshing using Smapp or the CLI where appropriate. - This guide uses Linux. So, all the commands are for a Linux terminal, and should be the same for most UNIX-based systems. In most cases, the same commands should work verbatim on other platforms including Windows and macOS with appropriate tweaks (e.g., using the correct platform-specific paths). Contributions containing correct instructions for different platforms are welcome. Feel free to open an issue with a contribution. diff --git a/docs/start/smeshing/smeshing_adv/troubleshooting.md b/docs/start/smeshing/smeshing_adv/troubleshooting.md index 4774eba1..b6f70a42 100644 --- a/docs/start/smeshing/smeshing_adv/troubleshooting.md +++ b/docs/start/smeshing/smeshing_adv/troubleshooting.md @@ -5,10 +5,8 @@ title: Troubleshooting ## Corrupt PoST Data -One of the realities of hard drives is that, once in a while, they fail, resulting in corrupt data. Data corruption can -also occur while [copying or moving](./advanced.md#moving-post-files) data across systems. Hopefully you'll never have -to deal with this situation, but if it does happen, you'll most likely find out when a message like the following -appears in your log: +One of the realities of hard drives is that, once in a while, they fail, resulting in corrupt data. Data corruption can also occur while [copying or moving](./advanced.md#moving-post-files) data across systems. Hopefully you'll never have +to deal with this situation, but if it does happen, you'll most likely find out when a message like the following appears in your log: ```console @@ -19,9 +17,7 @@ appears in your log: ``` -This message indicates that, despite the presence of a complete identity, the miner was unable to generate a PoST proof -for a particular epoch due to corruption in the PoST data. The best way to verify this is to run -[`postcli`](https://github.com/spacemeshos/post/tree/develop/cmd/postcli) in verify mode: +This message indicates that, despite the presence of a complete identity, the smesher was unable to generate a PoST proof for a particular epoch due to corruption in the PoST data. The best way to verify this is to run [`postcli`](https://github.com spacemeshos/post/tree/develop/cmd/postcli) in verify mode: ```console @@ -38,25 +34,14 @@ for a particular epoch due to corruption in the PoST data. The best way to verif ``` -You can do this for an entire identity, or only for a subset of files (using `-fromFile` and `-toFile`; see the -[README](https://github.com/spacemeshos/post/tree/develop/cmd/postcli) for more information). If nothing else is -touching the drive (e.g., if the node is shut down and the drive isn't being used for any other purpose), then running -`postcli verify` with `-fraction 0.01` should be quite quick; you can run with a larger fraction for a more thorough -check. Note also that multiple files may be corrupt; `postcli verify` will quit after detecting a single corrupt file, -and you can restart it with a higher `-fromFile` to continue the process. Serious miners may wish to run such a -verification process periodically to detect corruption issues before they lead to failures in proof generation and lost -rewards. - -Once corrupt data is detected, the only option is to delete and regenerate the affected files. If the files are deleted -and the node is restarted, it'll automatically restart the PoST initialization process to fill in the missing data, or -this can be done manually using `postcli`. +You can do this for an entire identity, or only for a subset of files (using `-fromFile` and `-toFile`. See the [README](https://github.com/spacemeshos/post/tree/develop/cmd/postcli) for more information). If nothing else is touching the drive (e.g., if the node is shut down and the drive isn't being used for any other purpose), then running `postcli verify` with `-fraction 0.01` should be quite quick; you can run with a larger fraction for a more thorough check. Note also that multiple files may be corrupt. `postcli verify` will quit after detecting a single corrupt file, and you can restart it with a higher `-fromFile` to continue the process. Serious smeshers may wish to run such a verification process periodically to detect corruption issues before they lead to failures in proof generation and lost rewards. Once corrupt data is detected, the only option is to delete and regenerate the affected files. If the files are deleted +and the node is restarted, it'll automatically restart the PoST initialization process to fill in the missing data, or this can be done manually using `postcli`. ## Additional troubleshooting ### `timesync: peers are not time synced` -Please make sure that your system clock is synced with the internet. Please refer to time synchronization instructions -for your operating system. +Please make sure that your system clock is synced with the internet. Please refer to time synchronization instructions for your operating system. If you're 100% certain that your time is correct you can disable the time sync check by setting the following config: @@ -72,9 +57,4 @@ If you're 100% certain that your time is correct you can disable the time sync c ### My node uses too much memory and I don't know why -Please add a `"pprof-server": true`, to the config at the main level or add `--pprof-server` to the command line. -Restart the node and then visit and - in your default browser and download the files. Please share then these files -on discord or github issue. - -Advanced users can use `go tool pprof http://localhost:6060/debug/pprof/heap` to see what is using the memory. +Please add a `"pprof-server": true`, to the config at the main level or add `--pprof-server` to the command line. Restart the node and then visit and in your default browser and download the files. Please share then these files on discord or github issue. Advanced users can use `go tool pprof http://localhost:6060/debug/pprof/heap` to see what is using the memory. diff --git a/docs/start/smeshing/start.md b/docs/start/smeshing/start.md index 6d9b4437..a3a517b1 100644 --- a/docs/start/smeshing/start.md +++ b/docs/start/smeshing/start.md @@ -25,7 +25,7 @@ Smeshing is a three-step process: 2. When you increase or decrease the allocated disk space after having already started smeshing. The output of this process is the PoS data stored on disk and an _"initial" PoS value_. -2. **[Proof of Elapsed Time (PoET)](../../learn/post.md#proof-of-elapsed-time)**: In this step, your node automatically submits a special value to a specialized [PoET server](./smeshing_adv/poet.md). This value includes the initial PoS (if you are mining for the first time), or a reference to the previous Activation Transaction (ATX) containing the last submitted PoST (see steps 3 and 4). The PoET server then uses this special value to generate the PoET over a period of time called a "PoET round", after which the PoET can be retrieved by your node. +2. **[Proof of Elapsed Time (PoET)](../../learn/post.md#proof-of-elapsed-time)**: In this step, your node automatically submits a special value to a specialized [PoET server](./smeshing_adv/poet.md). This value includes the initial PoS (if you are smeshing for the first time), or a reference to the previous Activation Transaction (ATX) containing the last submitted PoST (see steps 3 and 4). The PoET server then uses this special value to generate the PoET over a period of time called a "PoET round", after which the PoET can be retrieved by your node. 3. **[Proof of Space-Time (PoST)](../../learn/post.md#proof-of-space-time)**: Once the PoET round ends, a _"later" PoS_ is calculated after quickly reading the PoS data (stored on disk in step 1). This PoS value is then used along with the PoET value to verify that the data indeed spent an epoch stored on the disk. This is done by calculating the PoST by using these two values. At the end of this step, you will have a valid PoST. 4. **[PoST Submission](../../learn/post.md#proof-verification)**: Just successfully calculating the PoST is not enough. It must also be submitted to be eligible for rewards in the epoch for which it was calculated. This PoST submission must be done by including it in a special transaction called an Activation Transaction (ATX) and submitting it to the network during an interval called a Cycle Gap. This time window starts after a PoET round ends (so right after the PoET is calculated) and lasts for 12 hours, after which the next PoET round will start. This time is given to the smeshing nodes can have ample time to create and submit their PoST to the network.