Skip to content

Commit 984f552

Browse files
F-OBrienF-OBrien
committed
feat: add Polkadot SDK JSON-RPC methods documentation
1 parent d67d546 commit 984f552

File tree

2 files changed

+214
-19
lines changed

2 files changed

+214
-19
lines changed

‎docs/advanced/multichain/rpc-reference/polkadot-sdk-rpc.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
description: Polkadot SDK JSON-RPC Methods
3+
---
4+
5+
# Polkadot SDK
6+
7+
## polkadot_signTransaction
8+
9+
This method returns a signature for the provided transaction payload. It will be signed by the keypair corresponding to the requested signer address.
10+
11+
### Parameters
12+
13+
1. `Object` - Request parameters:
14+
- `address`: `string` - SS58 encoded address of the signer
15+
- `transactionPayload`: `Object` - As per Polkadot type `SignerPayloadJSON` containing:
16+
- `address`: `string` - The SS58 encoded address (must match outer address)
17+
- `assetId`: `HexString | null` - (optional) The id of the asset used to pay fees
18+
- `blockHash`: `HexString` - The checkpoint hash of the block, 32 bytes
19+
- `blockNumber`: `HexString` - The checkpoint block number (hex encoded)
20+
- `era`: `HexString` - The mortality period of this transaction
21+
- `genesisHash`: `HexString` - The genesis hash of the chain, 32 bytes
22+
- `metadataHash`: `HexString | null` - (optional) The hash of the metadata for verification
23+
- `method`: `string` - The SCALE encoded method data (hex encoded)
24+
- `mode`: `number` - (optional) The mode for metadata verification (0=none, 1=exact, 2=partial)
25+
- `nonce`: `HexString` - The nonce for this transaction (hex encoded)
26+
- `specVersion`: `HexString` - The current specification version (hex encoded)
27+
- `tip`: `HexString` - The tip for this transaction (hex encoded amount)
28+
- `transactionVersion`: `HexString` - The current transaction version (hex encoded)
29+
- `signedExtensions`: `string[]` - The array of signed extension identifiers
30+
- `version`: `number` - The extrinsic version number
31+
- `withSignedTransaction`: `boolean` - (optional) Request signed transaction bytes
32+
33+
### Returns
34+
35+
1. `Object` - Signature result:
36+
- `signature`: `string` - hex encoded signature
37+
38+
### Example
39+
40+
```javascript
41+
// Request
42+
{
43+
"id": 1,
44+
"jsonrpc": "2.0",
45+
"method": "polkadot_signTransaction",
46+
"params": {
47+
"address": "15UyNqZ7NB1QQVpY9xv7VGwkxtvXePKihFHx8kH4VgEcS1gU",
48+
"transactionPayload": {
49+
"address": "15UyNqZ7NB1QQVpY9xv7VGwkxtvXePKihFHx8kH4VgEcS1gU",
50+
"assetId": null,
51+
"blockHash": "0x1b1c32a33c3622044a3be1b7753ff9b24695c327fc9254f97c...",
52+
"blockNumber": "0x00000393",
53+
"era": "0x0500",
54+
"genesisHash": "0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3",
55+
"metadataHash": null,
56+
"method": "0x0400....",
57+
"mode": 0,
58+
"nonce": "0x00000000",
59+
"specVersion": "0x00000000",
60+
"tip": "0x00000000000000000000000000000000",
61+
"transactionVersion": "0x00000004",
62+
"signedExtensions": [
63+
"CheckNonZeroSender",
64+
"CheckSpecVersion",
65+
"CheckTxVersion",
66+
"CheckGenesis",
67+
"CheckMortality",
68+
"CheckNonce",
69+
"CheckWeight",
70+
"ChargeTransactionPayment"
71+
],
72+
"version": 4
73+
}
74+
}
75+
}
76+
77+
// Result
78+
{
79+
"id": 1,
80+
"jsonrpc": "2.0",
81+
"result": {
82+
"signature": "0x01234567..."
83+
}
84+
}
85+
```
86+
87+
Note: The `method` field in the transaction payload contains the SCALE encoded call data specific to the transaction being signed. This typically includes the pallet name, function name and any parameters required for that specific transaction.
88+
89+
## polkadot_signMessage
90+
91+
This method returns a signature for the provided message payload. It will be signed by the keypair corresponding to the requested signer address.
92+
93+
### Parameters
94+
95+
1. `Object` - As per Polkadot type `SignerPayloadRaw` containing:
96+
- `address`: `string` - SS58 encoded address
97+
- `data`: `string` - The hex-encoded data for this request
98+
- `type`: `'bytes' | 'payload'` - (optional) Identifies if the message is arbitrary bytes or a transaction payload
99+
100+
:::note
101+
`polkadot_signMessage` can potentially be used to sign arbitrary transactions blindly. To mitigate this security risk:
102+
103+
1. Always wrap messages in `<Bytes>message</Bytes>` tags before hex encoding when message `type` is `'bytes'` or not specified
104+
2. If the type is not `'payload'`, signers MUST verify that messages are properly wrapped
105+
3. Use `type: 'payload'` only when signing transaction-like data that should be possible to decrypt
106+
107+
This convention helps prevent malicious applications from using `polkadot_signMessage` for blind transaction signing while maintaining compatibility with widely-used Polkadot signing implementations.
108+
:::
109+
110+
### Returns
111+
112+
1. `Object` - Signature result:
113+
- `signature`: `string` - hex encoded signature
114+
115+
### Example
116+
117+
```javascript
118+
// Request
119+
{
120+
"id": 1,
121+
"jsonrpc": "2.0",
122+
"method": "polkadot_signMessage",
123+
"params": {
124+
"address": "15UyNqZ7NB1QQVpY9xv7VGwkxtvXePKihFHx8kH4VgEcS1gU",
125+
"data": "0x3c42797465733e68656c6c6f20776f726c643c2f42797465733e", // "<Bytes>hello world</Bytes>" hex encoded
126+
"type": "bytes"
127+
}
128+
}
129+
130+
// Result
131+
{
132+
"id": 1,
133+
"jsonrpc": "2.0",
134+
"result": {
135+
"signature": "0x6a98517e159dcaef1855cda5f5e5a61387ac3b63212b0f82642f5599502fc9eb1ea134e2db5dfbe0ec4530c6e7e576b177ad0618f68eaec37a3ac6dce819a30a"
136+
}
137+
}
138+
```

‎sidebars.js‎

Lines changed: 76 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -48,9 +48,10 @@ const advanced = {
4848
type: 'category',
4949
label: 'RPC Reference',
5050
items: [
51-
'advanced/multichain/rpc-reference/cosmos-rpc',
5251
'advanced/multichain/rpc-reference/ethereum-rpc',
5352
'advanced/multichain/rpc-reference/solana-rpc',
53+
'advanced/multichain/rpc-reference/polkadot-sdk-rpc',
54+
'advanced/multichain/rpc-reference/cosmos-rpc',
5455
'advanced/multichain/rpc-reference/near-rpc',
5556
'advanced/multichain/rpc-reference/starknet-rpc',
5657
'advanced/multichain/rpc-reference/stellar-rpc',
@@ -235,7 +236,7 @@ module.exports = {
235236
label: 'Features',
236237
collapsed: false,
237238
collapsible: true,
238-
link:{
239+
link: {
239240
type: 'doc',
240241
id: 'appkit/features/index'
241242
},
@@ -250,7 +251,11 @@ module.exports = {
250251
label: 'Telegram Mini Apps',
251252
id: 'appkit/features/telegram-mini-apps'
252253
},
253-
{ type: 'doc', label: 'Sponsored Transactions', id:'appkit/features/sponsored-transactions'}
254+
{
255+
type: 'doc',
256+
label: 'Sponsored Transactions',
257+
id: 'appkit/features/sponsored-transactions'
258+
}
254259
]
255260
},
256261
{
@@ -271,28 +276,64 @@ module.exports = {
271276
collapsible: true,
272277
items: [
273278
{ type: 'doc', label: 'Email & Social Login', id: 'appkit/authentication/socials' },
274-
{ type: 'doc', label: 'One-Click Auth', id: 'appkit/authentication/one-click-auth' },
279+
{
280+
type: 'doc',
281+
label: 'One-Click Auth',
282+
id: 'appkit/authentication/one-click-auth'
283+
},
275284
{
276285
type: 'doc',
277286
label: 'Sign in with X (SIWX)',
278287
id: 'appkit/features/siwx/default'
279-
},
288+
}
280289
]
281290
},
282291
{
283292
type: 'category',
284293
label: 'Recipes',
285-
collapsed:true,
294+
collapsed: true,
286295
collapsible: true,
287296
items: [
288-
{ type: 'doc', label: 'Build a Telegram Mini App', id: 'appkit/recipes/telegram-mini-app' },
289-
{ type: 'doc', label: 'Configure Virtual TestNets', id: 'appkit/recipes/tenderly-virtual-testnets'},
290-
{ type: 'doc', label: 'EVM Transactions using Wagmi', id: 'appkit/recipes/wagmi-send-transaction'},
291-
{ type: 'doc', label: 'EVM Transactions using Ethers', id: 'appkit/recipes/ethers-send-transaction'},
292-
{ type: 'doc', label: 'Solana Transactions using AppKit', id: 'appkit/recipes/solana-send-transaction'},
293-
{ type: 'doc', label: 'Bitcoin Transactions using AppKit', id: 'appkit/recipes/bitcoin-send-transaction'},
294-
{ type: 'doc', label: 'Support Send Calls', id: 'appkit/recipes/switching-to-send-calls' },
295-
{ type: 'doc', label: 'Sponsoring Transaction with our Paymaster', id: 'appkit/recipes/sponsoring-first-transaction' }
297+
{
298+
type: 'doc',
299+
label: 'Build a Telegram Mini App',
300+
id: 'appkit/recipes/telegram-mini-app'
301+
},
302+
{
303+
type: 'doc',
304+
label: 'Configure Virtual TestNets',
305+
id: 'appkit/recipes/tenderly-virtual-testnets'
306+
},
307+
{
308+
type: 'doc',
309+
label: 'EVM Transactions using Wagmi',
310+
id: 'appkit/recipes/wagmi-send-transaction'
311+
},
312+
{
313+
type: 'doc',
314+
label: 'EVM Transactions using Ethers',
315+
id: 'appkit/recipes/ethers-send-transaction'
316+
},
317+
{
318+
type: 'doc',
319+
label: 'Solana Transactions using AppKit',
320+
id: 'appkit/recipes/solana-send-transaction'
321+
},
322+
{
323+
type: 'doc',
324+
label: 'Bitcoin Transactions using AppKit',
325+
id: 'appkit/recipes/bitcoin-send-transaction'
326+
},
327+
{
328+
type: 'doc',
329+
label: 'Support Send Calls',
330+
id: 'appkit/recipes/switching-to-send-calls'
331+
},
332+
{
333+
type: 'doc',
334+
label: 'Sponsoring Transaction with our Paymaster',
335+
id: 'appkit/recipes/sponsoring-first-transaction'
336+
}
296337
]
297338
},
298339
{
@@ -310,7 +351,7 @@ module.exports = {
310351
label: 'Migration',
311352
collapsed: true,
312353
collapsible: true,
313-
link:{
354+
link: {
314355
type: 'doc',
315356
id: 'appkit/migration/index'
316357
},
@@ -419,7 +460,11 @@ module.exports = {
419460
{
420461
type: 'category',
421462
label: 'Transactions',
422-
items: ['appkit/react/transactions/onramp', 'appkit/react/transactions/swaps', 'appkit/react/transactions/sponsored-transactions']
463+
items: [
464+
'appkit/react/transactions/onramp',
465+
'appkit/react/transactions/swaps',
466+
'appkit/react/transactions/sponsored-transactions'
467+
]
423468
},
424469
{
425470
type: 'category',
@@ -518,7 +563,11 @@ module.exports = {
518563
{
519564
type: 'category',
520565
label: 'Transactions',
521-
items: ['appkit/next/transactions/onramp', 'appkit/next/transactions/swaps', 'appkit/next/transactions/sponsored-transactions']
566+
items: [
567+
'appkit/next/transactions/onramp',
568+
'appkit/next/transactions/swaps',
569+
'appkit/next/transactions/sponsored-transactions'
570+
]
522571
},
523572
{
524573
type: 'category',
@@ -614,7 +663,11 @@ module.exports = {
614663
{
615664
type: 'category',
616665
label: 'Transactions',
617-
items: ['appkit/vue/transactions/onramp', 'appkit/vue/transactions/swaps', 'appkit/vue/transactions/sponsored-transactions']
666+
items: [
667+
'appkit/vue/transactions/onramp',
668+
'appkit/vue/transactions/swaps',
669+
'appkit/vue/transactions/sponsored-transactions'
670+
]
618671
},
619672
{
620673
type: 'category',
@@ -710,7 +763,11 @@ module.exports = {
710763
{
711764
type: 'category',
712765
label: 'Transactions',
713-
items: ['appkit/javascript/transactions/onramp', 'appkit/javascript/transactions/swaps', 'appkit/javascript/transactions/sponsored-transactions']
766+
items: [
767+
'appkit/javascript/transactions/onramp',
768+
'appkit/javascript/transactions/swaps',
769+
'appkit/javascript/transactions/sponsored-transactions'
770+
]
714771
},
715772
{
716773
type: 'category',

0 commit comments

Comments
 (0)