Skip to content

Commit 18d6c48

Browse files
saiintbrissonsaiintbrisson
committed
chore: preparing for 23 release
1 parent 597cd62 commit 18d6c48

File tree

5 files changed

+269
-116
lines changed

5 files changed

+269
-116
lines changed

‎CHANGELOG.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,132 @@
11
# Changelog
22

3+
## Spec 23
4+
5+
This release builds upon the permission delegation system with enhanced re-delegation capabilities, enabling more sophisticated hierarchical permission structures for curators and namespace management.
6+
7+
### Major Features
8+
9+
#### Curator Re-delegation
10+
11+
Curators can now re-delegate their permissions to other agents, creating a hierarchical permission structure:
12+
13+
- The implementation tracks parent-child relationships between permissions and enforces inheritance rules where child permissions cannot exceed parent permission scopes.
14+
- Enables more flexible governance structures where curators can delegate specific subsets of their permissions to trusted agents, creating delegation chains.
15+
- Particularly useful for scaling curator operations and distributing workload while maintaining accountability through the permission hierarchy.
16+
- Existing curator permissions are automatically migrated to the new structure with their flags mapped to a single entry with no parent permission ID.
17+
18+
#### Namespace Re-delegation
19+
20+
Added support for namespace permission re-delegation with depth limiting:
21+
22+
- Agents can now delegate namespace permissions they've received to other agents, creating delegation chains up to 5 levels deep.
23+
- The system validates that child namespace paths exist and are properly owned before allowing delegation.
24+
- Allows namespace owners to create more complex delegation structures for namespace management.
25+
- Organizations can delegate namespace control to team leads who can further delegate to team members, enabling hierarchical namespace administration.
26+
- No migration needed for existing namespace permissions as they remain compatible with the new system.
27+
28+
#### Permission Instance Tracking
29+
30+
All permission types now support instance tracking through the instances parameter:
31+
32+
- Allows delegators to specify how many times a permission can be used concurrently, providing better control over permission usage.
33+
- Prevents permission abuse by limiting concurrent usage and provides better resource management for delegated operations.
34+
- Particularly important for curator and namespace permissions where parallel operations could cause conflicts.
35+
- Existing permissions are migrated with a default instance count of 1, maintaining current behavior.
36+
37+
### Infrastructure Changes
38+
39+
#### Storage Migration v5
40+
41+
Migrated the CuratorScope structure to support the new hierarchical permission model:
42+
43+
- The migration transforms the flat CuratorPermissions flags into a BoundedBTreeMap structure where existing permissions are mapped with no parent permission ID.
44+
- Ensures backward compatibility while enabling the new curator re-delegation features.
45+
- All existing curator permissions continue to work as before while gaining the ability to be re-delegated.
46+
- The migration runs automatically during runtime upgrade and is transparent to other pallets.
47+
48+
### Configuration Updates
49+
50+
- Added MaxCuratorSubpermissionsPerPermission parameter to limit the number of curator sub-permissions that can be delegated in a single permission contract (set to 16).
51+
- Added new error types to handle curator permission limits and namespace delegation depth restrictions.
52+
53+
This release enhances the permission system's flexibility while maintaining security through proper validation and depth limiting, enabling more sophisticated governance and namespace management structures.
54+
55+
## Spec 22
56+
57+
This release introduces a major redesign of the permission system from a grant-based to a delegation-based model, along with significant improvements to staking, agent registration, and emission distribution.
58+
59+
### Major Features
60+
61+
#### Permission Delegation System Redesign
62+
63+
The entire permission system has been redesigned around delegation rather than granting:
64+
65+
- All functions, events, and storage items renamed from "grant/grantor/grantee" to "delegate/delegator/recipient" terminology.
66+
- Better reflects the actual relationship between participants - one party delegates authority to another rather than simply granting permissions.
67+
- Improves the mental model for developers and users interacting with the permission system.
68+
- All client applications must update their calls to use the new extrinsic names and parameter names.
69+
70+
#### Hierarchical Namespace Permissions
71+
72+
Namespace permissions now support hierarchical delegation through a parent-child relationship system:
73+
74+
- The NamespaceScope structure changed from a simple set of paths to a map of parent permission IDs to path sets.
75+
- Permission contracts now track children and have instance limits.
76+
- Enables sophisticated permission delegation chains where a recipient of namespace permissions can re-delegate subsets of those permissions to other parties.
77+
- The instance system prevents over-delegation by limiting how many active delegations can exist from a single permission.
78+
79+
#### Staking System Overhaul
80+
81+
The staking system now uses named reserves instead of withdrawing and issuing tokens:
82+
83+
- Stakes are tracked using the Balances pallet's named reserve functionality with identifier "torstake".
84+
- Improves the economic model by ensuring staked tokens remain as part of the staker's balance but are properly reserved and cannot be spent.
85+
- Ensures the total issuance remains consistent and stakes are properly tracked by the underlying currency system.
86+
- The v6 migration automatically handles the conversion of existing stakes to the new reserve-based system.
87+
88+
#### Agent Registration Simplification
89+
90+
The register_agent extrinsic no longer takes a separate agent_key parameter:
91+
92+
- The agent key is now always the transaction signer.
93+
- The registration process also now checks for duplicate agent names in addition to duplicate keys.
94+
- Simplifies the registration process and ensures stronger consistency between the transaction signer and the registered agent.
95+
- Name uniqueness prevents confusion and impersonation attempts.
96+
97+
#### Enhanced Emission Distribution Tracking
98+
99+
The emission distribution system now emits more granular events:
100+
101+
- Individual EmissionDistribution events for each target and AccumulatedEmission events when tokens are accumulated for permissions.
102+
- Distribution functions now return DispatchResult and handle errors gracefully.
103+
- Provides better observability into the emission system, allowing external systems to track exactly how tokens flow through the network.
104+
- Error handling prevents the emission system from silently failing.
105+
106+
#### Whitelist-Based Consensus Participation
107+
108+
The emission system now considers agents to be eligible for consensus only if they are both registered and whitelisted:
109+
110+
- The registered field in ConsensusMemberInput was renamed to whitelisted to reflect this dual requirement.
111+
- Provides finer-grained control over network participation.
112+
- Allows the governance system to temporarily restrict agents from consensus without full deregistration.
113+
114+
#### Namespace Creation Event Granularity
115+
116+
Namespace creation and deletion now emit individual events for each namespace path rather than batch events:
117+
118+
- Provides more detailed tracking of namespace operations.
119+
- Better supports indexing and monitoring systems that need to track individual namespace state changes.
120+
- Applications listening to namespace events should expect multiple events per operation when multiple paths are involved.
121+
122+
### API Changes
123+
124+
- The Torus0Api stake_to method now returns DispatchResult instead of Result<(), Balance> for consistent error handling.
125+
- Added find_agent_by_name method to the Torus0Api to support name-based agent lookups.
126+
- Added agent_name method to NamespacePath to extract agent names from namespace paths.
127+
128+
This release represents a fundamental shift in how permissions are conceptualized and managed within the Torus Network, providing clearer semantics and more powerful delegation capabilities.
129+
3130
## Spec 21
4131

5132
This release introduces major architectural changes to enable decentralized economic relationships, improved governance flexibility, and preparation for off-chain service integration. The changes span several months of development focused on creating a more sophisticated and scalable network.

‎docs/changes/spec-23.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Runtime Spec Version 23 Changelog
2+
3+
This document details all runtime interface changes introduced in spec version 23.
4+
5+
## 1. Extrinsics
6+
7+
### permission0 pallet
8+
9+
- ```diff
10+
#[pallet::call_index(6)]
11+
pub fn delegate_curator_permission(
12+
origin: OriginFor<T>,
13+
recipient: T::AccountId,
14+
- flags: u32,
15+
+ flags: BoundedBTreeMap<
16+
+ Option<PermissionId>,
17+
+ u32,
18+
+ T::MaxCuratorSubpermissionsPerPermission,
19+
+ >,
20+
cooldown: Option<BlockNumberFor<T>>,
21+
duration: PermissionDuration<T>,
22+
revocation: RevocationTerms<T>,
23+
+ instances: u32,
24+
) -> DispatchResult
25+
```
26+
Modified the `delegate_curator_permission` extrinsic to support curator re-delegation. The `flags` parameter is now a map of optional parent permission IDs to permission flags, allowing delegated curators to further delegate specific permissions. Added `instances` parameter to control the number of permission instances that can be created. This enables hierarchical curator permission delegation with fine-grained control. See [Curator Re-delegation](#curator-re-delegation).
27+
28+
## 2. Events
29+
30+
No event changes in this version.
31+
32+
## 3. Storage Items
33+
34+
### permission0 pallet
35+
36+
- ```diff
37+
- const STORAGE_VERSION: StorageVersion = StorageVersion::new(4);
38+
+ const STORAGE_VERSION: StorageVersion = StorageVersion::new(5);
39+
```
40+
Storage version incremented from 4 to 5 due to structural changes in `CuratorScope`. Includes migration v5 to transform existing curator permissions into the new format with support for sub-delegations.
41+
42+
## 4. Structs & Enums
43+
44+
### permission0 pallet
45+
46+
- ```diff
47+
pub struct CuratorScope<T: Config> {
48+
- pub flags: CuratorPermissions,
49+
+ pub flags: BoundedBTreeMap<
50+
+ Option<PermissionId>,
51+
+ CuratorPermissions,
52+
+ T::MaxCuratorSubpermissionsPerPermission,
53+
+ >,
54+
pub cooldown: Option<BlockNumberFor<T>>,
55+
}
56+
```
57+
Modified `CuratorScope` to support hierarchical curator permissions. The `flags` field is now a map where each entry represents permissions that can be traced back to their parent permission ID, enabling curator re-delegation capabilities. See [Curator Re-delegation](#curator-re-delegation).
58+
59+
### permission0 pallet errors
60+
61+
- ```diff
62+
+ /// Too many curator permissions being delegated in a single permission.
63+
+ TooManyCuratorPermissions,
64+
+ /// Namespace delegation depth exceeded the maximum allowed limit.
65+
+ DelegationDepthExceeded,
66+
```
67+
Added new error types to handle curator permission limits and namespace delegation depth restrictions. These errors ensure the permission system remains manageable and prevents excessive nesting of delegations.
68+
69+
### permission0 pallet configuration
70+
71+
- ```diff
72+
+ /// Maximum number of curator subpermissions a single permission can delegate.
73+
+ #[pallet::constant]
74+
+ type MaxCuratorSubpermissionsPerPermission: Get<u32>;
75+
```
76+
Added configuration parameter to limit the number of curator sub-permissions that can be delegated in a single permission contract. Set to 16 in the runtime configuration.
77+
78+
## 5. Behavior Changes
79+
80+
### Curator Re-delegation
81+
82+
**What changed**: Curators can now re-delegate their permissions to other agents, creating a hierarchical permission structure. The implementation tracks parent-child relationships between permissions and enforces inheritance rules where child permissions cannot exceed parent permission scopes.
83+
84+
**Why it matters**: This enables more flexible governance structures where curators can delegate specific subsets of their permissions to trusted agents, creating delegation chains. This is particularly useful for scaling curator operations and distributing workload while maintaining accountability through the permission hierarchy.
85+
86+
**Migration needed**: Existing curator permissions are automatically migrated to the new structure with their flags mapped to a single entry with no parent permission ID.
87+
88+
*Tests*: See `pallets/permission0/tests/curator_tests.rs` for re-delegation scenarios.
89+
*Cross-pallet impact*: The governance pallet's curator operations now support hierarchical permission checking through the Permission0CuratorApi trait.
90+
91+
### Namespace Re-delegation
92+
93+
**What changed**: Added support for namespace permission re-delegation with depth limiting. Agents can now delegate namespace permissions they've received to other agents, creating delegation chains up to 5 levels deep. The system validates that child namespace paths exist and are properly owned before allowing delegation.
94+
95+
**Why it matters**: This allows namespace owners to create more complex delegation structures for namespace management. Organizations can delegate namespace control to team leads who can further delegate to team members, enabling hierarchical namespace administration.
96+
97+
**Migration needed**: No migration needed for existing namespace permissions as they remain compatible with the new system.
98+
99+
*Tests*: See `pallets/permission0/tests/namespace_tests.rs` for namespace re-delegation scenarios.
100+
*Cross-pallet impact*: The torus0 pallet's namespace operations now check delegation depth through the Permission0NamespacesApi trait.
101+
102+
### Permission Instance Tracking
103+
104+
**What changed**: All permission types now support instance tracking through the `instances` parameter. This allows delegators to specify how many times a permission can be used concurrently, providing better control over permission usage.
105+
106+
**Why it matters**: This prevents permission abuse by limiting concurrent usage and provides better resource management for delegated operations. It's particularly important for curator and namespace permissions where parallel operations could cause conflicts.
107+
108+
**Migration needed**: Existing permissions are migrated with a default instance count of 1, maintaining current behavior.
109+
110+
*Tests*: See `pallets/permission0/tests/permission_tests.rs` for instance tracking validation.
111+
*Cross-pallet impact*: All pallets using the Permission0 API must now check available instances before executing permission-gated operations.
112+
113+
### Storage Migration v5
114+
115+
**What changed**: Migrated the `CuratorScope` structure to support the new hierarchical permission model. The migration transforms the flat `CuratorPermissions` flags into a `BoundedBTreeMap` structure where existing permissions are mapped with no parent permission ID.
116+
117+
**Why it matters**: This ensures backward compatibility while enabling the new curator re-delegation features. All existing curator permissions continue to work as before while gaining the ability to be re-delegated.
118+
119+
**Migration needed**: Automatic - the migration runs during runtime upgrade and transforms all existing curator permissions to the new format.
120+
121+
*Tests*: See `pallets/permission0/src/migrations.rs` for migration logic.
122+
*Cross-pallet impact*: None - the migration is transparent to other pallets.

0 commit comments

Comments
 (0)