|
| 1 | +# Spec 26 Changelog |
| 2 | + |
| 3 | +This release introduces wallet stake delegation permissions, enabling secure delegation of staking operations to trusted accounts while maintaining control over funds. This feature creates a cold-hot wallet architecture for enhanced security. |
| 4 | + |
| 5 | +## 1. Extrinsics |
| 6 | + |
| 7 | +### permission0 pallet |
| 8 | + |
| 9 | +- ```diff |
| 10 | + + #[pallet::call_index(11)] |
| 11 | + + pub fn delegate_wallet_stake_permission( |
| 12 | + + origin: OriginFor<T>, |
| 13 | + + recipient: T::AccountId, |
| 14 | + + stake_details: WalletStake, |
| 15 | + + duration: PermissionDuration<T>, |
| 16 | + + revocation: RevocationTerms<T>, |
| 17 | + + ) -> DispatchResult |
| 18 | + ``` |
| 19 | + Creates a wallet permission that delegates stake management capabilities to a recipient account. The delegator can specify whether the recipient can transfer stake between validators and whether the delegation is exclusive (blocking the delegator from managing their own stake). See [Wallet Stake Delegation](#wallet-stake-delegation). |
| 20 | + |
| 21 | +- ```diff |
| 22 | + + #[pallet::call_index(12)] |
| 23 | + + pub fn execute_wallet_stake_permission( |
| 24 | + + caller: OriginFor<T>, |
| 25 | + + permission_id: PermissionId, |
| 26 | + + op: WalletStakeOperation<T>, |
| 27 | + + ) -> DispatchResult |
| 28 | + ``` |
| 29 | + Allows a permission recipient to execute delegated stake operations (unstaking or transferring stake between validators) on behalf of the delegator. The operation type and parameters are specified through the `WalletStakeOperation` enum. See [Wallet Stake Delegation](#wallet-stake-delegation). |
| 30 | + |
| 31 | +## 2. Events |
| 32 | + |
| 33 | +No new events were added in this release. The existing `PermissionDelegated` event is emitted when wallet permissions are created. |
| 34 | + |
| 35 | +## 3. Storage Items |
| 36 | + |
| 37 | +No new storage items were added. Wallet permissions are stored in the existing `Permissions` storage map with the new `Wallet` variant of `PermissionScope`. |
| 38 | + |
| 39 | +## 4. Structs & Enums |
| 40 | + |
| 41 | +### permission0 pallet |
| 42 | + |
| 43 | +- ```diff |
| 44 | + + pub struct WalletScope<T: Config> { |
| 45 | + + pub recipient: T::AccountId, |
| 46 | + + pub r#type: WalletScopeType, |
| 47 | + + } |
| 48 | + ``` |
| 49 | + Defines the wallet permission scope containing the recipient and the type of wallet operations they can perform. |
| 50 | + |
| 51 | +- ```diff |
| 52 | + + pub enum WalletScopeType { |
| 53 | + + Stake(WalletStake), |
| 54 | + + } |
| 55 | + ``` |
| 56 | + Specifies the type of wallet operations that can be delegated. Currently only supports stake operations, but designed to be extensible for future wallet operation types. |
| 57 | + |
| 58 | +- ```diff |
| 59 | + + pub struct WalletStake { |
| 60 | + + pub can_transfer_stake: bool, |
| 61 | + + pub exclusive_stake_access: bool, |
| 62 | + + } |
| 63 | + ``` |
| 64 | + Configuration for stake delegation permissions. `can_transfer_stake` allows transferring stake between validators, while `exclusive_stake_access` blocks the delegator from managing their own stake while the permission is active. |
| 65 | + |
| 66 | +- ```diff |
| 67 | + + pub enum WalletStakeOperation<T: Config> { |
| 68 | + + Unstake { staked: T::AccountId, amount: BalanceOf<T> }, |
| 69 | + + Transfer { from: T::AccountId, to: T::AccountId, amount: BalanceOf<T> }, |
| 70 | + + } |
| 71 | + ``` |
| 72 | + Specifies the stake operation to execute when calling `execute_wallet_stake_permission`. Supports unstaking from a validator or transferring stake between validators. |
| 73 | + |
| 74 | +- ```diff |
| 75 | + pub enum PermissionScope<T: Config> { |
| 76 | + Stream(StreamScope<T>), |
| 77 | + Curator(CuratorScope<T>), |
| 78 | + Namespace(NamespaceScope<T>), |
| 79 | + + Wallet(WalletScope<T>), |
| 80 | + } |
| 81 | + ``` |
| 82 | + Extended the permission scope enum to include the new `Wallet` variant for wallet operation delegations. |
| 83 | + |
| 84 | +### torus0 pallet |
| 85 | + |
| 86 | +- ```diff |
| 87 | + pub enum Error<T> { |
| 88 | + ... |
| 89 | + + StakeIsDelegated, |
| 90 | + } |
| 91 | + ``` |
| 92 | + New error returned when a user attempts to manage their stake directly while an exclusive wallet permission is active. |
| 93 | + |
| 94 | +## Behavior Changes |
| 95 | + |
| 96 | +### Wallet Stake Delegation |
| 97 | + |
| 98 | +**What changed**: A new permission system allows accounts to delegate their staking operations to trusted recipients. The delegator can grant permission to unstake tokens and optionally transfer stake between validators. When exclusive access is granted, the delegator cannot perform stake operations directly. |
| 99 | + |
| 100 | +**Why it matters**: This feature enables cold-hot wallet architectures where high-value accounts can remain offline while still participating in network staking. Cold wallets delegate staking management to hot wallets without exposing funds to transfer risks. If a hot wallet is compromised, attackers can only manage existing stakes, not drain accounts. |
| 101 | + |
| 102 | +**Migration needed**: No migration required. Existing staking operations continue to work normally unless users explicitly create wallet permissions. |
| 103 | + |
| 104 | +*Tests*: Tests validate permission creation, exclusive access enforcement, and proper execution of delegated operations. |
| 105 | +*Cross-pallet impact*: The torus0 pallet now checks for active wallet permissions before allowing direct stake operations, integrating with the permission0 pallet's wallet permission system. |
| 106 | + |
| 107 | +### Stake Operation Access Control |
| 108 | + |
| 109 | +**What changed**: The `remove_stake` and `transfer_stake` extrinsics in the torus0 pallet now check for exclusive wallet permissions before allowing operations. If an exclusive stake permission exists for the account, direct stake management is blocked with the `StakeIsDelegated` error. |
| 110 | + |
| 111 | +**Why it matters**: This ensures that when exclusive delegation is active, only the designated recipient can manage stakes, preventing conflicts between delegator and recipient operations and maintaining security guarantees. |
| 112 | + |
| 113 | +**Migration needed**: None. The check only applies to accounts that create exclusive wallet permissions. |
| 114 | + |
| 115 | +*Tests*: Integration tests verify that exclusive permissions properly block direct stake operations. |
| 116 | +*Cross-pallet impact*: Torus0 now depends on Permission0WalletApi trait to query active wallet permissions. |
| 117 | + |
| 118 | +### Permission System Extension |
| 119 | + |
| 120 | +**What changed**: The permission system's `PermissionScope` enum was extended with a `Wallet` variant, and the permission cleanup, revocation, and execution logic was updated to handle wallet permissions alongside existing stream, curator, and namespace permissions. |
| 121 | + |
| 122 | +**Why it matters**: The permission system is now more versatile, supporting not just emission and governance delegations but also operational delegations for wallet management. This creates a foundation for future wallet operation types beyond staking. |
| 123 | + |
| 124 | +**Migration needed**: The migration from v5 to v7 is already complete (spec 25). No additional migration needed for spec 26. |
| 125 | + |
| 126 | +*Tests*: Existing permission system tests extended to cover wallet permission lifecycle. |
| 127 | +*Cross-pallet impact*: All pallets using the permission system can now interact with wallet permissions through the unified API. |
0 commit comments