diff --git a/Lib9c/Action/ValidatorDelegation/SetValidatorCommission.cs b/Lib9c/Action/ValidatorDelegation/SetValidatorCommission.cs index a0d4b0e278..405d8a3666 100644 --- a/Lib9c/Action/ValidatorDelegation/SetValidatorCommission.cs +++ b/Lib9c/Action/ValidatorDelegation/SetValidatorCommission.cs @@ -7,6 +7,9 @@ namespace Nekoyume.Action.ValidatorDelegation { + /// + /// Set the commission percentage of the validator. + /// [ActionType(TypeIdentifier)] public sealed class SetValidatorCommission : ActionBase { diff --git a/Lib9c/Delegation/Delegatee.cs b/Lib9c/Delegation/Delegatee.cs index 6590f68b8e..8e16dedc10 100644 --- a/Lib9c/Delegation/Delegatee.cs +++ b/Lib9c/Delegation/Delegatee.cs @@ -165,12 +165,32 @@ public Address UnbondLockInAddress(Address delegatorAddress) public Address RebondGraceAddress(Address delegatorAddress) => Metadata.RebondGraceAddress(delegatorAddress); + /// + /// Get the of the distribution pool + /// where the rewards are distributed from. + /// + /// + /// of the distribution pool. + /// public Address DistributionPoolAddress() => Metadata.DistributionPoolAddress(); + /// + /// Get the of the current . + /// + /// + /// of the current . + /// public Address CurrentRewardBaseAddress() => Metadata.CurrentRewardBaseAddress(); + /// + /// Get the of the at the given height. + /// + /// + /// + /// of the at the given height. + /// public Address RewardBaseAddress(long height) => Metadata.RewardBaseAddress(height); @@ -404,6 +424,13 @@ ImmutableDictionary reward return reward; } + /// + /// Start a new reward period. + /// It generates a new and archives the current one. + /// + /// + /// The height of the block where the new reward period starts. + /// public void StartNewRewardPeriod(long height) { MigrateLumpSumRewardsRecords(); diff --git a/Lib9c/Delegation/DelegateeMetadata.cs b/Lib9c/Delegation/DelegateeMetadata.cs index a322ea03d8..c94524f100 100644 --- a/Lib9c/Delegation/DelegateeMetadata.cs +++ b/Lib9c/Delegation/DelegateeMetadata.cs @@ -20,6 +20,47 @@ public class DelegateeMetadata : IDelegateeMetadata private Address? _address; private readonly IComparer _currencyComparer = new CurrencyComparer(); + /// + /// Create a new instance of DelegateeMetadata. + /// + /// + /// The of the . + /// + /// + /// The of the account of the . + /// + /// + /// The used for delegation. + /// + /// + /// The enumerable of s used for reward. + /// + /// + /// The of the delegation pool that stores + /// delegated s. + /// + /// + /// The of the reward pool that gathers + /// rewards to be distributed. + /// + /// + /// The of the reward remainder pool to + /// sends the remainder of the rewards to. + /// + /// + /// The of the pool that sends the slashed + /// s to. + /// + /// + /// The period in blocks that the unbonded s + /// can be withdrawn. + /// + /// + /// The maximum number of entries that can be locked in for unbonding. + /// + /// + /// The maximum number of entries that can be locked in for rebonding. + /// public DelegateeMetadata( Address delegateeAddress, Address delegateeAccountAddress, @@ -340,18 +381,55 @@ public Address UnbondLockInAddress(Address delegatorAddress) public virtual Address RebondGraceAddress(Address delegatorAddress) => DelegationAddress.RebondGraceAddress(Address, delegatorAddress); + /// + /// Get the of the distribution pool + /// where the rewards are distributed from. + /// + /// + /// of the distribution pool. + /// public virtual Address DistributionPoolAddress() => DelegationAddress.DistributionPoolAddress(Address); + /// + /// Get the of the current . + /// + /// + /// of the current . + /// public virtual Address CurrentRewardBaseAddress() => DelegationAddress.CurrentRewardBaseAddress(Address); + /// + /// Get the of the at the given height. + /// + /// + /// + /// of the at the given height. + /// public virtual Address RewardBaseAddress(long height) => DelegationAddress.RewardBaseAddress(Address, height); + /// + /// Get the of the current lump sum rewards record. + /// This will be removed after the migration is done. + /// + /// + /// of the current lump sum rewards record. + /// public virtual Address CurrentLumpSumRewardsRecordAddress() => DelegationAddress.CurrentRewardBaseAddress(Address); + /// + /// Get the of the lump sum rewards record at the given height. + /// This will be removed after the migration is done. + /// + /// + /// The height of the lump sum rewards record. + /// + /// + /// of the lump sum rewards record at the given height. + /// public virtual Address LumpSumRewardsRecordAddress(long height) => DelegationAddress.RewardBaseAddress(Address, height); diff --git a/Lib9c/Delegation/DelegationAddress.cs b/Lib9c/Delegation/DelegationAddress.cs index 1e7a340b92..4a850d65dd 100644 --- a/Lib9c/Delegation/DelegationAddress.cs +++ b/Lib9c/Delegation/DelegationAddress.cs @@ -65,18 +65,54 @@ public static Address RebondGraceAddress( delegateeMetadataAddress, delegatorAddress.ByteArray); + /// + /// Get the of the current . + /// + /// + /// of the . + /// + /// + /// of the account of the . + /// + /// + /// of the current . + /// public static Address CurrentRewardBaseAddress( Address delegateeAddress, Address delegateeAccountAddress) => DeriveAddress( DelegationElementType.RewardBase, DelegateeMetadataAddress(delegateeAddress, delegateeAccountAddress)); + /// + /// Get the of the current . + /// + /// + /// of the . + /// + /// + /// of the current . + /// public static Address CurrentRewardBaseAddress( Address delegateeMetadataAddress) => DeriveAddress( DelegationElementType.RewardBase, delegateeMetadataAddress); + /// + /// Get the of the at the given height. + /// + /// + /// of the . + /// + /// + /// of the account of the . + /// + /// + /// The height of the . + /// + /// + /// of the at the given height. + /// public static Address RewardBaseAddress( Address delegateeAddress, Address delegateeAccountAddress, long height) => DeriveAddress( @@ -84,6 +120,18 @@ public static Address RewardBaseAddress( DelegateeMetadataAddress(delegateeAddress, delegateeAccountAddress), BitConverter.GetBytes(height)); + /// + /// Get the of the at the given height. + /// + /// + /// of the . + /// + /// + /// The height of the . + /// + /// + /// of the at the given height. + /// public static Address RewardBaseAddress( Address delegateeMetadataAddress, long height) => DeriveAddress( @@ -103,12 +151,35 @@ public static Address RewardPoolAddress( DelegationElementType.RewardPool, delegateeMetadataAddress); + /// + /// Get the of the distribution pool + /// where the rewards are distributed from. + /// + /// + /// of the . + /// + /// + /// of the account of the . + /// + /// + /// of the distribution pool. + /// public static Address DistributionPoolAddress( Address delegateeAddress, Address delegateeAccountAddress) => DeriveAddress( DelegationElementType.DistributionPool, DelegateeMetadataAddress(delegateeAddress, delegateeAccountAddress)); + /// + /// Get the of the distribution pool + /// where the rewards are distributed from. + /// + /// + /// of the . + /// + /// + /// of the distribution pool. + /// public static Address DistributionPoolAddress( Address delegateeMetadataAddress) => DeriveAddress( diff --git a/Lib9c/Delegation/DelegationRepository.cs b/Lib9c/Delegation/DelegationRepository.cs index d67bc2f614..26f33397b1 100644 --- a/Lib9c/Delegation/DelegationRepository.cs +++ b/Lib9c/Delegation/DelegationRepository.cs @@ -74,26 +74,59 @@ public DelegationRepository( .SetAccount(RewardBaseAccountAddress, rewardBaseAccount) .SetAccount(LumpSumRewardsRecordAccountAddress, lumpSumRewardsRecordAccount); + /// + /// of the current action. + /// public IActionContext ActionContext { get; } + /// + /// of the account. + /// public Address DelegateeAccountAddress { get; } + /// + /// of the account. + /// public Address DelegatorAccountAddress { get; } + /// + /// of the account. + /// public Address DelegateeMetadataAccountAddress { get; } + /// + /// of the account. + /// public Address DelegatorMetadataAccountAddress { get; } + /// + /// of the account. + /// public Address BondAccountAddress { get; } + /// + /// of the account. + /// public Address UnbondLockInAccountAddress { get; } + /// + /// of the account + /// public Address RebondGraceAccountAddress { get; } + /// + /// of the account. + /// public Address UnbondingSetAccountAddress { get; } + /// + /// of the account. + /// public Address RewardBaseAccountAddress { get; } + /// + /// of the account. + /// public Address LumpSumRewardsRecordAccountAddress { get; } public abstract IDelegatee GetDelegatee(Address address); @@ -170,6 +203,7 @@ public UnbondingSet GetUnbondingSet() ? new UnbondingSet(bencoded, this) : new UnbondingSet(this); + /// public RewardBase? GetCurrentRewardBase(IDelegatee delegatee) { Address address = delegatee.CurrentRewardBaseAddress(); @@ -179,6 +213,7 @@ public UnbondingSet GetUnbondingSet() : null; } + /// public RewardBase? GetRewardBase(IDelegatee delegatee, long height) { Address address = delegatee.RewardBaseAddress(height); @@ -251,6 +286,7 @@ public void SetUnbondingSet(UnbondingSet unbondingSet) : unbondingSetAccount.SetState(UnbondingSet.Address, unbondingSet.Bencoded); } + /// public void SetRewardBase(RewardBase rewardBase) { rewardBaseAccount = rewardBaseAccount.SetState(rewardBase.Address, rewardBase.Bencoded); @@ -262,6 +298,7 @@ public void SetLumpSumRewardsRecord(LumpSumRewardsRecord lumpSumRewardsRecord) lumpSumRewardsRecord.Address, lumpSumRewardsRecord.Bencoded); } + /// public void RemoveLumpSumRewardsRecord(LumpSumRewardsRecord lumpSumRewardsRecord) { lumpSumRewardsRecordAccount = lumpSumRewardsRecordAccount.RemoveState(lumpSumRewardsRecord.Address); diff --git a/Lib9c/Delegation/IDelegatee.cs b/Lib9c/Delegation/IDelegatee.cs index 54144830b1..463f9aaeb0 100644 --- a/Lib9c/Delegation/IDelegatee.cs +++ b/Lib9c/Delegation/IDelegatee.cs @@ -65,8 +65,23 @@ public interface IDelegatee Address RebondGraceAddress(Address delegatorAddress); + /// + /// Get the of the current . + /// + /// + /// The of the current . + /// Address CurrentRewardBaseAddress(); + /// + /// Get the of the at the given height. + /// + /// + /// The height of the . + /// + /// + /// The of the at the given height. + /// Address RewardBaseAddress(long height); Address CurrentLumpSumRewardsRecordAddress(); diff --git a/Lib9c/Delegation/IDelegationRepository.cs b/Lib9c/Delegation/IDelegationRepository.cs index c3520d4c41..cec2148a04 100644 --- a/Lib9c/Delegation/IDelegationRepository.cs +++ b/Lib9c/Delegation/IDelegationRepository.cs @@ -36,8 +36,31 @@ public interface IDelegationRepository UnbondingSet GetUnbondingSet(); + /// + /// Get the current of the . + /// + /// + /// The to get the current . + /// + /// + /// The current of the . + /// RewardBase? GetCurrentRewardBase(IDelegatee delegatee); + /// + /// Get the of the + /// at the given . + /// + /// + /// The to get the of. + /// + /// + /// The height to get the at. + /// + /// + /// The of the + /// at the given . + /// RewardBase? GetRewardBase(IDelegatee delegatee, long height); LumpSumRewardsRecord? GetCurrentLumpSumRewardsRecord(IDelegatee delegatee); @@ -62,10 +85,24 @@ public interface IDelegationRepository void SetUnbondingSet(UnbondingSet unbondingSet); + /// + /// Set the of the . + /// + /// + /// The to set. + /// void SetRewardBase(RewardBase rewardBase); void SetLumpSumRewardsRecord(LumpSumRewardsRecord lumpSumRewardsRecord); + /// + /// Remove the from the . + /// This is used when the is no longer needed. + /// This can be removed when the migration for is done. + /// + /// + /// The to remove. + /// void RemoveLumpSumRewardsRecord(LumpSumRewardsRecord lumpSumRewardsRecord); void TransferAsset(Address sender, Address recipient, FungibleAssetValue value); diff --git a/Lib9c/ValidatorDelegation/AbstainHistory.cs b/Lib9c/ValidatorDelegation/AbstainHistory.cs index deaedb1f12..3e67bab5b3 100644 --- a/Lib9c/ValidatorDelegation/AbstainHistory.cs +++ b/Lib9c/ValidatorDelegation/AbstainHistory.cs @@ -42,6 +42,9 @@ public AbstainHistory(List bencoded) public static int WindowSize => 10; + /// + /// Maximum abstain allowance to slash and jail. + /// public static int MaxAbstainAllowance => 9; public static Address Address => new Address(