Skip to content

Commit 830543c

Browse files
nhussein11dawnkelly09
nhussein11
and
dawnkelly09
authored
Add guide for remote proxy implemention (#875)
* fix: wip * fix: adding remote proxy page * Apply suggestions from code review Co-authored-by: Dawn Kelly <[email protected]> * fresh llms --------- Co-authored-by: Dawn Kelly <[email protected]> Co-authored-by: DAWN KELLY <[email protected]>
1 parent 45017b5 commit 830543c

File tree

4 files changed

+399
-0
lines changed

4 files changed

+399
-0
lines changed

‎.snippets/code/develop/toolkit/parachains/remote-proxies/remote-proxy-example.js‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
import { ApiPromise, WsProvider } from '@polkadot/api';
2+
3+
// Account configuration - replace with your addresses
4+
const RECIPIENT_ACCOUNT = 'INSERT_RECIPIENT_ACCOUNT';
5+
const PROXIED_ACCOUNT = 'INSERT_PROXIED_ACCOUNT';
6+
7+
async function executeRemoteProxyTransaction() {
8+
try {
9+
// Establish connections to both chains
10+
console.log('Connecting to Kusama relay chain...');
11+
const kusamaProvider = new WsProvider(
12+
'wss://kusama.public.curie.radiumblock.co/ws',
13+
);
14+
const kusamaApi = await ApiPromise.create({ provider: kusamaProvider });
15+
16+
console.log('Connecting to Kusama Asset Hub...');
17+
const assetHubProvider = new WsProvider(
18+
'wss://kusama-asset-hub-rpc.polkadot.io',
19+
);
20+
const assetHubApi = await ApiPromise.create({ provider: assetHubProvider });
21+
22+
// Step 1: Generate storage key for proxy definition
23+
const proxyStorageKey = kusamaApi.query.proxy.proxies.key(PROXIED_ACCOUNT);
24+
console.log(`Proxy storage key: ${proxyStorageKey}`);
25+
26+
// Step 2: Identify latest recognized block
27+
const blockToRootMapping = JSON.parse(
28+
await assetHubApi.query.remoteProxyRelayChain.blockToRoot(),
29+
);
30+
const latestRecognizedBlock =
31+
blockToRootMapping[blockToRootMapping.length - 1][0];
32+
const blockHash = await kusamaApi.rpc.chain.getBlockHash(
33+
latestRecognizedBlock,
34+
);
35+
36+
console.log(`Generating proof for block ${latestRecognizedBlock}`);
37+
38+
// Step 3: Create storage proof
39+
const storageProof = JSON.parse(
40+
await kusamaApi.rpc.state.getReadProof([proxyStorageKey], blockHash),
41+
);
42+
43+
// Step 4: Define target transaction
44+
const targetTransaction = assetHubApi.tx.balances.transferAll(
45+
RECIPIENT_ACCOUNT,
46+
false,
47+
);
48+
49+
// Step 5: Construct remote proxy call
50+
const remoteProxyCall = assetHubApi.tx.remoteProxyRelayChain.remoteProxy(
51+
PROXIED_ACCOUNT,
52+
null, // Proxy type filter (null accepts any compatible type)
53+
targetTransaction.method,
54+
{
55+
RelayChain: {
56+
proof: storageProof.proof,
57+
block: latestRecognizedBlock,
58+
},
59+
},
60+
);
61+
62+
console.log('\n✅ Remote proxy transaction constructed successfully!');
63+
console.log('\n📋 Next steps:');
64+
console.log('1. Copy the URL below');
65+
console.log('2. Open in Polkadot.js Apps');
66+
console.log('3. Submit the transaction within 1 minute');
67+
console.log('\n🔗 Polkadot.js Apps URL:');
68+
console.log(
69+
`https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkusama-asset-hub-rpc.polkadot.io#/extrinsics/decode/${remoteProxyCall.method.toHex()}`,
70+
);
71+
72+
// Cleanup connections
73+
await kusamaApi.disconnect();
74+
await assetHubApi.disconnect();
75+
} catch (error) {
76+
console.error('❌ Remote proxy execution failed:', error.message);
77+
}
78+
}
79+
80+
// Execute the remote proxy workflow
81+
executeRemoteProxyTransaction();

‎develop/toolkit/parachains/.nav.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@ nav:
66
- fork-chains
77
- e2e-testing
88
- 'Light Clients': light-clients.md
9+
- 'Remote Proxies': remote-proxies.md
910
- 'RPC Calls': rpc-calls.md
1011
- 'Polkadot Omni Node': polkadot-omni-node.md

‎develop/toolkit/parachains/remote-proxies.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
title: Remote Proxies
3+
description: Remote proxies enable cross-chain proxy functionality within the Polkadot ecosystem, allowing proxy accounts defined on one chain to execute transactions on different chains through cryptographic storage proofs.
4+
---
5+
6+
# Remote Proxies
7+
8+
!!!warning "Kusama Implementation Only"
9+
Remote proxies are currently only available on Kusama and its parachains (such as Kusama Asset Hub). This feature is not yet deployed on Polkadot MainNet. The examples and implementations described in this guide are specific to the Kusama ecosystem.
10+
11+
## Introduction
12+
13+
Remote proxies enable cross-chain proxy functionality within the Polkadot ecosystem, allowing proxy accounts defined on one chain to execute transactions on different chains through cryptographic storage proofs. This functionality extends the traditional [proxy system](https://wiki.polkadot.com/learn/learn-proxies/){target=\_blank} beyond single-chain boundaries.
14+
15+
This guide covers:
16+
17+
- Understanding remote proxy mechanics and architecture.
18+
- Implementation workflow and timing constraints.
19+
- Practical examples using Polkadot.js.
20+
- Advanced use cases and security considerations.
21+
22+
Remote proxies are particularly valuable for maintaining unified security models across multiple parachains while avoiding the complexity of managing separate proxy setups on each chain.
23+
24+
!!!note "Traditional vs Remote Proxies"
25+
Traditional proxies work within a single chain, where both the proxy and proxied accounts exist on the same blockchain. Remote proxies extend this concept across chains, using cryptographic proofs to verify proxy relationships without requiring account replication.
26+
27+
## Remote Proxy Architecture
28+
29+
Remote proxies operate through a trust and verification model using storage proofs. The target chain verifies the existence of proxy relationships on the source chain without requiring direct replication of proxy data.
30+
31+
```mermaid
32+
flowchart LR
33+
RC([Relay Chain])-- Proxy Definition -->AH([Asset Hub])
34+
RC -- Storage Proof --> AH
35+
AH -- Verify Proof --> TX([Execute Transaction])
36+
AH -- Trust Relationship --> RC
37+
```
38+
39+
In this architecture, Asset Hub trusts proxy definitions from the Relay Chain. When a remote proxy transaction is initiated, Asset Hub verifies the storage proof against its stored block roots from the Relay Chain, ensuring the proxy relationship is authentic and current.
40+
41+
The verification process utilizes [Merkle proofs](/polkadot-protocol/glossary/#trie-patricia-merkle-tree){target=\_blank} to confirm proxy permissions exist on the source chain at a specific block height.
42+
43+
!!!note "What makes remote proxies secure?"
44+
Remote proxies maintain security through cryptographic storage proofs that cannot be forged. The target chain verifies these proofs against trusted block roots, ensuring proxy relationships are authentic without requiring blind trust in external nodes.
45+
46+
## Implementation Workflow
47+
48+
Remote proxy execution follows a time-constrained workflow requiring coordination between multiple chains. The remote proxy workflow consists of several critical steps that must be completed within a narrow time window.
49+
50+
1. **Block Synchronization**: Query the target chain for recognized source chain blocks.
51+
2. **Storage Proof Creation**: Generate cryptographic proof of proxy relationship.
52+
3. **Transaction Construction**: Build the wrapped transaction with proof data.
53+
4. **Execution**: Submit the transaction before proof expiration.
54+
55+
Remote proxies operate under strict timing limitations.
56+
57+
- **Proof Validity**: Storage proofs expire after approximately **1 minute**.
58+
- **Block Recognition**: Target chains maintain only recent source chain block roots.
59+
- **Execution Window**: Transactions must be submitted immediately after proof generation.
60+
61+
These constraints exist to prevent replay attacks and ensure proof freshness while maintaining system security.
62+
63+
| Constraint Type | Duration | Purpose |
64+
| :-------------: | :------: | :-----: |
65+
| Proof Validity | ~1 minute | Prevent replay attacks |
66+
| Block Storage | ~10 minutes | Balance security and usability |
67+
| Execution Window | Immediate | Ensure proof freshness |
68+
69+
## Practical Implementation
70+
71+
### Prerequisites
72+
73+
Before implementing remote proxies, ensure you have:
74+
75+
- Active proxy relationship on the source chain (Kusama).
76+
- Access to both source and target chain RPC endpoints.
77+
- Compatible proxy types between chains.
78+
- Node.js environment for script execution.
79+
80+
### Installation and Setup
81+
82+
To implement remote proxies, you need to install the [`@polkadot/api`](/develop/toolkit/api-libraries/polkadot-js-api/){target=\_blank} package and create a script to execute the remote proxy transaction:
83+
84+
```bash
85+
pnpm add @polkadot/api
86+
```
87+
88+
Create your implementation script:
89+
90+
```bash
91+
touch remote-proxy-example.js
92+
```
93+
94+
### Implementation Example
95+
96+
Here is a complete implementation example of a remote proxy transaction:
97+
98+
```javascript title="remote-proxy-example.js"
99+
--8<-- "code/develop/toolkit/parachains/remote-proxies/remote-proxy-example.js"
100+
```
101+
102+
Ensure to replace the `RECIPIENT_ACCOUNT` and `PROXIED_ACCOUNT` with your accounts. For a concrete example, check out the [Sending a remote proxy transaction via Polkadot-JS](https://blog.kchr.de/polkadot/guides/remote-proxies-for-the-braves/#sending-a-remote-proxy-transaction-via-polkadot-js){target=\_blank} section in the Remote Proxies article.
103+
104+
The code snippet above is a complete implementation example of a remote proxy transaction. It demonstrates how to:
105+
106+
- **Storage Key Generation**: The `proxyStorageKey` identifies where proxy relationship data is stored on Kusama. This key is used to create a proof that the relationship exists.
107+
- **Block Synchronization**: Asset Hub maintains a mapping of recent Kusama block numbers to their storage roots to enable proof verification without requiring full blockchain synchronization.
108+
- **Proof Creation**: The `getReadProof` RPC call generates a cryptographic proof that specific data exists in Kusama's state at a given block height.
109+
- **Transaction Wrapping**: The target transaction is wrapped within a `remoteProxy` call that includes both the proof data and the block anchor.
110+
111+
## Resources
112+
113+
- **[Remote Proxies for Braves](https://blog.kchr.de/polkadot/guides/remote-proxies-for-the-braves){target=\_blank}**
114+
- **[Ecosystem Proxy](https://blog.kchr.de/ecosystem-proxy/){target=\_blank}**
115+
- **[RFC: Pure Proxy Replication](https://github.com/polkadot-fellows/RFCs/pull/111){target=\_blank}**
116+
- **[Learn Proxies](https://wiki.polkadot.com/learn/learn-proxies/){target=\_blank}**

0 commit comments

Comments
 (0)