Skip to content

Commit 57120e2

Browse files
SipherSipher
committed
Add Wallet Stake Permission explanations and create guide for setting it up in Torus Portal to improve documentation clarity
1 parent 5fc9ae2 commit 57120e2

File tree

3 files changed

+164
-0
lines changed

3 files changed

+164
-0
lines changed

‎astro.config.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ export default defineConfig({
4040
{ label: "Control Space", slug: "explanations/system/control-space" },
4141
{ label: "Permission System", slug: "explanations/system/permission-system" },
4242
{ label: "Recursive Delegation", slug: "explanations/system/recursive-delegation" },
43+
{ label: "Wallet Stake Permission", slug: "explanations/system/wallet-scope-delegation" },
4344
{ label: "Stream Permissions", slug: "explanations/system/stream-permissions" },
4445
{ label: "Capability Permissions", slug: "explanations/system/capability-permissions" },
4546
],
@@ -88,6 +89,7 @@ export default defineConfig({
8889

8990
{ label: "Create Capability Permission", slug: "how-to-guides/system/create-capability-permission" },
9091
{ label: "Create Stream Permission", slug: "how-to-guides/system/create-stream-permission" },
92+
{ label: "Create Wallet Stake Permission", slug: "how-to-guides/system/create-wallet-stake-permission" },
9193
{ label: "Manage Permissions", slug: "how-to-guides/system/manage-permissions" },
9294
],
9395
},

‎src/content/docs/explanations/system/wallet-scope-delegation.mdx‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: Wallet Stake Permission
3+
description: Understanding secure wallet staking permissions and delegation.
4+
---
5+
6+
import {
7+
Aside,
8+
Card,
9+
CardGrid,
10+
} from "@astrojs/starlight/components";
11+
12+
<Aside type="note" title="Version notice">
13+
This version is based on the Torus v0.69 and is expected to change with the Torus v1.
14+
</Aside>
15+
16+
The Wallet scope enables cold-hot wallet behavior, where high-value accounts can delegate specific
17+
operations to more accessible accounts without exposing private keys.
18+
This significantly improves security by allowing cold storage accounts to remain offline while still participating in network staking activities.
19+
20+
### Core Functions
21+
22+
* **Cold-Hot Wallet Architecture:** High-value accounts can delegate operational permissions while keeping primary keys in cold storage, eliminating the security-convenience tradeoff.
23+
* **Granular Operation Control:** Specific wallet operations can be delegated independently, allowing precise control over what delegated accounts can perform.
24+
* **Non-Transferable Delegation:** Delegated operations cannot access or transfer the principal funds, maintaining asset security even if hot wallets are compromised.
25+
26+
#### Rules
27+
28+
* **Operation Scoping:** Each delegation specifies exactly which wallet operations are permitted, preventing scope creep.
29+
* **Principal Protection:** Delegated accounts cannot perform operations that would reduce the principal balance or transfer core assets.
30+
* **Revocation Terms:** Can be configured as revocable or irrevocable.
31+
* **Constraint Inheritance:** Security constraints from the cold wallet apply to all delegated operations, ensuring consistent security policies.
32+
* **Time-bound Delegation:** Delegations can include expiration times for automatic security cleanup.
33+
34+
#### Active Delegation Behavior
35+
36+
When a wallet permission delegation is active, the delegator can choose the level of operational control:
37+
38+
* **Optional Exclusive Access:** The delegator can choose whether to retain direct control alongside the recipient through the exclusive access parameter
39+
* **Recipient Authority:** The designated recipient can perform the specific wallet operations covered by the permission
40+
* **Asset Constraints:** All operations are constrained to existing assets, meaning no new staking from available balance
41+
42+
### Related Concepts
43+
44+
- **[Permission System](https://docs.torus.network/explanations/system/permission-system/)** - Core permission mechanics and delegation basics
45+
- **[Recursive Delegation](https://docs.torus.network/explanations/system/recursive-delegation/)** - Advanced delegation patterns and composition
46+
- **[Staking](https://docs.torus.network/explanations/holders/staking/)** - Understanding staking mechanics and rewards
47+
48+
<Aside type="tip" title="Ready to Set Up Wallet Delegation?">
49+
Follow our [step-by-step guide to create wallet permissions](https://docs.torus.network/how-to-guides/system/create-wallet-permission/) for practical implementation instructions.
50+
</Aside>

‎src/content/docs/how-to-guides/system/create-wallet-stake-permission.mdx‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
title: Create Wallet Stake Permission
3+
description: Step-by-step guide to creating wallet stake permissions to delegate staking operations while keeping your keys secure.
4+
---
5+
6+
import {
7+
Steps,
8+
Aside,
9+
CardGrid,
10+
Card
11+
} from "@astrojs/starlight/components";
12+
13+
import RedText from '/src/components/RedText.astro';
14+
15+
In this guide, we'll walk through how to create wallet stake permissions in the Torus Portal.
16+
Wallet stake permissions enable cold-hot wallet behavior, allowing you to delegate staking operations
17+
to more accessible accounts while keeping your primary keys securely stored offline.
18+
19+
## Why Create Wallet Stake Permission?
20+
21+
You want to maintain high security for your primary wallet while still being able to manage staking operations efficiently.
22+
Wallet stake permissions let you delegate staking management to hot wallets without exposing your principal funds to transfer risks.
23+
24+
#### What we will accomplish
25+
26+
- [Create wallet stake permission](#create-wallet-stake-permission)
27+
28+
<Aside>
29+
⏱️ **Estimated time to complete this guide: 3 minutes**
30+
</Aside>
31+
32+
## Prerequisites
33+
34+
<CardGrid>
35+
<Card title="Wallet with Stake" icon="seti:license">
36+
You must have an account with existing stake that you want to delegate management for.
37+
Follow the [staking guide](https://docs.torus.network/how-to-guides/holders/stake-your-torus/) to understand staking basics.
38+
</Card>
39+
<Card title="Hot Wallet Account" icon="seti:pipeline">
40+
Know the address of the hot wallet account that will manage your staking operations.
41+
</Card>
42+
<Card title="Torus Balance" icon="seti:shell">
43+
Ensure you have enough TORUS to cover permission creation transaction fees.
44+
</Card>
45+
</CardGrid>
46+
47+
## Create Wallet Stake Permission
48+
49+
<Steps>
50+
51+
1. **Visit the [Wallet Permissions Tab in the Torus Portal](https://portal.torus.network/permissions/create-permission/wallet)**
52+
Click the <RedText variant="light">**Wallet Permission**</RedText> tab under Permissions in the Torus Portal.
53+
54+
2. **Connect your Cold Wallet**
55+
Ensure you're <RedText variant="light">connected with the wallet account</RedText> that holds the stakes you want to delegate management for.
56+
57+
3. **Fill the form**
58+
```md
59+
# Recipient Address
60+
Search agents by name or address that will receive the staking permission.
61+
If your target is not an agent, you can enter the wallet address directly.
62+
63+
# Stake Permissions
64+
- **Exclusive Delegation**: Grant exclusive access to stake operations
65+
(prevents delegator from using stake directly)
66+
- **Allow Stake Movement**: Delegate permission to unstake,
67+
exclusively granting it to the recipient
68+
69+
# Duration
70+
- **Indefinite**: Permission remains valid indefinitely
71+
- **Until Block**: Permission expires at a specific block
72+
73+
# Revocation Terms
74+
- **Irrevocable**: Cannot be revoked
75+
- **Revocable by Delegator**: Only you can revoke this permission
76+
- **Revocable After**: Can be revoked after a specific condition is met
77+
```
78+
79+
<Aside type="note">
80+
**Operation Constraints**
81+
All delegated operations are limited to existing stakes only. The recipient cannot:
82+
- Create new stakes from your available balance
83+
- Transfer your principal funds
84+
- Access non-staking wallet operations
85+
</Aside>
86+
87+
4. **Submit and Sign Transaction**
88+
Click <RedText variant="light">**Create Wallet Stake Permission**</RedText>.
89+
Open SubWallet and <RedText variant="light">sign the transaction</RedText>.
90+
91+
5. **All Done**
92+
You've successfully created the wallet stake permission.
93+
The receiving account can now manage your staking operations within the limits you've set.
94+
95+
</Steps>
96+
97+
## What's Next?
98+
99+
Now that you've created wallet stake permission, you might want to:
100+
101+
- **Monitor your delegations**: Track delegation status in the [Manage Permissions tab](https://portal.torus.network/permissions/manage-permission)
102+
- **Optimize your stakes**: Work with your hot wallet to [manage staking positions](https://docs.torus.network/how-to-guides/holders/stake-your-torus/) efficiently
103+
- **Understand COLD vs HOT Wallet**: Watch [this Coingecko video](https://www.youtube.com/watch?v=kf28zqP_F2s)
104+
105+
Connect with the community:
106+
- [Discord](https://discord.gg/torus) — Technical discussions, support, and announcements
107+
- [Telegram](https://t.me/torusnetwork) — General chat and announcements
108+
- [Twitter](https://x.com/torus_network) — Updates and ecosystem news
109+
110+
<Aside type="tip" title="Want to Learn More?">
111+
Learn about [wallet stake permission concepts](https://docs.torus.network/explanations/system/wallet-scope-delegation/) and the security benefits of cold-hot wallet architecture.
112+
</Aside>

0 commit comments

Comments
 (0)