Skip to content

Commit

Permalink
Merge remote-tracking branch 'origin/master' into nhussein11/tutorial…
Browse files Browse the repository at this point in the history 
…s-substrate-acquire-a-testnet-slot
  • Loading branch information
@eshaben
eshaben committed Sep 30, 2024
1 parent 4c67b3a commit a4ac880
Show file tree
Hide file tree
Showing 61 changed files with 1,534 additions and 232 deletions.
38 changes: 32 additions & 6 deletions .CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Contribute to the Polkadot Developer Docs

The documentation source files are written in [Markdown](https://daringfireball.net/projects/markdown) and generally follow the [PaperMoon style guide](https://github.com/papermoonio/documentation-style-guide/blob/main/style-guide.md). If the PaperMoon style guide does not provide explicit guidance on a particular subject, please default to the [Google developer documentation style guide](https://developers.google.com/style).
The documentation source files are written in [Markdown](https://daringfireball.net/projects/markdown) and generally follow the [PaperMoon style guide](https://github.com/papermoonio/documentation-style-guide/blob/main/style-guide.md). If the PaperMoon style guide doesn't provide explicit guidance on a particular subject, please default to the [Google developer documentation style guide](https://developers.google.com/style).

This guide covers how to contribute to the documentation, including serving a local version of the site, adding new pages and directories, managing images and code snippets, and a few SEO tips.

Expand All @@ -18,6 +18,7 @@ This guide covers how to contribute to the documentation, including serving a lo
- [Adding Code and Text Snippets](#adding-code-and-text-snippets)
- [Adding Images](#adding-images)
- [Optimizing for SEO](#search-enging-optimization-seo)
- [Tools for Editing](#tools-for-editing)

## Viewing Site Locally

Expand All @@ -27,9 +28,9 @@ You may want to spin up a local version of the documentation site to preview you

Building and serving the site requires cloning two repositories:

- **[Polkadot MkDocs](https://github.com/papermoonio/polkadot-mkdocs)** - contains the MkDocs config files, theme overrides, and custom CSS for the Polkadot documentation site
- **[Polkadot MkDocs](https://github.com/papermoonio/polkadot-mkdocs)** - contains the MkDocs configuration files, theme overrides, and custom CSS for the Polkadot documentation site

- **[Polkadot Docs](https://github.com/polkadot-developers/polkadot-docs)** - the actual content is stored in the polkadot-docs repo and pulled into the polkadot-mkdocs directory during build
- **[Polkadot Docs](https://github.com/polkadot-developers/polkadot-docs)** - the actual content is stored in the `polkadot-docs` repository and pulled into the `polkadot-mkdocs` directory during build

For everything to work correctly, the file structure needs to be as follows:

Expand Down Expand Up @@ -65,7 +66,7 @@ To set up the structure, follow these steps:

This command will install all dependencies listed in the `requirements.txt` file.

2. In the polkadot-mkdocs folder (which should be the current one), you can build the site by running:
2. In the `polkadot-mkdocs` folder (which should be the current one), you can build the site by running:

```bash
mkdocs serve
Expand Down Expand Up @@ -127,7 +128,7 @@ If you are adding pages to an existing section, the steps are simplified. Howeve
- Add the new markdown page to the appropriate section. Note that the filename becomes part of the URL for this page. See the [style guide](https://github.com/papermoonio/documentation-style-guide/blob/main/style-guide.md#naming-conventions) for additional guidance on naming conventions.
- Ensure the new content page includes the following:
- **`title`** - represents the `<title>` tag and is used for SEO purposes (not displayed on the published site) Titles have a maximum length of 45 characters.
- **`description`** - represents the meta-description and is also used for SEO purposes (not displayed on the published site). Descriptions should be between 120-160 characters and should provide a preview into the page topic.
- **`description`** - represents the meta-description and is also used for SEO purposes (not displayed on the published site). Descriptions should be 120-160 characters and should provide a preview into the page topic.
- **Page title** - an H1 heading title to be displayed at the top of the page
- **`## Checking Prerequisites` section** - if the guide requires the user to have specific developer tools installed, for example, Docker or MetaMask, it should be listed here
Expand Down Expand Up @@ -168,7 +169,7 @@ More resources for [SEO Optimization](#search-engine-optimization-seo) of titles
3. Once you commit and push all of your changes, open a pull request for the new content branch against the `main` branch
4. Monitor notifications and pull requests for feedback from code owners. At least one approval is required before merging content
If your additions or modifications are limited to content on an existing page, there is no need to worry about the [`.pages`](#example-pages-file) or [`index.md`](#example-indexmd-file) files, as changes to page content do not affect these files.
If your additions or modifications are limited to content on an existing page, there is no need to worry about the [`.pages`](#example-pages-file) or [`index.md`](#example-indexmd-file) files, as changes to page content don't affect these files.

## Adding Code and Text Snippets

Expand Down Expand Up @@ -208,3 +209,28 @@ Here are some resources to help you create good titles and descriptions for SEO:
- [Google's recommendation on good descriptions](https://developers.google.com/search/docs/advanced/appearance/snippet?hl=en)

In general, titles should be between 50 and 60 characters and descriptions should be between 120 and 160 characters.

## Tools for Editing

There are a few tools you may find useful for proofreading and editing your contributions:

- **[Vale](https://vale.sh/)** - the `polkadot-mkdocs` repository contains configuration for Vale, an open source NLP-powered linter for text. The configuration is a work in progress with a growing custom dictionary tailored toward software engineering, blockchain, and Polkadot terms. Running Vale against your files locally can serve as a first round of feedback to speed up the review process

To use Vale locally to screen your work:

1. Visit the Vale site and follow the [installation instructions](https://vale.sh/docs/vale-cli/installation/)
2. From the `polkadot-mkdocs` directory, run the following in your terminal:

```bash
vale INSERT_PATH_TO_FILE
```

The output will look something like:

![Vale sample terminal output](images/contributing/vale-output-01.webp)

3. You can use CMD+click to open the file with the flagged items. This is especially helpful if you run Vale against a directory with multiple files

4. Each flag tells you the line and location of the flagged item, the level of the flag (error, warning, or suggestion), and a suggestion for how to resolve the flag

5. Once you have addressed the flagged items and made edits as needed, you can complete the normal steps to commit your changes and open a pull request to review for merge
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
node_modules
11 changes: 11 additions & 0 deletions .husky/pre-commit
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

echo "Running Prettier on .snippets/code/**/*.{js,json,html}"
npx prettier --write .snippets/code/**/*.{js,json,html}

echo "Running Taplo to format TOML files"
npx taplo fmt .snippets/code/**/*.toml

echo "Adding formatted files back to the commit..."
git add .snippets/code/**/*.{js,json,html,toml}
24 changes: 24 additions & 0 deletions ...evelop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<div id="termynal" data-termynal>
<span data-ty="input"><span class="file-path"></span>ts-node localParachainTx.ts</span>
<br>
<span data-ty>Call data:</span>
<span data-ty>{</span>
<span data-ty> "origin": "moonbeam",</span>
<span data-ty> "dest": "moonbeam",</span>
<span data-ty> "direction": "local",</span>
<span data-ty> "xcmVersion": null,</span>
<span data-ty> "method": "balances::transferKeepAlive",</span>
<span data-ty> "format": "call",</span>
<span data-ty> "tx": "0x0a03f977814e90da44bfa03b6295a0616a897441acec821a0600"</span>
<span data-ty>}</span>
<span data-ty></span>
<span data-ty>Decoded tx:</span>
<span data-ty>{</span>
<span data-ty> "args": {</span>
<span data-ty> "dest": "0xF977814e90dA44bFA03b6295A0616a897441aceC",</span>
<span data-ty> "value": "1,000,000,000,000,000,000"</span>
<span data-ty> },</span>
<span data-ty> "method": "transferKeepAlive",</span>
<span data-ty> "section": "balances"</span>
<span data-ty>}</span>
</div>
37 changes: 37 additions & 0 deletions ...ets/code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.ts
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
import {
AssetTransferApi,
constructApiPromise,
} from "@substrate/asset-transfer-api";

async function main() {
const { api, specName, safeXcmVersion } = await constructApiPromise(
"wss://wss.api.moonbeam.network"
);
const assetApi = new AssetTransferApi(api, specName, safeXcmVersion);

let callInfo;
try {
callInfo = await assetApi.createTransferTransaction(
"2004",
"0xF977814e90dA44bFA03b6295A0616a897441aceC",
[],
["1000000000000000000"],
{
format: "call",
keepAlive: true,
}
);

console.log(`Call data:\n${JSON.stringify(callInfo, null, 4)}`);
} catch (e) {
console.error(e);
throw Error(e as string);
}

const decoded = assetApi.decodeExtrinsic(callInfo.tx, "call");
console.log(`\nDecoded tx:\n${JSON.stringify(JSON.parse(decoded), null, 4)}`);
}

main()
.catch((err) => console.error(err))
.finally(() => process.exit());
87 changes: 87 additions & 0 deletions ...code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
<div id='termynal' data-termynal>
<span data-ty='input'><span class='file-path'></span>ts-node paraToPara.ts</span>

<br>
<span data-ty>Call data:</span>
<span data-ty>{</span>
<span data-ty> "origin": "moonriver",</span>
<span data-ty> "dest": "bifrost",</span>
<span data-ty> "direction": "ParaToPara",</span>
<span data-ty> "xcmVersion": 2,</span>
<span data-ty> "method": "transferMultiassets",</span>
<span data-ty> "format": "call",</span>
<span data-ty> "tx": "0x6a05010800010200451f06080101000700e40b540200010200451f0608010a0002093d000000000001010200451f0100c4db7bcb733e117c0b34ac96354b10d47e84a006b9e7e66a229d174e8ff2a06300"</span>
<span data-ty>}</span>
<span data-ty></span>
<span data-ty>Decoded tx:</span>
<span data-ty>{</span>
<span data-ty> "args": {</span>
<span data-ty> "assets": {</span>
<span data-ty> "V2": [</span>
<span data-ty> {</span>
<span data-ty> "id": {</span>
<span data-ty> "Concrete": {</span>
<span data-ty> "parents": "1",</span>
<span data-ty> "interior": {</span>
<span data-ty> "X2": [</span>
<span data-ty> {</span>
<span data-ty> "Parachain": "2,001"</span>
<span data-ty> },</span>
<span data-ty> {</span>
<span data-ty> "GeneralKey": "0x0101"</span>
<span data-ty> }</span>
<span data-ty> ]</span>
<span data-ty> }</span>
<span data-ty> }</span>
<span data-ty> },</span>
<span data-ty> "fun": {</span>
<span data-ty> "Fungible": "10,000,000,000"</span>
<span data-ty> }</span>
<span data-ty> },</span>
<span data-ty> {</span>
<span data-ty> "id": {</span>
<span data-ty> "Concrete": {</span>
<span data-ty> "parents": "1",</span>
<span data-ty> "interior": {</span>
<span data-ty> "X2": [</span>
<span data-ty> {</span>
<span data-ty> "Parachain": "2,001"</span>
<span data-ty> },</span>
<span data-ty> {</span>
<span data-ty> "GeneralKey": "0x010a"</span>
<span data-ty> }</span>
<span data-ty> ]</span>
<span data-ty> }</span>
<span data-ty> }</span>
<span data-ty> },</span>
<span data-ty> "fun": {</span>
<span data-ty> "Fungible": "1,000,000"</span>
<span data-ty> }</span>
<span data-ty> }</span>
<span data-ty> ]</span>
<span data-ty> },</span>
<span data-ty> "fee_item": "0",</span>
<span data-ty> "dest": {</span>
<span data-ty> "V2": {</span>
<span data-ty> "parents": "1",</span>
<span data-ty> "interior": {</span>
<span data-ty> "X2": [</span>
<span data-ty> {</span>
<span data-ty> "Parachain": "2,001"</span>
<span data-ty> },</span>
<span data-ty> {</span>
<span data-ty> "AccountId32": {</span>
<span data-ty> "network": "Any",</span>
<span data-ty> "id": "0xc4db7bcb733e117c0b34ac96354b10d47e84a006b9e7e66a229d174e8ff2a063"</span>
<span data-ty> }</span>
<span data-ty> }</span>
<span data-ty> ]</span>
<span data-ty> }</span>
<span data-ty> }</span>
<span data-ty> },</span>
<span data-ty> "dest_weight_limit": "Unlimited"</span>
<span data-ty> },</span>
<span data-ty> "method": "transferMultiassets",</span>
<span data-ty> "section": "xTokens"</span>
<span data-ty>}</span>
</div>
36 changes: 36 additions & 0 deletions .snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.ts
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
import {
AssetTransferApi,
constructApiPromise,
} from "@substrate/asset-transfer-api";

async function main() {
const { api, specName, safeXcmVersion } = await constructApiPromise(
"wss://moonriver.public.blastapi.io"
);
const assetApi = new AssetTransferApi(api, specName, safeXcmVersion);
let callInfo;
try {
callInfo = await assetApi.createTransferTransaction(
"2001",
"0xc4db7bcb733e117c0b34ac96354b10d47e84a006b9e7e66a229d174e8ff2a063",
["vMOVR", "72145018963825376852137222787619937732"],
["1000000", "10000000000"],
{
format: "call",
xcmVersion: safeXcmVersion,
}
);

console.log(`Call data:\n${JSON.stringify(callInfo, null, 4)}`);
} catch (e) {
console.error(e);
throw Error(e as string);
}

const decoded = assetApi.decodeExtrinsic(callInfo.tx, "call");
console.log(`\nDecoded tx:\n${JSON.stringify(JSON.parse(decoded), null, 4)}`);
}

main()
.catch((err) => console.error(err))
.finally(() => process.exit());
62 changes: 62 additions & 0 deletions ...e/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
<div id="termynal" data-termynal>
<span data-ty="input"><span class="file-path"></span>ts-node relayToSystem.ts</span>
<br>
<span data-ty>Call data:</span>
<span data-ty>{</span>
<span data-ty> "origin": "westend",</span>
<span data-ty> "dest": "westmint",</span>
<span data-ty> "direction": "RelayToSystem",</span>
<span data-ty> "xcmVersion": 3,</span>
<span data-ty> "method": "transferAssets",</span>
<span data-ty> "format": "call",</span>
<span data-ty> "tx": "0x630b03000100a10f03000101006c0c32faf970eacb2d4d8e538ac0dab3642492561a1be6f241c645876c056c1d030400000000070010a5d4e80000000000"</span>
<span data-ty>}</span>
<span data-ty></span>
<span data-ty>Decoded tx:</span>
<span data-ty>{</span>
<span data-ty> "args": {</span>
<span data-ty> "dest": {</span>
<span data-ty> "V3": {</span>
<span data-ty> "parents": "0",</span>
<span data-ty> "interior": {</span>
<span data-ty> "X1": {</span>
<span data-ty> "Parachain": "1,000"</span>
<span data-ty> }</span>
<span data-ty> }</span>
<span data-ty> }</span>
<span data-ty> },</span>
<span data-ty> "beneficiary": {</span>
<span data-ty> "V3": {</span>
<span data-ty> "parents": "0",</span>
<span data-ty> "interior": {</span>
<span data-ty> "X1": {</span>
<span data-ty> "AccountId32": {</span>
<span data-ty> "network": null,</span>
<span data-ty> "id": "0x6c0c32faf970eacb2d4d8e538ac0dab3642492561a1be6f241c645876c056c1d"</span>
<span data-ty> }</span>
<span data-ty> }</span>
<span data-ty> }</span>
<span data-ty> }</span>
<span data-ty> },</span>
<span data-ty> "assets": {</span>
<span data-ty> "V3": [</span>
<span data-ty> {</span>
<span data-ty> "id": {</span>
<span data-ty> "Concrete": {</span>
<span data-ty> "parents": "0",</span>
<span data-ty> "interior": "Here"</span>
<span data-ty> }</span>
<span data-ty> },</span>
<span data-ty> "fun": {</span>
<span data-ty> "Fungible": "1,000,000,000,000"</span>
<span data-ty> }</span>
<span data-ty> }</span>
<span data-ty> ]</span>
<span data-ty> },</span>
<span data-ty> "fee_asset_item": "0",</span>
<span data-ty> "weight_limit": "Unlimited"</span>
<span data-ty> },</span>
<span data-ty> "method": "transferAssets",</span>
<span data-ty> "section": "xcmPallet"</span>
<span data-ty>}</span>
</div>
36 changes: 36 additions & 0 deletions .snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.ts
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
import {
AssetTransferApi,
constructApiPromise,
} from "@substrate/asset-transfer-api";

async function main() {
const { api, specName, safeXcmVersion } = await constructApiPromise(
"wss://westend-rpc.polkadot.io"
);
const assetApi = new AssetTransferApi(api, specName, safeXcmVersion);
let callInfo;
try {
callInfo = await assetApi.createTransferTransaction(
"1000",
"5EWNeodpcQ6iYibJ3jmWVe85nsok1EDG8Kk3aFg8ZzpfY1qX",
["WND"],
["1000000000000"],
{
format: "call",
xcmVersion: safeXcmVersion,
}
);

console.log(`Call data:\n${JSON.stringify(callInfo, null, 4)}`);
} catch (e) {
console.error(e);
throw Error(e as string);
}

const decoded = assetApi.decodeExtrinsic(callInfo.tx, "call");
console.log(`\nDecoded tx:\n${JSON.stringify(JSON.parse(decoded), null, 4)}`);
}

main()
.catch((err) => console.error(err))
.finally(() => process.exit());
Loading

0 comments on commit a4ac880

Please sign in to comment.