An initial stab at speccing Pledge Collateral

See context in #60.

Thanks to @whyrusleeping for help translating this into spec.

actors.md

@@ -484,10 +484,11 @@ func CommitSector(sectorID SectorID, commD, commR, commRStar []byte, proof SealP
 		Fatal("sector already committed!")
 	}
 
-	// make sure the miner has enough collateral to add more storage
-	coll = CollateralForSector(miner.SectorSize)
+  // Power of the miner after adding this sector
+  futurePower = miner.power + miner.SectorSize
+  collateralRequired = collateralForPower(futurePower)
 
-	if coll < vm.MyBalance()-miner.ActiveCollateral {
+  if collateralRequired > vm.MyBalance() {
 		Fatal("not enough collateral")
 	}
 
@@ -511,6 +512,16 @@ func CommitSector(sectorID SectorID, commD, commR, commRStar []byte, proof SealP
 		miner.ProvingPeriodEnd = chain.Now() + ProvingPeriodDuration(miner.SectorSize)
 	}
 }
+
+func collateralForPower(power BytesAmount) TokenAmount {
+  availableFil = FakeGlobalMethods.GetAvailableFil()
+  totalNetworkPower = StorageMinerActor.GetTotalStorage()
+  numMiners = FakeGlobalMethods.GetTotalNumMiners()
+  powerCollateral = availableFil * NetworkConstants.POWER_COLLATERAL_PROPORTION * power / totalNetworkPower
+  perCapitaCollateral = availableFil * NetworkConstants.PER_CAPITA_COLLATERAL_PROPORTION / numMiners
+  collateralRequired = minerPowerCollateral + minerPerCapitaCollateral
+  return collateralRequired
+}
 ```
 
 ### SubmitPoSt

mining.md

@@ -306,7 +306,7 @@ To create a block, the eligible miner must compute a few fields:
 - `MsgRoot` - To compute this:
   - Select a set of messages from the mempool to include in the block.
   - Insert them into a Merkle Tree and take its root.
-    - Note: Messages with BLS signatures should be included as raw `Message` types, and not `SignedMessage`. Their signatures should be gathered up and aggregated for the `BLSAggregate` field. 
+    - Note: Messages with BLS signatures should be included as raw `Message` types, and not `SignedMessage`. Their signatures should be gathered up and aggregated for the `BLSAggregate` field.
 - `StateRoot` - Apply each chosen message to the `ParentState` to get this.
 - `ReceiptsRoot` - To compute this:
   - Apply the set of messages selected above to the parent state, collecting invocation receipts as this happens.
@@ -371,6 +371,8 @@ HalvingPeriodBlocks = 6 * 365 * 24 * 60 * 2
 
 Note: Due to jitter in EC, and the gregorian calendar, there may be some error in the issuance schedule over time. This is expected to be small enough that it's not worth correcting for. Additionally, since the payout mechanism is transferring from the network account to the miner, there is no risk of minting *too much* FIL.
 
+TODO: Ensure that if a miner earns a block reward while undercollateralized, then `min(blockReward, requiredCollateral-availableBalance)` is garnished (transfered to the miner actor instead of the owner).
+
 ### Open Questions
 
 - How should receipts for tipsets 'virtual blocks' be referenced? It is common for applications to provide the merkleproof of a receipt to prove that a transaction was successfully executed.

pledge-collateral.md

@@ -0,0 +1,63 @@
+# Pledge Collateral
+
+Filecoin includes a concept of "Pledge Collateral", which is FIL collateral that storage miners must lock up when participating as miners.
+
+Pledge collateral serves several functions in Filecoin. It:
+- makes it possible to slash misbehaving or slow miners
+- ensures that miners have skin in the game (for the Filecoin network as a whole)
+- increases the cost of launching a 51% attack
+
+
+## Computing Pledge Collateral
+
+The total pledge collateral across all miners is a fixed proportion of available FIL.
+Available FIL is computed as the total amount of FIL that has been mined, plus the total amount of FIL that's been vested.
+
+```go
+availableFil := minedFil + vestedFil
+```
+
+Pledge collateral is subdivided into two kinds: power collateral and per-capita collateral.
+Power collateral is split across miners according to their share of the total network power, and per-capita collateral is split across miners evenly.
+Two parameters, `POWER_COLLATERAL_PROPORTION` and `PER_CAPITA_COLLATERAL_PROPORTION`, relate the total amount of collateral to the `availableFil`.
+
+```go
+totalPowerCollateral := availableFil * POWER_COLLATERAL_PROPORTION
+totalPerCapitaCollateral := availableFil * PER_CAPITA_COLLATERAL_PROPORTION
+totalPledgeCollateral := totalPowerCollateral + totalPerCapitaCollateral
+```
+
+Power-based collateral ensures that miners' collateral is proportional to their economic size and to their expected rewards.
+The presence of per-capital collateral acts as a deterrent against Sibyl attacks.
+We intend for the `POWER_COLLATERAL_PROPORTION` to be several times larger than the `PER_CAPITA_COLLATERAL_PROPORTION`.
+
+To calculate any particular miner's collateral requirements, we need to know the miner's power, the total network power, and the total number of miners in the network.
+
+```go
+minerPowerCollateral := totalPowerCollateral * minerPower / totalNetworkPower
+minerPerCapitaCollateral := totalPerCapitaCollateral / numMiners
+```
+
+Putting all these variables together, we have each miner's individual collateral requirement:
+```go
+minerPlegeCollateral := availableFil * ( POWER_COLLATERAL_PROPORTION * minerPower / totalNetworkPower PER_CAPITA_COLLATERAL_PROPORTION / numMiners)
+```
+
+## Dealing with Undercollateralization
+
+In the course of normal events, miners may become undercollateralized.
+
+They cannot directly undercollateralized themselves by adding more power, as commitSector will fail if they do not have sufficient collateral to cover their power requirements.
+However, their collateral requirement could increase due to growth in availableFil, a reduction in the total network power, or a reduction in the total number of miners.
+In such cases, the miner may continue to submit PoSts and mine blocks. When they win blocks, their block rewards will be garnished while they remain undercollateralized.
+
+## Parameter Choices
+
+We provisionally propose the following two parameters choices:
+
+```go
+POWER_COLLATERAL_PROPORTION := 0.2
+PER_CAPITA_COLLATERAL_PROPORTION := 0.05
+```
+
+These are subject to change before launch.