Skip to content

Commit

Permalink
Merge pull request #597 from ethersphere/quick-fixes
Browse files Browse the repository at this point in the history
small fixes
  • Loading branch information
NoahMaizels authored May 22, 2024
2 parents 6821008 + 5a577ff commit 3a6dbfd
Show file tree
Hide file tree
Showing 3 changed files with 14 additions and 7 deletions.
15 changes: 9 additions & 6 deletions docs/develop/access-the-swarm/buy-a-stamp-batch.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,21 +90,24 @@ Once your batch has been purchased, it will take a few minutes for other Bee nod

When purchasing a batch of stamps there are several parameters and options which must be considered. The `depth` parameter will control how many chunks can be uploaded with a batch of stamps. The `amount` parameter determines how much xBZZ will be allocated per chunk, and therefore also controls how long the chunks will be stored. While the `immutable` header option sets the batch as either mutable or immutable, which can significantly alter the behavior of the batch utilisation (more details below).

:::caution
The minimum value for `depth` is 17, however a minimum depth of 23 is recommended for most use cases due to the [mechanics of stamp batch utilisation](/docs/learn/technology/contracts/postage-stamp#batch-utilisation). See [the depths utilisation table](/docs/learn/technology/contracts/postage-stamp#effective-utilisation-table) to help decide which depth is best for your use case.

The minimum `amount` value for purchasing stamps is required to be at least enough to pay for 24 hours of storage. To find this value multiply the lastPrice value from the postage stamp contract times 17280 (the number of blocks in 24 hours). This requirement is in place in order to prevent spamming the network.
:::

### Choosing `depth`

:::caution
The minimum value for `depth` is 17, however a higher depth value is recommended for most use cases due to the [mechanics of stamp batch utilisation](/docs/learn/technology/contracts/postage-stamp#batch-utilisation). See [the depths utilisation table](/docs/learn/technology/contracts/postage-stamp#effective-utilisation-table) to help decide which depth is best for your use case.
:::

One notable aspect of batch utilisation is that the entire batch is considered fully utilised as soon as any one of its buckets are filled. This means that the actual amount of chunks storable by a batch is less than the nominal maximum amount.

See the [postage stamp contract page](/docs/learn/technology/contracts/postage-stamp#batch-utilisation) for a more complete explanation of how batch utilisation works and a [table](/docs/learn/technology/contracts/postage-stamp#effective-utilisation-table) with the specific amounts of data which can be safely uploaded for each `depth` value.

### Choosing `amount`

The `amount` parameter determines how much xBZZ is assigned per chunk for a postage stamp batch. You can use the calculators below to find the appropriate `amount` value for your target duration of storage and can also preview the price. For more information see the [postage stamp batch contract page](/docs/learn/technology/contracts/postage-stamp#batch-amount--batch-cost) where a more complete description is inclu
:::caution
The minimum `amount` value for purchasing stamps is required to be at least enough to pay for 24 hours of storage. To find this value multiply the lastPrice value from the postage stamp contract times 17280 (the number of blocks in 24 hours). You can also use the [calculator](#calculators) below. This requirement is in place in order to prevent spamming the network.
:::

The `amount` parameter determines how much xBZZ is assigned per chunk for a postage stamp batch. You can use the calculators below to find the appropriate `amount` value for your target duration of storage and can also preview the price. For more information see the [postage stamp batch contract page](/docs/learn/technology/contracts/postage-stamp#batch-amount--batch-cost) where a more complete description is included.

### Mutable or Immutable?

Expand Down
2 changes: 1 addition & 1 deletion docs/learn/advanced/neighbourhoods.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ As the address of the chunk shown above shares the same ten leading binary bits

### Neighbourhood Doubling

As more and more chunks are assigned to neighbourhoods, the chunk reserves of the nodes of the nodes in that neighbourhood will begin to fill up. Once the nodes' reserves in a neighbourhood become full and can no longer store additional chunks, that neighbourhood will split, with each half of the neighbourhood taking responsibility for half of the chunks. This event is referred to as a "doubling", as it results in double the number of neighbourhoods. The split is done by increasing the storage depth by one, so that the number of shared leading bits is increased by one. This results in a binary splitting of the neighbourhood and associated chunks into two new neighbourhoods and respective groups of chunks.
As more and more chunks are assigned to neighbourhoods, the chunk reserves of the nodes in that neighbourhood will begin to fill up. Once the nodes' reserves in a neighbourhood become full and can no longer store additional chunks, that neighbourhood will split, with each half of the neighbourhood taking responsibility for half of the chunks. This event is referred to as a "doubling", as it results in double the number of neighbourhoods. The split is done by increasing the storage depth by one, so that the number of shared leading bits is increased by one. This results in a binary splitting of the neighbourhood and associated chunks into two new neighbourhoods and respective groups of chunks.

:::info
Note that when chunks begin to expire and new chunks are not uploaded to Swarm, it is possible for node's reserves to empty out, once they fall below a certain threshold, a "halving" will occur in which the storage depth will be decreased by one and two neighbourhoods will merge to make a new one so that they are responsible for a wider set of chunks.
Expand Down
4 changes: 4 additions & 0 deletions docs/learn/technology/contracts/postage-stamp.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,10 @@ Each batch of stamps has two key parameters, `batch depth` and `amount`, which a

### Batch Depth

:::caution
The minimum value for `depth` is 17, however higher depths are recommended for most use cases due to the [mechanics of stamp batch utilisation](#batch-utilisation). See [the depths utilisation table](#effective-utilisation-table) to help decide which depth is best for your use case.
:::

`Batch depth` determines how much data can be stored by a batch. The number of chunks which can be stored (stamped) by a batch is equal to $$2^{batchDepth}$$.

For a batch with a `batch depth` of 24, a maximum of $$2^{24} = 16,777,216$$ chunks can be stamped.
Expand Down

0 comments on commit 3a6dbfd

Please sign in to comment.