pure proxies wip

chideraao · chideraao · commit 7b958cd3f4ae · 2025-09-30T19:16:40.000+01:00
diff --git a/docs/keys/proxies/create-proxy.md b/docs/keys/proxies/create-proxy.md
@@ -2,9 +2,23 @@
 toc_max_heading_level: 2
 ---
 
-# Create a Proxy in Bittensor
+# Create a Proxy Account
 
-This page describes creating and managing a proxy using the Polkadot.js web app. You will create a delegate account, add it as a proxy to your real account with a chosen `ProxyType`, and optionally use announcements for delayed execution.
+This tutorial walks you through creating a standard proxy and executing a call from the proxy account using the Polkadot.js web app. You will set up a delegate account, add it as a proxy to your real account with a chosen `ProxyType`, and optionally use announcements for delayed execution.
+
+---
+
+A standard proxy links a _delegator_ to a known account. The delegator specifies:
+
+- The _delegate_ account.
+- The allowed `ProxyType` (scope of permissions).
+- An optional delay.
+
+The delegate has access to funds in the real account and can then execute calls on behalf of the real account within the constraints of the specified `ProxyType`.
+
+:::info When to use standard proxies
+Delegating through a standard proxy is a good option when you want to entrust control to trusted individuals or organizations who can act on your behalf. In this setup, the delegate maintains their own independent signing capability, which allows them to initiate and authorize actions without relying on your key. This approach provides maximum operational flexibility while also making the delegate responsible for managing the security of their own keys.
+:::
 
 ## Prerequisites
 
@@ -32,12 +46,12 @@ If the web app does not connect to your local chain, your browser’s privacy or
 
 1. In the navbar menu, navigate to **Developers** → **Extrinsics**.
 2. Under “using the selected account”, pick the funded delegator account.
-3. Under “submit the following extrinsic”, choose the `proxy` pallete and call `addProxy(delegate, proxyType, delay)`.
+3. Under “submit the following extrinsic”, choose the `proxy` pallet and call `addProxy(delegate, proxyType, delay)`.
 4. Fill the parameters:
 
    - `delegate`: select the imported delegate account from the _Accounts_ dropdown.
    - `proxyType`: select `SmallTransfer`; this should allow us transfer amounts that do not exceed 0.5τ.
-   - `delay`: Optionally, include a delay in blocks.
+   - `delay`: optionally, include a delay in blocks.
 
 5. Click **Submit Transaction** and sign with the _delegator_ account.
 
@@ -74,6 +88,10 @@ This returns the set of proxies related to the account and their information—`
 
 The runtime verifies that the call is permitted by the proxy filter and that any delay requirements have been met, then dispatches the call as if signed by the Real account.
 
+:::info
+After submitting the transaction, check the Polkadot.JS web app's **Explorer** page for a `balances.Transfer` event. Notice the sender is the delegator account.
+:::
+
 :::warning
 
 - With the SmallTransfer proxy type, transfers are limited to less than 0.5 TAO (500,000,000 RAO). Use the Transfer proxy type for amounts above this limit.
@@ -93,7 +111,7 @@ Announcing a delayed proxy call requires the hash of the call that you intend to
 4. Fill the parameters:
    - `dest`: select the recipient account.
    - `value`: input the amount to be transferred in RAO—1 TAO = 1<sup>9</sup>RAO.
-5. Copy the hex code shown in the **encoded call data** field. You will use this to announce †he call in the next step.
+5. Copy the hex code shown in the **encoded call data** field. You will use this to announce the call in the next step.
 
 ---
 
@@ -165,3 +183,4 @@ After the announcement waiting period has passed, the delegate account can now e
 - `proxy.Unproxyable`/`system.CallFiltered`: The call is not permitted under the current `ProxyType`.
 - `proxy.TooMany`: You exceeded `MaxProxies` or `MaxPending`. Remove unused proxies/announcements.
 - `proxy.NotProxy`: Ensure you’re submitting from the delegate account and referencing the correct real account.
+- `Token.FundsUnavailable`: Ensure that your real account has enough available funds to cover the transaction.
diff --git a/docs/keys/proxies/index.md b/docs/keys/proxies/index.md
@@ -6,7 +6,7 @@ This page introduces the proxy pattern used in Bittensor and explains how it ena
 
 ## What is a proxy?
 
-Rather than using funds in a single account, smaller accounts with unique roles can complete tasks on behalf of the main stash account.
+Rather than using funds in a single account, accounts with unique roles can complete tasks on behalf of the main stash account.
 A proxy lets one account (the delegator, or "real" account) authorize another account (the delegate) to make permitted calls on its behalf. Proxies allow a delegator to keep their "real" accounts safe and "cold", thereby adding an extra layer of security to the tokens in the account.
 
 The permission scope is determined by the `ProxyType` call filter. This call filter allows the delegator account set the roles and limitations of the delegate account. Optionally, actions can require an on-chain announcement period—`delay`, giving the delegator time to reject a call made by a delegate.
@@ -17,7 +17,7 @@ The following concepts define how proxy relationships are set up and managed:
 
 - **Real account**: The account whose identity and funds are at stake.
 - **Delegate account**: The account with access to tokens in the real account and allowed to perform certain actions for the real account.
-- **ProxyType**: A capability profile that restricts which calls can be made by the delegate account.
+- **ProxyType**: A call filter that restricts which calls can be made by the delegate account.
 - **Delay/announcement**: Optional time window before a proxy action can be executed.
 
 ## Common use cases
@@ -72,7 +72,6 @@ The following table shows the available `ProxyType` options and their descriptio
 | `Registration`           | Allows registration-related operations.                                             |
 | `Transfer`               | Allows unrestricted transfer operations.                                            |
 | `SmallTransfer`          | Allows transfers capped at 0.5 TAO.                                                 |
-| `RootWeights`            | Deprecated.                                                                         |
 | `ChildKeys`              | Allows child key operations.                                                        |
 | `SudoUncheckedSetCode`   | Restricted to a single privileged call form.                                        |
 | `SwapHotkey`             | Allows hotkey swap operations.                                                      |
diff --git a/docs/keys/proxies/pure-proxies.md b/docs/keys/proxies/pure-proxies.md
@@ -0,0 +1,96 @@
+# Pure Proxies
+
+Pure proxies are a specialized type of proxy account in Bittensor that provide enhanced security and isolation for complex delegation scenarios. Unlike standard proxies that use existing accounts, pure proxies create new, keyless accounts that can only operate through their delegator relationship.
+
+This page walks you through creating a pure proxy account, executing a transfer through it, and eventually removing it using the Polkadot.js web app. You will set up a new delegate account, add it to your Polkadot.js accounts, and use it to execute transactions on the blockchain.
+
+## Overview of pure proxies
+
+Pure proxies are **keyless, non-deterministic accounts** that are created fresh using the `createPure` extrinsic. They represent a unique approach to account delegation where:
+
+- The proxy account has **no private key** and cannot sign transactions independently
+- The proxy can **only act through its delegator** - all operations must be initiated by the delegator
+- The account is **completely isolated** and cannot escalate its own permissions
+
+Unlike standard proxies, where the delegate can access the delegator’s funds to execute calls on their behalf, pure proxies operate differently. A pure proxy account must hold its own funds, while the real account acts as an _any proxy_ for it—signing and authorizing transactions on the proxy’s behalf.
+
+:::info when to use pure proxies
+Pure proxies are valuable when you want to keep your real account secure by reducing direct key exposure to the blockchain. They provide a keyless, flexible account that enables permissionless management and are especially effective for multisigs, since they allow updates to membership or thresholds without changing the account address.
+:::
+
+## Transaction flow in pure proxies
+
+All transactions involving a pure proxy must be signed by the delegator account. Once signed, the transaction is executed on-chain as if it originated directly from the pure proxy. Unlike standard proxies, a pure proxy must hold its own funds to cover fees or transfers. The delegator then acts as an _any proxy_, handling the signing and authorization of calls, but the balance used comes from the pure proxy's account.
+
+When submitting calls with the `proxy(real, forceProxyType, call)` extrinsic, the pure proxy account is passed as the `real` argument, while the delegator signs the transaction. This effectively reverses the usual proxy relationship where the proxy account only authorizes the transaction, while the real account appears as the origin on chain.
+
+:::info
+You can modify who signs for a pure proxy by assigning another account as its _any proxy_. This is done by executing a proxy call that creates a standard proxy with the `Any` proxy type. The new account can then sign on behalf of the pure proxy—for example, when updating signers in a multisig wallet.
+:::
+
+## Prerequisites
+
+- A locally running subtensor development chain. For more information, see [run a local Bittensor blockchain instance](../../local-build/deploy.md).
+- [Polkadot‑JS browser app](https://polkadot.js.org/apps/?#/explorer) connected to your local Bittensor instance and [Polkadot‑JS browser extension](https://chrome.google.com/webstore/detail/polkadot%7Bjs%7D-extension/mopnmbcafieddcagagdcbnhejhlodfdd) installed. For information on connecting the Polkadot-JS browser app to your local blockchain instance, see [Connect Polkadot to your local chain](./create-proxy.md#step-1-connect-polkadotjs-to-your-local-chain).
+- An accessible 'Alice' wallet. For more information, see [Provision Wallets for Local Deploy](../../local-build/provision-wallets).
+- At least 2 different accounts in your Polkadot-JS app:
+  - Real (delegator) account that controls funds and adds the proxy.
+  - A recipient account to receive transferred funds.
+
+## Create a pure proxy
+
+Use the `proxy::createPure` extrinsic to create a pure proxy as shown:
+
+1. In the navbar menu, navigate to **Developers** → **Extrinsics**.
+2. Under “using the selected account”, pick the delegator account.
+3. Under “submit the following extrinsic”, choose the `proxy` pallet and call `createPure(proxyType, delay, index)`.
+4. Fill the parameters:
+
+   - `proxyType`: select `SmallTransfer`; this should allow us transfer amounts that do not exceed 0.5τ.
+   - `delay`: optionally, include a delay in blocks.
+   - `index`: leave as zero.
+
+5. Click **Submit Transaction** and sign with the _delegator_ account.
+
+### Retrieve and import the proxy account
+
+1. After creating the pure proxy, go to **Network** → **Explorer** in the Polkadot-JS web app.
+2. On the **recent events** panel, find the `proxy.PureCreated` event from the transaction. This event shows details of the proxy created including the address of the newly spawned account.
+3. Copy the address of the proxy account.
+4. Go to **Accounts** → **Accounts**.
+5. Click **+ Proxied**.
+6. Paste the proxy account address in the **proxied account** field and then provide a name for the pure proxy account.
+
+Importing the proxy account makes it selectable in the Polkadot-JS web app UI.
+
+:::tip
+
+- Record the block number and extrinsic index where the pure proxy was created. These values are required when removing the proxy.
+- When creating a proxy on mainnet, you can check block details on the [Tao.app block explorer page](https://www.tao.app/blocks).
+
+:::
+
+## Executing calls via a pure proxy
+
+1. Go to **Developer** → **Extrinsics**.
+2. Under “using the selected account”, choose the delegate account—account that created the proxy.
+3. Select the `proxy` pallet and choose `proxy(real, forceProxyType, call)`.
+4. Fill the parameters:
+   - `real`: select the pure proxy account from the UI.
+   - `forceProxyType`: leave option unchecked.
+   - `call`: the call to be made by the delegate account. Fill the following parameters:
+     - Select the `balances` pallet and choose the `transferKeepAlive(dest, value)` extrinsic.
+     - `dest`: select the recipient account.
+     - `value`: input the amount to be transferred in RAO—1 TAO = 1<sup>9</sup>RAO.
+5. Click **Submit Transaction** and sign the transaction from the delegate account.
+
+:::info
+
+- After submitting the transaction, check the Polkadot.JS web app's **Explorer** page for a `balances.Transfer` event. Notice the sender is the pure proxy account.
+- Ensure the pure proxy account holds enough funds to cover both the transfer and associated fees.
+  :::
+
+## Troubleshooting
+
+- funds unavailable
+- cant sign with locked key pair: using pure proxy as signer
diff --git a/sidebars.js b/sidebars.js
@@ -47,7 +47,7 @@ const sidebars = {
       collapsed: true,
       items: [
         "learn/introduction",
-        "resources/questions-and-answers",        
+        "resources/questions-and-answers",
         "subnets/understanding-subnets",
         "learn/anatomy-of-incentive-mechanism",
 
@@ -90,22 +90,20 @@ const sidebars = {
           collapsible: true,
           collapsed: true,
           link: { type: "doc", id: "keys/proxies/index" },
-          items: ["keys/proxies/create-proxy"],
+          items: ["keys/proxies/create-proxy", "keys/proxies/pure-proxies"],
         },
         "keys/handle-seed-phrase",
         "keys/coldkey-hotkey-security",
         "keys/multisig",
         "keys/schedule-coldkey-swap",
-      },
+      ],
+    },
     {
       type: "category",
       label: "Research",
       collapsible: true,
       collapsed: true,
-      items: [
-      "research/synchronized-halving",
-        "research/halvings-problem",                
-      ],
+      items: ["research/synchronized-halving", "research/halvings-problem"],
     },
     {
       type: "category",
