Revise to line up with implementation (#325)

FIPS/fip-0029.md

@@ -42,26 +42,25 @@ The following channges apply to specs-actors module:
 
 ### Beneficiary information in state
 - Add **Beneficiary** address into **MinerInfo** structure
-- Add **BeneficiaryInfo** structure into **MinerInfo** structure to include `{beneficialQuota (attoFIL), beneficialExpiration(Height), usedQuota(attoFIL)}`. 
+- Add **BeneficiaryTerm** structure into **MinerInfo** structure to include `{Quota (attoFIL), Expiration(Height), usedQuota(attoFIL)}`. 
 - The **Beneficiary** is set to the same address of **Owner** when initiating a miner without specifying a beneficiary address (for back-compatibility)
 - The **Beneficiary** address could be a signable address, or multisig address, or actor address (for smart contract)
-- Add a **ProposedBeneficiaryInfo** structure into **MinerInfo** structure to record the `ChangeBeneficiary` information and progress, including parameters and who has approved it.
+- Add a **PendingBeneficiaryTerm** structure into **MinerInfo** structure to record the `ChangeBeneficiary` information and progress, including parameters and who has approved it.
 
 ### Withdrawals to beneficiary
 - The **WithdrawBalance** method of a miner can be called by the miner's **Beneficiary** or **Owner**, but the balance always being sent to the beneficiary. The total balance withdrawed to a beneficiary address could not exceed the quota if it is set.
 
 ### Setting the beneficiary address
-- Add **ChangeBeneficiary** method to miner actor to propose or confirm a change of beneficiary address and/or beneficiaryInfo. When changing beneficiaryInfo, the quota must be larger than the usedQuota. The beneficiaryChange is following a proposal/confirmation manner. There are different scenarios under which the proposal and confirmation steps are different, as below:
-    1) The current beneficiary address is the owner, the ChangeBeneficiary just can be sent by the Owner
-        - ChangeBeneficiary command needs to propose a new beneficiary address, at the same time, the beneficiaryInfo can be set at the same time
-        - The new beneficiary should send the same command to confirm, and then it can take effect. In addition, the usedQuota is set to 0 since it's new.
-    2) The beneficiary (not the owner) is expired or the quota is used up, the ChangeBeneficiary command can only be sent by the owner
-        - When the new beneficiary is back to owner, the BeneficiaryInfo is set to default, and the change takes effect immediately
-        - When the beneficiary address keeps the same, only beneficiaryInfo is set. In this case, the usedQuota keeps no change, and the new Quota should be larger than or equal to the usedQuota
-        - When there is a new beneficiary (not the owner itself), after the owner sent the ChangeBeneficiary command to change the beneficiary and beneficiaryInfo, the new beneficiary should send the same command to confirm, and then it can take effect. In addition, the usedQuota is set to 0 since it's new.
-    3) The beneficiary (not the owner) is not expired and quota is not used up, the ChangeBeneficiary command is also firstly sent by the owner, and next confirmed by both the existing and new beneficiary(ies) to take effect.
-        - When the beneficiary address does not change, i.e. only change beneficiaryInfo, thus, only need the beneficiary to send the same command to confirm (like what we do for owner change)
-        - When there is a new beneficiary address is proposed. It requires the current beneficiary to send the same command to confirm, and followed the new beneficiary confirmation command the the same parameters. In this case, the usedQuota is set to 0, and the newly set quota is counted from 0.  
+- Add **ChangeBeneficiary** method to miner actor to propose or confirm a change of beneficiary address and/or beneficiaryTerm. When changing beneficiaryTerm, the quota must be larger than the usedQuota. The beneficiaryChange is following a proposal/confirmation manner. A **ChangeBeneficiary** proposal can only be submitted by the **Owner**, and it takes effect only after approval(s) related parties if effective. The related parties include the **Owner**, the current Beneficiary, and the proposed Beneficiary. However, there are scenarios of auto-approval (no message required) as below: 
+    - The **Owner** always auto-approves the proposal since Only the owner can send **ChangeBeneficiary** proposal
+    - When current Beneficiary or proposed Beneficiary shares the Owner's address
+    - When the current Beneficiary is expired or Quota is used up
+    - When current and proposed Beneficiaries are the same, One's approval means both approvals.
+- Some other consideration related to **ChangeBeneficiary**: 
+    - A succssful **ChangeOwnerAddress** will invalidate any **pendingBeneficiaryTerm**, which means, a non-fully approved **ChangeBeneficiary** will be deleted whenever the **Owner** address changs
+    - **UsedQuota** is set to 0 whenever the Beneficiary address changes, but keeps no change if the proposed Beneficiary equals to the current Beneficiary
+    - Both **Experition**, **Quota** and **UserdQuota** set back to default (0) when the Beneficiary changes back to the **Owner**
+
 - Add a **GetBeneficiary** method to the miner actor which retrieves the currently active and proposed beneficiary information.
 This method is for use by other actors (such as those acting as beneficiaries), and to abstract the state representation for clients.
 
@@ -82,15 +81,15 @@ In addition, if we have the security feature, it will protest the storage provid
 
 **ChangeBeneficiary** design
 - Security is one of the main considerations when desigining the `ChangeBeneficiary` process, especially when beneficiary can be transferred to the lending part. The basic idea is that every change of beneficiary information is based on the agreement among related parties, so the design includes proposal and confirmation process, and every part need to be involved to make it happen.
-- `beneficialQuota` and `usedQuota` is used to track the financial setting and status for a beneficiary. An altenative of this design is to use only one parameter - `remainingQuota` to record the status. Considering that people want to control total `beneficialQuota` in most cases, especially in lending market. The 2 parameters' design is more user-friendly.
+- `Quota` and `usedQuota` is used to track the financial setting and status for a beneficiary. An altenative of this design is to use only one parameter - `remainingQuota` to record the status. Considering that people want to control total `Quota` in most cases, especially in lending market. The 2 parameters' design is more user-friendly.
 
 
 ## Backwards Compatibility
 <!--All FIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The FIP must explain how the author proposes to deal with these incompatibilities. FIP submissions without a sufficient backwards compatibility treatise may be rejected outright.-->
 
 This FIP changes built-in actors' behavior so it requires a new Filecoin network version.
 This FIP changes the miner actor state schema, so requires a migration to update all miners to the new schema.
-For each existing miner, the `Beneficiary` address is set to the current owner address, and the `BeneficiaryInfo` set to zero values.
+For each existing miner, the `Beneficiary` address is set to the current owner address, and the `beneficiaryTerm` set to zero values.
 
 This will result in no change to existing functional behaviour, so is fully backwards compatible.
 
@@ -131,11 +130,8 @@ The implementation of separating beneficiary from owner will bring the ecosystem
 ## Implementation
 Specs-actors PR: https://github.com/filecoin-project/specs-actors/pull/1571
 
-The overall flow chart of the ChangeBeneficiary proposal process: 
-![The proposal process of ChangeBeneficiary by the owner](../resources/fip-0029/propose-beneficiary-flow.png)
-
-The overall flow chart of the ChangeBeneficiary approval process: 
-![The approval process by the beneficiary(ies)](../resources/fip-0029/approve-beneficiary-flow.png)
+The overall flow chart of the ChangeBeneficiary process: 
+![The overll process of ChangeBeneficiary](../resources/fip-0029/ChangeBeneficiary-flow.png)
 
 
 ## Copyright