Skip to content

Commit be5bec1

Browse files
DinonardDinonard
authored
dApp staking v3 precompile docs (#1121)
* dApp staking v3 precompile docs * Renaming
1 parent 1fa3c7b commit be5bec1

File tree

4 files changed

+205
-167
lines changed

4 files changed

+205
-167
lines changed

‎precompiles/dapp-staking-v3/DappsStakingV1.sol

-98
This file was deleted.

‎precompiles/dapp-staking-v3/DappsStakingV2.sol

+77-69
Original file line numberDiff line numberDiff line change
@@ -5,88 +5,96 @@ pragma solidity >=0.8.0;
55
/// Predeployed at the address 0x0000000000000000000000000000000000005001
66
/// For better understanding check the source code:
77
/// repo: https://github.com/AstarNetwork/Astar
8-
/// code: pallets/dapp-staking-v3
9-
interface DAppStaking {
8+
///
9+
/// **NOTE:** This is a soft-deprecated interface used by the old dApps staking v2.
10+
/// It is still supported by the network, but doesn't reflect how dApp staking v3 should be used.
11+
/// Please refer to the `v3` interface for the latest version of the dApp staking precompile.
12+
///
13+
/// It is possible that dApp staking feature will once again evolve in the future so all developers are encouraged
14+
/// to keep their smart contracts which utilize dApp staking precompile interface as upgradable, or implement their logic
15+
/// in such a way it's relatively simple to migrate to the new version of the interface.
16+
interface DappsStaking {
1017

1118
// Types
1219

13-
/// Describes the subperiod in which the protocol currently is.
14-
enum Subperiod {Voting, BuildAndEarn}
15-
16-
/// Describes current smart contract types supported by the network.
17-
enum SmartContractType {EVM, WASM}
18-
19-
/// @notice Describes protocol state.
20-
/// @param era: Ongoing era number.
21-
/// @param period: Ongoing period number.
22-
/// @param subperiod: Ongoing subperiod type.
23-
struct ProtocolState {
24-
uint256 era;
25-
uint256 period;
26-
Subperiod subperiod;
27-
}
28-
29-
/// @notice Used to describe smart contract. Astar supports both EVM & WASM smart contracts
30-
/// so it's important to differentiate between the two. This approach also allows
31-
/// easy extensibility in the future.
32-
/// @param contract_type: Type of the smart contract to be used
33-
struct SmartContract {
34-
SmartContractType contract_type;
35-
bytes contract_address;
36-
}
20+
/// Instruction how to handle reward payout for staker.
21+
/// `FreeBalance` - Reward will be paid out to the staker (free balance).
22+
/// `StakeBalance` - Reward will be paid out to the staker and is immediately restaked (locked balance)
23+
enum RewardDestination {FreeBalance, StakeBalance}
3724

3825
// Storage getters
3926

40-
/// @notice Get the current protocol state.
41-
/// @return (current era, current period number, current subperiod type).
42-
function protocol_state() external view returns (ProtocolState memory);
27+
/// @notice Read current era.
28+
/// @return era: The current era
29+
function read_current_era() external view returns (uint256);
4330

44-
/// @notice Get the unlocking period expressed in the number of blocks.
45-
/// @return period: The unlocking period expressed in the number of blocks.
46-
function unlocking_period() external view returns (uint256);
31+
/// @notice Read the unbonding period (or unlocking period) in the number of eras.
32+
/// @return period: The unbonding period in eras
33+
function read_unbonding_period() external view returns (uint256);
4734

35+
/// @notice Read Total network reward for the given era - sum of staker & dApp rewards.
36+
/// @return reward: Total network reward for the given era
37+
function read_era_reward(uint32 era) external view returns (uint128);
4838

49-
// Extrinsic calls
50-
51-
/// @notice Lock the given amount of tokens into dApp staking protocol.
52-
/// @param amount: The amount of tokens to be locked.
53-
function lock(uint128 amount) external returns (bool);
54-
55-
/// @notice Start the unlocking process for the given amount of tokens.
56-
/// @param amount: The amount of tokens to be unlocked.
57-
function unlock(uint128 amount) external returns (bool);
39+
/// @notice Read Total staked amount for the given era
40+
/// @return staked: Total staked amount for the given era
41+
function read_era_staked(uint32 era) external view returns (uint128);
5842

59-
/// @notice Claims unlocked tokens, if there are any
60-
function claim_unlocked() external returns (bool);
43+
/// @notice Read Staked amount for the staker
44+
/// @param staker: The staker address in form of 20 or 32 hex bytes
45+
/// @return amount: Staked amount by the staker
46+
function read_staked_amount(bytes calldata staker) external view returns (uint128);
6147

62-
/// @notice Stake the given amount of tokens on the specified smart contract.
63-
/// The amount specified must be precise, otherwise the call will fail.
64-
/// @param smart_contract: The smart contract to be staked on.
65-
/// @param amount: The amount of tokens to be staked.
66-
function stake(SmartContract calldata smart_contract, uint128 amount) external returns (bool);
48+
/// @notice Read Staked amount on a given contract for the staker
49+
/// @param contract_id: The smart contract address used for staking
50+
/// @param staker: The staker address in form of 20 or 32 hex bytes
51+
/// @return amount: Staked amount by the staker
52+
function read_staked_amount_on_contract(address contract_id, bytes calldata staker) external view returns (uint128);
6753

68-
/// @notice Unstake the given amount of tokens from the specified smart contract.
69-
/// The amount specified must be precise, otherwise the call will fail.
70-
/// @param smart_contract: The smart contract to be unstaked from.
71-
/// @param amount: The amount of tokens to be unstaked.
72-
function unstake(SmartContract calldata smart_contract, uint128 amount) external returns (bool);
54+
/// @notice Read the staked amount from the era when the amount was last staked/unstaked
55+
/// @return total: The most recent total staked amount on contract
56+
function read_contract_stake(address contract_id) external view returns (uint128);
7357

74-
/// @notice Claims one or more pending staker rewards.
75-
function claim_staker_rewards() external returns (bool);
7658

77-
/// @notice Claim the bonus reward for the specified smart contract.
78-
/// @param smart_contract: The smart contract for which the bonus reward should be claimed.
79-
function claim_bonus_reward(SmartContract calldata smart_contract) external returns (bool);
80-
81-
/// @notice Claim dApp reward for the specified smart contract & era.
82-
/// @param smart_contract: The smart contract for which the dApp reward should be claimed.
83-
/// @param era: The era for which the dApp reward should be claimed.
84-
function claim_dapp_reward(SmartContract calldata smart_contract, uint256 era) external returns (bool);
85-
86-
/// @notice Unstake all funds from the unregistered smart contract.
87-
/// @param smart_contract: The smart contract which was unregistered and from which all funds should be unstaked.
88-
function unstake_from_unregistered(SmartContract calldata smart_contract) external returns (bool);
59+
// Extrinsic calls
8960

90-
/// @notice Used to cleanup all expired contract stake entries from the caller.
91-
function cleanup_expired_entries() external returns (bool);
61+
/// @notice Register is root origin only and not allowed via evm precompile.
62+
/// This should always fail.
63+
function register(address) external returns (bool);
64+
65+
/// @notice Stake provided amount on the contract.
66+
/// If the staker has sufficient locked amount to cover the stake, no additional amount is locked.
67+
/// If the staker has insufficient locked amount to cover the stake, an attempt will be made to lock the missing amount.
68+
function bond_and_stake(address, uint128) external returns (bool);
69+
70+
/// @notice Unstake balance from the smart contract, and begin the unlocking process.
71+
function unbond_and_unstake(address, uint128) external returns (bool);
72+
73+
/// @notice Withdraw all funds that have completed the unbonding process.
74+
function withdraw_unbonded() external returns (bool);
75+
76+
/// @notice Claim earned staker rewards for the oldest unclaimed era.
77+
/// In order to claim multiple eras, this call has to be called multiple times.
78+
/// Staker account is derived from the caller address.
79+
/// @param smart_contract: The smart contract address used for staking
80+
function claim_staker(address smart_contract) external returns (bool);
81+
82+
/// @notice Claim one era of unclaimed dapp rewards for the specified contract and era.
83+
/// @param smart_contract: The smart contract address used for staking
84+
/// @param era: The era to be claimed
85+
function claim_dapp(address smart_contract, uint128 era) external returns (bool);
86+
87+
/// @notice This call is deprecated and will always fail.
88+
/// @param reward_destination: The instruction on how the reward payout should be handled (ignored)
89+
function set_reward_destination(RewardDestination reward_destination) external returns (bool);
90+
91+
/// @notice Unstake funds from an unregistered contract.
92+
/// @param smart_contract: The smart contract address used for staking
93+
function withdraw_from_unregistered(address smart_contract) external returns (bool);
94+
95+
/// @notice Transfer part or entire nomination from origin smart contract to target smart contract
96+
/// @param origin_smart_contract: The origin smart contract address
97+
/// @param amount: The amount to transfer from origin to target, must be precise.
98+
/// @param target_smart_contract: The target smart contract address
99+
function nomination_transfer(address origin_smart_contract, uint128 amount, address target_smart_contract) external returns (bool);
92100
}

‎precompiles/dapp-staking-v3/DappsStakingV3.sol

+92
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
// SPDX-License-Identifier: BSD-3-Clause
2+
3+
pragma solidity >=0.8.0;
4+
5+
/// Predeployed at the address 0x0000000000000000000000000000000000005001
6+
/// For better understanding check the source code:
7+
/// repo: https://github.com/AstarNetwork/Astar
8+
/// code: pallets/dapp-staking-v3
9+
interface DAppStaking {
10+
11+
// Types
12+
13+
/// Describes the subperiod in which the protocol currently is.
14+
enum Subperiod {Voting, BuildAndEarn}
15+
16+
/// Describes current smart contract types supported by the network.
17+
enum SmartContractType {EVM, WASM}
18+
19+
/// @notice Describes protocol state.
20+
/// @param era: Ongoing era number.
21+
/// @param period: Ongoing period number.
22+
/// @param subperiod: Ongoing subperiod type.
23+
struct ProtocolState {
24+
uint256 era;
25+
uint256 period;
26+
Subperiod subperiod;
27+
}
28+
29+
/// @notice Used to describe smart contract. Astar supports both EVM & WASM smart contracts
30+
/// so it's important to differentiate between the two. This approach also allows
31+
/// easy extensibility in the future.
32+
/// @param contract_type: Type of the smart contract to be used
33+
struct SmartContract {
34+
SmartContractType contract_type;
35+
bytes contract_address;
36+
}
37+
38+
// Storage getters
39+
40+
/// @notice Get the current protocol state.
41+
/// @return (current era, current period number, current subperiod type).
42+
function protocol_state() external view returns (ProtocolState memory);
43+
44+
/// @notice Get the unlocking period expressed in the number of blocks.
45+
/// @return period: The unlocking period expressed in the number of blocks.
46+
function unlocking_period() external view returns (uint256);
47+
48+
49+
// Extrinsic calls
50+
51+
/// @notice Lock the given amount of tokens into dApp staking protocol.
52+
/// @param amount: The amount of tokens to be locked.
53+
function lock(uint128 amount) external returns (bool);
54+
55+
/// @notice Start the unlocking process for the given amount of tokens.
56+
/// @param amount: The amount of tokens to be unlocked.
57+
function unlock(uint128 amount) external returns (bool);
58+
59+
/// @notice Claims unlocked tokens, if there are any
60+
function claim_unlocked() external returns (bool);
61+
62+
/// @notice Stake the given amount of tokens on the specified smart contract.
63+
/// The amount specified must be precise, otherwise the call will fail.
64+
/// @param smart_contract: The smart contract to be staked on.
65+
/// @param amount: The amount of tokens to be staked.
66+
function stake(SmartContract calldata smart_contract, uint128 amount) external returns (bool);
67+
68+
/// @notice Unstake the given amount of tokens from the specified smart contract.
69+
/// The amount specified must be precise, otherwise the call will fail.
70+
/// @param smart_contract: The smart contract to be unstaked from.
71+
/// @param amount: The amount of tokens to be unstaked.
72+
function unstake(SmartContract calldata smart_contract, uint128 amount) external returns (bool);
73+
74+
/// @notice Claims one or more pending staker rewards.
75+
function claim_staker_rewards() external returns (bool);
76+
77+
/// @notice Claim the bonus reward for the specified smart contract.
78+
/// @param smart_contract: The smart contract for which the bonus reward should be claimed.
79+
function claim_bonus_reward(SmartContract calldata smart_contract) external returns (bool);
80+
81+
/// @notice Claim dApp reward for the specified smart contract & era.
82+
/// @param smart_contract: The smart contract for which the dApp reward should be claimed.
83+
/// @param era: The era for which the dApp reward should be claimed.
84+
function claim_dapp_reward(SmartContract calldata smart_contract, uint256 era) external returns (bool);
85+
86+
/// @notice Unstake all funds from the unregistered smart contract.
87+
/// @param smart_contract: The smart contract which was unregistered and from which all funds should be unstaked.
88+
function unstake_from_unregistered(SmartContract calldata smart_contract) external returns (bool);
89+
90+
/// @notice Used to cleanup all expired contract stake entries from the caller.
91+
function cleanup_expired_entries() external returns (bool);
92+
}

0 commit comments

Comments
 (0)