diff --git a/astro.config.mjs b/astro.config.mjs index 41fd85f..a3c3256 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -40,6 +40,7 @@ export default defineConfig({ { label: "Control Space", slug: "explanations/system/control-space" }, { label: "Permission System", slug: "explanations/system/permission-system" }, { label: "Recursive Delegation", slug: "explanations/system/recursive-delegation" }, + { label: "Wallet Stake Permission", slug: "explanations/system/wallet-stake-permission" }, { label: "Stream Permissions", slug: "explanations/system/stream-permissions" }, { label: "Capability Permissions", slug: "explanations/system/capability-permissions" }, ], @@ -88,6 +89,7 @@ export default defineConfig({ { label: "Create Capability Permission", slug: "how-to-guides/system/create-capability-permission" }, { label: "Create Stream Permission", slug: "how-to-guides/system/create-stream-permission" }, + { label: "Create Wallet Stake Permission", slug: "how-to-guides/system/create-wallet-stake-permission" }, { label: "Manage Permissions", slug: "how-to-guides/system/manage-permissions" }, ], }, diff --git a/src/content/docs/explanations/system/wallet-stake-permission.mdx b/src/content/docs/explanations/system/wallet-stake-permission.mdx new file mode 100644 index 0000000..58a06e2 --- /dev/null +++ b/src/content/docs/explanations/system/wallet-stake-permission.mdx @@ -0,0 +1,41 @@ +--- +title: Wallet Stake Permission +description: Understanding secure wallet staking permissions and delegation. +--- + +import { + Aside, + Card, + CardGrid, +} from "@astrojs/starlight/components"; + + + +The Wallet Permission Scope will enable granular delegation of all wallet operations through the Torus Permission System. Currently, only Stake operations are implemented as low-hanging fruit for wallet security improvements. + +**Cold-Hot Key Behavior** + +The Wallet Stake Permission enables cold-hot wallet behavior, where high-value secured keys can delegate stake operations to less secure keys utilized only for active protocol participation. + +**Tool for Key Security** + +This feature also enables to create a highly secure offline cold-key that never interacts with any webapp and delegate Stake Permission as exclusive (delegator loses permission) & irrevocable to the new key. If your main key gets compromised the tokens cannot be unstaked and hence not transferred. +However, an attacker could attempt to immediately transfer as soon as you choose to unstake. But as long as staked, tokens are untouchable. + +It's not a perfect security feature and as standard practice it will eventually be replaced by Transfer Permissions, but it is a meaningful improvement and we recommend high-value keys to apply it. + +### Core Functions of Stake Permission +* **Exclusive Delegation** The delegator key loses the wallet permission. +* **Improved Key Security:** Enables cold-hotkey behavior. + +### Related Concepts + +- **[Permission System](https://docs.torus.network/explanations/system/permission-system/)** - Core permission mechanics and delegation basics +- **[Recursive Delegation](https://docs.torus.network/explanations/system/recursive-delegation/)** - Advanced delegation patterns and composition +- **[Staking](https://docs.torus.network/explanations/holders/staking/)** - Understanding staking mechanics and rewards + + diff --git a/src/content/docs/explanations/table-of-contents.mdx b/src/content/docs/explanations/table-of-contents.mdx index 07041c1..70808ac 100644 --- a/src/content/docs/explanations/table-of-contents.mdx +++ b/src/content/docs/explanations/table-of-contents.mdx @@ -25,6 +25,7 @@ Core system components and mechanisms: - [Control Space](https://docs.torus.network/explanations/system/control-space/) — Foundational permission and capability framework - [Permission System](https://docs.torus.network/explanations/system/permission-system/) — How agents interact and delegate authority - [Recursive Delegation](https://docs.torus.network/explanations/system/recursive-delegation/) — Specific capability delegation mechanisms +- [Wallet Stake Permission](https://docs.torus.network/explanations/system/wallet-stake-permission/) — Secure cold-hot wallet staking delegation - [Stream Permissions](https://docs.torus.network/explanations/system/emission-permissions/) — How emissions are allocated and controlled - [Capability Permissions](https://docs.torus.network/explanations/system/capability-permissions/) — Fine-grained access control for agent endpoints diff --git a/src/content/docs/how-to-guides/system/create-wallet-stake-permission.mdx b/src/content/docs/how-to-guides/system/create-wallet-stake-permission.mdx new file mode 100644 index 0000000..41ee08e --- /dev/null +++ b/src/content/docs/how-to-guides/system/create-wallet-stake-permission.mdx @@ -0,0 +1,112 @@ +--- +title: Create Wallet Stake Permission +description: Step-by-step guide to creating wallet stake permissions to delegate staking operations while keeping your keys secure. +--- + +import { + Steps, + Aside, + CardGrid, + Card +} from "@astrojs/starlight/components"; + +import RedText from '/src/components/RedText.astro'; + +In this guide, we'll walk through how to create wallet stake permissions in the Torus Portal. +Wallet stake permissions enable cold-hot wallet behavior, allowing you to delegate staking operations +to more accessible accounts while keeping your primary keys securely stored offline. + +## Why Create Wallet Stake Permission? + +You want to maintain high security for your primary wallet while still being able to manage staking operations efficiently. +Wallet stake permissions let you delegate staking management to hot wallets without exposing your principal funds to transfer risks. + +#### What we will accomplish + +- [Create wallet stake permission](#create-wallet-stake-permission) + + + +## Prerequisites + + + + You must have an account with existing stake that you want to delegate management for. + Follow the [staking guide](https://docs.torus.network/how-to-guides/holders/stake-your-torus/) to understand staking basics. + + + Know the address of the hot wallet account that will manage your staking operations. + + + Ensure you have enough TORUS to cover permission creation transaction fees. + + + +## Create Wallet Stake Permission + + + +1. **Visit the [Wallet Permissions Tab in the Torus Portal](https://portal.torus.network/permissions/create-permission/wallet)** + Click the **Wallet Permission** tab under Permissions in the Torus Portal. + +2. **Connect your Cold Wallet** + Ensure you're connected with the wallet account that holds the stakes you want to delegate management for. + +3. **Fill the form** + ```md + # Recipient Address + Search agents by name or address that will receive the staking permission. + If your target is not an agent, you can enter the wallet address directly. + + # Stake Permissions + - **Exclusive Delegation**: Grant exclusive access to stake operations + (prevents delegator from using stake directly) + - **Allow Stake Movement**: Delegate permission to unstake, + exclusively granting it to the recipient + + # Duration + - **Indefinite**: Permission remains valid indefinitely + - **Until Block**: Permission expires at a specific block + + # Revocation Terms + - **Irrevocable**: Cannot be revoked + - **Revocable by Delegator**: Only you can revoke this permission + - **Revocable After**: Can be revoked after a specific condition is met + ``` + + + +4. **Submit and Sign Transaction** + Click **Create Wallet Stake Permission**. + Open SubWallet and sign the transaction. + +5. **All Done** + You've successfully created the wallet stake permission. + The receiving account can now manage your staking operations within the limits you've set. + + + +## What's Next? + +Now that you've created wallet stake permission, you might want to: + +- **Monitor your delegations**: Track delegation status in the [Manage Permissions tab](https://portal.torus.network/permissions/manage-permission) +- **Optimize your stakes**: Work with your hot wallet to [manage staking positions](https://docs.torus.network/how-to-guides/holders/stake-your-torus/) efficiently +- **Understand COLD vs HOT Wallet**: Watch [this Coingecko video](https://www.youtube.com/watch?v=kf28zqP_F2s) + +Connect with the community: +- [Discord](https://discord.gg/torus) — Technical discussions, support, and announcements +- [Telegram](https://t.me/torusnetwork) — General chat and announcements +- [Twitter](https://x.com/torus_network) — Updates and ecosystem news + + \ No newline at end of file diff --git a/src/content/docs/how-to-guides/table-of-contents.mdx b/src/content/docs/how-to-guides/table-of-contents.mdx index 2cb0dec..bc19142 100644 --- a/src/content/docs/how-to-guides/table-of-contents.mdx +++ b/src/content/docs/how-to-guides/table-of-contents.mdx @@ -26,6 +26,7 @@ If you're managing permissions and system-level coordination: - [Create Capability Permission](https://docs.torus.network/how-to-guides/system/create-capability-permission/) — Delegate access to specific agent endpoints and services - [Create Stream Permission](https://docs.torus.network/how-to-guides/system/create-stream-permission/) — Share token emission streams with other agents +- [Create Wallet Stake Permission](https://docs.torus.network/how-to-guides/system/create-wallet-stake-permission/) — Enable secure cold-hot wallet staking delegation - [Manage Permissions](https://docs.torus.network/how-to-guides/system/manage-permissions/) — View, edit, and revoke existing permission delegations ---