Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Jump to bottom

Remove duplication of the storage market actor interface in storage-market.md #324

Closed
wants to merge 1 commit into from
+22 −50
Closed

Remove duplication of the storage market actor interface in storage-market.md #324

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

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
24 changes: 16 additions & 8 deletions actors.md
View file
Open in desktop
Expand Up @@ -156,20 +156,20 @@ The storage market actor is the central point for the Filecoin storage market. I

```go
type StorageMarketActor struct {
// A set containing the actor address of all storage miner actors.
Miners AddressSet

// TODO: Determine correct unit of measure. Could be denominated in the
// smallest sector size supported by the network.
TotalStorage BytesAmount
// The number of bytes of proven storage in the market.
TotalComittedStorage BytesAmount
}
```
### Code Cid

`<codec:raw><mhType:identity><"smarket">`

| Index | Method Name |
| -------- | ---------- |
| 1 | `CreateStorageMiner` |
| --------- | ---------- |
| 1 | `CreateStorageMiner` |
| 2 | `SlashConsensusFault` |
| 3 | `UpdateStorage` |
| 4 | `GetTotalStorage` |
Expand All @@ -179,6 +179,8 @@ type StorageMarketActor struct {

### CreateStorageMiner

> CreateStorageMiner registers a new storage miner with the given public key. The miner's collateral is set by the value in the message. The public key must match the private key used to sign off on blocks created by this miner. This key is the 'worker' key for the miner. The libp2p peer ID specified should reference the libp2p identity that the miner is operating. This is the ID to which clients will connect to propose deals.

Parameters:

- worker Address
Expand All @@ -193,7 +195,7 @@ func CreateStorageMiner(worker Address, sectorSize BytesAmount, pid PeerID) Addr
Fatal("Unsupported sector size")
}

newminer := InitActor.Exec(MinerActorCodeCid, EncodeParams(pubkey, pledge, sectorSize, pid))
newminer := InitActor.Exec(MinerActorCodeCid, EncodeParams(worker, sectorSize, pid))

self.Miners.Add(newminer)

Expand All @@ -203,6 +205,8 @@ func CreateStorageMiner(worker Address, sectorSize BytesAmount, pid PeerID) Addr

### SlashConsensusFault

> SlashConsensusFault penalizes a miner which submits two different blocks at the same block height. The signatures on each block are validated and the offending miner has their entire collateral burned. All storage the miner is providing is invalidated and the actor is removed from the market's list of miners and from the network state. The caller is rewarded an amount to compensate for gas fees. See [faults](faults.md#consensus-faults).

Parameters:

- block1 BlockHeader
Expand Down Expand Up @@ -263,14 +267,14 @@ func SlashConsensusFault(block1, block2 BlockHeader) {
self.Miners.Remove(miner)
self.UpdateStorage(-1 * miner.Power)

// Now delete the miner (maybe this is a bit harsh, but i'm okay with it for now)
// Remove the actor's state from the network entirely.
miner.SelfDestruct()
}
```

### UpdateStorage

UpdateStorage is used to update the global power table.
> UpdateStorage alters the market's total committed storage amount. It is callable only by a miner actor.

Parameters:

Expand All @@ -290,6 +294,8 @@ func UpdateStorage(delta BytesAmount) {

### GetTotalStorage

> GetTotalStorage returns the total committed storage in the system. This number is also used as the 'total power' in the system for the purposes of the power table.

Parameters: None

Return: BytesAmount
Expand Down Expand Up @@ -648,6 +654,8 @@ func ComputeTemporarySectorFailureFee(sectorSize BytesAmount, numSectors Integer

### SlashStorageFault

> SlashStorageFault penalizes a storage miner for not submitting a PoSt within the required time window. This may be called by anyone who detects the faulty behavior. The slashed miner loses all of their staked collateral and all of their power, and as a result, is no longer a candidate leader for extending the chain. See [faults](faults.md#market-faults).

Parameters:

- miner Address
Expand Down
3 changes: 2 additions & 1 deletion faults.md
View file
Open in desktop
Expand Up @@ -10,7 +10,7 @@ A fault is what happens when partcipants in the protocol are behaving incorrectl
- **Condition:** If any miner posts two blocks satisfying the slashing conditions defined in [Expected Consensus](./expected-consensus.md).
- **Reporting:** Anyone may call `SlashConsensusFault` and pass in the two offending block headers.
- **Check:** The chain checks that both blocks are valid, correctly signed by the same miner, and satisfy the consensus slashing conditions.
- **Penalization:** All of the miner's pledge collateral and all of their power is irrevocably slashed. This miner can never again produce blocks, even if they attempt to repost their collateral.
- **Penalization:** All of the miner's pledge collateral and power is slashed and the miner is irrevocably removed from the market. This miner can never again produce blocks, even if they attempt to repost their collateral.

### Market Faults

Expand All @@ -33,6 +33,7 @@ A fault is what happens when partcipants in the protocol are behaving incorrectl
- *Economic Penalization*: Miner loses all collateral.
- *Power Penalization*: Miner loses all power.
- Note: If a miner is in this state, where they have failed to submit a PoST, any block they attempt to mine will be invalid, even if the election function selects them. (the election function should probably be made to never select them)
- Note: This penalty is recoverable; a miner may post new collateral and commit new sectors.
- Future design note: There is a way to tolerate Internet connection faults. A miner runs an Emergency PoSt which does not take challenges from the chain, if the miner gets reconnected before the VDF attack time (based on Amax), then, they can submit the Emergency PoSt and get pay a late penalization fee.
- **Reported storage fault penalty:**
- **Condition:** The miner submits their PoSt with a non-empty set of 'missing sectors'.
Expand Down
45 changes: 4 additions & 41 deletions storage-market.md
View file
Open in desktop
Expand Up @@ -14,42 +14,7 @@ TODO: This is a high level overview of how the storage market interacts with com

## The Market Interface

This interface, written using Go type notation, defines the set of methods that are callable on the storage market actor. The storage market actor is a built-in network actor. For more information about Actors, see TODO.

```go
type StorageMarket interface {
// CreateStorageMiner registers a new storage miner with the given public key and a
// pledge of the given size. The miners collateral is set by the value in the message.
// The public key must match the private key used to sign off on blocks created
// by this miner. This key is the 'worker' key for the miner.
// The libp2p peer ID specified should reference the libp2p identity that the
// miner is operating. This is the ID that clients will connect to to propose deals
// TODO: maybe rename to 'RegisterStorageMiner'?
CreateStorageMiner(pubk PublicKey, pledge BytesAmount, pid libp2p.PeerID) Address

// SlashConsensusFault is used to slash a misbehaving miner who submitted two different
// blocks at the same block height. The signatures on each block are validated
// and the offending miner has their entire collateral slashed, including the
// invalidation of any any all storage they are providing. The caller is rewarded
// a small amount to compensate for gas fees (TODO: maybe it should be more?)
SlashConsensusFault(blk1, blk2 BlockHeader)

// SlashStorageFault slashes a storage miner for not submitting their PoSTs within
// the correct [time window](#TODO-link-to-faulty-submission). This may be called by anyone who detects the faulty behavior.
// The slashed miner then loses all of their staked collateral, and also loses all
// of their power, and as a result, is no longer a candidate leader for extending the chain.
SlashStorageFault(miner Address)

// UpdateStorage is called by a miner to adjust the storage market actors
// accounting of the total storage in the storage market.
UpdateStorage(delta BytesAmount)

// GetTotalStorage returns the total committed storage in the system. This number is
// also used as the 'total power' in the system for the purposes of the power table
GetTotalStorage() BytesAmount
}
```

The market is defined and operated by a built-in network actor. See [storage market actor](actors.md#storage-market-actor).

## The Filecoin Storage Market Operation

Expand Down Expand Up @@ -115,16 +80,14 @@ TODO: 'complete' isnt really the right word here, as it implies that the deal is

## The Power Table

The `power table` is exported by the storage market for use by consensus. There isn't actually a concrete object that is the power table, instead, there is a 'total power' exported by the storage market actor, and each individual miner reports its power through their actor.
The storage market actor maintains a total committed storage amount, aka "total power". The "power table" is a logical construct which is the fraction of this total power that each miner contributes. This is used by the consensus algorithm.

TODO: rephrase the above to make it clear that power is updated only on PoSt submission and when slashed.
Each individual miner reports its power through its on-chain actor. A miner's power (and hence the total power) is updated only upon PoSt submission (when the set of sectors being proved may change) or when a miner is slashed.
Copy link
Contributor

Choose a reason for hiding this comment

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

Might be good to note that this submission is dependent on the individual miner, rather than a global operation

Copy link
Contributor

Choose a reason for hiding this comment

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

Actually this is already clear, as this is talking about a specific miner, nvm



### Power Updates

A miners power is updated only when they submit a valid PoSt to the chain, or if they are slashed.

TODO: link to methods for post submission and slashing.
A miner's power is updated only when they submit a valid PoSt to the chain, or when slashed. See [storage market actor](actors.md#storage-market-actor).

Power is deducted when miners remove sectors by reporting the sector 'missing' or 'done' in a PoSt.

Expand Down