Skip to content

Commit 395416d

Browse files
volivavoliva
committed
chore: referenda-sdk corrections
1 parent cdd0a15 commit 395416d

File tree

1 file changed

+40
-41
lines changed

1 file changed

+40
-41
lines changed

‎docs/pages/sdks/governance/referenda.md

Lines changed: 40 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,25 @@
11
# Referenda SDK
22

3-
The referenda SDK helps with the following:
3+
The Referenda SDK provides the following features:
44

5-
- Abstract over preimages
6-
- When creating a referendum, it will only create a preimage if it's required by length, significantly reducing deposit costs.
7-
- When reading from a referendum, it resolves the calldata regardless if it's a preimage or not.
8-
- Decide the best spender track for a referendum with a value.
9-
- Will always set the track to the appropriate value.
10-
- Approval / Support curves for tracks
11-
- Provides them as regular JS functions, useful to create charts.
12-
- Calculates the confirmation start/end given block number for the current results of a referendum.
5+
- Abstraction over Preimages
6+
- When creating a referendum, it only generates a preimage if required by the length, significantly reducing deposit costs.
7+
- When reading a referendum, it resolves the calldata regardless of whether it's a preimage or not.
8+
- Automatic Track Selection for Spender Referenda
9+
- Automatically selects the appropriate spender track for a referendum with a given value.
10+
- Approval/Support Curves for Tracks
11+
- Provides approval/support curves as regular JavaScript functions, useful for creating charts.
12+
- Calculates the confirmation start and end blocks based on the current referendum results.
1313

1414
## Getting Started
1515

16-
Install the governance sdk through your package manager:
16+
Install the governance SDK using your package manager:
1717

1818
```sh
1919
pnpm i @polkadot-api/sdk-governance
2020
```
2121

22-
Then create it passing in the `typedApi` for your chain
22+
Then, initialize it by passing in the `typedApi` for your chain:
2323

2424
```ts
2525
import { createReferendaSdk } from '@polkadot-api/sdk-governance';
@@ -28,30 +28,31 @@ import { getSmProvider } from 'polkadot-api/sm-provider';
2828
import { chainSpec } from 'polkadot-api/chains/polkadot';
2929
import { start } from 'polkadot-api/smoldot';
3030
import { createClient } from 'polkadot-api';
31-
31+
3232
const smoldot = start();
3333
const chain = await smoldot.addChain({ chainSpec });
34-
34+
3535
const client = createClient(getSmProvider(chain));
3636
const typedApi = client.getTypedApi(dot);
3737

3838
const referendaSdk = createReferendaSdk(typedApi);
3939
```
4040

41-
Different chains come with different spender track configurations, which unfortunately is not available on-chain, but rather as hard-coded values. By default, referenda SDK will use the values from polkadot, but other chains might have others. To use kusama, you can import the kusama configuration and pass it into the options parameter:
41+
Different chains have their own spender track configurations, which unfortunately are hard-coded and not available on-chain. By default, the Referenda SDK uses Polkadot's configuration. For Kusama, you can import the Kusama configuration and pass it into the options parameter:
4242

4343
```ts
4444
import { createReferendaSdk, kusamaSpenderOrigin } from '@polkadot-api/sdk-governance';
45+
4546
const referendaSdk = createReferendaSdk(typedApi, {
4647
spenderOrigin: kusamaSpenderOrigin
4748
});
4849
```
4950

50-
## Create a referendum
51+
## Creating a Referendum
5152

52-
There are many origins to choose when creating a referendum, each one have [specific purposes](https://wiki.polkadot.network/docs/learn-polkadot-opengov-origins#origins-and-tracks-info).
53+
There are multiple origins to choose from when creating a referendum, each with [specific purposes](https://wiki.polkadot.network/docs/learn-polkadot-opengov-origins#origins-and-tracks-info).
5354

54-
For creating a referendum that requires a treasury spend of a certain value, this Referenda SDK will choose the appropriate origin for you:
55+
For creating a referendum that requires a treasury spend, the SDK automatically selects the appropriate origin:
5556

5657
```ts
5758
const beneficiaryAddress = "………";
@@ -64,21 +65,21 @@ const callData = await spendCall.getEncodedData();
6465

6566
const tx = referendaSdk.createSpenderReferenda(callData, amount);
6667

67-
// Submitting the tx will create the referendum on-chain
68+
// Submitting the transaction will create the referendum on-chain
6869
const result = await tx.signAndSubmit(signer);
6970
const referendumInfo = referendaSdk.getSubmittedReferendum(result);
7071
if (referendumInfo) {
71-
console.log("Referendum ID: ", referendumInfo.index);
72-
console.log("Referendum Track: ", referendumInfo.track);
72+
console.log("Referendum ID:", referendumInfo.index);
73+
console.log("Referendum Track:", referendumInfo.track);
7374
}
7475
```
7576

76-
In cases where you are not using a spender track, then you will need to provide the origin:
77+
For non-spender referenda, you need to provide the origin:
7778

7879
```ts
7980
const remarkCall = typedApi.tx.System.remark({
80-
remark: Binary.fromText("Make polkadot even better")
81-
})
81+
remark: Binary.fromText("Make Polkadot even better")
82+
});
8283
const callData = await remarkCall.getEncodedData();
8384

8485
const tx = referendaSdk.createReferenda(
@@ -89,50 +90,48 @@ const tx = referendaSdk.createReferenda(
8990
const result = await tx.signAndSubmit(signer);
9091
const referendumInfo = referendaSdk.getSubmittedReferendum(result);
9192
if (referendumInfo) {
92-
console.log("Referendum ID: ", referendumInfo.index);
93-
console.log("Referendum Track: ", referendumInfo.track);
93+
console.log("Referendum ID:", referendumInfo.index);
94+
console.log("Referendum Track:", referendumInfo.track);
9495
}
9596
```
9697

97-
When creating a referendum, if the call is not too long it can be inlined in the same referendum submit call, otherwise it needs to be registered as a preimage.
98-
99-
The Referenda SDK for both cases (createReferenda and createSpenderReferenda) will inline the call as long as the call data falls within that limit, otherwise it will automatically create a batch call that will do both creating the preimage and submitting the referendum with the same transaction.
98+
When creating a referendum, if the call is short it can be inlined directly in the referendum submit call. Otherwise, it must be registered as a preimage. The SDK automatically handles this, inlining the call if possible or creating a batch transaction to register the preimage and submit the referendum with just one transaction.
10099

101-
## Get ongoing referenda
100+
## Fetching Ongoing Referenda
102101

103-
Referenda get mostly removed from chain once they are closed. Referenda SDK relies with on-chain data, so currently it will list the ongoing referenda from on-chain data.
102+
Closed referenda are mostly removed from the chain. The Referenda SDK lists ongoing referenda based from on-chain data:
104103

105104
```ts
106105
const referenda: Array<OngoingReferendum> = await referendaSdk.getOngoingReferenda();
107106
```
108107

109-
`OngoingReferendum` represents an ongoing referendum, and adds a few methods to work with it.
108+
`OngoingReferendum` provides helpful methods to interact with proposals.
110109

111110
First of all, the proposal on a referendum can be inlined or through a preimage. `OngoingReferendum` unwraps this to get the raw call data or even the decoded call data:
112111

113112
```ts
114-
console.log(referenda[0].proposal.rawValue) // PreimagesBounded
115-
console.log(await referenda[0].proposal.resolve()) // Binary with the call data
116-
console.log(await referenda[0].proposal.decodedCall()) // Decoded call data
113+
console.log(referenda[0].proposal.rawValue); // PreimagesBounded
114+
console.log(await referenda[0].proposal.resolve()); // Binary with the call data
115+
console.log(await referenda[0].proposal.decodedCall()); // Decoded call data
117116
```
118117

119-
It also adds a couple of functions to get the expected block this referendum will enter confirmation or finish confirmation:
118+
You can also check when the referendum enters or finishes the confirmation phase:
120119

121120
```ts
122-
console.log(await referenda[0].getConfirmationStart()) // number | null
123-
console.log(await referenda[0].getConfirmationEnd()) // number | null
121+
console.log(await referenda[0].getConfirmationStart()); // number | null
122+
console.log(await referenda[0].getConfirmationEnd()); // number | null
124123
```
125124

126-
Lastly, there is some useful information that's not available on-chain, but through the public forums (e.g. OpenGov or subsquare). To get the title of a referendum, the one you would see in either of the forums, you can use a [Subscan API Key](https://support.subscan.io) to fetch that information for you:
125+
Lastly, there is some useful information that's not available on-chain, but through the public forums (e.g. OpenGov or subsquare). To fetch this information, like the referendum title, you can use a [Subscan API Key](https://support.subscan.io):
127126

128127
```ts
129128
const apiKey = "………";
130-
console.log(await referenda[0].getDetails(apiKey)) // { title: string }
129+
console.log(await referenda[0].getDetails(apiKey)); // { title: string }
131130
```
132131

133-
## Get track details
132+
## Accessing Track Details
134133

135-
The track for a referendum is a runtime constant that contains the name and different values for the period and minimum approval and support curves.
134+
Referendum tracks are runtime constants with specific properties for periods, approval, and support curves.
136135

137136
This SDK enhances the track by adding some helper functions to easily work with the curves.
138137

0 commit comments

Comments
 (0)