diff --git a/.CONTRIBUTING.md b/.CONTRIBUTING.md index fded11620..e5d820f55 100644 --- a/.CONTRIBUTING.md +++ b/.CONTRIBUTING.md @@ -1,3 +1,236 @@ # Contribute to the Polkadot Developer Docs -TODO +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. + +## Contents + +- [Viewing Site Locally](#view-site-locally) + - [Clone Repositories](#clone-repositories) + - [Install Dependencies and Serve Site](#install-dependencies) +- [Adding New Pages](#adding-new-pages) + - [Creating a Subdirectory](#creating-a-subdirectory) + - [Example `.pages` File](#example-pages-file) + - [Example `index.md` File](#example-indexmd-file) + - [Adding Pages to Existing Subdirectory](#adding-pages-to-existing-subdirectory) +- [Modifying Existing Pages](#modifying-existing-pages) +- [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 + +You may want to spin up a local version of the documentation site to preview your changes. This guide will cover the steps needed to serve a local version. + +### Clone Repositories + +Building and serving the site requires cloning two repositories: + +- **[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` repository and pulled into the `polkadot-mkdocs` directory during build + +For everything to work correctly, the file structure needs to be as follows: + +```bash +polkadot-mkdocs +|--- /material-overrides/ (folder) +|--- /polkadot-docs/ (repository) +|--- mkdocs.yml +``` + +To set up the structure, follow these steps: + +1. Clone this repository: + + ```bash + git clone https://github.com/papermoonio/polkadot-mkdocs + ``` + +2. Inside the folder just created, clone the `polkadot-docs` repository: + + ```bash + cd polkadot-mkdocs + git clone https://github.com/polkadot-developers/polkadot-docs.git + ``` + +### Install Dependencies and Serve Site + +1. Now that the repositories are cloned and properly nested, use the [pip](https://pypi.org/project/pip/) package installer to install [mkdocs](https://www.mkdocs.org/) and other required dependencies by running the command: + + ```bash + pip install -r requirements.txt + ``` + + 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: + + ```bash + mkdocs serve + ``` + +After a successful build, the site should be available at http://127.0.0.1:8000. + +## Adding New Pages + +When adding new pages to the documentation site, it is important to ensure all relevant items are updated correctly to prevent broken links and unexpected behavior. This section guides you through the steps to add new documentation pages. + +### Creating a New Section + +To create a new section of pages, you will first need to create a subdirectory with the desired name of the section. The root directory, and every subdirectory, must contain the following files: + +- `.pages` - defines the structure of the documentation site +- `index.md` - a landing page which can be used to provide more context about the content in the section + +#### Example `.pages` File + +```markdown +title: Application Developers +nav: + - index.md + - 'Polkadot SDK': 'polkadot-sdk.md' + - interact + - tooling +``` + +This example would result in adding 'Application Developers' as a section with two files inside, `index.md` and `polkadot-sdk.md`, and two additional subdirectories named `interact` and `tooling`. + +Some important things to note: + +- The `title` field at the top of the page represents the display name for the section. This is displayed on the left-side navigation bar when viewing the site +- The `index.md` page should always be the first item in the `nav` list +- Files follow the convention of `'Display Name': 'file-name.md'` +- Sections are listed by their directory name in the source code. For example, the Tooling section will be added to the navigation simply by using the directory name: `tooling` + +#### Example `index.md` File + +```markdown +--- +title: Build Chains with Polkadot +description: Learn how to build and customize blockchains with Polkadot SDK. Explore flexible tools, pre-built modules, and tutorials for efficient blockchain development. +--- + + +``` + +Some important things to note: + +- The `title` represents the `` tag and is used for SEO purposes +- The `description` represents the meta-description and is also used for SEO purposes + +### Adding Pages to Existing Section + +If you are adding pages to an existing section, the steps are simplified. However, it's essential to ensure you complete these steps to display the new page and its title on the documentation site correctly: + +- 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 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 + +- Add the 'Display Name': 'file-name.md' for the new page to the `.pages` folder in the same subdirectory where you added the new page + +An example new content page might look like: + +```md +--- +title: Title for SEO purposes +description: Description for SEO purposes. This should be a sentence or two that is between 120-160 characters long. +--- + +# Page Title + +## Introduction + +Write 2-3 paragraphs to serve as the introduction here. + +... +``` + +More resources for [SEO Optimization](#search-engine-optimization-seo) of titles and descriptions. + +## Modifying Existing Pages + + To modify existing pages: + +1. Ensure you are in the `polkadot-docs` directory, then create a new branch for your content: + + ```bash + git checkout -b INSERT_NEW_BRANCH_NAME + ``` + +2. Modify content as desired. Remember to place images and code snippets in the appropriate folders (see the following sections for details) +3. Review the [style guide](https://github.com/papermoonio/documentation-style-guide/blob/main/style-guide.md) to ensure your new content meets the guidelines +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 don't affect these files. + +## Adding Code and Text Snippets + +Snippets are used to manage reusable lines of code or text. They are organized to mirror the structure of the docs site and stored under the root-level `.snippets` directory. For example, to add a code snippet to the page `develop/application-devs/tooling/chopsticks/overview.md`, you would place the code snippet in the folder `.snippets/code/application-devs/tooling/chopsticks/overview`. + +Text snippets are useful for pieces of copy you find the need to reuse often, such as disclaimers. Code snippets allow you to reuse pieces of code throughout a document while maintaining a single place to update that code when needed. + +To link to a snippet, you can use the following syntax in the Markdown file: + +```markdown +--8<-- 'code/<subdirectory>/<snippet-file-name>.js' +``` + +Text snippets are written in Markdown, as `.md` files, while code snippets should be written in their individual programming languages, for example, `.py` for Python or `.js` for JavaScript. + +Learn more about the effective use of [snippets](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/). + +## Adding Images + +Images are stored in the `images` subdirectory. They are organized to mirror the structure of the docs site. For example, to add an image to the page `/develop/application-devs/tooling/chopsticks/overview.md`, you would place the image in the folder `images/application-devs/tooling/chopsticks/overview` + +All images intended for display on the website should be in `.webp` format. You can look up an image converter online to convert from `.jpeg`, `.png`, or other formats to `.webp`. + +To add an image to your page, you should have [alt text](https://developers.google.com/style/images#alt-text) and use the following syntax: + +```markdown +![Alt text goes here](/docs/images/<subdirectory>/<image-file-name>.webp) +``` + +See the [style guide](https://github.com/papermoonio/documentation-style-guide/blob/main/style-guide.md#screenshots) for more tips on handling images. + +## Search Engine Optimization (SEO) + +Here are some resources to help you create good titles and descriptions for SEO: + +- [Google's recommendation on good titles](https://developers.google.com/search/docs/advanced/appearance/title-link?hl=en) +- [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 \ No newline at end of file diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 000000000..b9bcc0745 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,20 @@ +[*.ts] +indent_style=space +indent_size=2 +max_line_length=80 +quote_type=single + +[*.js] +indent_style=space +indent_size=2 +max_line_length=80 +quote_type=single + +[*.json] +indent_style=space +indent_size=4 +max_line_length=80 +quote_type=double + +[*.html] +max_line_length=off diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 000000000..c24b193e9 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,5 @@ +# Request reviews from the formatting team for all PRs +* @polkadot-developers/docs-formatting-team + +# Request reviews from the content team for all PRs +* @polkadot-developers/docs-content-team \ No newline at end of file diff --git a/.github/hooks/pre-commit b/.github/hooks/pre-commit new file mode 100755 index 000000000..7d67ce521 --- /dev/null +++ b/.github/hooks/pre-commit @@ -0,0 +1,9 @@ +#!/bin/sh + +# Run Prettier on all files in snippets/code +echo "Running Prettier on the following files:" +npx prettier --write ".snippets/code/**/*.{js,ts,json,css,html}" + +# Add formatted files back to the commit +echo "Adding formatted files back to the commit..." +git add $(find .snippets/code -name "*.js" -o -name "*.ts" -o -name "*.json" -o -name "*.css" -o -name "*.html") diff --git a/.github/scripts/check_repositories.py b/.github/scripts/check_repositories.py new file mode 100644 index 000000000..b4b02e7d0 --- /dev/null +++ b/.github/scripts/check_repositories.py @@ -0,0 +1,89 @@ +import requests +import json +from urllib.parse import urlparse +import sys +import yaml + + +def get_latest_release(repo_url): + """Get the latest release tag from a GitHub repository.""" + try: + # Extract owner and repo name from the URL + path = urlparse(repo_url).path.strip("/") + owner, repo = path.split("/")[-2:] + + # Make the GET request to the GitHub API + api_url = f"https://api.github.com/repos/{owner}/{repo}/releases/latest" + response = requests.get(api_url) + + if response.status_code == 200: + data = response.json() + return data["tag_name"] + else: + print(f"Failed to fetch data for {repo_url}: HTTP {response.status_code}") + return None + except Exception as e: + print(f"Error fetching the latest release for {repo_url}: {e}") + sys.exit(1) + + +def check_releases(releases_source_file): + """Check the release tags for a list of repositories.""" + try: + with open(releases_source_file, "r") as file: + data = yaml.safe_load(file) + repos = data.get("dependencies", {}) + #print(repos) + except Exception as e: + print(f"Error reading releases source file '{releases_source_file}': {e}") + sys.exit(1) + + outdated_repos = [] + + for name, repo_info in repos.items(): + repo_url = repo_info.get("repository_url") + current_version = repo_info.get("version") + + if not repo_url or not current_version: + print(f"Invalid repository entry: {name}") + continue + + latest_version = get_latest_release(repo_url) + + if latest_version and latest_version != current_version: + outdated_repos.append( + { + "repository": repo_url, + "current_version": current_version, + "latest_version": latest_version, + } + ) + + return outdated_repos + + +def main(releases_source_file): + """Main function to check releases and generate an output file.""" + try: + outdated_repos = check_releases(releases_source_file) + + # Output results in a format suitable for GitHub Actions + output = { + "outdated_repos": outdated_repos, + "outdated_count": len(outdated_repos), + } + + # Write the output to a JSON file + with open("outdated_repositories.json", "w") as f: + json.dump(output, f, indent=2) + + # Print the output for GitHub Actions + print(json.dumps(output)) + + except Exception as e: + print(f"Error in main execution: {e}") + sys.exit(1) + + +if __name__ == "__main__": + main("variables.yml") \ No newline at end of file diff --git a/.github/scripts/create_issues.py b/.github/scripts/create_issues.py new file mode 100644 index 000000000..10c918660 --- /dev/null +++ b/.github/scripts/create_issues.py @@ -0,0 +1,97 @@ +import requests +import json +import os +import sys +from urllib.parse import urlparse + +GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN") + + +def parse_github_url(url): + """Extract owner and repo from a GitHub URL.""" + try: + path = urlparse(url).path.strip("/") + return path.split("/")[-2:] + except Exception as e: + print(f"Error parsing GitHub URL: {e}") + sys.exit(1) + + +def issue_exists(owner, repo, title): + """Check if an issue with the same title already exists.""" + try: + url = f"https://api.github.com/repos/polkadot-developers/polkadot-docs/issues" + headers = { + "Authorization": f"token {GITHUB_TOKEN}", + "Accept": "application/vnd.github.v3+json", + } + response = requests.get(url, headers=headers) + response.raise_for_status() + + issues = response.json() + for issue in issues: + if issue["title"] == title: + return True + return False + except Exception as e: + print(f"Error checking for existing issues: {e}") + sys.exit(1) + + +def create_github_issue(owner, repo, title, body): + """Create a GitHub issue using the GitHub API.""" + try: + if issue_exists(owner, repo, title): + print(f"Issue '{title}' already exists. Skipping creation.") + return + + url = f"https://api.github.com/repos/polkadot-developers/polkadot-docs/issues" + headers = { + "Authorization": f"token {GITHUB_TOKEN}", + "Accept": "application/vnd.github.v3+json", + } + data = {"title": title, "body": body} + response = requests.post(url, headers=headers, json=data) + + if response.status_code == 201: + print(f"Successfully created issue '{title}'") + return + else: + print( + f"Failed to create issue '{title}'. Status code: {response.status_code}" + ) + print(response.text) + sys.exit(1) + except Exception as e: + print(f"Error creating issue: {e}") + sys.exit(1) + + +def main(): + # Check if GITHUB_TOKEN is set + if not GITHUB_TOKEN: + print("Error: GITHUB_TOKEN environment variable is not set.") + sys.exit(1) + + # Read the JSON file with outdated repositories + try: + with open("outdated_repositories.json", "r") as f: + data = json.load(f) + except Exception as e: + print(f"Error reading JSON file: {e}") + sys.exit(1) + + for repo in data.get("outdated_repos", []): + owner, repo_name = parse_github_url(repo["repository"]) + title = f"Update needed: {repo_name} ({repo['current_version']} -> {repo['latest_version']})" + body = f"""A new release has been detected for {repo['repository']}. +Current version: {repo['current_version']} +Latest version: {repo['latest_version']} + +Please review the change log and update the documentation accordingly.""" + + create_github_issue(owner, repo_name, title, body) + + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/.github/workflows/check-repositories.yaml b/.github/workflows/check-repositories.yaml new file mode 100644 index 000000000..1edfc3c97 --- /dev/null +++ b/.github/workflows/check-repositories.yaml @@ -0,0 +1,36 @@ +name: Check Repositories + +on: + schedule: # Run every day at midnight. + - cron: '0 0 * * *' + workflow_dispatch: # Allows manual triggering of the workflow. + +jobs: + check-repositories: + runs-on: ubuntu-latest + permissions: + issues: write + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.x' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install requests pyyaml + + - name: Check for Outdated Repositories + id: check_repositories + run: | + python .github/scripts/check_repositories.py + + - name: Create GitHub Issues for Outdated Repositories + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + python .github/scripts/create_issues.py \ No newline at end of file diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml index abc64acae..00f436cee 100644 --- a/.github/workflows/vale.yml +++ b/.github/workflows/vale.yml @@ -1,16 +1,16 @@ -name: Vale Review +# name: Vale Review -on: - pull_request: - branches: master +# on: +# pull_request: +# branches: master -jobs: - vale-review-docs: - permissions: - pull-requests: write - uses: papermoonio/polkadot-mkdocs/.github/workflows/vale.yml@main - with: - repo: ${{ github.repository }} - pr_number: ${{ github.event.pull_request.number }} - secrets: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file +# jobs: +# vale-review-docs: +# permissions: +# pull-requests: write +# uses: papermoonio/polkadot-mkdocs/.github/workflows/vale.yml@main +# with: +# repo: ${{ github.repository }} +# pr_number: ${{ github.event.pull_request.number }} +# secrets: +# GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..b512c09d4 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +node_modules \ No newline at end of file diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100755 index 000000000..a07e2a6aa --- /dev/null +++ b/.husky/pre-commit @@ -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} diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.md new file mode 100644 index 000000000..58667b413 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.md @@ -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> \ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.ts new file mode 100644 index 000000000..efe7976cf --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.ts @@ -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()); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.md new file mode 100644 index 000000000..ff1535601 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.md @@ -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> \ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.ts new file mode 100644 index 000000000..6e1919650 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.ts @@ -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()); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.md new file mode 100644 index 000000000..dea06e3b5 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.md @@ -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> \ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.ts new file mode 100644 index 000000000..75ae4b5a7 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.ts @@ -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()); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/setup.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/setup.ts new file mode 100644 index 000000000..7a95e5b07 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/overview/setup.ts @@ -0,0 +1,16 @@ +import { + AssetTransferApi, + constructApiPromise, +} from '@substrate/asset-transfer-api'; + +async function main() { + const { api, specName, safeXcmVersion } = await constructApiPromise( + 'INSERT_WEBSOCKET_URL', + ); + + const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion); + + // Your code using assetsApi goes here +} + +main(); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/asset-transfer-type.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/asset-transfer-type.md new file mode 100644 index 000000000..b9029d958 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/asset-transfer-type.md @@ -0,0 +1,10 @@ +```ts +export type AssetTransferType = + | LocalReserve + | DestinationReserve + | Teleport + | RemoteReserve; +``` + +!!! note + To use the `assetTransferType` parameter, which is a string, you should use the `AssetTransferType` type as if each of its variants are strings. For example: `assetTransferType = 'LocalReserve'`. \ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-request.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-request.ts new file mode 100644 index 000000000..bb9bf4695 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-request.ts @@ -0,0 +1,35 @@ +import { + AssetTransferApi, + constructApiPromise, +} from '@substrate/asset-transfer-api'; + +async function main() { + const { api, specName, safeXcmVersion } = await constructApiPromise( + 'wss://westend-rpc.polkadot.io', + ); + const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion); + + let callInfo; + try { + callInfo = await assetsApi.claimAssets( + [ + `{"parents":"0","interior":{"X2":[{"PalletInstance":"50"},{"GeneralIndex":"1984"}]}}`, + ], + ['1000000000000'], + '0xf5d5714c084c112843aca74f8c498da06cc5a2d63153b825189baa51043b1f0b', + { + format: 'call', + xcmVersion: 2, + }, + ); + + console.log(`Call data:\n${JSON.stringify(callInfo, null, 4)}`); + } catch (e) { + console.error(e); + throw Error(e as string); + } +} + +main() + .catch((err) => console.error(err)) + .finally(() => process.exit()); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-response.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-response.md new file mode 100644 index 000000000..cea34c61c --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-response.md @@ -0,0 +1,12 @@ +<div id="termynal" data-termynal> + <span data-ty>Call data:</span> + <span data-ty>{</span> + <span data-ty> "origin": "0",</span> + <span data-ty> "dest": "westend",</span> + <span data-ty> "direction": "local",</span> + <span data-ty> "xcmVersion": 2,</span> + <span data-ty> "method": "claimAssets",</span> + <span data-ty> "format": "call",</span> + <span data-ty> "tx": "0x630c0104000002043205011f00070010a5d4e80100010100f5d5714c084c112843aca74f8c498da06cc5a2d63153b825189baa51043b1f0b"</span> + <span data-ty>}</span> +<div> \ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-fn-signature.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-fn-signature.ts new file mode 100644 index 000000000..4303c60d1 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ca-fn-signature.ts @@ -0,0 +1,6 @@ +public async claimAssets<T extends Format>( + assetIds: string[], + amounts: string[], + beneficiary: string, + opts: TransferArgsOpts<T> +): Promise<TxResult<T>>; diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/constructed-format.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/constructed-format.md new file mode 100644 index 000000000..7b610adf8 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/constructed-format.md @@ -0,0 +1,15 @@ +```ts +export type ConstructedFormat<T> = T extends 'payload' + ? GenericExtrinsicPayload + : T extends 'call' + ? `0x${string}` + : T extends 'submittable' + ? SubmittableExtrinsic<'promise', ISubmittableResult> + : never; +``` + +The `ConstructedFormat` type is a conditional type that returns a specific type based on the value of the TxResult `format` field. + +- Payload format - if the format field is set to `'payload'`, the `ConstructedFormat` type will return a [`GenericExtrinsicPayload`](https://github.com/polkadot-js/api/blob/3b7b44f048ff515579dd233ea6964acec39c0589/packages/types/src/extrinsic/ExtrinsicPayload.ts#L48){target=_blank} +- Call format - if the format field is set to `'call'`, the `ConstructedFormat` type will return a hexadecimal string (`0x${string}`). This is the encoded representation of the extrinsic call +- Submittable format - if the format field is set to `'submittable'`, the `ConstructedFormat` type will return a [`SubmittableExtrinsic`](https://github.com/polkadot-js/api/blob/3b7b44f048ff515579dd233ea6964acec39c0589/packages/api-base/src/types/submittable.ts#L56){target=_blank}. This is a Polkadot.js type that represents a transaction that can be submitted to the blockchain \ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-request.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-request.ts new file mode 100644 index 000000000..93c6bbb4c --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-request.ts @@ -0,0 +1,34 @@ +import { + AssetTransferApi, + constructApiPromise, +} from '@substrate/asset-transfer-api'; + +async function main() { + const { api, specName, safeXcmVersion } = await constructApiPromise( + 'wss://wss.api.moonbeam.network', + ); + const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion); + + let callInfo; + try { + callInfo = await assetsApi.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); + } +} + +main() + .catch((err) => console.error(err)) + .finally(() => process.exit()); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-response.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-response.md new file mode 100644 index 000000000..a1bb01f6a --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-response.md @@ -0,0 +1,12 @@ +<div id="termynal" data-termynal> + <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> +<div> \ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-fn-signature.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-fn-signature.ts new file mode 100644 index 000000000..0af1ef38c --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-fn-signature.ts @@ -0,0 +1,7 @@ +public async createTransferTransaction<T extends Format>( + destChainId: string, + destAddr: string, + assetIds: string[], + amounts: string[], + opts: TransferArgsOpts<T> = {} +): Promise<TxResult<T>>; diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-request.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-request.ts new file mode 100644 index 000000000..f9c7a679b --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-request.ts @@ -0,0 +1,27 @@ +import { + AssetTransferApi, + constructApiPromise, +} from '@substrate/asset-transfer-api'; + +async function main() { + const { api, specName, safeXcmVersion } = await constructApiPromise( + 'wss://wss.api.moonbeam.network', + ); + const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion); + + const encodedExt = '0x0a03f977814e90da44bfa03b6295a0616a897441acec821a0600'; + + try { + const decodedExt = assetsApi.decodeExtrinsic(encodedExt, 'call'); + console.log( + `Decoded tx:\n ${JSON.stringify(JSON.parse(decodedExt), null, 4)}`, + ); + } catch (e) { + console.error(e); + throw Error(e as string); + } +} + +main() + .catch((err) => console.error(err)) + .finally(() => process.exit()); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-response.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-response.md new file mode 100644 index 000000000..3bc83e19d --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-response.md @@ -0,0 +1,11 @@ +<div id='termynal' data-termynal> + <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": "100,000"</span> + <span data-ty> },</span> + <span data-ty> "method": "transferKeepAlive",</span> + <span data-ty> "section": "balances"</span> + <span data-ty>}</span> +</div> \ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-fn-signature.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-fn-signature.ts new file mode 100644 index 000000000..197d817df --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/de-fn-signature.ts @@ -0,0 +1,4 @@ +public decodeExtrinsic<T extends Format>( + encodedTransaction: string, + format: T +): string; diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-request.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-request.ts new file mode 100644 index 000000000..3067907eb --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-request.ts @@ -0,0 +1,25 @@ +import { + AssetTransferApi, + constructApiPromise, +} from '@substrate/asset-transfer-api'; + +async function main() { + const { api, specName, safeXcmVersion } = await constructApiPromise( + 'wss://wss.api.moonbeam.network', + ); + const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion); + + const encodedExt = '0x0a03f977814e90da44bfa03b6295a0616a897441acec821a0600'; + + try { + const decodedExt = await assetsApi.fetchFeeInfo(encodedExt, 'call'); + console.log(`Fee info:\n${JSON.stringify(decodedExt, null, 4)}`); + } catch (e) { + console.error(e); + throw Error(e as string); + } +} + +main() + .catch((err) => console.error(err)) + .finally(() => process.exit()); diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-response.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-response.md new file mode 100644 index 000000000..3f90dea38 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-response.md @@ -0,0 +1,11 @@ +<div id='termynal' data-termynal> + <span data-ty>Fee info:</span> + <span data-ty>{</span> + <span data-ty> "weight": {</span> + <span data-ty> "refTime": 163777000,</span> + <span data-ty> "proofSize": 3581</span> + <span data-ty> },</span> + <span data-ty> "class": "Normal",</span> + <span data-ty> "partialFee": 0</span> + <span data-ty>}</span> +</div> \ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-fn-signature.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-fn-signature.ts new file mode 100644 index 000000000..7f87e9aa8 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-fn-signature.ts @@ -0,0 +1,4 @@ +public async fetchFeeInfo<T extends Format>( + tx: ConstructedFormat<T>, + format: T +): Promise<RuntimeDispatchInfo | RuntimeDispatchInfoV1 | null>; diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/format.ts b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/format.ts new file mode 100644 index 000000000..9fe23a678 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/format.ts @@ -0,0 +1 @@ +export type Format = 'payload' | 'call' | 'submittable'; diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/transfer-arg-opts.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/transfer-arg-opts.md new file mode 100644 index 000000000..e244fecbc --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/transfer-arg-opts.md @@ -0,0 +1,94 @@ +Options for customizing the claim assets transaction. These options allow you to specify the transaction format, fee payment details, weight limits, XCM versions, and more. + +??? child "Show more" + + `format` ++"T extends Format"++ + + Specifies the format for returning a transaction. + + ??? child "Type `Format`" + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/format.ts' + ``` + + --- + + `paysWithFeeOrigin` ++"string"++ + + The Asset ID to pay fees on the current common good parachain. The defaults are as follows: + + - Polkadot Asset Hub - `'DOT'` + - Kusama Asset Hub - `'KSM'` + + --- + + `paysWithFeeDest` ++"string"++ + + Asset ID to pay fees on the destination parachain. + + --- + + `weightLimit` ++"{ refTime?: string, proofSize?: string }"++ + + Custom weight limit option. If not provided, it will default to unlimited. + + --- + + `xcmVersion` ++"number"++ + + Sets the XCM version for message construction. If this is not present a supported version will be queried, and if there is no supported version a safe version will be queried. + + --- + + `keepAlive` ++"boolean"++ + + Enables `transferKeepAlive` for local asset transfers. For creating local asset transfers, if `true` this will allow for a `transferKeepAlive` as opposed to a `transfer`. + + --- + + `transferLiquidToken` ++"boolean"++ + + Declares if this will transfer liquidity tokens. Default is `false`. + + --- + + `assetTransferType` ++"string"++ + + The XCM transfer type used to transfer assets. The `AssetTransferType` type defines the possible values for this parameter. + + ??? child "Type `AssetTransferType`" + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/asset-transfer-type.md' + + --- + + `remoteReserveAssetTransferTypeLocation` ++"string"++ + + The remove reserve location for the XCM transfer. Should be provided when specifying an `assetTransferType` of `RemoteReserve`. + + --- + + `feesTransferType` ++"string"++ + + XCM TransferType used to pay fees for XCM transfer. The `AssetTransferType` type defines the possible values for this parameter. + + ??? child "Type `AssetTransferType`" + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/asset-transfer-type.md' + + --- + + `remoteReserveFeesTransferTypeLocation` ++"string"++ + + The remote reserve location for the XCM transfer fees. Should be provided when specifying a `feesTransferType` of `RemoteReserve`. + + --- + + `customXcmOnDest` ++"string"++ + + A custom XCM message to be executed on the destination chain. Should be provided if a custom XCM message is needed after transferring assets. Defaults to: + + ```bash + Xcm(vec![DepositAsset { assets: Wild(AllCounted(assets.len())), beneficiary }]) + ``` \ No newline at end of file diff --git a/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/tx-result.md b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/tx-result.md new file mode 100644 index 000000000..389d58391 --- /dev/null +++ b/.snippets/code/develop/application-devs/tooling/asset-transfer-api/reference/tx-result.md @@ -0,0 +1,148 @@ +A promise containing the result of constructing the transaction. + +??? child "Show more" + + `dest` ++"string"++ + + The destination `specName` of the transaction. + + --- + + `origin` ++"string"++ + + The origin `specName` of the transaction. + + --- + + `format` ++"Format | 'local'"++ + + The format type the transaction is outputted in. + + ??? child "Type `Format`" + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/format.ts' + ``` + + --- + + `xcmVersion` ++"number | null"++ + + The XCM version that was used to construct the transaction. + + --- + + `direction` ++"Direction | 'local'"++ + + The direction of the cross-chain transfer. + + ??? child "Enum `Direction` values" + + `Local` + + Local transaction. + + --- + + `SystemToPara` + + System parachain to parachain. + + --- + + `SystemToRelay` + + System paracahin to system relay chain. + + --- + + `SystemToSystem` + + System parachain to System parachain chain. + + --- + + `SystemToBridge` + + System parachain to an external `GlobalConsensus` chain. + + --- + + `ParaToPara` + + Parachain to Parachain. + + --- + + `ParaToRelay` + + Parachain to Relay chain. + + --- + + `ParaToSystem` + + Parachain to System parachain. + + --- + + `RelayToSystem` + + Relay to System Parachain. + + --- + + `RelayToPara` + + Relay chain to Parachain. + + --- + + `RelayToBridge` + + Relay chain to an external `GlobalConsensus` chain. + + `method` ++"Methods"++ + + The method used in the transaction. + + ??? child "Type `Methods`" + + ```ts + type Methods = + | LocalTransferTypes + | 'transferAssets' + | 'transferAssetsUsingTypeAndThen' + | 'limitedReserveTransferAssets' + | 'limitedTeleportAssets' + | 'transferMultiasset' + | 'transferMultiassets' + | 'transferMultiassetWithFee' + | 'claimAssets'; + ``` + + ??? child "Type `LocalTransferTypes`" + + ```ts + type LocalTransferTypes = + | 'assets::transfer' + | 'assets::transferKeepAlive' + | 'foreignAssets::transfer' + | 'foreignAssets::transferKeepAlive' + | 'balances::transfer' + | 'balances::transferKeepAlive' + | 'poolAssets::transfer' + | 'poolAssets::transferKeepAlive' + | 'tokens::transfer' + | 'tokens::transferKeepAlive'; + ``` + + --- + + `tx` ++"ConstructedFormat<T>"++ + + The constructed transaction. + + ??? child "Type `ConstructedFormat<T>`" + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/constructed-format.md' diff --git a/.snippets/code/develop/parachain-devs/get-started/polkadot-sdk/install-deps/termynal-1.html b/.snippets/code/develop/parachain-devs/get-started/polkadot-sdk/install-deps/termynal-1.html new file mode 100644 index 000000000..bb3fb9c5b --- /dev/null +++ b/.snippets/code/develop/parachain-devs/get-started/polkadot-sdk/install-deps/termynal-1.html @@ -0,0 +1,5 @@ +<div id="termynal" data-termynal markdown> + <span data-ty="input"><span class="file-path"></span>brew --version</span> + <span data-ty>Homebrew 4.3.15</span> + <span data-ty="input"><span class="file-path"></span></span> +</div> diff --git a/.snippets/code/develop/parachain-devs/get-started/polkadot-sdk/install-deps/termynal-2.html b/.snippets/code/develop/parachain-devs/get-started/polkadot-sdk/install-deps/termynal-2.html new file mode 100644 index 000000000..00eee2496 --- /dev/null +++ b/.snippets/code/develop/parachain-devs/get-started/polkadot-sdk/install-deps/termynal-2.html @@ -0,0 +1,19 @@ +<div id="termynal" data-termynal> + <span data-ty="input"><span class="file-path"></span>rustup show</span> + <span data-ty>...</span> + <br /> + <span data-ty>active toolchain</span> + <span data-ty>----------------</span> + <br /> + <span data-ty>stable-x86_64-apple-darwin (default)</span> + <span data-ty>rustc 1.81.0 (eeb90cda1 2024-09-04)</span> + <br /> + <span data-ty>...</span> + <br /> + <span data-ty>active toolchain</span> + <span data-ty>----------------</span> + <br /> + <span data-ty>nightly-x86_64-apple-darwin (overridden by +toolchain on the command line)</span> + <span data-ty>rustc 1.83.0-nightly (6c6d21008 2024-09-22)</span> + <span data-ty="input"><span class="file-path"></span></span> +</div> diff --git a/.snippets/code/develop/parachain-devs/interoperability/hrmp-channels/hrmp-query-output.json b/.snippets/code/develop/parachain-devs/interoperability/hrmp-channels/hrmp-query-output.json new file mode 100644 index 000000000..3c8189e6f --- /dev/null +++ b/.snippets/code/develop/parachain-devs/interoperability/hrmp-channels/hrmp-query-output.json @@ -0,0 +1,38 @@ +[ + [ + [ + { + "sender": 1000, + "recipient": 2500 + } + ], + { + "maxCapacity": 8, + "maxTotalSize": 8192, + "maxMessageSize": 1048576, + "msgCount": 0, + "totalSize": 0, + "mqcHead": null, + "senderDeposit": 0, + "recipientDeposit": 0 + } + ], + [ + [ + { + "sender": 2500, + "recipient": 1000 + } + ], + { + "maxCapacity": 8, + "maxTotalSize": 8192, + "maxMessageSize": 1048576, + "msgCount": 0, + "totalSize": 0, + "mqcHead": null, + "senderDeposit": 0, + "recipientDeposit": 0 + } + ] +] diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/compilation-output.html b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/compilation-output.html new file mode 100644 index 000000000..ddd0db1a7 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/compilation-output.html @@ -0,0 +1,5 @@ +<div id="termynal" data-termynal> + <span data-ty="input"><span class="file-path"></span>cargo build --release</span> + <span data-ty>Compiling solochain-template-node</span> + <span data-ty>Finished `release` profile [optimized] target(s) in 27.12s</span> +</div> diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/node-block-production.html b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/node-block-production.html new file mode 100644 index 000000000..5b1f8a6d7 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/node-block-production.html @@ -0,0 +1,11 @@ +<div id="termynal" data-termynal> + <span data-ty>...</span> + <span data-ty>2024-09-09 08:32:47 💤 Idle (0 peers), best: #0 (0x0eef…935d), finalized #0 (0x0eef…935d), ⬇ 0 ⬆ 0</span> + <span data-ty>...</span> + <span data-ty>2024-09-09 08:32:52 💤 Idle (0 peers), best: #1 (0xcb3d…265b), finalized #0 (0x0eef…935d), ⬇ 0 ⬆ 0</span> + <span data-ty>...</span> + <span data-ty>2024-09-09 08:32:57 💤 Idle (0 peers), best: #2 (0x16d7…083f), finalized #0 (0x0eef…935d), ⬇ 0 ⬆ 0</span> + <span data-ty>...</span> + <span data-ty>2024-09-09 08:33:02 💤 Idle (0 peers), best: #3 (0xe6a4…2cc4), finalized #1 (0xcb3d…265b), ⬇ 0 ⬆ 0</span> + <span data-ty>...</span> +</div> diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/node-output.html b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/node-output.html new file mode 100644 index 000000000..e0819b6a5 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/node-output.html @@ -0,0 +1,27 @@ +<div id="termynal" data-termynal> + <span data-ty="input"><span class="file-path"></span>./target/release/solochain-template-node --dev</span> + <br /> + <span data-ty>2024-09-09 08:32:42 Substrate Node</span> + <span data-ty>2024-09-09 08:32:42 ✌️ version 0.1.0-8599efc46ae</span> + <span data-ty>2024-09-09 08:32:42 ❤️ by Parity Technologies <admin@parity.io>, 2017-2024</span> + <span data-ty>2024-09-09 08:32:42 📋 Chain specification: Development</span> + <span data-ty>2024-09-09 08:32:42 🏷 Node name: light-boundary-7850</span> + <span data-ty>2024-09-09 08:32:42 👤 Role: AUTHORITY</span> + <span data-ty>2024-09-09 08:32:42 💾 Database: RocksDb at /var/folders/x0/xl_kjddj3ql3bx7752yr09hc0000gn/T/substrate0QH9va/chains/dev/db/full</span> + <span data-ty>2024-09-09 08:32:42 🔨 Initializing Genesis block/state (state: 0xc2a0…16ba, header-hash: 0x0eef…935d)</span> + <span data-ty>2024-09-09 08:32:42 👴 Loading GRANDPA authority set from genesis on what appears to be first startup.</span> + <span data-ty>2024-09-09 08:32:42 Using default protocol ID "sup" because none is configured in the chain specs</span> + <span data-ty>2024-09-09 08:32:42 🏷 Local node identity is: 12D3KooWPhdUzf66di1SuuRFgjkFs6X8jm3Uj2ss5ri31WuVAbgt</span> + <span data-ty>2024-09-09 08:32:42 Running libp2p network backend</span> + <span data-ty>2024-09-09 08:32:42 💻 Operating system: macos</span> + <span data-ty>2024-09-09 08:32:42 💻 CPU architecture: aarch64</span> + <span data-ty>2024-09-09 08:32:42 📦 Highest known block at #0</span> + <span data-ty>2024-09-09 08:32:42 〽️ Prometheus exporter started at 127.0.0.1:9615</span> + <span data-ty>2024-09-09 08:32:42 Running JSON-RPC server: addr=127.0.0.1:9944, allowed origins=["*"]</span> + <span data-ty>2024-09-09 08:32:47 💤 Idle (0 peers), best: #0 (0x0eef…935d), finalized #0 (0x0eef…935d), ⬇ 0 ⬆ 0</span> + <span data-ty>2024-09-09 08:32:48 🙌 Starting consensus session on top of parent 0x0eef4a08ef90cc04d01864514dc5cb2bd822314309b770b49b0177f920ed935d (#0)</span> + <span data-ty>2024-09-09 08:32:48 🎁 Prepared block for proposing at 1 (1 ms) [hash: 0xc14630b76907550bef9037dcbfafa2b25c8dc763495f30d9e36ad4b93b673b36; parent_hash: 0x0eef…935d; extrinsics (1): [0xbcd8…5132]</span> + <span data-ty>2024-09-09 08:32:48 🔖 Pre-sealed block for proposal at 1. Hash now 0xcb3d2f28bc73807dac5cf19fcfb2ac6d7e922756da9d41ca0c9dadbd0e45265b, previously 0xc14630b76907550bef9037dcbfafa2b25c8dc763495f30d9e36ad4b93b673b36.</span> + <span data-ty>2024-09-09 08:32:48 🏆 Imported #1 (0x0eef…935d → 0xcb3d…265b)</span> + <span data-ty>...</span> +</div> diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network/node-output-1.html b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network/node-output-1.html new file mode 100644 index 000000000..bb4550546 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network/node-output-1.html @@ -0,0 +1,19 @@ +<div id="termynal" data-termynal> + <span data-ty>...</span> + <span data-ty>2024-09-10 09:04:57 discovered: 12D3KooWHdiAxVd8uMQR1hGWXccidmfCwLqcMpGwR6QcTP6QRMuD /ip4/192.168.1.4/tcp/30334</span> + <span data-ty>2024-09-10 09:04:58 💤 Idle (0 peers), best: #0 (0x850f…951f), finalized #0 (0x850f…951f), ⬇ 0.3kiB/s ⬆ 0.3kiB/s</span> + <span data-ty>2024-09-10 09:05:00 🙌 Starting consensus session on top of parent 0x850ffab4827cb0297316cbf01fc7c2afb954c5124f366f25ea88bfd19ede951f (#0)</span> + <span data-ty>2024-09-10 09:05:00 🎁 Prepared block for proposing at 1 (2 ms) [hash: 0xe21a305e6647b0b0c6c73ba31a49ae422809611387fadb7785f68d0a1db0b52d; parent_hash: 0x850f…951f; extrinsics (1): [0x0c18…08d8]</span> + <span data-ty>2024-09-10 09:05:00 🔖 Pre-sealed block for proposal at 1. Hash now 0x75bbb026db82a4d6ff88b96f952a29e15dac2b7df24d4cb95510945e2bede82d, previously 0xe21a305e6647b0b0c6c73ba31a49ae422809611387fadb7785f68d0a1db0b52d.</span> + <span data-ty>2024-09-10 09:05:00 🏆 Imported #1 (0x850f…951f → 0x75bb…e82d)</span> + <span data-ty>2024-09-10 09:05:03 💤 Idle (1 peers), best: #1 (0x75bb…e82d), finalized #0 (0x850f…951f), ⬇ 0.7kiB/s ⬆ 0.8kiB/s</span> + <span data-ty>2024-09-10 09:05:06 🏆 Imported #2 (0x75bb…e82d → 0x774d…a176)</span> + <span data-ty>2024-09-10 09:05:08 💤 Idle (1 peers), best: #2 (0x774d…a176), finalized #0 (0x850f…951f), ⬇ 0.6kiB/s ⬆ 0.5kiB/s</span> + <span data-ty>2024-09-10 09:05:12 🙌 Starting consensus session on top of parent 0x774dec6bff7a27c38e21106a5a7428ae5d50b991f39cda7c0aa3c0c9322da176 (#2)</span> + <span data-ty>2024-09-10 09:05:12 🎁 Prepared block for proposing at 3 (0 ms) [hash: 0x10bb4589a7a13bac657219a9ff06dcef8d55e46a4275aa287a966b5648a6d486; parent_hash: 0x774d…a176; extrinsics (1): [0xdcd4…b5ec]</span> + <span data-ty>2024-09-10 09:05:12 🔖 Pre-sealed block for proposal at 3. Hash now 0x01e080f4b8421c95d0033aac7310b36972fdeef7c6025f8a153c436c1bb214ee, previously 0x10bb4589a7a13bac657219a9ff06dcef8d55e46a4275aa287a966b5648a6d486.</span> + <span data-ty>2024-09-10 09:05:12 🏆 Imported #3 (0x774d…a176 → 0x01e0…14ee)</span> + <span data-ty>2024-09-10 09:05:13 💤 Idle (1 peers), best: #3 (0x01e0…14ee), finalized #0 (0x850f…951f), ⬇ 0.6kiB/s ⬆ 0.6kiB/s</span> + <span data-ty>2024-09-10 09:05:18 🏆 Imported #4 (0x01e0…14ee → 0xe176…0430)</span> + <span data-ty>2024-09-10 09:05:18 💤 Idle (1 peers), best: #4 (0xe176…0430), finalized #1 (0x75bb…e82d), ⬇ 0.6kiB/s ⬆ 0.6kiB/s</span> +</div> diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network/node-output.html b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network/node-output.html new file mode 100644 index 000000000..4307d2c07 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network/node-output.html @@ -0,0 +1,21 @@ +<div id="termynal" data-termynal> + <span data-ty="input"><span class="file-path"></span>./target/release/solochain-template-node \ --base-path /tmp/alice \ --chain local \ --alice \ --port 30333 \ --rpc-port 9945 \ --node-key 0000000000000000000000000000000000000000000000000000000000000001 \ --validator </span> + <span data-ty>2024-09-10 08:35:43 Substrate Node</span> + <span data-ty>2024-09-10 08:35:43 ✌️ version 0.1.0-8599efc46ae</span> + <span data-ty>2024-09-10 08:35:43 ❤️ by Parity Technologies <admin@parity.io>, 2017-2024</span> + <span data-ty>2024-09-10 08:35:43 📋 Chain specification: Local Testnet</span> + <span data-ty>2024-09-10 08:35:43 🏷 Node name: Alice</span> + <span data-ty>2024-09-10 08:35:43 👤 Role: AUTHORITY</span> + <span data-ty>2024-09-10 08:35:43 💾 Database: RocksDb at /tmp/alice/chains/local_testnet/db/full</span> + <span data-ty>2024-09-10 08:35:43 🔨 Initializing Genesis block/state (state: 0x074c…27bd, header-hash: 0x850f…951f)</span> + <span data-ty>2024-09-10 08:35:43 👴 Loading GRANDPA authority set from genesis on what appears to be first startup.</span> + <span data-ty>2024-09-10 08:35:43 Using default protocol ID "sup" because none is configured in the chain specs</span> + <span data-ty>2024-09-10 08:35:43 🏷 Local node identity is: 12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp</span> + <span data-ty>2024-09-10 08:35:43 Running libp2p network backend</span> + <span data-ty>2024-09-10 08:35:43 💻 Operating system: macos</span> + <span data-ty>2024-09-10 08:35:43 💻 CPU architecture: aarch64</span> + <span data-ty>2024-09-10 08:35:43 📦 Highest known block at #0</span> + <span data-ty>2024-09-10 08:35:43 〽️ Prometheus exporter started at 127.0.0.1:9615</span> + <span data-ty>2024-09-10 08:35:43 Running JSON-RPC server: addr=127.0.0.1:9945, allowed origins=["http://localhost:*", "http://127.0.0.1:*", "https://localhost:*", "https://127.0.0.1:*", "https://polkadot.js.org"]</span> + <span data-ty>2024-09-10 08:35:48 💤 Idle (0 peers), best: #0 (0x850f…951f), finalized #0 (0x850f…951f), ⬇ 0 ⬆ 0</span> +</div> diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network/node-shutdown.html b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network/node-shutdown.html new file mode 100644 index 000000000..6500822f7 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network/node-shutdown.html @@ -0,0 +1,4 @@ +<div id="termynal" data-termynal> + <span data-ty>2024-09-10 09:10:03 💤 Idle (1 peers), best: #51 (0x0dd6…e763), finalized #49 (0xb70a…1fc0), ⬇ 0.7kiB/s ⬆ 0.6kiB/s</span> + <span data-ty>2024-09-10 09:10:08 💤 Idle (0 peers), best: #52 (0x2c40…a50e), finalized #49 (0xb70a…1fc0), ⬇ 0.3kiB/s ⬆ 0.3kiB/s</span> +</div> diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/config-trait-impl.rs b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/config-trait-impl.rs new file mode 100644 index 000000000..b0f9ca342 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/config-trait-impl.rs @@ -0,0 +1,14 @@ +... +/// Configure the pallet-template in pallets/template +impl pallet_template::Config for Runtime { + ... +} + +// Add here after all the other pallets implementations +impl pallet_utility::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type RuntimeCall = RuntimeCall; + type PalletsOrigin = OriginCaller; + type WeightInfo = pallet_utility::weights::SubstrateWeight<Runtime>; +} +... \ No newline at end of file diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/fs-runtime-macro.rs b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/fs-runtime-macro.rs new file mode 100644 index 000000000..5af557390 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/fs-runtime-macro.rs @@ -0,0 +1,12 @@ +// Create the runtime by composing the FRAME pallets that were previously configured +#[frame_support::runtime] +mod runtime { + ... + // Include the custom logic from the pallet-template in the runtime + #[runtime::pallet_index(7)] + pub type TemplateModule = pallet_template; + + #[runtime::pallet_index(8)] + pub type Utility = pallet_utility; + ... +} \ No newline at end of file diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/runtime-version-macro.rs b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/runtime-version-macro.rs new file mode 100644 index 000000000..3fcd07bf8 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/runtime-version-macro.rs @@ -0,0 +1,11 @@ +#[sp_version::runtime_version] +pub const VERSION: RuntimeVersion = RuntimeVersion { + spec_name: create_runtime_str!("solochain-template-runtime"), + impl_name: create_runtime_str!("solochain-template-runtime"), + authoring_version: 1, + spec_version: 101, + impl_version: 1, + apis: RUNTIME_API_VERSIONS, + transaction_version: 1, + state_version: 1, +}; \ No newline at end of file diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-1.json b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-1.json new file mode 100644 index 000000000..b6ff2c407 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-1.json @@ -0,0 +1,25 @@ +{ + "...": "...", + "relay_chain": "paseo", + "para_id": 4508, + "genesis": { + "runtime": { + "...": {}, + "parachainInfo": { + "parachainId": 4508 + }, + "session": { + "keys": [ + [ + "5HErbKmL5JmUKDVsH1aGyXTGZb4i9iaNsFhSgkNDr8qp2Dvj", + "5HErbKmL5JmUKDVsH1aGyXTGZb4i9iaNsFhSgkNDr8qp2Dvj", + { + "aura": "5HErbKmL5JmUKDVsH1aGyXTGZb4i9iaNsFhSgkNDr8qp2Dvj" + } + ] + ] + } + }, + "...": {} + } +} diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-2.html b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-2.html new file mode 100644 index 000000000..19e9bba40 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-2.html @@ -0,0 +1,7 @@ +<div id="termynal" data-termynal> + <span data-ty="input"><span class="file-path"></span>./target/release/parachain-template-node build-spec --chain plain-parachain-chainspec.json --disable-default-bootnode --raw > raw-parachain-chainspec.json</span> + <br /> + <span data-ty="progress">2024-09-11 09:48:15 Building chain spec</span> + <span data-ty="progress">2024-09-11 09:48:15 assembling new collators for new session 0 at #0</span> + <span data-ty="progress">2024-09-11 09:48:15 assembling new collators for new session 1 at #0</span> +</div> diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-1.rs b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-1.rs new file mode 100644 index 000000000..6c0468616 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-1.rs @@ -0,0 +1,13 @@ +parameter_types! { + pub const ParaDeposit: Balance = 40 * UNITS; +} + +impl paras_registrar::Config for Runtime { + type RuntimeOrigin = RuntimeOrigin; + type RuntimeEvent = RuntimeEvent; + type Currency = Balances; + type OnSwap = (Crowdloan, Slots); + type ParaDeposit = ParaDeposit; + type DataDepositPerByte = DataDepositPerByte; + type WeightInfo = weights::runtime_common_paras_registrar::WeightInfo<Runtime>; +} \ No newline at end of file diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.json b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.json new file mode 100644 index 000000000..b0ac0211a --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.json @@ -0,0 +1,15 @@ +{ + "...": "...", + "relay_chain": "rococo-local", + "para_id": 2000, + "protocolId": "template-local", + "genesis": { + "runtime": { + "...": {}, + "parachainInfo": { + "parachainId": 2000 + } + }, + "...": {} + } +} diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-3.html b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-3.html new file mode 100644 index 000000000..f58a0792a --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-3.html @@ -0,0 +1,5 @@ +<div id="termynal" data-termynal> + <span data-ty="progress">2024-09-10 14:34:58 Building chain spec</span> + <span data-ty="progress">2024-09-10 14:34:59 assembling new collators for new session 0 at #0</span> + <span data-ty="progress">2024-09-10 14:34:59 assembling new collators for new session 1 at #0</span> +</div> diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-4.html b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-4.html new file mode 100644 index 000000000..3f882595b --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-4.html @@ -0,0 +1,3 @@ +<div id="termynal" data-termynal> + <span data-ty="progress">2024-09-10 14:41:13 🔨 Initializing Genesis block/state (state: 0xb089…1830, header-hash: 0x6b0b…bd69)</span> +</div> diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-5.html b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-5.html new file mode 100644 index 000000000..64e01e649 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-5.html @@ -0,0 +1,11 @@ +<div id="termynal" data-termynal> + <span>...</span> + <br /> + <span>2024-09-10 16:26:30 [Parachain] PoV size { header: 0.21875kb, extrinsics: 3.6103515625kb, storage_proof: 3.150390625kb }</span> + <br /> + <span>2024-09-10 16:26:30 [Parachain] Compressed PoV size: 6.150390625kb</span> + <br /> + <span>2024-09-10 16:26:33 [Relaychain] 💤 Idle (2 peers), best: #1729 (0x3aa4…cb6b), finalized #1726 (0xff7a…4352), ⬇ 9.1kiB/s ⬆ 3.8kiB/s</span> + <br /> + <span>...</span> +</div> diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-6.html b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-6.html new file mode 100644 index 000000000..9ed121a02 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-6.html @@ -0,0 +1,25 @@ +<div id="termynal" data-termynal> + <span>...</span> + <br /> + <span>[Relaychain] 💤 Idle (2 peers), best: #90 (0x5f73…1ccf), finalized #87 (0xeb50…68ea), ⬇ 1.4kiB/s ⬆ 1.1kiB/s</span> + <br /> + <span>[Parachain] 💤 Idle (0 peers), best: #0 (0x3626…fef3), finalized #0 (0x3626…fef3), ⬇ 1.2kiB/s ⬆ 0.7kiB/s</span> + <br /> + <span>[Relaychain] 💤 Idle (2 peers), best: #90 (0x5f73…1ccf), finalized #88 (0xd43c…c3e6), ⬇ 0.7kiB/s ⬆ 0.5kiB/s</span> + <br /> + <span>[Parachain] 💤 Idle (0 peers), best: #0 (0x3626…fef3), finalized #0 (0x3626…fef3), ⬇ 1.0kiB/s ⬆ 0.6kiB/s</span> + <br /> + <span>[Relaychain] 👶 New epoch 9 launching at block 0x1c93…4aa9 (block slot 281848325 >= start slot 281848325)</span> + <br /> + <span>[Relaychain] 👶 Next epoch starts at slot 281848335</span> + <br /> + <span>[Relaychain] ✨ Imported #91 (0x1c93…4aa9)</span> + <br /> + <span>[Parachain] Starting collation. relay_parent=0x1c936289cfe15fabaa369f7ae5d73050581cb12b75209c11976afcf07f6a4aa9 at=0x36261113c31019d4b2a1e27d062e186f46da0e8f6786177dc7b35959688ffef3</span> + <br /> + <span>[Relaychain] 💤 Idle (2 peers), best: #91 (0x1c93…4aa9), finalized #88 (0xd43c…c3e6), ⬇ 1.2kiB/s ⬆ 0.7kiB/s</span> + <br /> + <span>[Parachain] 💤 Idle (0 peers), best: #0 (0x3626…fef3), finalized #0 (0x3626…fef3), ⬇ 0.2kiB/s ⬆ 37 B/s</span> + <br /> + <span>...</span> +</div> diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain/relay-chain-1.html b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain/relay-chain-1.html new file mode 100644 index 000000000..601dd4443 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain/relay-chain-1.html @@ -0,0 +1,21 @@ +<div id="termynal" data-termynal> + <span>2024-09-09 13:49:58 Parity Polkadot</span> + <br /> + <span>2024-09-09 13:49:58 ✌️ version 1.15.2-d6f482d5593</span> + <br /> + <span>2024-09-09 13:49:58 ❤️ by Parity Technologies <admin@parity.io>, 2017-2024</span> + <br /> + <span>2024-09-09 13:49:58 📋 Chain specification: Rococo Local Testnet</span> + <br /> + <span>2024-09-09 13:49:58 🏷 Node name: Alice</span> + <br /> + <span>2024-09-09 13:49:58 👤 Role: AUTHORITY</span> + <br /> + <span>2024-09-09 13:49:58 💾 Database: RocksDb at /tmp/relay/alice/chains/rococo_local_testnet/db/full</span> + <br /> + <span>2024-09-09 13:49:59 🏷 Local node identity is: 12D3KooWG393uX82rR3QgDkZpb7U8StzuRx9BQUXCvWsP1ctgygp</span> + <br /> + <span>2024-09-09 13:49:59 Running libp2p network backend</span> + <br /> + <span>...</span> +</div> diff --git a/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain/relay-chain-2.html b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain/relay-chain-2.html new file mode 100644 index 000000000..982b8b333 --- /dev/null +++ b/.snippets/code/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain/relay-chain-2.html @@ -0,0 +1,9 @@ +<div id="termynal" data-termynal> + <span>...</span> + <br /> + <span>2024-09-10 13:29:38 🏆 Imported #55 (0xad6a…567c → 0xecae…ad12)</span> + <br /> + <span>2024-09-10 13:29:38 💤 Idle (1 peers), best: #55 (0xecae…ad12), finalized #0 (0x1cac…618d), ⬇ 2.0kiB/s ⬆ 1.6kiB/s</span> + <br /> + <span>...</span> +</div> diff --git a/.snippets/code/tutorials/tooling/chopsticks/overview/replay-block.json b/.snippets/code/tutorials/tooling/chopsticks/overview/replay-block.json index 21230a01f..3360f1c42 100644 --- a/.snippets/code/tutorials/tooling/chopsticks/overview/replay-block.json +++ b/.snippets/code/tutorials/tooling/chopsticks/overview/replay-block.json @@ -74,10 +74,7 @@ "0x2b06af9719ac64d755623cda8ddd9b94b1c371ded9e9c565e89ba783c4d5f5f9b4def25cfda6ef3a000000006f3d6b177c8acbd8dc9974cdb3cebfac4d31333c30865ff66c35c1bf898df5c5dd2924d3280e7201", "0x9b000000" ], - [ - "0x3a65787472696e7369635f696e646578", - null - ], + ["0x3a65787472696e7369635f696e646578", null], [ "0x3f1467a096bcd71a5b6a0c8155e208103f2edf3bdf381debe331ab7446addfdc", "0x550057381efedcffffffffffffffffff" @@ -146,4 +143,4 @@ "offchainStorageDiff": [], "runtimeLogs": [] } -} \ No newline at end of file +} diff --git a/.snippets/code/tutorials/tooling/chopsticks/overview/terminal/fork-output.html b/.snippets/code/tutorials/tooling/chopsticks/overview/terminal/fork-output.html new file mode 100644 index 000000000..ba045ad8d --- /dev/null +++ b/.snippets/code/tutorials/tooling/chopsticks/overview/terminal/fork-output.html @@ -0,0 +1,29 @@ +<div id="termynal" data-termynal> + <span data-ty="input"><span class="file-path"></span>npx @acala-network/chopsticks xcm \</span> + <span data-ty>--r polkadot \</span> + <span data-ty>--p moonbeam \</span> + <span data-ty>--p astar</span> + <br /> + <span data-ty>[13:46:07.901] INFO: Loading config file https://raw.githubusercontent.com/AcalaNetwork/chopsticks/master/configs/moonbeam.yml</span> + <span data-ty> app: "chopsticks"</span> + <span data-ty>[13:46:12.631] INFO: Moonbeam RPC listening on port 8000</span> + <span data-ty> app: "chopsticks"</span> + <span data-ty>[13:46:12.632] INFO: Loading config file https://raw.githubusercontent.com/AcalaNetwork/chopsticks/master/configs/astar.yml</span> + <span data-ty> app: "chopsticks"</span> + <span data-ty> chopsticks::executor TRACE: Calling Metadata_metadata</span> + <span data-ty> chopsticks::executor TRACE: Completed Metadata_metadata</span> + <span data-ty>[13:46:23.669] INFO: Astar RPC listening on port 8001</span> + <span data-ty> app: "chopsticks"</span> + <span data-ty>[13:46:25.144] INFO (xcm): Connected parachains [2004,2006]</span> + <span data-ty> app: "chopsticks"</span> + <span data-ty>[13:46:25.144] INFO: Loading config file https://raw.githubusercontent.com/AcalaNetwork/chopsticks/master/configs/polkadot.yml</span> + <span data-ty> app: "chopsticks"</span> + <span data-ty> chopsticks::executor TRACE: Calling Metadata_metadata</span> + <span data-ty> chopsticks::executor TRACE: Completed Metadata_metadata</span> + <span data-ty>[13:46:53.320] INFO: Polkadot RPC listening on port 8002</span> + <span data-ty> app: "chopsticks"</span> + <span data-ty>[13:46:54.038] INFO (xcm): Connected relaychain 'Polkadot' with parachain 'Moonbeam'</span> + <span data-ty> app: "chopsticks"</span> + <span data-ty>[13:46:55.028] INFO (xcm): Connected relaychain 'Polkadot' with parachain 'Astar'</span> + <span data-ty> app: "chopsticks"</span> +</div> diff --git a/.snippets/code/tutorials/tooling/chopsticks/overview/terminal/fork-output.md b/.snippets/code/tutorials/tooling/chopsticks/overview/terminal/fork-output.md deleted file mode 100644 index 1b14cce7f..000000000 --- a/.snippets/code/tutorials/tooling/chopsticks/overview/terminal/fork-output.md +++ /dev/null @@ -1,29 +0,0 @@ -<div id="termynal" data-termynal> - <span data-ty="input"><span class="file-path"></span>npx @acala-network/chopsticks xcm \ ---r polkadot \ ---p moonbeam \ ---p astar</span> - <br> - <span data-ty>[13:46:07.901] INFO: Loading config file https://raw.githubusercontent.com/AcalaNetwork/chopsticks/master/configs/moonbeam.yml</span> - <span data-ty> app: "chopsticks"</span> - <span data-ty>[13:46:12.631] INFO: Moonbeam RPC listening on port 8000</span> - <span data-ty> app: "chopsticks"</span> - <span data-ty>[13:46:12.632] INFO: Loading config file https://raw.githubusercontent.com/AcalaNetwork/chopsticks/master/configs/astar.yml</span> - <span data-ty> app: "chopsticks"</span> - <span data-ty> chopsticks::executor TRACE: Calling Metadata_metadata</span> - <span data-ty> chopsticks::executor TRACE: Completed Metadata_metadata</span> - <span data-ty>[13:46:23.669] INFO: Astar RPC listening on port 8001</span> - <span data-ty> app: "chopsticks"</span> - <span data-ty>[13:46:25.144] INFO (xcm): Connected parachains [2004,2006]</span> - <span data-ty> app: "chopsticks"</span> - <span data-ty>[13:46:25.144] INFO: Loading config file https://raw.githubusercontent.com/AcalaNetwork/chopsticks/master/configs/polkadot.yml</span> - <span data-ty> app: "chopsticks"</span> - <span data-ty> chopsticks::executor TRACE: Calling Metadata_metadata</span> - <span data-ty> chopsticks::executor TRACE: Completed Metadata_metadata</span> - <span data-ty>[13:46:53.320] INFO: Polkadot RPC listening on port 8002</span> - <span data-ty> app: "chopsticks"</span> - <span data-ty>[13:46:54.038] INFO (xcm): Connected relaychain 'Polkadot' with parachain 'Moonbeam'</span> - <span data-ty> app: "chopsticks"</span> - <span data-ty>[13:46:55.028] INFO (xcm): Connected relaychain 'Polkadot' with parachain 'Astar'</span> - <span data-ty> app: "chopsticks"</span> -</div> \ No newline at end of file diff --git a/.snippets/code/tutorials/tooling/zombienet/overview/base-example.json b/.snippets/code/tutorials/tooling/zombienet/overview/base-example.json index ca336a2c1..306fb2162 100644 --- a/.snippets/code/tutorials/tooling/zombienet/overview/base-example.json +++ b/.snippets/code/tutorials/tooling/zombienet/overview/base-example.json @@ -4,7 +4,7 @@ "bootnode": false, "provider": "kubernetes", "backchannel": false, - ... + "...": {} }, - ... + "...": {} } diff --git a/.snippets/code/tutorials/tooling/zombienet/overview/base-example.toml b/.snippets/code/tutorials/tooling/zombienet/overview/base-example.toml index fff1b657a..b9d669a28 100644 --- a/.snippets/code/tutorials/tooling/zombienet/overview/base-example.toml +++ b/.snippets/code/tutorials/tooling/zombienet/overview/base-example.toml @@ -3,6 +3,4 @@ timeout = 1000 bootnode = false provider = "kubernetes" backchannel = false -... - - +# ... diff --git a/.snippets/code/tutorials/tooling/zombienet/overview/collator-example.json b/.snippets/code/tutorials/tooling/zombienet/overview/collator-example.json index 1547a6791..a0baec8e7 100644 --- a/.snippets/code/tutorials/tooling/zombienet/overview/collator-example.json +++ b/.snippets/code/tutorials/tooling/zombienet/overview/collator-example.json @@ -1,18 +1,18 @@ { "parachain": { - "id": 100, - "add_to_genesis": true, - "cumulus_based": true, - "genesis_wasm_path": "/path/to/wasm", - "genesis_state_path": "/path/to/state", - "collators": [ - { - "name": "alice", - "image": "polkadot-parachain", - "command": "polkadot-parachain", - ... - }, - ], + "id": 100, + "add_to_genesis": true, + "cumulus_based": true, + "genesis_wasm_path": "/path/to/wasm", + "genesis_state_path": "/path/to/state", + "collators": [ + { + "name": "alice", + "image": "polkadot-parachain", + "command": "polkadot-parachain", + "...": {} + } + ] }, - ... - } \ No newline at end of file + "...": {} +} diff --git a/.snippets/code/tutorials/tooling/zombienet/overview/collator-example.toml b/.snippets/code/tutorials/tooling/zombienet/overview/collator-example.toml index 6da7fdc67..efdf82897 100644 --- a/.snippets/code/tutorials/tooling/zombienet/overview/collator-example.toml +++ b/.snippets/code/tutorials/tooling/zombienet/overview/collator-example.toml @@ -9,4 +9,4 @@ genesis_state_path = "/path/to/state" name = "alice" image = "polkadot-parachain" command = "polkadot-parachain" -... \ No newline at end of file +# ... diff --git a/.snippets/code/tutorials/tooling/zombienet/overview/collator-groups-example.json b/.snippets/code/tutorials/tooling/zombienet/overview/collator-groups-example.json index 48aef41b6..598487102 100644 --- a/.snippets/code/tutorials/tooling/zombienet/overview/collator-groups-example.json +++ b/.snippets/code/tutorials/tooling/zombienet/overview/collator-groups-example.json @@ -11,9 +11,9 @@ "count": 2, "image": "polkadot-parachain", "command": "polkadot-parachain", - ... - }, - ], + "...": {} + } + ] }, - ... -} \ No newline at end of file + "...": {} +} diff --git a/.snippets/code/tutorials/tooling/zombienet/overview/collator-groups-example.toml b/.snippets/code/tutorials/tooling/zombienet/overview/collator-groups-example.toml index 01965c726..09a27e87d 100644 --- a/.snippets/code/tutorials/tooling/zombienet/overview/collator-groups-example.toml +++ b/.snippets/code/tutorials/tooling/zombienet/overview/collator-groups-example.toml @@ -10,4 +10,4 @@ name = "group-1" count = 2 image = "polkadot-parachain" command = "polkadot-parachain" -... \ No newline at end of file +# ... diff --git a/.snippets/code/tutorials/tooling/zombienet/overview/parachain-example.json b/.snippets/code/tutorials/tooling/zombienet/overview/parachain-example.json index 156cc1626..8f7510400 100644 --- a/.snippets/code/tutorials/tooling/zombienet/overview/parachain-example.json +++ b/.snippets/code/tutorials/tooling/zombienet/overview/parachain-example.json @@ -1,11 +1,11 @@ { "parachain": { - "id": 100, - "add_to_genesis": true, - "cumulus_based": true, - "genesis_wasm_path": "/path/to/wasm", - "genesis_state_path": "/path/to/state", - ... + "id": 100, + "add_to_genesis": true, + "cumulus_based": true, + "genesis_wasm_path": "/path/to/wasm", + "genesis_state_path": "/path/to/state", + "...": {} }, - ... -} \ No newline at end of file + "...": {} +} diff --git a/.snippets/code/tutorials/tooling/zombienet/overview/parachain-example.toml b/.snippets/code/tutorials/tooling/zombienet/overview/parachain-example.toml index cb96b3579..7858c54c4 100644 --- a/.snippets/code/tutorials/tooling/zombienet/overview/parachain-example.toml +++ b/.snippets/code/tutorials/tooling/zombienet/overview/parachain-example.toml @@ -4,4 +4,4 @@ add_to_genesis = true cumulus_based = true genesis_wasm_path = "/path/to/wasm" genesis_state_path = "/path/to/state" -... \ No newline at end of file +# ... diff --git a/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-node-groups.json b/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-node-groups.json index b9921be50..5b6f5e928 100644 --- a/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-node-groups.json +++ b/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-node-groups.json @@ -1,5 +1,4 @@ { - ..., "relaychain": { "default_command": "polkadot", "default_image": "polkadot-debug:master", @@ -15,7 +14,7 @@ "args": ["--chain", "rococo-local"] } ], - ... + "...": {} }, - ... -} \ No newline at end of file + "...": {} +} diff --git a/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-node-groups.toml b/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-node-groups.toml index 04169f5e0..03dd7a9f3 100644 --- a/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-node-groups.toml +++ b/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-node-groups.toml @@ -11,4 +11,4 @@ count = 2 image = "polkadot-debug:master" command = "polkadot" args = ["--chain", "rococo-local"] -... \ No newline at end of file +# ... diff --git a/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-nodes.json b/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-nodes.json index f8cbc14fa..9b3357303 100644 --- a/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-nodes.json +++ b/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-nodes.json @@ -1,5 +1,4 @@ { - ..., "relaychain": { "default_command": "polkadot", "default_image": "polkadot-debug:master", @@ -17,8 +16,6 @@ "validator": true, "balance": 1000000000000 } - ], - ... - }, - ... -} \ No newline at end of file + ] + } +} diff --git a/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-nodes.toml b/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-nodes.toml index 396668a6a..30e19d435 100644 --- a/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-nodes.toml +++ b/.snippets/code/tutorials/tooling/zombienet/overview/relaychain-example-nodes.toml @@ -14,4 +14,4 @@ balance = 1000000000000 name = "bob" validator = true balance = 1000000000000 -... \ No newline at end of file +# ... diff --git a/.snippets/code/tutorials/tooling/zombienet/tutorials/spawn-a-basic-network/alice-logs.html b/.snippets/code/tutorials/tooling/zombienet/tutorials/spawn-a-basic-network/alice-logs.html new file mode 100644 index 000000000..9c50e5d1b --- /dev/null +++ b/.snippets/code/tutorials/tooling/zombienet/tutorials/spawn-a-basic-network/alice-logs.html @@ -0,0 +1,26 @@ +<div id="termynal" data-termynal> + <span data-ty="input"><span class="file-path"></span>tail -f /var/folders/f4/7rdt2m9d7j361dm453cpggbm0000gn/T/zombie-75a01b93c92d571f6198a67bcb380fcd_21724-SEzfCidQ1za4/alice.log </span> + <br /> + <span data-ty>2024-08-29 16:03:54 🙌 Starting consensus session on top of parent 0x81bfcf7de46ca0f5c0eca78639dbfa67afa0a22c7f1a98dfc5778449cb0a82f9</span> + <span data-ty>2024-08-29 16:03:54 🎁 Prepared block for proposing at 11 (1 ms) [hash: 0x4ae2c654439a9be25cedd03fb9a091a5be7b53eae82276850e8c7061cb656d26; parent_hash: 0x81bf…82f9; extrinsics (2): [0x469d…d7d3, 0x8dd2…66e8]</span> + <span data-ty>2024-08-29 16:03:54 🔖 Pre-sealed block for proposal at 11. Hash now 0xb74014d0fcd6df55fbe42848e21ddb556aa5f7358c66795e9a5131f0a666dbbc, previously 0x4ae2c654439a9be25cedd03fb9a091a5be7b53eae82276850e8c7061cb656d26.</span> + <span data-ty>2024-08-29 16:03:54 👶 New epoch 1 launching at block 0xb740…dbbc (block slot 287493039 >= start slot 287493039).</span> + <span data-ty>2024-08-29 16:03:54 👶 Next epoch starts at slot 287493049</span> + <span data-ty>2024-08-29 16:03:54 🏆 Imported #11 (0x81bf…82f9 → 0xb740…dbbc)</span> + <span data-ty>2024-08-29 16:03:54 Node uses the following topology indices index_in_gossip_topology=Some(ValidatorIndex(0)) index_in_parachain_authorities=Some(Active(ValidatorIndex(0)))</span> + <span data-ty>2024-08-29 16:03:57 💤 Idle (2 peers), best: #11 (0xb740…dbbc), finalized #8 (0x2282…6f0d), ⬇ 2.7kiB/s ⬆ 2.1kiB/s</span> + <span data-ty>2024-08-29 16:04:00 🏆 Imported #12 (0xb740…dbbc → 0x49f4…fbd8)</span> + <span data-ty>2024-08-29 16:04:02 💤 Idle (2 peers), best: #12 (0x49f4…fbd8), finalized #9 (0x470a…9184), ⬇ 2.4kiB/s ⬆ 2.1kiB/s</span> + <span data-ty>2024-08-29 16:04:06 🙌 Starting consensus session on top of parent 0x49f420d6d1d84031712f8b7535fdcd73fda740e7a1db6c61c4cf35d8aef9fbd8</span> + <span data-ty>2024-08-29 16:04:06 🎁 Prepared block for proposing at 13 (5 ms) [hash: 0xd5cb11f7ebc5ece3f9a6c304ab5f6209f1ba148c334efc0844e76dd0815b4ff9; parent_hash: 0x49f4…fbd8; extrinsics (2): [0x9e7c…30ff, 0x7e55…1806]</span> + <span data-ty>2024-08-29 16:04:06 🔖 Pre-sealed block for proposal at 13. Hash now 0xa5022ff182095544d5db8714b2c10d81c75d8aff53c53515f22fcd7220ce97d5, previously 0xd5cb11f7ebc5ece3f9a6c304ab5f6209f1ba148c334efc0844e76dd0815b4ff9.</span> + <span data-ty>2024-08-29 16:04:06 🏆 Imported #13 (0x49f4…fbd8 → 0xa502…97d5)</span> + <span data-ty>2024-08-29 16:04:06 ♻️ Reorg on #13,0xa502…97d5 to #13,0xb6c8…5c34, common ancestor #12,0x49f4…fbd8</span> + <span data-ty>2024-08-29 16:04:06 🏆 Imported #13 (0x49f4…fbd8 → 0xb6c8…5c34)</span> + <span data-ty>2024-08-29 16:04:07 💤 Idle (2 peers), best: #13 (0xb6c8…5c34), finalized #10 (0x81bf…82f9), ⬇ 4.0kiB/s ⬆ 4.0kiB/s</span> + <span data-ty>2024-08-29 16:04:11 🥩 New Rounds for validator set id: 1 with session_start 11</span> + <span data-ty>2024-08-29 16:04:11 🥩 Concluded mandatory round #11</span> + <span data-ty>2024-08-29 16:04:12 🏆 Imported #14 (0xb6c8…5c34 → 0xb51a…f125)</span> + <span data-ty>2024-08-29 16:04:12 💤 Idle (2 peers), best: #14 (0xb51a…f125), finalized #11 (0xb740…dbbc), ⬇ 2.8kiB/s ⬆ 3.5kiB/s</span> + ... +</div> diff --git a/.snippets/code/tutorials/tooling/zombienet/tutorials/spawn-a-basic-network/spawn-a-basic-network-test-output.html b/.snippets/code/tutorials/tooling/zombienet/tutorials/spawn-a-basic-network/spawn-a-basic-network-test-output.html new file mode 100644 index 000000000..9c0852051 --- /dev/null +++ b/.snippets/code/tutorials/tooling/zombienet/tutorials/spawn-a-basic-network/spawn-a-basic-network-test-output.html @@ -0,0 +1,74 @@ +<div id="test-results" data-termynal> + <table> + <tr> + <td colspan="2">🛎️ Tests are currently running. Results will appear at the end</td> + </tr> + <tr> + <th colspan="2">Test Results</th> + </tr> + <tr> + <td>8/29/2024, 4:34:53 PM</td> + <td>✅ alice: is up (104ms)</td> + </tr> + <tr> + <td colspan="2">2024-08-29 16:34:54 API/INIT: RPC methods not decorated: chainHead_v1_body, chainHead_v1_call, chainHead_v1_continue, chainHead_v1_follow, chainHead_v1_header, chainHead_v1_stopOperation, chainHead_v1_storage, chainHead_v1_unfollow, chainHead_v1_unpin, chainSpec_v1_chainName, chainSpec_v1_genesisHash, chainSpec_v1_properties, transactionWatch_v1_submitAndWatch, transactionWatch_v1_unwatch, transaction_v1_broadcast, transaction_v1_stop</td> + </tr> + <tr> + <td colspan="2">2024-08-29 16:34:54 API/INIT: rococo/1014000: Not decorating unknown runtime apis: 0x6ff52ee858e6c5bd/1, 0x91b1c8b16328eb92/1, 0x9ffb505aa738d69c/1</td> + </tr> + <tr> + <td>8/29/2024, 4:34:56 PM</td> + <td>✅ alice: parachain 100 is registered within 225 seconds (2362ms)</td> + </tr> + <tr> + <td>8/29/2024, 4:34:58 PM</td> + <td>✅ alice: parachain 100 block height is at least 10 within 250 seconds (2037ms)</td> + </tr> + <tr> + <td>8/29/2024, 4:34:58 PM</td> + <td>✅ bob: is up (43ms)</td> + </tr> + <tr> + <td colspan="2">2024-08-29 16:34:58 API/INIT: RPC methods not decorated: chainHead_v1_body, chainHead_v1_call, chainHead_v1_continue, chainHead_v1_follow, chainHead_v1_header, chainHead_v1_stopOperation, chainHead_v1_storage, chainHead_v1_unfollow, chainHead_v1_unpin, chainSpec_v1_chainName, chainSpec_v1_genesisHash, chainSpec_v1_properties, transactionWatch_v1_submitAndWatch, transactionWatch_v1_unwatch, transaction_v1_broadcast, transaction_v1_stop</td> + </tr> + <tr> + <td colspan="2">2024-08-29 16:34:58 API/INIT: rococo/1014000: Not decorating unknown runtime apis: 0x6ff52ee858e6c5bd/1, 0x91b1c8b16328eb92/1, 0x9ffb505aa738d69c/1</td> + </tr> + <tr> + <td>8/29/2024, 4:35:00 PM</td> + <td>✅ bob: parachain 100 is registered within 225 seconds (2206ms)</td> + </tr> + <tr> + <td>8/29/2024, 4:35:02 PM</td> + <td>✅ bob: parachain 100 block height is at least 10 within 250 seconds (2037ms)</td> + </tr> + <tr> + <td>8/29/2024, 4:35:02 PM</td> + <td>✅ alice: reports node_roles is 4 (0ms)</td> + </tr> + <tr> + <td>8/29/2024, 4:35:02 PM</td> + <td>✅ alice: reports sub_libp2p_is_major_syncing is 0 (0ms)</td> + </tr> + <tr> + <td>8/29/2024, 4:35:02 PM</td> + <td>✅ bob: reports node_roles is 4 (1ms)</td> + </tr> + <tr> + <td>8/29/2024, 4:35:02 PM</td> + <td>✅ collator01: reports node_roles is 4 (22ms)</td> + </tr> + <tr> + <td colspan="2">📓 To see the full logs of the nodes please go to:</td> + </tr> + <tr> + <td colspan="2">/var/folders/f4/7rdt2m9d7j361dm453cpggbm0000gn/T/zombie-68b7ea2539c6ce9ad6350d8a88674147_-90400-wSMnGnsj9Gnu/logs</td> + </tr> + <tr> + <th colspan="2">Result: 10/10</th> + </tr> + <tr> + <td colspan="2">exit code 0</td> + </tr> + </table> +</div> diff --git a/develop/application-devs/interact/.pages b/develop/application-devs/interact/.pages index 0dbe45da2..64add0b63 100644 --- a/develop/application-devs/interact/.pages +++ b/develop/application-devs/interact/.pages @@ -1,3 +1,4 @@ title: Interact with the Network nav: - index.md + - 'Node Endpoints': 'endpoints.md' diff --git a/develop/application-devs/interact/endpoints.md b/develop/application-devs/interact/endpoints.md new file mode 100644 index 000000000..44c1bcdfd --- /dev/null +++ b/develop/application-devs/interact/endpoints.md @@ -0,0 +1,78 @@ +--- +title: Node Endpoints +description: List of node endpoints and examples of use. These endpoints can be used for development, RPC, or other purposes for which network access is required. +--- + +# Node Endpoints + +## Introduction + +One may utilize their own node when interacting with the [Polkadot network](https://polkadot.network/){target=\_blank} via [Polkadot.js Apps](https://polkadot.js.org/apps/){target=\_blank} or other user interfaces and programmatic methods. Another option would be to connect to one of the several public endpoints provided by infrastructure and API service providers. For development convenience, [Parity Tech](https://www.parity.io/){target=\_blank} maintains archive nodes for Polkadot, Kusama, and their TestNets with public endpoints. These endpoints can be used with [Polkadot.js API](https://polkadot.js.org/docs/api){target=\_blank} to interact with their respective chains. + +## Network Endpoints + +Endpoints for all production and test networks are available on [Polkadot.js Apps](https://polkadot.js.org/apps/#/accounts){target=\_blank}, sourced from the [endpoints directory](https://github.com/polkadot-js/apps/tree/master/packages/apps-config/src/endpoints){target=\_blank} in the Polkadot.js repository. The community maintains endpoints for the Polkadot and Kusama relay chains, parachains, and the Paseo TestNet. Parity Technologies maintains endpoints for system parachains, as well as the Westend and Rococo test networks, listed below. Please note that [Paseo](https://github.com/paseo-network){target=\_blank} is maintained by the broader community. + + +=== "Polkadot" + + ``` text title="Asset Hub" + wss://polkadot-asset-hub-rpc.polkadot.io + ``` + + ``` text title="Bridge Hub" + wss://polkadot-bridge-hub-rpc.polkadot.io + ``` + + ``` text title="Collectives" + wss://polkadot-collectives-rpc.polkadot.io + ``` + ``` text title="People Chain" + wss://polkadot-people-rpc.polkadot.io + ``` + +=== "Kusama" + + ``` text title="Asset Hub" + wss://kusama-asset-hub-rpc.polkadot.io + ``` + ``` text title="Bridge Hub" + wss://kusama-bridge-hub-rpc.polkadot.io + ``` + ``` text title="Collectives" + wss://kusama-collectives-rpc.polkadot.io + ``` + ``` text title="People Chain" + wss://kusama-people-rpc.polkadot.io + ``` + ``` text title="Coretime Chain" + wss://kusama-coretime-rpc.polkadot.io + ``` + +=== "TestNet" + + ``` text title="Westend" + wss://westend-rpc.polkadot.io + ``` + ``` text title="Rococo" + wss://rococo-rpc.polkadot.io + ``` + ``` text title="Paseo" + wss://paseo-rpc.dwellir.com + ``` + +## Third Party Providers + +There are a number of third-party providers of RPC infrastructure to the Polkadot and Kusama communities, commonly providing access to multiple networks and parachains in a single service. They provide additional services such as higher rate limits, potentially more reliable and scalable service, and additional metrics. + +!!! note + The list of third party RPC endpoints for Polkadot and Kusama is directly fetched from [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer){target=\_blank}. + +- [OnFinality](https://onfinality.io){target=\_blank} +- [Dwellir](https://dwellir.com){target=\_blank} +- [Radium Block](https://radiumblock.com/){target=\_blank} +- [1RPC](https://1rpc.io/){target=\_blank} +- [NOWNodes](https://nownodes.io/){target=\_blank} +- [All That Node](https://www.allthatnode.com/){target=\_blank} +- [SubQuery](https://subquery.network/rpc/list/){target=\_blank} +- [dRPC](https://drpc.org/){target=\_blank} diff --git a/develop/application-devs/interact/light-clients.md b/develop/application-devs/interact/light-clients.md new file mode 100644 index 000000000..5fb24c053 --- /dev/null +++ b/develop/application-devs/interact/light-clients.md @@ -0,0 +1,50 @@ +--- +title: Using Light Clients +description: Information about light client options available in the Polkadot ecosystem and how they simplify interactions with the network. +--- +# Using Light Clients + +## Introduction + +Conventionally, applications use a JSON-RPC protocol for communication between a user interface (UI) and a Polkadot SDK-built node with one of the following approaches: + +- **User controlled nodes** - the UI connects to a node client the user has installed on their machine. These nodes are secure, but installation and maintenance of these nodes tend to be an inconvenience + +- **Publicly accessible nodes** - the UI connects to a third-party-owned publicly accessible node client. While these nodes are more prevalent in their usage as they are convenient to use, they are centralized and insecure + +With the advent of light clients, applications no longer have to rely on RPC nodes. Light clients don't sync entire blocks. Instead, they merely verify the finalized network headers. This option provides a cryptographically robust and less resource-intensive way to interact with and ensure the state of the network. Light clients are also available locally and embedded as part of the application, enabling a trustless solution versus running an RPC node. + +<!-- TODO: add link to chain specification when glossary is merged --> +You can use a light client implementation to connect to a Polkadot SDK-based network, both in and outside the browser, as long as a [chain specification]() for that network is available. + +## Light Client Options + +Popular options for Polkadot ecosystem light clients include: + +- The [Polkadot API (PAPI)](https://papi.how/){target=\_blank} integrates [`smoldot`](https://github.com/smol-dot/smoldot){target=\_blank} as a choice of light client for both browser and server-based implementations + +- [Substrate Connect](https://github.com/paritytech/substrate-connect){target=\_blank} is a browser extension and JavaScript library that enables developers to build application-specific light clients for Polkadot SDK chains + +## Light Client Benefits + +A light client allows for all essential features of the chain, such as fetching data and transferring tokens, but it doesn't store a copy of the entire blockchain or require the trust of remote peers. Light clients fetch the needed data from a node with an associated proof to validate the data. + +=== "Full RPC Node" + + - Complete verification of all blocks of the chain + - Holds all the previous block data and the chain's storage in database + - Installation, maintenance, and execution tend to be exhaustive and require system administration expertise + + +=== "Light Client" + + - Only verifies the authenticity of blocks of the chain + - No database + - No need to provision servers or other DevOps-related maintenance, singificantly reducing initialization time from startup + + +## Resources + +Learn more about light clients and how they help you develop on Polkadot: + +- [What is a light client and why you should care?](https://medium.com/paritytech/what-is-a-light-client-and-why-you-should-care-75f813ae2670){target=\_blank} \ No newline at end of file diff --git a/develop/application-devs/tooling/.pages b/develop/application-devs/tooling/.pages index 19e5de2ad..873708359 100644 --- a/develop/application-devs/tooling/.pages +++ b/develop/application-devs/tooling/.pages @@ -3,3 +3,4 @@ nav: - index.md - chopsticks - zombienet + - asset-transfer-api diff --git a/develop/application-devs/tooling/asset-transfer-api/.pages b/develop/application-devs/tooling/asset-transfer-api/.pages new file mode 100644 index 000000000..cb23f4fbd --- /dev/null +++ b/develop/application-devs/tooling/asset-transfer-api/.pages @@ -0,0 +1,6 @@ +title: Asset Transfer API +hide: false +nav: + - index.md + - 'Overview': 'overview.md' + - 'API Reference': 'reference.md' diff --git a/develop/application-devs/tooling/asset-transfer-api/index.md b/develop/application-devs/tooling/asset-transfer-api/index.md new file mode 100644 index 000000000..836f37f56 --- /dev/null +++ b/develop/application-devs/tooling/asset-transfer-api/index.md @@ -0,0 +1,7 @@ +--- +title: Asset Transfer API +description: Asset Transfer API is a library that simplifies the transfer of assets for Substrate based chains. It provides methods for cross-chain and local transfers. +template: subsection-index-page.html +hide: + - feedback +--- diff --git a/develop/application-devs/tooling/asset-transfer-api/overview.md b/develop/application-devs/tooling/asset-transfer-api/overview.md new file mode 100644 index 000000000..9f0d54667 --- /dev/null +++ b/develop/application-devs/tooling/asset-transfer-api/overview.md @@ -0,0 +1,130 @@ +--- +title: Asset Transfer API +description: Asset Transfer API is a library that simplifies the transfer of assets for Substrate-based chains. It provides methods for cross-chain and local transfers. +--- + +# Asset Transfer API + +## Introduction + +[Asset Transfer API](https://github.com/paritytech/asset-transfer-api){target=_blank}, a tool developed and maintained by [Parity](https://www.parity.io/){target=_blank}, is a specialized library designed to streamline asset transfers for Substrate-based blockchains. This API provides a simplified set of methods for users to: + +- Execute asset transfers to other parachains or locally within the same chain +- Facilitate transactions involving system parachains like Asset Hub (Polkadot and Kusama) + +Using this API, developers can manage asset transfers more efficiently, reducing the complexity of cross-chain transactions and enabling smoother operations within the ecosystem. + +For additional support and information, please reach out through [GitHub Issues](https://github.com/paritytech/asset-transfer-api/issues){target=_blank}. + +## Prerequisites + +Before you begin, ensure you have the following installed: + +- [Node.js](https://nodejs.org/en/){target=_blank} (recommended version 21 or greater) +- Package manager - [npm](https://www.npmjs.com/){target=_blank} should be installed with Node.js by default. Alternatively, you can use other package managers like [Yarn](https://yarnpkg.com/){target=_blank} + +## Install Asset Transfer API + +To use `asset-transfer-api`, you need a TypeScript project. If you don't have one, you can create a new one: + +1. Create a new directory for your project: + + ```bash + mkdir my-asset-transfer-project \ + && cd my-asset-transfer-project + ``` + +2. Initialize a new TypeScript project: + + ```bash + npm init -y \ + && npm install typescript ts-node @types/node --save-dev \ + && npx tsc --init + ``` + +Once you have a project set up, you can install the `asset-transfer-api` package: + +```bash +npm install @substrate/asset-transfer-api@{{dependencies.asset_transfer_api.version}} +``` + +!!!note + This documentation covers version `{{dependencies.asset_transfer_api.version}}` of Asset Transfer API. + +## Set Up Asset Transfer API + +To initialize the Asset Transfer API, you need three key components: + +- A Polkadot.js API instance +- The `specName` of the chain +- The XCM version to use + +<!-- You can set up the API in two ways. Choose the option that best fits your project's structure and requirements. Both methods will result in a fully initialized AssetTransferApi instance ready for use: + +### Using an Existing Polkadot.js API + +If you already have an initialized Polkadot.js API instance, you can use it to set up the Asset Transfer API: + +```ts +// Assuming 'api' is your initialized Polkadot.js API instance +const { specName } = await api.rpc.state.getRuntimeVersion(); +const safeXcmVersion = await fetchSafeXcmVersion(api); + +const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion); +``` +--> + +### Using Helper Function from Library + +For a simpler setup process, you can leverage the `constructApiPromise` helper function provided by the library. It not only constructs a Polkadot.js `ApiPromise` but also automatically retrieves the chain's `specName` and fetches a safe XCM version. By using this function, developers can significantly reduce boilerplate code and potential configuration errors, making the initial setup both quicker and more robust. + +<!-- This method automatically initializes the Polkadot.js API, retrieves the specName, and determines the safe XCM version. --> + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/overview/setup.ts' +``` + +!!!note + The code examples are enclosed in an async main function to provide the necessary asynchronous context. However, you can use the code directly if you're already working within an async environment. The key is to ensure you're in an async context when working with these asynchronous operations, regardless of your specific setup. + +## Asset Transfer API Reference + +For detailed information on the Asset Transfer API, including available methods, data types, and functionalities, refer to the [Asset Transfer API Reference](/develop/application-devs/tooling/asset-transfer-api/reference) section. This resource provides in-depth explanations and technical specifications to help you integrate and utilize the API effectively. + +## Examples + +### Relay to System Parachain Transfer + +This example demonstrates how to initiate a cross-chain token transfer from a relay chain to a system parachain. Specifically, 1 WND will be transferred from a Westend (relay chain) account to a Westmint (system parachain) account. + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.ts' +``` + +After running the script, you'll see the following output in the terminal, which shows the call data for the cross-chain transfer and its decoded extrinsic details: + +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/overview/relayToSystem.md' + +### Local Parachain Transfer + +The following example demonstrates a local GLMR transfer within Moonbeam, using the `balances` pallet. It transfers 1 GLMR token from one account to another account, where both the sender and recipient accounts are located on the same parachain. + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.ts' +``` + +Upon executing this script, the terminal will display the following output, illustrating the encoded extrinsic for the cross-chain message and its corresponding decoded format: + +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/overview/localParachainTx.md' + +### Parachain to Parachain Transfer + +This example demonstrates creating a cross-chain asset transfer between two parachains. It shows how to send vMOVR and vBNC from a Moonriver account to a Bifrost Kusama account using the safe XCM version. It connects to Moonriver, initializes the API, and uses the `createTransferTransaction` method to prepare a transaction. + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.ts' +``` + +After running this script, you'll see the following output in your terminal. This output presents the encoded extrinsic for the cross-chain message, along with its decoded format, providing a clear view of the transaction details. + +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/overview/paraToPara.md' \ No newline at end of file diff --git a/develop/application-devs/tooling/asset-transfer-api/reference.md b/develop/application-devs/tooling/asset-transfer-api/reference.md new file mode 100644 index 000000000..5ba57557c --- /dev/null +++ b/develop/application-devs/tooling/asset-transfer-api/reference.md @@ -0,0 +1,266 @@ +--- +title: Asset Transfer API Reference +description: Explore the Asset Transfer API Reference for comprehensive details on methods, data types, and functionalities. Essential for cross-chain asset transfers. +--- + +# Asset Transfer API Reference + +<br> +<div class="grid cards" markdown> +- :octicons-download-16:{ .lg .middle } __Install the Asset Transfer API__ + + --- + + Learn how to install [`asset-transfer-api`](https://github.com/paritytech/asset-transfer-api){target=\_blank} into a new or existing project. + + <br> + [:octicons-arrow-right-24: Get started](../asset-transfer-api/overview.md) + +- :octicons-code-16:{ .lg .middle } __Dive in with a tutorial__ + + --- + + Ready to start coding? Follow along with a step-by-step tutorial. + + <br> + [:octicons-arrow-right-24: How to use the Asset Transfer API](../asset-transfer-api/overview.md/#examples) +</div> +<br> + + +## Asset Transfer API Class + +Holds open an API connection to a specified chain within the `ApiPromise` to help construct transactions for assets and estimate fees. + +For a more in-depth explanation of the Asset Transfer API class structure, check the [source code](https://github.com/paritytech/asset-transfer-api/blob/f2aa50db83882f23492f975221dd5501c35a26d5/src/AssetTransferApi.ts#L106){target=_blank}. + +### Methods + +#### Create Transfer Transaction + +Generates an XCM transaction for transferring assets between chains. It simplifies the process by inferring what type of transaction is required given the inputs, ensuring that the assets are valid, and that the transaction details are correctly formatted. + +After obtaining the transaction, you must handle the signing and submission process separately. + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-fn-signature.ts' +``` + +??? interface "Request parameters" + + `destChainId` ++"string"++ <span class="required" markdown>++"required"++</span> + + ID of the destination chain (`'0'` for relay chain, other values for parachains). + + --- + + `destAddr` ++"string"++ <span class="required" markdown>++"required"++</span> + + Address of the recipient account on the destination chain. + + --- + + `assetIds` ++"string[]"++ <span class="required" markdown>++"required"++</span> + + Array of asset IDs to be transferred. + + When asset IDs are provided, the API dynamically selects the appropriate pallet for the current chain to handle these specific assets. If the array is empty, the API defaults to using the `balances` pallet. + + --- + + `amounts` ++"string[]"++ <span class="required" markdown>++"required"++</span> + + Array of amounts corresponding to each asset in `assetIds`. + + --- + + `opts` ++"TransferArgsOpts<T>"++ + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/transfer-arg-opts.md' + +??? interface "Response parameters" + + ++"Promise<TxResult<T>>"++ + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/tx-result.md' + +??? interface "Example" + + ***Request*** + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-request.ts' + ``` + + ***Response*** + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ctt-example-response.md' + +#### Claim Assets + +Creates a local XCM transaction to retrieve trapped assets. This function can be used to claim assets either locally on a system parachain, on the relay chain, or on any chain that supports the `claimAssets` runtime call. + + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ca-fn-signature.ts' +``` + +??? interface "Request parameters" + + `assetIds` ++"string[]"++ <span class="required" markdown>++"required"++</span> + + Array of asset IDs to be claimed from the `AssetTrap`. + + --- + + `amounts` ++"string[]"++ <span class="required" markdown>++"required"++</span> + + Array of amounts corresponding to each asset in `assetIds`. + + --- + + `beneficiary` ++"string"++ <span class="required" markdown>++"required"++</span> + + Address of the account to receive the trapped assets. + + --- + + `opts` ++"TransferArgsOpts<T>"++ + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/transfer-arg-opts.md' + +??? interface "Response parameters" + + ++"Promise<TxResult<T>>"++ + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/tx-result.md' + +??? interface "Example" + + ***Request*** + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-request.ts' + ``` + + ***Response*** + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ca-example-response.md' + + +#### Decode Extrinsic + +Decodes the hex of an extrinsic into a string readable format. + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/de-fn-signature.ts' +``` + +??? interface "Request parameters" + + `encodedTransaction` ++"string"++ <span class="required" markdown>++"required"++</span> + + A hex encoded extrinsic. + + --- + + `format` ++"T extends Format"++ <span class="required" markdown>++"required"++</span> + + Specifies the format for returning a transaction. + + ??? child "Type `Format`" + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/format.ts' + ``` + +??? interface "Response parameters" + + ++"string"++ + + Decoded extrinsic in string readable format. + +??? interface "Example" + + ***Request*** + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-request.ts' + ``` + + ***Response*** + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/de-example-response.md' + +#### Fetch Fee Info + +Fetch estimated fee information for an extrinsic. + +```ts +--8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-fn-signature.ts' +``` + +??? interface "Request parameters" + + `tx` ++"ConstructedFormat<T>"++ <span class="required" markdown>++"required"++</span> + + The constructed transaction. + + ??? child "Type `ConstructedFormat<T>`" + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/constructed-format.md' + + --- + + `format` ++"T extends Format"++ <span class="required" markdown>++"required"++</span> + + Specifies the format for returning a transaction. + + ??? child "Type `Format`" + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/format.ts' + ``` + +??? interface "Response parameters" + + ++"Promise<RuntimeDispatchInfo | RuntimeDispatchInfoV1 | null>"++ + + A promise containing the estimated fee information for the provided extrinsic. + + ??? child "Type `RuntimeDispatchInfo`" + + ```ts + export interface RuntimeDispatchInfo extends Struct { + readonly weight: Weight; + readonly class: DispatchClass; + readonly partialFee: Balance; + } + ``` + + For more information on the underlying types and fields of `RuntimeDispatchInfo`, check the [RuntimeDispatchInfo](https://github.com/polkadot-js/api/blob/2329af239eaf194696daeaa58ebf89f0080a5e0d/packages/types/src/interfaces/payment/types.ts#L21){target=_blank} source code. + + + ??? child "Type `RuntimeDispatchInfoV1`" + + ```ts + export interface RuntimeDispatchInfoV1 extends Struct { + readonly weight: WeightV1; + readonly class: DispatchClass; + readonly partialFee: Balance; + } + ``` + + For more information on the underlying types and fields of `RuntimeDispatchInfoV1`, check the [RuntimeDispatchInfoV1](https://github.com/polkadot-js/api/blob/2329af239eaf194696daeaa58ebf89f0080a5e0d/packages/types/src/interfaces/payment/types.ts#L28){target=_blank} source code. + +??? interface "Example" + + ***Request*** + + ```ts + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-request.ts' + ``` + + ***Response*** + + --8<-- 'code/develop/application-devs/tooling/asset-transfer-api/reference/ffi-example-response.md' \ No newline at end of file diff --git a/develop/application-devs/tooling/chopsticks/overview.md b/develop/application-devs/tooling/chopsticks/overview.md index 7280f860a..a2f5fdd03 100644 --- a/develop/application-devs/tooling/chopsticks/overview.md +++ b/develop/application-devs/tooling/chopsticks/overview.md @@ -226,7 +226,7 @@ npx @acala-network/chopsticks xcm \ After running it, you should see output similar to the following: ---8<-- 'code/tutorials/tooling/chopsticks/overview/terminal/fork-output.md' +--8<-- 'code/tutorials/tooling/chopsticks/overview/terminal/fork-output.html' Now you can interact with your forked chains using the ports specified in the output. diff --git a/develop/application-devs/tooling/zombienet/tutorials/spawn-a-basic-network.md b/develop/application-devs/tooling/zombienet/tutorials/spawn-a-basic-network.md index b9d77f4b4..90c2bc91b 100644 --- a/develop/application-devs/tooling/zombienet/tutorials/spawn-a-basic-network.md +++ b/develop/application-devs/tooling/zombienet/tutorials/spawn-a-basic-network.md @@ -191,7 +191,11 @@ To check the nodes’ logs, you can use the provided command listed by the outpu tail -f /var/folders/f4/7rdt2m9d7j361dm453cpggbm0000gn/T/zombie-75a01b93c92d571f6198a67bcb380fcd_21724-SEzfCidQ1za4/alice.log ``` -After running this command, you will see the logs of the `alice` node in real-time, which can be useful for debugging purposes. The logs of the `bob` and `collator01` nodes can be checked similarly. +After running this command, you will see the logs of the `alice` node in real-time, which can be useful for debugging purposes. The logs will be displayed in the terminal in the following format: + +--8<-- 'code/tutorials/tooling/zombienet/tutorials/spawn-a-basic-network/alice-logs.html' + +The logs of the `bob` and `collator01` nodes can be checked similarly. ## Running a Test @@ -234,4 +238,6 @@ To run the test, execute the following command: zombienet -p native test spawn-a-basic-network-test.zndsl ``` -This command will execute the test scenario defined in the `spawn-a-basic-network-test.zndsl` file on the network. If successful, the terminal will display the test output, indicating whether the test passed or failed. \ No newline at end of file +This command will execute the test scenario defined in the `spawn-a-basic-network-test.zndsl` file on the network. If successful, the terminal will display the test output, indicating whether the test passed or failed. For example, the following output shows the test results for the basic network: + +--8<-- 'code/tutorials/tooling/zombienet/tutorials/spawn-a-basic-network/spawn-a-basic-network-test-output.html' \ No newline at end of file diff --git a/develop/parachain-devs/get-started/polkadot-sdk/.pages b/develop/parachain-devs/get-started/polkadot-sdk/.pages index 7ad7de401..b49cc167c 100644 --- a/develop/parachain-devs/get-started/polkadot-sdk/.pages +++ b/develop/parachain-devs/get-started/polkadot-sdk/.pages @@ -1,3 +1,4 @@ title: Polkadot SDK nav: - index.md + - 'Install Polkadot SDK Dependencies': install-deps.md diff --git a/develop/parachain-devs/get-started/polkadot-sdk/install-deps.md b/develop/parachain-devs/get-started/polkadot-sdk/install-deps.md new file mode 100644 index 000000000..620c3865f --- /dev/null +++ b/develop/parachain-devs/get-started/polkadot-sdk/install-deps.md @@ -0,0 +1,336 @@ +--- +title: Install Polkadot SDK Dependencies +description: Install everything you need to begin working with Substrated-based blockchains and the Polkadot SDK, the framework for building blockchains. +--- + +# Install Dependencies for the Polkadot SDK + +This guide provides step-by-step instructions for installing the dependencies you need to work with the Polkadot SDK and Substrate-based chains and their required dependencies on macOS, Linux, and Windows. Follow the appropriate section for your operating system to ensure all necessary tools are installed and configured properly. + +## macOS + +You can install Rust and set up a Substrate development environment on Apple macOS computers with Intel or Apple M1 processors. + +### Before You Begin + +Before you install Rust and set up your development environment on macOS, verify that your computer meets the following basic requirements: + +- Operating system version is 10.7 Lion or later +- Processor speed of at least 2 GHz. Note that 3 GHz is recommended +- Memory of at least 8 GB RAM. Note that 16 GB is recommended +- Storage of at least 10 GB of available space +- Broadband Internet connection + +#### Install Homebrew + +In most cases, you should use Homebrew to install and manage packages on macOS computers. If you don't already have Homebrew installed on your local computer, you should download and install it before continuing. + +To install Homebrew: + +1. Open the Terminal application + +2. Download and install Homebrew by running the following command: + + ```bash + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" + ``` + +3. Verify Homebrew has been successfully installed by running the following command: + + ```bash + brew --version + ``` + + The command displays output similar to the following: + + --8<-- 'code/develop/parachain-devs/get-started/polkadot-sdk/install-deps/termynal-1.html' + +#### Support for Apple Silicon + +Protobuf must be installed before the build process can begin. To install it, run the following command: + +```bash +brew install protobuf +``` + +### Install Required Packages and Rust + +Because the blockchain requires standard cryptography to support the generation of public/private key pairs and the validation of transaction signatures, you must also have a package that provides cryptography, such as `openssl`. + +To install `openssl` and the Rust toolchain on macOS: + +1. Open the Terminal application + +2. Ensure you have an updated version of Homebrew by running the following command: + + ```bash + brew update + ``` + +3. Install the `openssl` package by running the following command: + + ```bash + brew install openssl + ``` + +4. Download the `rustup` installation program and use it to install Rust by running the following + command: + + ```bash + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +5. Follow the prompts displayed to proceed with a default installation + +6. Update your current shell to include Cargo by running the following command: + + ```bash + source ~/.cargo/env + ``` + +7. Configure the Rust toolchain to default to the latest stable version by running the following + commands: + + ```bash + rustup default stable + rustup update + rustup target add wasm32-unknown-unknown + ``` + +8. Add the `nightly` release and the `nightly` Wasm targets to your development + environment by running the following commands: + + ```bash + rustup update nightly + rustup target add wasm32-unknown-unknown --toolchain nightly + ``` + +9. [Verify your installation](#verifying-installation) + +10. Install `cmake` using the following command: + + ```bash + brew install cmake + ``` + +## Linux + +Rust supports most Linux distributions. Depending on the specific distribution and version of the operating system you use, you might need to add some software dependencies to your environment. In general, your development environment should include a linker or C-compatible compiler, such as `clang` and an appropriate integrated development environment (IDE). + +### Before You Begin {: #before-you-begin-linux } + +Check the documentation for your operating system for information about the installed packages and how to download and install any additional packages you might need. For example, if you use Ubuntu, you can use the Ubuntu Advanced Packaging Tool (`apt`) to install the `build-essential` package: + +```bash +sudo apt install build-essential +``` + +At a minimum, you need the following packages before you install Rust: + +```text +clang curl git make +``` + +Because the blockchain requires standard cryptography to support the generation of public/private key pairs and the validation of transaction signatures, you must also have a package that provides cryptography, such as `libssl-dev` or `openssl-devel`. + +### Install Required Packages and Rust {: #install-required-packages-and-rust-linux } + +To install the Rust toolchain on Linux: + +1. Open a terminal shell + +2. Check the packages you have installed on the local computer by running an appropriate package management command for your Linux distribution + +3. Add any package dependencies you are missing to your local development environment by running the appropriate package management command for your Linux distribution: + + === "Ubuntu" + + ```bash + sudo apt install --assume-yes git clang curl libssl-dev protobuf-compiler + ``` + + === "Debian" + + ```sh + sudo apt install --assume-yes git clang curl libssl-dev llvm libudev-dev make protobuf-compiler + ``` + + === "Arch" + + ```sh + pacman -Syu --needed --noconfirm curl git clang make protobuf + ``` + + === "Fedora" + + ```sh + sudo dnf update + sudo dnf install clang curl git openssl-devel make protobuf-compiler + ``` + + === "OpenSUSE" + + ```sh + sudo zypper install clang curl git openssl-devel llvm-devel libudev-devel make protobuf + ``` + + Remember that different distributions might use different package managers and bundle packages in different ways. For example, depending on your installation selections, Ubuntu Desktop and Ubuntu Server might have different packages and different requirements. However, the packages listed in the command-line examples are applicable for many common Linux distributions, including Debian, Linux Mint, MX Linux, and Elementary OS. + +4. Download the `rustup` installation program and use it to install Rust by running the following command: + + ```bash + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +5. Follow the prompts displayed to proceed with a default installation + +6. Update your current shell to include Cargo by running the following command: + + ```bash + source $HOME/.cargo/env + ``` + +7. Verify your installation by running the following command: + + ```bash + rustc --version + ``` + +8. Configure the Rust toolchain to default to the latest stable version by running the following commands: + + ```bash + rustup default stable + rustup update + ``` + +9. Add the `nightly` release and the `nightly` Wasm targets to your development environment by running the following commands: + + ```bash + rustup update nightly + rustup target add wasm32-unknown-unknown --toolchain nightly + ``` + +10. [Verify your installation](#verifying-installation) + +## Windows (WSL) + +In general, UNIX-based operating systems—like macOS or Linux—provide a better development environment for building Substrate-based blockchains. + +However, suppose your local computer uses Microsoft Windows instead of a UNIX-based operating system. In that case, you can configure it with additional software to make it a suitable development environment for building Substrate-based blockchains. To prepare a development environment on a Microsoft Windows computer, you can use Windows Subsystem for Linux (WSL) to emulate a UNIX operating environment. + +### Before You Begin {: #before-you-begin-windows } + +Before installing on Microsoft Windows, verify the following basic requirements: + +- You have a computer running a supported Microsoft Windows operating system: + - **For Windows desktop** - you must be running Microsoft Windows 10, version 2004 or later, or Microsoft Windows 11 to install WSL + - **For Windows server** - you must be running Microsoft Windows Server 2019, or later, to install WSL on a server operating system +- You have good internet connection and access to a shell terminal on your local computer + +### Set Up Windows Subsystem for Linux + +WSL enables you to emulate a Linux environment on a computer that uses the Windows operating system. The primary advantage of this approach for Substrate development is that you can use all of the code and command-line examples as described in the Substrate documentation. For example, you can run common commands—such as `ls` and `ps`—unmodified. By using WSL, you can avoid configuring a virtual machine image or a dual-boot operating system. + +To prepare a development environment using WSL: + +1. Check your Windows version and build number to see if WSL is enabled by default. + + If you have Microsoft Windows 10, version 2004 (Build 19041 and higher), or Microsoft Windows 11, WSL is available by default and you can continue to the next step. + + If you have an older version of Microsoft Windows installed, see the [WSL manual installation steps for older versions](https://docs.microsoft.com/en-us/windows/wsl/install-manual){target=\_blank}. If you are installing on an older version of Microsoft Windows, you can download and install WLS 2 if your computer has Windows 10, version 1903 or higher + +2. Select **Windows PowerShell** or **Command Prompt** from the **Start** menu, right-click, then **Run as administrator** + +3. In the PowerShell or Command Prompt terminal, run the following command: + + ```bash + wsl --install + ``` + + This command enables the required WSL 2 components that are part of the Windows operating system, downloads the latest Linux kernel, and installs the Ubuntu Linux distribution by default. + + If you want to review the other Linux distributions available, run the following command: + + ```bash + wsl --list --online + ``` + +4. After the distribution is downloaded, close the terminal + +5. Click the **Start** menu, select **Shut down or sign out**, then click **Restart** to restart the + computer. + + Restarting the computer is required to start the installation of the Linux distribution. It can take a few minutes for the installation to complete after you restart. + + For more information about setting up WSL as a development environment, see the [Set up a WSL development environment](https://docs.microsoft.com/en-us/windows/wsl/setup/environment){target=\_blank} docs + +### Install Required Packages and Rust {: #install-required-packages-and-rust-windows } + +To install the Rust toolchain on WSL: + +1. Click the **Start** menu, then select **Ubuntu** + +2. Type a UNIX user name to create user account + +3. Type a password for your UNIX user, then retype the password to confirm it + +4. Download the latest updates for the Ubuntu distribution using the Ubuntu Advanced Packaging Tool (`apt`) by running the following command: + + ```bash + sudo apt update + ``` + +5. Add the required packages for the Ubuntu distribution by running the following command: + + ```bash + sudo apt install --assume-yes git clang curl libssl-dev llvm libudev-dev make protobuf-compiler + ``` + +6. Download the `rustup` installation program and use it to install Rust for the Ubuntu distribution by running the following command: + + ```bash + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +7. Follow the prompts displayed to proceed with a default installation + +8. Update your current shell to include Cargo by running the following command: + + ```bash + source ~/.cargo/env + ``` + +9. Verify your installation by running the following command: + + ```bash + rustc --version + ``` + +10. Configure the Rust toolchain to use the latest stable version as the default toolchain by running the following commands: + + ```bash + rustup default stable + rustup update + ``` + +11. Add the `nightly` version of the toolchain and the `nightly` Wasm target to your development environment by running the following commands: + + ```bash + rustup update nightly + rustup target add wasm32-unknown-unknown --toolchain nightly + ``` + +12. [Verify your installation](#verifying-installation) + +## Verifying Installation + +Verify the configuration of your development environment by running the following command: + +```bash +rustup show +rustup +nightly show +``` + +The command displays output similar to the following: + +--8<-- 'code/develop/parachain-devs/get-started/polkadot-sdk/install-deps/termynal-2.html' diff --git a/develop/parachain-devs/interoperability/.pages b/develop/parachain-devs/interoperability/.pages index 3d01b25ba..d5f77eeaa 100644 --- a/develop/parachain-devs/interoperability/.pages +++ b/develop/parachain-devs/interoperability/.pages @@ -1,3 +1,4 @@ title: Interoperability nav: - index.md + - hrmp-channels diff --git a/develop/parachain-devs/interoperability/hrmp-channels/.pages b/develop/parachain-devs/interoperability/hrmp-channels/.pages new file mode 100644 index 000000000..05df7ec31 --- /dev/null +++ b/develop/parachain-devs/interoperability/hrmp-channels/.pages @@ -0,0 +1,7 @@ +title: HRMP Channels +hide: false +nav: + - index.md + - 'Overview': 'overview.md' + - 'Opening HRMP Channels Between Parachains': 'para-to-para.md' + - 'Opening HRMP Channels with System Parachains': 'para-to-system.md' diff --git a/develop/parachain-devs/interoperability/hrmp-channels/index.md b/develop/parachain-devs/interoperability/hrmp-channels/index.md new file mode 100644 index 000000000..836c4f0f1 --- /dev/null +++ b/develop/parachain-devs/interoperability/hrmp-channels/index.md @@ -0,0 +1,7 @@ +--- +title: HRMP Channels +description: HRMP channels enable cross-chain communication in Polkadot, a temporary solution before the more efficient XCMP protocol is implemented. +template: subsection-index-page.html +hide: + - feedback +--- diff --git a/develop/parachain-devs/interoperability/hrmp-channels/overview.md b/develop/parachain-devs/interoperability/hrmp-channels/overview.md new file mode 100644 index 000000000..8a9c04140 --- /dev/null +++ b/develop/parachain-devs/interoperability/hrmp-channels/overview.md @@ -0,0 +1,56 @@ +--- +title: HRMP Channels +description: Discover Horizontal Relay-routed Message Passing (HRMP) channels in Polkadot. Learn how parachains establish and use these channels for interoperability. +--- + +# HRMP Channels + +## Introduction + +Polkadot is designed to enable seamless interoperability between its connected parachains. At the core of this interoperability is the [Cross-Consensus Message Format (XCM)](https://wiki.polkadot.network/docs/learn-xcm), a standard language that allows parachains to communicate and interact with each other. + +The network-layer protocol responsible for delivering XCM-formatted messages between parachains is the Cross-Chain Message Passing (XCMP) protocol. XCMP maintains messaging queues on the relay chain, serving as a bridge to facilitate cross-chain interactions. + +As XCMP is still under development, Polkadot has implemented a temporary alternative called Horizontal Relay-routed Message Passing (HRMP). HRMP offers the same interface and functionality as the planned XCMP but it has a crucial difference, it stores all messages directly in the relay chain’s storage, which is more resource-intensive. + +Once XCMP is fully implemented, HRMP will be deprecated in favor of the native XCMP protocol. XCMP will offer a more efficient and scalable solution for cross-chain message passing, as it will not require the relay chain to store all the messages. + +## Establishing HRMP Channels + +To enable communication between parachains using the HRMP protocol, the parachains must explicitly establish communication channels by registering them on the relay chain. + +Downward and upward channels from and to the relay chain are implicitly available, meaning they do not need to be explicitly opened. + +Opening an HRMP channel requires the parachains involved to make a deposit on the relay chain. This deposit serves a specific purpose, it covers the costs associated with using the relay chain's storage for the message queues linked to the channel. The amount of this deposit varies based on parameters defined by the specific relay chain being used. + +### Relay Chain Parameters + +The Polkadot relay chain utilizes a set of configurable parameters that govern all aspects of runtime configuration with respect to parachains. Key parameters include `hrmpSenderDeposit`, `hrmpRecipientDeposit`, `hrmpChannelMaxMessageSize` and `hrmpChannelMaxCapacity`. For a complete list of parameters, consult the [`HostConfiguration`](https://paritytech.github.io/polkadot-sdk/master/polkadot_runtime_parachains/configuration/struct.HostConfiguration.html#){target=\_blank} struct in the Polkadot SDK documentation. + +When a parachain wants to open a new channel, it must consider these parameter values to ensure the channel is configured correctly. + +To view the current values of these parameters in the Polkadot network: + +1. Visit [Polkadot.js Apps](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fpolkadot.api.onfinality.io%2Fpublic-ws#/explorer), navigate to the **Developer** dropdown and select the **Chain state** option + + ![](/images/develop/parachain-devs/interoperability/hrmp-channels/overview/hrmp-overview-1.webp) + +2. Query the chain configuration parameters. The result will display the current settings for all the Polkadot network parameters, including the HRMP channel settings + 1. Select **configuration** + 2. Choose the **activeConfig()** call + 3. Click the **+** button to execute the query + 4. Check the chain configuration + + ![](/images/develop/parachain-devs/interoperability/hrmp-channels/overview/hrmp-overview-2.webp) + +### Dispatching Extrinsics + +Establishing new HRMP channels between parachains requires dispatching specific extrinsic calls on the Polkadot relay chain from the parachain's origin. + +The most straightforward approach is to implement the channel opening logic off-chain, then use the XCM pallet's `send` extrinsic to submit the necessary instructions to the relay chain. However, the ability to send arbitrary programs through the `Transact` instruction in XCM is typically restricted to privileged origins, such as the `sudo` pallet or governance mechanisms. + +Parachain developers have a few options for triggering the required extrinsic calls from their parachain's origin, depending on the configuration and access controls defined: + +- **Sudo** - if the parachain has a `sudo` pallet configured, the sudo key holder can use the sudo extrinsic to dispatch the necessary channel opening calls +- **Governance** - the parachain's governance system, such as a council or OpenGov, can be used to authorize the channel opening calls +- **Privileged Accounts** - the parachain may have other designated privileged accounts that are allowed to dispatch the HRMP channel opening extrinsics \ No newline at end of file diff --git a/develop/parachain-devs/interoperability/hrmp-channels/para-to-para.md b/develop/parachain-devs/interoperability/hrmp-channels/para-to-para.md new file mode 100644 index 000000000..cff7a8f2f --- /dev/null +++ b/develop/parachain-devs/interoperability/hrmp-channels/para-to-para.md @@ -0,0 +1,181 @@ +--- +title: Opening HRMP Channels Between Parachains +description: Learn how to open HRMP channels between parachains on Polkadot. Discover the step-by-step process for establishing uni- and bidirectional communication. +--- + +# Opening HRMP Channels Between Parachains + +## Introduction + +For establishing communication channels between parachains on the Polkadot network using the Horizontal Relay-routed Message Passing (HRMP) protocol, the following steps are required: + +1. **Channel request** - the parachain that wants to open an HRMP channel must make a request to the parachain it wishes to have an open channel with +2. **Channel acceptance** - the other parachain must then accept this request to complete the channel establishment + +This process results in a unidirectional HRMP channel, where messages can flow in only one direction between the two parachains. + +An additional HRMP channel must be established in the opposite direction to enable bidirectional communication. This requires repeating the request and acceptance process but with the parachains reversing their roles. + +Once both unidirectional channels are established, the parachains can send messages back and forth freely through the bidirectional HRMP communication channel. + +## Prerequisites + +Before proceeding, ensure you meet the following requirements: + +- Network with a relay chain and at least two connected parachains +- Wallet with sufficient funds to execute transactions on the participant chains + +## Procedure for Initiating HRMP Channel Setup + +This example will demonstrate how to open a channel between parachain 2500 and parachain 2600, using Rococo Local as the relay chain. + +### Fund Sender Sovereign Account +<!-- This content will be moved to a new page because it is used in multiple places --> +The [sovereign account](https://github.com/polkadot-fellows/xcm-format/blob/10726875bd3016c5e528c85ed6e82415e4b847d7/README.md?plain=1#L50){target=_blank} for parachain 2500 on the relay chain must be funded so it can take care of any XCM transact fees. + +Use [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer){target=\_blank} UI to connect to the relay chain and transfer funds from your account to the parachain 2500 sovereign account. +![](/images/develop/parachain-devs/interoperability/hrmp-channels/hrmp-channels-2.webp) + +??? note "Calculating Parachain Sovereign Account" + To generate the sovereign account address for a parachain, you'll need to follow these steps: + + 1. Determine if the parachain is an "up/down" chain (parent or child) or a "sibling" chain: + + - Up/down chains use the prefix `0x70617261` (which decodes to `b"para"`) + + - Sibling chains use the prefix `0x7369626c` (which decodes to `b"sibl"`) + + 2. Calculate the u32 scale encoded value of the parachain ID: + - Parachain 2500 would be encoded as `c4090000` + + 3. Combine the prefix and parachain ID encoding to form the full sovereign account address: + + The sovereign account of parachain 2500 in relay chain will be `0x70617261c4090000000000000000000000000000000000000000000000000000` + and the SS58 format of this address is `5Ec4AhPSY2GEE4VoHUVheqv5wwq2C1HMKa7c9fVJ1WKivX1Y` + + To perform this conversion, you can also use the **"Para ID" to Address** section in [Substrate Utilities](https://www.shawntabrizi.com/substrate-js-utilities/). + +### Create Channel Opening Extrinsic + +1. In Polkadot.js Apps, connect to the relay chain, navigate to the **Developer** dropdown and select the **Extrinsics** option + + ![](/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-1.webp) + +2. Construct an `hrmpInitOpenChannel` extrinsic call + + 1. Select the **`hrmp`** pallet + 2. Choose the **`hrmpInitOpenChannel`** extrinsic + 3. Fill in the parameters + - **`recipient`** - parachain ID of the target chain (in this case, 2600) + - **`proposedMaxCapacity`** - max number of messages that can be pending in the channel at once + - **`proposedMaxMessageSize`** - max message size that could be put into the channel + 4. Copy the encoded call data + ![](/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-2.webp) + The encoded call data for opening a channel with parachain 2600 is `0x3c00280a00000800000000001000`. + +### Crafting and Submitting the XCM Message from the Sender + +To initiate the HRMP channel opening process, you need to create an XCM message that includes the encoded `hrmpInitOpenChannel` call data from the previous step. This message will be sent from your parachain to the relay chain. + +This example uses the `sudo` pallet to dispatch the extrinsic. Verify the XCM configuration of the parachain you're working with and ensure you're using an origin with the necessary privileges to execute the `polkadotXcm.send` extrinsic. + +The XCM message should contain the following instructions: + +- **`WithdrawAsset`** - withdraws assets from the origin's ownership and places them in the Holding Register +- **`BuyExecution`** - pays for the execution of the current message using the assets in the Holding Register +- **`Transact`** - execute the encoded transaction call +- **`RefundSurplus`** - increases the Refunded Weight Register to the value of the Surplus Weight Register, attempting to reclaim any excess fees paid via BuyExecution +- **`DepositAsset`** - subtracts assets from the Holding Register and deposits equivalent on-chain assets under the specified beneficiary's ownership + +!!!note + For more detailed information about XCM's functionality, complexities, and instruction set, refer to the [xcm-format](https://github.com/polkadot-fellows/xcm-format){target=_blank} documentation. + +In essence, this process withdraws funds from the parachain's sovereign account to the XCVM Holding Register, then uses these funds to purchase execution time for the XCM `Transact` instruction, executes `Transact`, refunds any unused execution time and deposits any remaining funds into a specified account. + +To send the XCM message to the relay chain, connect to parachain 2500 in Polkadot.js Apps. Fill in the required parameters as shown in the image below, ensuring that you: + +1. Replace the **`call`** field with your encoded `hrmpInitOpenChannel` call data from the previous step +2. Use the correct beneficiary information +3. Click the **Submit Transaction** button to dispatch the XCM message to the relay chain + +![](/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-3.webp) + +!!! note + The exact process and parameters for submitting this XCM message may vary depending on your specific parachain and relay chain configurations. Always refer to the most current documentation for your particular network setup. + +After submitting the XCM message to initiate the HRMP channel opening, you should verify that the request was successful. Follow these steps to check the status of your channel request: + +1. Using Polkadot.js Apps, connect to the relay chain and navigate to the **Developer** dropdown, then select the **Chain state** option + + ![](/images/develop/parachain-devs/interoperability/hrmp-channels/hrmp-channels-1.webp) + +2. Query the HRMP open channel requests + 1. Select **`hrmp`** + 2. Choose the **`hrmpOpenChannelRequests`** call + 3. Click the **+** button to execute the query + 4. Check the status of all pending channel requests + + ![](/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-4.webp) + +If your channel request was successful, you should see an entry for your parachain ID in the list of open channel requests. This confirms that your request has been properly registered on the relay chain and is awaiting acceptance by the target parachain. + +## Procedure for Accepting HRMP Channel + +For the channel to be fully established, the target parachain must accept the channel request by submitting an XCM message to the relay chain. + +### Fund Receiver Sovereign Account + +Before proceeding, ensure that the sovereign account of parachain 2600 on the relay chain is funded. This account will be responsible for covering any XCM transact fees. +To fund the account, follow the same process described in the previous section [Step 1 - Fund Sovereign Account](#step-1---fund-sender-sovereign-account). + +### Create Channel Accepting Extrinsic + +1. In Polkadot.js Apps, connect to the relay chain, navigate to the **Developer** dropdown and select the **Extrinsics** option + + ![](/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-1.webp) + +2. Construct an `hrmpAcceptOpenChannel` extrinsic call + + 1. Select the **`hrmp`** pallet + 2. Choose the **`hrmpAcceptOpenChannel`** extrinsic + 3. Fill in the parameters: + - **`sender`** - parachain ID of the requesting chain (in this case, 2500) + 4. Copy the encoded call data + ![](/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-5.webp) + The encoded call data for accepting a channel with parachain 2500 should be `0x3c01c4090000` + +### Crafting and Submitting the XCM Message from the Receiver + +To accept the HRMP channel opening, you need to create and submit an XCM message that includes the encoded `hrmpAcceptOpenChannel` call data from the previous step. This process is similar to the one described in the previous section's [Step 3 - Crafting and Submitting the XCM Message](#step-3---crafting-and-submitting-the-xcm-message-from-the-sender), with a few key differences: + +- Use the encoded call data for `hrmpAcceptOpenChannel` obtained in Step 2 of this section +- In the last XCM instruction (DepositAsset), set the beneficiary to parachain 2600's sovereign account to receive any surplus funds + +To send the XCM message to the relay chain, connect to parachain 2600 in Polkadot.js Apps. Fill in the required parameters as shown in the image below, ensuring that you: + +1. Replace the **`call`** field with your encoded `hrmpAcceptOpenChannel` call data from the previous step +2. Use the correct beneficiary information +3. Click the **Submit Transaction** button to dispatch the XCM message to the relay chain + +![](/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-6.webp) + +After submitting the XCM message to accept the HRMP channel opening, verify that the channel has been set up correctly. + +1. Using Polkadot.js Apps, connect to the relay chain and navigate to the **Developer** dropdown, then select the **Chain state** option + + ![](/images/develop/parachain-devs/interoperability/hrmp-channels/hrmp-channels-1.webp) + +2. Query the HRMP channels + 1. Select **`hrmp`** + 2. Choose the **`hrmpChannels`** call + 3. Click the **+** button to execute the query + 4. Check the status of the opened channel + + ![](/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-7.webp) + +If the channel has been successfully established, you should see the channel details in the query results. + +By following these steps, you will have successfully accepted the HRMP channel request and established a unidirectional channel between the two parachains. + +!!! note + Remember that for full bidirectional communication, you'll need to repeat this process in the opposite direction, with parachain 2600 initiating a channel request to parachain 2500. \ No newline at end of file diff --git a/develop/parachain-devs/interoperability/hrmp-channels/para-to-system.md b/develop/parachain-devs/interoperability/hrmp-channels/para-to-system.md new file mode 100644 index 000000000..a5a19c955 --- /dev/null +++ b/develop/parachain-devs/interoperability/hrmp-channels/para-to-system.md @@ -0,0 +1,105 @@ +--- +title: Opening HRMP Channels with System Parachains +description: Learn how to open HRMP channels with Polkadot system parachains. Discover the process for establishing bi-directional communication using a single XCM message. +--- + +# Opening HRMP Channels with System Parachains + +## Introduction + +While establishing Horizontal Relay-routed Message Passing (HRMP) channels between regular parachains involves a two-step request and acceptance procedure, opening channels with system parachains follows a more straightforward approach. + +System parachains are specialized chains that provide core functionality to the Polkadot network. Examples include Asset Hub for cross-chain asset transfers and Bridge Hub for connecting to external networks. Given their critical role, establishing communication channels with these system parachains has been optimized for efficiency and ease of use. + +Any parachain can establish a bidirectional channel with a system chain through a single operation, requiring just one XCM message from the parachain to the relay chain. + +## Prerequisites + +To successfully complete this process, you'll need to have the following in place: + +- Access to a blockchain network consisting of: + - A relay chain + - A parachain + - An Asset Hub system chain +- A wallet containing enough funds to cover transaction fees on each of the participating chains + +## Procedure for Establishing HRMP Channel + +This guide demonstrates opening an HRMP channel between parachain 2500 and system chain Asset Hub (parachain 1000) on the Rococo Local relay chain. + +### Fund Parachain Sovereign Account +<!-- This content will be moved to a new page because it is used in multiple places --> +The [sovereign account](https://github.com/polkadot-fellows/xcm-format/blob/10726875bd3016c5e528c85ed6e82415e4b847d7/README.md?plain=1#L50){target=_blank} for parachain 2500 on the relay chain must be funded so it can take care of any XCM transact fees. + +Use [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer){target=\_blank} UI to connect to the relay chain and transfer funds from your account to the parachain 2500 sovereign account. +![](/images/develop/parachain-devs/interoperability/hrmp-channels/hrmp-channels-2.webp) + +??? note "Calculating Parachain Sovereign Account" + To generate the sovereign account address for a parachain, you'll need to follow these steps: + + 1. Determine if the parachain is an "up/down" chain (parent or child) or a "sibling" chain: + + - Up/down chains use the prefix `0x70617261` (which decodes to `b"para"`) + + - Sibling chains use the prefix `0x7369626c` (which decodes to `b"sibl"`) + + 2. Calculate the u32 scale encoded value of the parachain ID: + - Parachain 2500 would be encoded as `c4090000` + + 3. Combine the prefix and parachain ID encoding to form the full sovereign account address: + + The sovereign account of parachain 2500 in relay chain will be `0x70617261c4090000000000000000000000000000000000000000000000000000` + and the SS58 format of this address is `5Ec4AhPSY2GEE4VoHUVheqv5wwq2C1HMKa7c9fVJ1WKivX1Y` + + To perform this conversion, you can also use the **"Para ID" to Address** section in [Substrate Utilities](https://www.shawntabrizi.com/substrate-js-utilities/). + +### Create Establish Channel with System Extrinsic + +1. In Polkadot.js Apps, connect to the relay chain, navigate to the **Developer** dropdown and select the **Extrinsics** option + + ![](/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-1.webp) + +2. Construct an `establish_channel_with_system` extrinsic call + + 1. Select the **`hrmp`** pallet + 2. Choose the **`establish_channel_with_system`** extrinsic + 3. Fill in the parameters: + - **`target_system_chain`** - parachain ID of the target system chain (in this case, 1000) + 4. Copy the encoded call data + ![](/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-system/hrmp-para-to-system-1.webp) + The encoded call data for establishing a channel with system parachain 1000 should be `0x3c0ae8030000` + +### Crafting and Submitting the XCM Message + +Connect to parachain 2500 using Polkadot.js Apps to send the XCM message to the relay chain. Input the necessary parameters as illustrated in the image below. Make sure to: + +1. Insert your previously encoded `establish_channel_with_system` call data into the **`call`** field +2. Provide beneficiary details +3. Dispatch the XCM message to the relay chain by clicking the **Submit Transaction** button +![](/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-system/hrmp-para-to-system-2.webp) + +!!! note + The exact process and parameters for submitting this XCM message may vary depending on your specific parachain and relay chain configurations. Always refer to the most current documentation for your particular network setup. + +After successfully submitting the XCM message to the relay chain, two HRMP channels should be created, establishing bidirectional communication between parachain 2500 and system chain 1000. To verify this, follow these steps: + +1. Using Polkadot.js Apps, connect to the relay chain and navigate to the **Developer** dropdown, then select **Chain state** + ![](/images/develop/parachain-devs/interoperability/hrmp-channels/hrmp-channels-1.webp) + +2. Query the HRMP channels + 1. Select **`hrmp`** from the options + 2. Choose the **`hrmpChannels`** call + 3. Click the **+** button to execute the query + ![](/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-system/hrmp-para-to-system-3.webp) + +3. Examine the query results. You should see output similar to the following: + ```json + --8<-- 'code/develop/parachain-devs/interoperability/hrmp-channels/hrmp-query-output.json' + ``` + +The output confirms the successful establishment of two HRMP channels: + +- From chain 1000 (system chain) to chain 2500 (parachain) +- From chain 2500 (parachain) to chain 1000 (system chain) + +This bidirectional channel enables direct communication between the system chain and the parachain, allowing for cross-chain message passing. \ No newline at end of file diff --git a/develop/parachain-devs/system-parachains/.pages b/develop/parachain-devs/system-parachains/.pages index 4b3910505..ee727bd4d 100644 --- a/develop/parachain-devs/system-parachains/.pages +++ b/develop/parachain-devs/system-parachains/.pages @@ -1,3 +1,6 @@ title: System Parachains nav: - index.md + - 'Register a Local Asset on Asset Hub': register-a-local-asset-on-asset-hub.md + - 'Register a Foreign Asset on Asset Hub': register-a-foreign-asset-on-asset-hub.md + diff --git a/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub.md b/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub.md new file mode 100644 index 000000000..95b8e0b02 --- /dev/null +++ b/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub.md @@ -0,0 +1,140 @@ +--- +title: Register a Foreign Asset on Asset Hub +description: An in-depth guide to registering a foreign asset on the Asset Hub parachain, providing clear, step-by-step instructions. +--- + +# Register a Foreign Asset on Asset Hub + +## Introduction + +As outlined in the [Asset Hub Overview](TODO:update-path){target=\_blank}, Asset Hub supports two categories of assets: local and foreign. Local assets are created on the Asset Hub system parachain and are identified by integer IDs. On the other hand, foreign assets, which originate outside of Asset Hub, are recognized by [Multilocations](https://wiki.polkadot.network/docs/learn/xcm/fundamentals/multilocation-summary){target=\_blank}. + +When registering a foreign asset on Asset Hub, it's essential to notice that the process involves communication between two parachains. The Asset Hub parachain will be the destination of the foreign asset, while the source parachain will be the origin of the asset. The communication between the two parachains is facilitated by the [Cross-Chain Message Passing (XCMP)](https://wiki.polkadot.network/docs/learn-xcm){target=\_blank} protocol. + +This guide will take you through the process of registering a foreign asset on the Asset Hub parachain. + +## Prerequisites + +The Asset Hub parachain is one of the system parachains on a relay chain, such as [Polkadot](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fpolkadot.api.onfinality.io%2Fpublic-ws#/explorer){target=\_blank} or [Kusama](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fkusama.api.onfinality.io%2Fpublic-ws#/explorer){target=\_blank}. To interact with these parachains, you can use the [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer){target=\_blank} interface for: + +- [Polkadot Asset Hub](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fasset-hub-polkadot-rpc.dwellir.com#/explorer){target=\_blank} +- [Kusama Asset Hub](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fsys.ibp.network%2Fstatemine#/explorer){target=\_blank} + +For testing purposes, you can also interact with the Asset Hub instance on the following test networks: + +- [Paseo Asset Hub](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fpas-rpc.stakeworld.io%2Fassethub#/explorer){target=\_blank} + +Before you start, ensure that you have: + +- Access to the Polkadot.js Apps interface, and you are connected to the desired chain +- A parachain that supports the XCMP protocol to interact with the Asset Hub parachain +- A funded wallet to pay for the transaction fees and subsequent registration of the foreign asset + +This guide will use Polkadot, its local Asset Hub instance, and the [Astar](https://astar.network/){target=\_blank} parachain (`ID` 2006), as stated in the [Test Environment Setup](#test-environment-setup) section. However, the process is the same for other relay chains and their respective Asset Hub parachain, regardless of the network you are using and the parachain owner of the foreign asset. + +## Steps to Register a Foreign Asset + +### Asset Hub + +1. Open the [Polkadot.js Apps](https://polkadot.js.org/apps/){target=\_blank} interface and connect to the Asset Hub parachain using the network selector in the top left corner + + - Testing foreign asset registration is recommended on TestNet before proceeding to MainNet. If you haven't set up a local testing environment yet, consult the [Environment setup](#test-environment-setup) guide. After setting up, connect to the Local Node (Chopsticks) at `ws://127.0.0.1:8000` + - For live network operations, connect to the Asset Hub parachain. You can choose either Polkadot or Kusama Asset Hub from the dropdown menu, selecting your preferred RPC provider. + +2. Navigate to the **Extrinsics** page + 1. Click on the **Developer** tab from the top navigation bar + 2. Select **Extrinsics** from the dropdown + + ![Access to Developer Extrinsics section](/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-1.webp) + +3. Select the Foreign Assets pallet + 3. Select the **`foreignAssets`** pallet from the dropdown list + 4. Choose the **`create`** extrinsic + + ![Select the Foreign Asset pallet](/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-2.webp) + +3. Fill out the required fields and click on the copy icon to copy the **encoded call data** to your clipboard. The fields to be filled are: + + - **id** - as this is a foreign asset, the ID will be represented by a Multilocation that reflects its origin. For this case, the Multilocation of the asset will be from the source parachain perspective: + + ```javascript + MultiLocation {parents: 1, interior: X1(Parachain(2006))}; + ``` + + - **admin** - refers to the account that will be the admin of this asset. This account will be able to manage the asset, including updating its metadata. As the registered asset corresponds to a native asset of the source parachain, the admin account should be the sovereign account of the source parachain + + ??? note "Obtain the sovereign account" + The sovereign account can be obtained through [Substrate Utilities](https://www.shawntabrizi.com/substrate-js-utilities/){target=\_blank}. + + Ensure that **Sibling** is selected and that the **Para ID** corresponds to the source parachain. In this case, since the guide follows the test setup stated in the [Test Environment Setup](#test-environment-setup) section, the **Para ID** is `2006`. + + ![Get parachain sovereign account](/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-3.webp) + + + - **`minBalance`** - the minimum balance required to hold this asset + + ![Fill out the required fields](/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-4.webp) + + ??? note "Encoded call data" + If you want an example of the encoded call data, you can copy the following: + ``` + 0x3500010100591f007369626cd6070000000000000000000000000000000000000000000000000000a0860100000000000000000000000000 + ``` + + +### Source Parachain + +1. Navigate to the **Developer > Extrinsics** section +2. Create the extrinsic to register the foreign asset through XCM + 1. Paste the **encoded call data** copied in the previous step + 2. Click the **Submit Transaction** button + + ![Register foreign asset through XCM](/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-5.webp) + + This XCM call involves withdrawing DOT from the sibling account of the parachain, using it to initiate an execution. The transaction will be carried out with XCM as the origin kind, and will be a hex-encoded call to create a foreign asset on Asset Hub for the specified parachain asset multilocation. Any surplus will be refunded, and the asset will be deposited into the sibling account. + + !!! warning + Note that the sovereign account on the Asset Hub parachain must have a sufficient balance to cover the XCM `BuyExecution` instruction. If the account does not have enough balance, the transaction will fail. + + ??? note "Example of the encoded call data" + If you want to have the whole XCM call ready to be copied, go to the **Developer > Extrinsics > Decode** section and paste the following hex-encoded call data: + ``` + 0x6300330003010100a10f030c000400010000070010a5d4e81300010000070010a5d4e80006030700b4f13501419ce03500010100591f007369626cd607000000000000000000000000000000000000000000000000000000000000000000000000000000000000 + ``` + + Ensure to replace the encoded call data with the one you copied in the previous step. + +After the transaction is successfully executed, the foreign asset will be registered on the Asset Hub parachain. + +## Asset Registration Verification + +To confirm that a foreign asset has been successfully accepted and registered on the Asset Hub parachain, you can navigate to the `Network > Explorer` section of the Polkadot.js Apps interface for Asset Hub. You should be able to see an event that includes the following details: + +![Asset registration event](/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-6.webp) + +In the image above, the **success** field indicates whether the asset registration was successful. + +## Test Environment Setup + +To test the foreign asset registration process before deploying it on a live network, you can set up a local parachain environment. This guide uses Chopsticks to simulate that process. For more information on using Chopsticks, please refer to the [Chopsticks documentation](../../../dev-tools/chopsticks/overview.md){target=\_blank}. + +To set up a test environment, run the following command: + +```bash +npx @acala-network/chopsticks xcm \ +--r polkadot \ +--p polkadot-asset-hub \ +--p astar +``` +!!! note + The above command will create a lazy fork of Polkadot as the relay chain, its Asset Hub instance, and the Astar parachain. The `xcm` parameter enables communication through the XCMP protocol between the relay chain and the parachains, allowing the registration of foreign assets on Asset Hub. For further information on the chopsticks usage of the XCMP protocol, refer to the [XCM Testing](../../../dev-tools/chopsticks/overview.md#xcm-testing){target=\_blank} section of the Chopsticks documentation. + +After executing the command, the terminal will display the subsequent output: + +--8<-- 'code/build-on-polkadot/parachains/asset-hub/register-a-foreign-asset/terminal/chopstick-test-env-output.md' + +According to the output, the Polkadot relay chain, the Polkadot Asset Hub, and the Astar parachain are running locally and connected through XCM. They can be accessed via the Polkadot.js Apps interface: + +- [Polkadot Relay Chain](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Flocalhost%3A8002#/explorer){target=\_blank} +- [Polkadot Asset Hub](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Flocalhost%3A8000#/explorer){target=\_blank} +- [Astar Parachain](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Flocalhost%3A8001#/explorer){target=\_blank} \ No newline at end of file diff --git a/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub.md b/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub.md new file mode 100644 index 000000000..d3a111a16 --- /dev/null +++ b/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub.md @@ -0,0 +1,96 @@ +--- +title: Register a Local Asset +description: Comprehensive guide to registering a local asset on the Asset Hub system parachain, including step-by-step instructions. +--- + +# Register a Local Asset on Asset Hub + +## Introduction + +As detailed in the [Asset Hub Overview](TODO:update-path){target=\_blank} page, Asset Hub accommodates two types of assets: local and foreign. Local assets are those that were created in Asset Hub and are identifiable by an integer ID. On the other hand, foreign assets originate from a sibling parachain and are identified by a Multilocation. + +This guide will take you through the steps of registering a local asset on the Asset Hub parachain. + +## Prerequisites + +Before you begin, ensure you have access to the [Polkadot.js Apps](https://polkadot.js.org/apps/){target=\_blank} interface and a funded wallet with DOT or KSM. + +- For Polkadot Asset Hub, you would need a deposit of 10 DOT and around 0.201 DOT for the metadata +- For Kusama Asset Hub, the deposit is 0.1 KSM and around 0.000669 KSM for the metadata + +You need to ensure that your Asset Hub account balance is a bit more than the sum of those two deposits, which should seamlessly account for the required deposits and transaction fees. + +## Steps to Register a Local Asset + +To register a local asset on the Asset Hub parachain, follow these steps: + +1. Open the [Polkadot.js Apps](https://polkadot.js.org/apps/){target=\_blank} interface and connect to the Asset Hub parachain using the network selector in the top left corner + + - You may prefer to test local asset registration on TestNet before registering the asset on a MainNet hub. If you still need to set up a local testing environment, review the [Environment setup](#test-setup-environment) section for instructions. Once the local environment is set up, connect to the Local Node (Chopsticks) available on `ws://127.0.0.1:8000` + - For the live network, connect to the `Asset Hub` parachain. Either Polkadot or Kusama Asset Hub can be selected from the dropdown list, choosing the desired RPC provider + +2. Click on the **Network** tab on the top navigation bar and select **Assets** from the dropdown list + + ![Access to Asset Hub through Polkadot.JS](/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-1.webp) + +3. Now, you need to examine all the registered asset IDs. This step is crucial to ensure that the asset ID you are about to register is unique. Asset IDs are displayed in the **assets** column + + ![Asset IDs on Asset Hub](/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-2.webp) + +4. Once you have confirmed that the asset ID is unique, click on the **Create** button on the top right corner of the page + + ![Create a new asset](/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-3.webp) + +5. Fill in the required fields in the **Create Asset** form: + + 1. **creator account** - the account to be used for creating this asset and setting up the initial metadata + 2. **asset name** - the descriptive name of the asset you are registering + 3. **asset symbol** - the symbol that will be used to represent the asset + 4. **asset decimals** - the number of decimal places for this token, with a maximum of 20 allowed through the user interface + 5. **minimum balance** - the minimum balance for the asset. This is specified in the units and decimals as requested + 6. **asset ID** - the selected id for the asset. This should not match an already-existing asset id + 7. Click on the **Next** button + + ![Create Asset Form](/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-4.webp) + +6. Choose the accounts for the roles listed below: + + 1. **admin account** - the account designated for continuous administration of the token + 2. **issuer account** - the account that will be used for issuing this token + 3. **freezer account** - the account that will be used for performing token freezing operations + 4. Click on the **Create** button + + ![Admin, Issuer, Freezer accounts](/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-5.webp) + +7. Click on the **Sign and Submit** button to complete the asset registration process + + ![Sign and Submit](/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-6.webp) + +## Verify Asset Registration + +After completing these steps, the asset will be successfully registered. You can now view your asset listed on the [**Assets**](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fasset-hub-polkadot-rpc.dwellir.com#/assets){target=\_blank} section of the Polkadot.js Apps interface. + +![Asset listed on Polkadot.js Apps](/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-7.webp) + +!!! note + Take into consideration that the **Assets** section’s link may differ depending on the network you are using. For the local environment, the link will be `ws://127.0.0.1:8000/#/assets`. + +In this way, you have successfully registered a local asset on the Asset Hub parachain. + +For an in-depth explanation of Asset Hub and its features, please refer to the Polkadot Wiki page on [Asset Hub](https://wiki.polkadot.network/docs/learn-assets){target=\_blank}. + +## Test Setup Environment + +You can set up a local parachain environment to test the asset registration process before deploying it on the live network. This guide uses `chopsticks` to simulate that process. For further information on chopsticks usage, refer to the [Chopsticks](TODO:update-path){target=\_blank} documentation. + +To set up a test environment, execute the following command: + +```bash +npx @acala-network/chopsticks \ +--config=https://raw.githubusercontent.com/AcalaNetwork/chopsticks/master/configs/polkadot-asset-hub.yml +``` + +!!!note + The above command will spawn a lazy fork of Polkadot Asset Hub with the latest block data from the network. If you need to test Kusama Asset Hub, replace `polkadot-asset-hub.yml` with `kusama-asset-hub.yml` in the command. + +An Asset Hub instance is now running locally, and you can proceed with the asset registration process. Note that the local registration process does not differ from the live network process. Once you have a successful TestNet transaction, you can use the same steps to register the asset on MainNet. \ No newline at end of file diff --git a/images/contributing/vale-output-01.webp b/images/contributing/vale-output-01.webp new file mode 100644 index 000000000..16e9790e1 Binary files /dev/null and b/images/contributing/vale-output-01.webp differ diff --git a/images/develop/parachain-devs/interoperability/hrmp-channels/hrmp-channels-1.webp b/images/develop/parachain-devs/interoperability/hrmp-channels/hrmp-channels-1.webp new file mode 100644 index 000000000..05db36743 Binary files /dev/null and b/images/develop/parachain-devs/interoperability/hrmp-channels/hrmp-channels-1.webp differ diff --git a/images/develop/parachain-devs/interoperability/hrmp-channels/hrmp-channels-2.webp b/images/develop/parachain-devs/interoperability/hrmp-channels/hrmp-channels-2.webp new file mode 100644 index 000000000..f5191aedb Binary files /dev/null and b/images/develop/parachain-devs/interoperability/hrmp-channels/hrmp-channels-2.webp differ diff --git a/images/develop/parachain-devs/interoperability/hrmp-channels/overview/hrmp-overview-1.webp b/images/develop/parachain-devs/interoperability/hrmp-channels/overview/hrmp-overview-1.webp new file mode 100644 index 000000000..c5a1932fa Binary files /dev/null and b/images/develop/parachain-devs/interoperability/hrmp-channels/overview/hrmp-overview-1.webp differ diff --git a/images/develop/parachain-devs/interoperability/hrmp-channels/overview/hrmp-overview-2.webp b/images/develop/parachain-devs/interoperability/hrmp-channels/overview/hrmp-overview-2.webp new file mode 100644 index 000000000..dc8d4e629 Binary files /dev/null and b/images/develop/parachain-devs/interoperability/hrmp-channels/overview/hrmp-overview-2.webp differ diff --git a/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-1.webp b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-1.webp new file mode 100644 index 000000000..14aa85ec7 Binary files /dev/null and b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-1.webp differ diff --git a/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-2.webp b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-2.webp new file mode 100644 index 000000000..d707f19ad Binary files /dev/null and b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-2.webp differ diff --git a/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-3.webp b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-3.webp new file mode 100644 index 000000000..db1b8cbbc Binary files /dev/null and b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-3.webp differ diff --git a/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-4.webp b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-4.webp new file mode 100644 index 000000000..632740bea Binary files /dev/null and b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-4.webp differ diff --git a/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-5.webp b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-5.webp new file mode 100644 index 000000000..e81e13b89 Binary files /dev/null and b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-5.webp differ diff --git a/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-6.webp b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-6.webp new file mode 100644 index 000000000..45428be23 Binary files /dev/null and b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-6.webp differ diff --git a/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-7.webp b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-7.webp new file mode 100644 index 000000000..091b94250 Binary files /dev/null and b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-para/hrmp-para-to-para-7.webp differ diff --git a/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-system/hrmp-para-to-system-1.webp b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-system/hrmp-para-to-system-1.webp new file mode 100644 index 000000000..8de18a3af Binary files /dev/null and b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-system/hrmp-para-to-system-1.webp differ diff --git a/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-system/hrmp-para-to-system-2.webp b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-system/hrmp-para-to-system-2.webp new file mode 100644 index 000000000..29f2a7d7c Binary files /dev/null and b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-system/hrmp-para-to-system-2.webp differ diff --git a/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-system/hrmp-para-to-system-3.webp b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-system/hrmp-para-to-system-3.webp new file mode 100644 index 000000000..ec72cbcdd Binary files /dev/null and b/images/develop/parachain-devs/interoperability/hrmp-channels/para-to-system/hrmp-para-to-system-3.webp differ diff --git a/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-1.webp b/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-1.webp new file mode 100644 index 000000000..495d07c58 Binary files /dev/null and b/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-1.webp differ diff --git a/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-2.webp b/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-2.webp new file mode 100644 index 000000000..569e97fd0 Binary files /dev/null and b/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-2.webp differ diff --git a/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-3.webp b/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-3.webp new file mode 100644 index 000000000..42b0535af Binary files /dev/null and b/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-3.webp differ diff --git a/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-4.webp b/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-4.webp new file mode 100644 index 000000000..4a63258fa Binary files /dev/null and b/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-4.webp differ diff --git a/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-5.webp b/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-5.webp new file mode 100644 index 000000000..f86e46970 Binary files /dev/null and b/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-5.webp differ diff --git a/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-6.webp b/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-6.webp new file mode 100644 index 000000000..446380578 Binary files /dev/null and b/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreign-asset-6.webp differ diff --git a/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreing-asset-3.webp b/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreing-asset-3.webp new file mode 100644 index 000000000..ce8254102 Binary files /dev/null and b/images/develop/parachain-devs/system-parachains/register-a-foreign-asset-on-asset-hub/register-a-foreing-asset-3.webp differ diff --git a/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-1.webp b/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-1.webp new file mode 100644 index 000000000..8eda3ebae Binary files /dev/null and b/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-1.webp differ diff --git a/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-2.webp b/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-2.webp new file mode 100644 index 000000000..7e4202753 Binary files /dev/null and b/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-2.webp differ diff --git a/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-3.webp b/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-3.webp new file mode 100644 index 000000000..494e877df Binary files /dev/null and b/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-3.webp differ diff --git a/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-4.webp b/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-4.webp new file mode 100644 index 000000000..875085a4e Binary files /dev/null and b/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-4.webp differ diff --git a/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-5.webp b/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-5.webp new file mode 100644 index 000000000..3cd23c39e Binary files /dev/null and b/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-5.webp differ diff --git a/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-6.webp b/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-6.webp new file mode 100644 index 000000000..2e4b4fba9 Binary files /dev/null and b/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-6.webp differ diff --git a/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-7.webp b/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-7.webp new file mode 100644 index 000000000..8b7766ee7 Binary files /dev/null and b/images/develop/parachain-devs/system-parachains/register-a-local-asset-on-asset-hub/register-a-local-asset-7.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-1.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-1.webp new file mode 100644 index 000000000..8643a1d64 Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-1.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-10.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-10.webp new file mode 100644 index 000000000..8df1af6d4 Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-10.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-11.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-11.webp new file mode 100644 index 000000000..c1f54af55 Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-11.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-12.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-12.webp new file mode 100644 index 000000000..0b43ced7e Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-12.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-13.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-13.webp new file mode 100644 index 000000000..5ef63687f Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-13.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-14.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-14.webp new file mode 100644 index 000000000..209c5b949 Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-14.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-15.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-15.webp new file mode 100644 index 000000000..13ce8cfde Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-15.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-16.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-16.webp new file mode 100644 index 000000000..50807e2ae Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-16.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-2.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-2.webp new file mode 100644 index 000000000..5394a597b Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-2.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-3.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-3.webp new file mode 100644 index 000000000..682e59ca2 Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-3.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-4.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-4.webp new file mode 100644 index 000000000..5657e1621 Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-4.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-5.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-5.webp new file mode 100644 index 000000000..26389f384 Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-5.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-6.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-6.webp new file mode 100644 index 000000000..134adb4d3 Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-6.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-7.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-7.webp new file mode 100644 index 000000000..305611c7f Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-7.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-8.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-8.webp new file mode 100644 index 000000000..487eb4fb5 Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-8.webp differ diff --git a/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-9.webp b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-9.webp new file mode 100644 index 000000000..b4e1a3c51 Binary files /dev/null and b/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-9.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/build-a-local-blockchain-1.webp b/images/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/build-a-local-blockchain-1.webp new file mode 100644 index 000000000..4e17e597c Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/build-a-local-blockchain-1.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/build-a-local-blockchain-2.webp b/images/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/build-a-local-blockchain-2.webp new file mode 100644 index 000000000..7d763d26f Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/build-a-local-blockchain-2.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/build-a-local-blockchain-3.webp b/images/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/build-a-local-blockchain-3.webp new file mode 100644 index 000000000..7d23df61f Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/build-a-local-blockchain-3.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-1.webp b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-1.webp new file mode 100644 index 000000000..545d2f97d Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-1.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-2.webp b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-2.webp new file mode 100644 index 000000000..f1fff4759 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-2.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-3.webp b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-3.webp new file mode 100644 index 000000000..9c98dc612 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-3.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-4.webp b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-4.webp new file mode 100644 index 000000000..e1b7572ba Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-4.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-5.webp b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-5.webp new file mode 100644 index 000000000..475f69117 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-5.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-6.webp b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-6.webp new file mode 100644 index 000000000..e229c5034 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-6.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-7.webp b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-7.webp new file mode 100644 index 000000000..6644e63ed Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-7.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-8.webp b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-8.webp new file mode 100644 index 000000000..cebe655a2 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-8.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-9.webp b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-9.webp new file mode 100644 index 000000000..005da7efe Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-9.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-1.webp b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-1.webp new file mode 100644 index 000000000..c4e158833 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-1.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-10.webp b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-10.webp new file mode 100644 index 000000000..d59781df6 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-10.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-11.webp b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-11.webp new file mode 100644 index 000000000..a6e57f3fc Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-11.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-2.webp b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-2.webp new file mode 100644 index 000000000..a16157b75 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-2.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-3.webp b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-3.webp new file mode 100644 index 000000000..364236c89 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-3.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-4.webp b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-4.webp new file mode 100644 index 000000000..0b24f9b85 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-4.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-5.webp b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-5.webp new file mode 100644 index 000000000..72ab3736e Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-5.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-6.webp b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-6.webp new file mode 100644 index 000000000..1bcdce67e Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-6.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-7.webp b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-7.webp new file mode 100644 index 000000000..c78531c07 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-7.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-8.webp b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-8.webp new file mode 100644 index 000000000..d637e391e Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-8.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-9.webp b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-9.webp new file mode 100644 index 000000000..805c9a18d Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-9.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-1.webp b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-1.webp new file mode 100644 index 000000000..770d1ff67 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-1.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-10.webp b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-10.webp new file mode 100644 index 000000000..f42be2145 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-10.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.webp b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.webp new file mode 100644 index 000000000..e108e40d8 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-3.webp b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-3.webp new file mode 100644 index 000000000..ba0a4335f Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-3.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-4.webp b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-4.webp new file mode 100644 index 000000000..d24f794fa Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-4.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-5.webp b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-5.webp new file mode 100644 index 000000000..640f86478 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-5.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-6.webp b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-6.webp new file mode 100644 index 000000000..a0abb7516 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-6.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-7.webp b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-7.webp new file mode 100644 index 000000000..4d2cdf3a2 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-7.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-8.webp b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-8.webp new file mode 100644 index 000000000..112507549 Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-8.webp differ diff --git a/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-9.webp b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-9.webp new file mode 100644 index 000000000..ec313425f Binary files /dev/null and b/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-9.webp differ diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 000000000..65b7775ac --- /dev/null +++ b/package-lock.json @@ -0,0 +1,43 @@ +{ + "name": "polkadot-docs", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "polkadot-docs", + "version": "1.0.0", + "license": "ISC", + "devDependencies": { + "@taplo/cli": "^0.7.0", + "husky": "^8.0.0" + } + }, + "node_modules/@taplo/cli": { + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/@taplo/cli/-/cli-0.7.0.tgz", + "integrity": "sha512-Ck3zFhQhIhi02Hl6T4ZmJsXdnJE+wXcJz5f8klxd4keRYgenMnip3JDPMGDRLbnC/2iGd8P0sBIQqI3KxfVjBg==", + "dev": true, + "license": "MIT", + "bin": { + "taplo": "dist/cli.js" + } + }, + "node_modules/husky": { + "version": "8.0.3", + "resolved": "https://registry.npmjs.org/husky/-/husky-8.0.3.tgz", + "integrity": "sha512-+dQSyqPh4x1hlO1swXBiNb2HzTDN1I2IGLQx1GrBuiqFJfoMrnZWwVmatvSiO+Iz8fBUnf+lekwNo4c2LlXItg==", + "dev": true, + "license": "MIT", + "bin": { + "husky": "lib/bin.js" + }, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/typicode" + } + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 000000000..0abdd3630 --- /dev/null +++ b/package.json @@ -0,0 +1,17 @@ +{ + "name": "polkadot-docs", + "version": "1.0.0", + "description": "This package contains tools to support the development and maintenance of the polkadot-docs repository.", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "prepare": "husky install" + }, + "keywords": [], + "author": "", + "license": "ISC", + "devDependencies": { + "@taplo/cli": "^0.7.0", + "husky": "^8.0.0" + } +} diff --git a/polkadot-protocol/introduction/.pages b/polkadot-protocol/introduction/.pages index 1ba238f1e..f9f573565 100644 --- a/polkadot-protocol/introduction/.pages +++ b/polkadot-protocol/introduction/.pages @@ -1,4 +1,5 @@ title: Introduction to Polkadot nav: - index.md + - 'Glossary': 'glossary.md' - parachains diff --git a/polkadot-protocol/introduction/glossary.md b/polkadot-protocol/introduction/glossary.md new file mode 100644 index 000000000..da623ae4f --- /dev/null +++ b/polkadot-protocol/introduction/glossary.md @@ -0,0 +1,343 @@ +--- +title: Glossary +description: Glossary of terms used within the Polkadot ecosystem, Polkadot SDK, its subsequent libraries, and other relevant Web3 terminology. +--- + +# Glossary + +Key definitions, concepts, and terminology specific to the Polkadot ecosystem are included here. + +Additional glossaries from around the ecosystem you might find helpful: + +- [Polkadot Wiki Glossary](https://wiki.polkadot.network/docs/glossary){target=\_blank} +- [Polkadot SDK Glossary](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/glossary/index.html){target=\_blank} + +## Authority + +The role in a blockchain that can participate in consensus mechanisms. + +- [GRANDPA](#grandpa) - the authorities vote on chains they consider final +- [Blind Assignment of Blockchain Extension](#blind-assignment-of-blockchain-extension-babe) (BABE) - the authorities are also [block authors](#block-author) + +Authority sets can be used as a basis for consensus mechanisms such as the [Nominated Proof of Stake (NPoS)](#nominated-proof-of-stake-npos) protocol. + +## Authority Round (Aura) + +A deterministic [consensus](#consensus) protocol where block production is limited to a rotating list of [authorities](#authority) that take turns creating blocks. In authority round (Aura) consensus, most online authorities are assumed to be honest. It is often used in combination with [GRANDPA](#grandpa) as a [hybrid consensus](#hybrid-consensus) protocol. + +Learn more by reading the official [Aura consensus algorithm](https://openethereum.github.io/Aura){target=\_blank} wiki article. + +## Blind Assignment of Blockchain Extension (BABE) + +A [block authoring](#block-author) protocol similar to [Aura](#authority-round-aura), except [authorities](#authority) win [slots](#slot) based on a Verifiable Random Function (VRF) instead of the round-robin selection method. The winning authority can select a chain and submit a new block. + +Learn more by reading the official Web3 Foundation [BABE research document](https://research.web3.foundation/Polkadot/protocols/block-production/Babe){target=\_blank}. + +## Block Author + +The node responsible for the creation of a block, also called _block producers_. In a Proof of Work (PoW) blockchain, these nodes are called _miners_. + +## Byzantine Fault Tolerance (BFT) + +The ability of a distributed computer network to remain operational if a certain proportion of its nodes or [authorities](#authority) are defective or behaving maliciously. + +!!!note + + A distributed network is typically considered Byzantine fault tolerant if it can remain functional, with up to one-third of nodes assumed to be defective, offline, actively malicious, and part of a coordinated attack. + +### Byzantine Failure + +The loss of a network service due to node failures that exceed the proportion of nodes required to reach consensus. + +### Practical Byzantine Fault Tolerance (pBFT) + +An early approach to Byzantine fault tolerance (BFT), practical Byzantine fault tolerance (pBFT) systems tolerate Byzantine behavior from up to one-third of participants. + +The communication overhead for such systems is `O(n²)`, where `n` is the number of nodes (participants) in the system. + +## Call + +In the context of pallets containing functions to be dispatched to the runtime, `Call` is an enumeration data type that describes the functions that can be dispatched with one variant per pallet. A `Call` represents a [dispatch](#dispatchable) data structure object. + +## Chain Specification + +A chain specification file defines the properties required to run a node in an active or new Polkadot SDK-built network. It often contains the initial genesis runtime code, network properties (such as the network's name), the initial state for some pallets, and the boot node list. The chain specification file makes it easy to use a single Polkadot SDK codebase as the foundation for multiple independently configured chains. + +## Collator + +An [author](#block-author) of a [parachain](#parachain) network. +They aren't [authorities](#authority) in themselves, as they require a [relay chain](#relay-chain) to coordinate [consensus](#consensus). + +More details are found on the [Polkadot Collator Wiki](https://wiki.polkadot.network/docs/learn-collator){target=\_blank}. + +## Collective + +Most often used to refer to an instance of the Collective pallet on Polkadot SDK-based networks such as [Kusama](#kusama) or [Polkadot](#polkadot) if the Collective pallet is part of the FRAME-based runtime for the network. + +## Consensus + +Consensus is the process blockchain nodes use to agree on a chain's canonical fork. It is composed of [authorship](#block-author), finality, and [fork-choice rule](#fork-choice-rulestrategy). In the Polkadot ecosystem, these three components are usually separate and the term consensus often refers specifically to authorship. + +See also [hybrid consensus](#hybrid-consensus). + +## Consensus Algorithm + +Ensures a set of [actors](#authority)—who don't necessarily trust each other—can reach an agreement about the state as the result of some computation. Most consensus algorithms assume that up to one-third of the actors or nodes can be [Byzantine fault tolerant](#byzantine-fault-tolerance-bft). + +Consensus algorithms are generally concerned with ensuring two properties: + +- **Safety** - indicating that all honest nodes eventually agreed on the state of the chain +- **Liveness** - indicating the ability of the chain to keep progressing + +## Consensus Engine + +The node subsystem responsible for consensus tasks. + +For detailed information about the consensus strategies of the [Polkadot](#polkadot) network, see the [Polkadot Consensus](https://wiki.polkadot.network/docs/learn-consensus){target=\_blank} blog series. + +See also [hybrid consensus](#hybrid-consensus). + +## Development Phrase + +A [mnemonic phrase](https://en.wikipedia.org/wiki/Mnemonic#For_numerical_sequences_and_mathematical_operations){target=\_blank} that is intentionally made public. + +Well-known development accounts, such as Alice, Bob, Charlie, Dave, Eve, and Ferdie, are generated from the same secret phrase: + +``` +bottom drive obey lake curtain smoke basket hold race lonely fit walk +``` + +Many tools in the Polkadot SDK ecosystem, such as [`subkey`](https://github.com/paritytech/polkadot-sdk/tree/HEAD/substrate/bin/utils/subkey){target=\_blank}, allow you to implicitly specify an account using a derivation path such as `//Alice`. + +## Digest + +An extensible field of the [block header](#header) that encodes information needed by several actors in a blockchain network, including: + +- [Light clients](#light-client) for chain synchronization +- Consensus engines for block verification +- The runtime itself, in the case of pre-runtime digests + +## Dispatchable + +Function objects that act as the entry points in FRAME [pallets](#pallet). Internal or external entities can call them to interact with the blockchain’s state. They are a core aspect of the runtime logic, handling [transactions](#transaction) and other state-changing operations. + +## Events + +A means of recording that some particular [state](#state) transition happened. + +In the context of [FRAME](#frame-framework-for-runtime-aggregation-of-modularized-entities), events are composable data types that each [pallet](#pallet) can individually define. Events in FRAME are implemented as a set of transient storage items inspected immediately after a block has been executed and reset during block initialization. + +## Executor + +A means of executing a function call in a given [runtime](#runtime) with a set of dependencies. +There are two orchestration engines in Polkadot SDK, _WebAssembly_ and _native_. + +- The _native executor_ uses a natively compiled runtime embedded in the node to execute calls. This is a performance optimization available to up-to-date nodes + +- The _WebAssembly executor_ uses a [Wasm](#webassembly-wasm) binary and a Wasm interpreter to execute calls. The binary is guaranteed to be up-to-date regardless of the version of the blockchain node because it is persisted in the [state](#state) of the Polkadot SDK-based chain + +## Existential Deposit + +The minimum balance an account is allowed to have in the [Balances pallet](https://paritytech.github.io/polkadot-sdk/master/pallet_balances/index.html){target=\_blank}. Accounts cannot be created with a balance less than the existential deposit amount. + +If an account balance drops below this amount, the Balances pallet uses [a FRAME System API](https://paritytech.github.io/substrate/master/frame_system/pallet/struct.Pallet.html#method.dec_ref){target=\_blank} to drop its references to that account. + +If the Balances pallet reference to an account is dropped, the account can be [reaped](https://paritytech.github.io/substrate/master/frame_system/pallet/struct.Pallet.html#method.allow_death){target=\_blank}. + +## Extrinsic + +A general term for data that originates outside the runtime, is included in a block, and leads to some action. This includes user-initiated transactions and inherent transactions placed into the block by the block builder. + +It is a SCALE-encoded array typically consisting of a version number, signature, and varying data types indicating the resulting runtime function to be called. Extrinsics can take two forms: [inherents](#inherent-transactions) and [transactions](#transaction). + +For more technical details, see the [Polkadot spec](https://spec.polkadot.network/id-extrinsics){target=\_blank}. + +## Fork Choice Rule/Strategy + +A fork choice rule or strategy helps determine which chain is valid when reconciling several network forks. A common fork choice rule is the [longest chain](https://paritytech.github.io/polkadot-sdk/master/sc_consensus/struct.LongestChain.html){target=\_blank}, in which the chain with the most blocks is selected. + +## FRAME (Framework for Runtime Aggregation of Modularized Entities) + +Enables developers to create blockchain [runtime](#runtime) environments from a modular set of components called [pallets](#pallet). It utilizes a set of procedural macros to construct runtimes. + +[Visit the Polkadot SDK docs for more details on FRAME.](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/frame_runtime/index.html){target=\_blank} + +## Full Node + +A node that prunes historical states, keeping only recently finalized block states to reduce storage needs. Full nodes provide current chain state access and allow direct submission and validation of [extrinsics](#extrinsic), maintaining network decentralization. + +## Genesis Configuration + +A mechanism for specifying the initial state of a blockchain. By convention, this initial state or first block is commonly referred to as the genesis state or genesis block. The genesis configuration for Polkadot SDK-based chains is accomplished by way of a [chain specification](#chain-specification) file. + +## GRANDPA + +A deterministic finality mechanism for blockchains that is implemented in the [Rust](https://www.rust-lang.org/){target=\_blank} programming language. + +The [formal specification](https://github.com/w3f/consensus/blob/master/pdf/grandpa-old.pdf){target=\_blank} is maintained by the [Web3 Foundation](https://web3.foundation/){target=\_blank}. + +## Header + +A structure that aggregates the information used to summarize a block. Primarily, it consists of cryptographic information used by [light clients](#light-client) to get minimally secure but very efficient chain synchronization. + +## Hybrid Consensus + +A blockchain consensus protocol that consists of independent or loosely coupled mechanisms for [block production](#block-author) and finality. + +Hybrid consensus allows the chain to grow as fast as probabilistic consensus protocols, such as [Aura](#authority-round-aura), while maintaining the same level of security as deterministic finality consensus protocols, such as [GRANDPA](#grandpa). + +## Inherent Transactions + +A special type of unsigned transaction, referred to as _inherents_, that enables a block authoring node to insert information that doesn't require validation directly into a block. + +Only the block-authoring node that calls the inherent transaction function can insert data into its block. In general, validators assume the data inserted using an inherent transaction is valid and reasonable even if it can't be deterministically verified. + +## JSON-RPC + +A stateless, lightweight remote procedure call protocol encoded in JavaScript Object Notation (JSON). JSON-RPC provides a standard way to call functions on a remote system by using JSON. + +For Polkadot SDK, this protocol is implemented through the [Parity JSON-RPC](https://github.com/paritytech/jsonrpc){target=\_blank} crate. + +## Keystore + +A subsystem for managing keys for the purpose of producing new blocks. + +## Kusama + +[Kusama](https://kusama.network/){target=\_blank} is a Polkadot SDK-based blockchain that implements a design similar to the [Polkadot](#polkadot) network. + +Kusama is a [canary](https://en.wiktionary.org/wiki/canary_in_a_coal_mine){target=\_blank} network and is referred to as [Polkadot's "wild cousin."](https://wiki.polkadot.network/docs/learn-comparisons-kusama){target=\_blank} + +As a canary network, Kusama is expected to be more stable than a test network like [Westend](#westend) but less stable than a production network like [Polkadot](#polkadot). Kusama is controlled by its network participants and is intended to be stable enough to encourage meaningful experimentation. + +## libp2p + +A peer-to-peer networking stack that allows the use of many transport mechanisms, including WebSockets (usable in a web browser). + +Polkadot SDK uses the [Rust implementation](https://github.com/libp2p/rust-libp2p){target=\_blank} of the `libp2p` networking stack. + +## Light Client + +A type of blockchain node that doesn't store the [chain state](#state) or produce blocks. + +A light client can verify cryptographic primitives and provides a [remote procedure call (RPC)](https://en.wikipedia.org/wiki/Remote_procedure_call){target=\_blank} server, enabling blockchain users to interact with the network. + +## Metadata + +Data that provides information about one or more aspects of a system. +The metadata that exposes information about a Polkadot SDK blockchain enables you to interact with that system. + +## Nominated Proof of Stake (NPoS) + +A method for determining [validators](#validator) or _[authorities](#authority)_ based on a willingness to commit their stake to the proper functioning of one or more block-producing nodes. + +## Oracle + +An entity that connects a blockchain to a non-blockchain data source. Oracles enable the blockchain to access and act upon information from existing data sources and incorporate data from non-blockchain systems and services. + +## Origin + +A [FRAME](#frame-framework-for-runtime-aggregation-of-modularized-entities) primitive that identifies the source of a [dispatched](#dispatchable) function call into the [runtime](#runtime). The FRAME System pallet defines three built-in [origins](#origin). As a [pallet](#pallet) developer, you can also define custom origins, such as those defined by the [Collective pallet](https://paritytech.github.io/substrate/master/pallet_collective/enum.RawOrigin.html){target=\_blank}. + +## Pallet + +A module that can be used to extend the capabilities of a [FRAME](#frame-framework-for-runtime-aggregation-of-modularized-entities)-based [runtime](#runtime). +Pallets bundle domain-specific logic with runtime primitives like [events](#events) and [storage items](#storage-item). + +## Parachain + +A parachain is a blockchain that derives shared infrastructure and security from a _[relay chain](#relay-chain)_. +You can learn more about parachains on the [Polkadot Wiki](https://wiki.polkadot.network/docs/en/learn-parachains){target=\_blank}. + +## Paseo + +Paseo TestNet provisions testing on Polkadot's "production" runtime, which means less chance of feature or code mismatch when developing parachain apps. Specifically, after the [Polkadot Technical fellowship](https://wiki.polkadot.network/docs/learn-polkadot-technical-fellowship){target=\_blank} proposes a runtime upgrade for Polkadot, this TestNet is updated, giving a period where the TestNet will be ahead of Polkadot to allow for testing. + +## Polkadot + +The [Polkadot network](https://polkadot.network/){target=\_blank} is a blockchain that serves as the central hub of a heterogeneous blockchain network. It serves the role of the [relay chain](#relay-chain) and provides shared infrastructure and security to support [parachains](#parachain). + +## Relay Chain + +Relay chains are blockchains that provide shared infrastructure and security to the [parachains](#parachain) in the network. In addition to providing [consensus](#consensus) capabilities, relay chains allow parachains to communicate and exchange digital assets without needing to trust one another. + +## Rococo + +A [parachain](#parachain) test network for the Polkadot network. The [Rococo](#rococo) network is a Polkadot SDK-based blockchain with an October 14, 2024 deprecation date. Development teams are encouraged to use the Paseo TestNet instead. + +## Runtime + +The runtime provides the [state transition function](#state-transition-function-stf) for a node. In Polkadot SDK, the runtime is stored as a [Wasm](#webassembly-wasm) binary in the chain state. + +## Slot + +A fixed, equal interval of time used by consensus engines such as [Aura](#authority-round-aura) and [BABE](#blind-assignment-of-blockchain-extension-babe). In each slot, a subset of [authorities](#authority) is permitted, or obliged, to [author](#block-author) a block. + +## Sovereign Account + +The unique account identifier for each chain in the relay chain ecosystem. It is often used in cross-consensus (XCM) interactions to sign XCM messages sent to the relay chain or other chains in the ecosystem. + +The sovereign account for each chain is a root-level account that can only be accessed using the Sudo pallet or through governance. The account identifier is calculated by concatenating the Blake2 hash of a specific text string and the registered parachain identifier. + +## SS58 Address Format + +A public key address based on the Bitcoin [`Base-58-check`](https://en.bitcoin.it/wiki/Base58Check_encoding){target=\_blank} encoding. Each Polkadot SDK SS58 address uses a `base-58` encoded value to identify a specific account on a specific Polkadot SDK-based chain + +The [canonical `ss58-registry`](https://github.com/paritytech/ss58-registry){target=\_blank} provides additional details about the address format used by different Polkadot SDK-based chains, including the network prefix and website used for different networks + +## State Transition Function (STF) + +The logic of a blockchain that determines how the state changes when a block is processed. In Polkadot SDK, the state transition function is effectively equivalent to the [runtime](#runtime). + +## Storage Item + +[FRAME](#frame-framework-for-runtime-aggregation-of-modularized-entities) primitives that provide type-safe data persistence capabilities to the [runtime](#runtime). +Learn more in the [storage items](https://paritytech.github.io/polkadot-sdk/master/frame_support/storage/types/index.html){target=\_blank} reference document in the Polkadot SDK. + +## Substrate + +A flexible framework for building modular, efficient, and upgradeable blockchains. Substrate is written in the [Rust](https://www.rust-lang.org/){target=\_blank} programming language and is maintained by [Parity Technologies](https://www.parity.io/){target=\_blank}. + +## Transaction + +An [extrinsic](#extrinsic) that includes a signature that can be used to verify the account authorizing it inherently or via [signed extensions](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/signed_extensions/index.html){target=\_blank}. + +## Transaction Era + +A definable period expressed as a range of block numbers during which a transaction can be included in a block. +Transaction eras are used to protect against transaction replay attacks if an account is reaped and its replay-protecting nonce is reset to zero. + +## Trie (Patricia Merkle Tree) + +A data structure used to represent sets of key-value pairs and enables the items in the data set to be stored and retrieved using a cryptographic hash. Because incremental changes to the data set result in a new hash, retrieving data is efficient even if the data set is very large. With this data structure, you can also prove whether the data set includes any particular key-value pair without access to the entire data set. + +In Polkadot SDK-based blockchains, state is stored in a trie data structure that supports the efficient creation of incremental digests. This trie is exposed to the [runtime](#runtime) as [a simple key/value map](#storage-item) where both keys and values can be arbitrary byte arrays. + +## Validator + +A validator is a node that participates in the consensus mechanism of the network. Its roles include block production, transaction validation, network integrity, and security maintenance. + +## WebAssembly (Wasm) + +An execution architecture that allows for the efficient, platform-neutral expression of +deterministic, machine-executable logic. + +[Wasm](https://webassembly.org/){target=\_blank} can be compiled from many languages, including +the [Rust](http://rust-lang.org/){target=\_blank} programming language. Polkadot SDK-based chains use a Wasm binary to provide portable [runtimes](#runtime) that can be included as part of the chain's state. + +## Weight + +A convention used in Polkadot SDK-based blockchains to measure and manage the time it takes to validate a block. +Polkadot SDK defines one unit of weight as one picosecond of execution time on reference hardware. + +The maximum block weight should be equivalent to one-third of the target block time with an allocation of one-third each for: + +- Block construction +- Network propagation +- Import and verification + +By defining weights, you can trade-off the number of transactions per second and the hardware required to maintain the target block time appropriate for your use case. Weights are defined in the runtime, meaning you can tune them using runtime updates to keep up with hardware and software improvements. + +## Westend + +Westend is a Parity-maintained, Polkadot SDK-based blockchain that serves as a test network for the [Polkadot](#polkadot) network. \ No newline at end of file diff --git a/polkadot-protocol/system-parachains/asset-hub/.pages b/polkadot-protocol/system-parachains/asset-hub/.pages index 3698714a1..1eb23bdb3 100644 --- a/polkadot-protocol/system-parachains/asset-hub/.pages +++ b/polkadot-protocol/system-parachains/asset-hub/.pages @@ -1,3 +1,5 @@ title: Asset Hub nav: - index.md + - 'Asset Hub Introduction': asset-hub-introduction.md + - 'Asset Conversion': asset-conversion.md diff --git a/polkadot-protocol/system-parachains/asset-hub/asset-conversion.md b/polkadot-protocol/system-parachains/asset-hub/asset-conversion.md new file mode 100644 index 000000000..41b042d48 --- /dev/null +++ b/polkadot-protocol/system-parachains/asset-hub/asset-conversion.md @@ -0,0 +1,321 @@ +--- +title: Convert Assets on Asset Hub +description: A guide detailing the step-by-step process of converting assets on Asset Hub, helping users efficiently navigate asset management on the platform. +--- + +# Asset Conversion on Asset Hub + +## Introduction + +Asset Conversion is an Automated Market Maker (AMM) utilizing [Uniswap V2](https://github.com/Uniswap/v2-core){target=\_blank} logic and implemented as a pallet on Polkadot's Asset Hub. For more details about this feature, please visit the [Asset Conversion on Asset Hub](https://wiki.polkadot.network/docs/learn-asset-conversion-assethub){target=\_blank} wiki page. + +This guide will provide detailed information about the key functionalities offered by the +[Asset Conversion](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/asset-conversion){target=\_blank} pallet on Asset Hub, including: + +- Creating a liquidity pool +- Adding liquidity to a pool +- Swapping assets +- Withdrawing liquidity from a pool + +## Prerequisites + +Before converting assets on Asset Hub, you must ensure you have: + +- Access to the [Polkadot.js Apps](https://Polkadot.js.org/apps){target=\_blank} interface and a connection with the intended blockchain +- A funded wallet containing the assets you wish to convert and enough available funds to cover the transaction fees +- An asset registered on Asset Hub that you want to convert. If you haven't created an asset on Asset Hub yet, refer to the [Register a Local Asset](./docs/build-on-polkadot/parachains/asset-hub/register-a-foreign-asset.md){target=\_blank} or [Register a Foreign Asset](./docs/build-on-polkadot/parachains/asset-hub/register-a-local-asset.md){target=\_blank} documentation to create an asset. + +## Creating a Liquidity Pool + +If an asset on Asset Hub does not have an existing liquidity pool, the first step is to create one. + +The asset conversion pallet provides the `createPool` extrinsic to create a new liquidity pool, creating an empty liquidity pool and a new `LP token` asset. + +!!! note + A testing token with the asset ID `1112` and the name `PPM` was created for this example. + +As stated in the [Test Environment Setup](#test-environment-setup) section, this tutorial is based on the assumption that you have an instance of Polkadot Asset Hub running locally. Therefore, the demo liquidity pool will be created between DOT and PPM tokens. However, the same steps can be applied to any other asset on Asset Hub. + +From the Asset Hub perspective, the Multilocation that identifies the PPM token is the following: + +```javascript +{ + parents: 0, + interior: { + X2: [{PalletInstance: 50}, {GeneralIndex: 1112}] + } +} +``` + +!!!note + The `PalletInstance` value of `50` represents the Assets pallet on Asset Hub. The `GeneralIndex` value of `1112` is the PPM asset's Asset ID. + +To create the liquidity pool, you can follow these steps: + +1. Navigate to the **Extrinsics** section on the Polkadot.js App interface + 1. Select **Developer** from the top menu + 2. Click on **Extrinsics** from the dropdown menu + + ![Extrinsics Section](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-1.webp) + +2. Choose the **`AssetConversion`** pallet and click on the **`createPool`** extrinsic + 3. Select the **`AssetConversion`** pallet + 4. Choose the **`createPool`** extrinsic from the list of available extrinsics + + ![Create Pool Extrinsic](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-2.webp) + +3. Fill in the required fields: + 1. **`asset1`** - the Multilocation of the first asset in the pool. In this case, it is the DOT token, which the following Multilocation represents: + ```javascript + { + parents: 0, + interior: Here + } + ``` + 2. **`asset2`** - the second asset's Multilocation within the pool. This refers to the PPM token, which the following Multilocation identifies: + ```javascript + { + parents: 0, + interior: { + X2: [{PalletInstance: 50}, {GeneralIndex: 1112}] + } + } + ``` + 5. Click on **Submit Transaction** to create the liquidity pool + + ![Create Pool Fields](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-3.webp) + +Signing and submitting the transaction triggers the creation of the liquidity pool. To verify the new pool's creation, check the **Explorer** section on the Polkadot.js App interface and ensure that the **`PoolCreated`** event was emitted. + +![Pool Created Event](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-4.webp) + +As the preceding image shows, the **`lpToken`** ID created for this pool is 19. This ID is essential to identify the liquidity pool and associated LP tokens. + +## Adding Liquidity to a Pool + +The `addLiquidity` extrinsic allows users to provide liquidity to a pool of two assets. Users specify their preferred amounts for both assets and minimum acceptable quantities. The function determines the best asset contribution, which may vary from the amounts desired but won't fall below the specified minimums. Providers receive liquidity tokens representing their pool portion in return for their contribution. + +To add liquidity to a pool, follow these steps: + +1. Navigate to the **Extrinsics** section on the Polkadot.js App interface + 1. Select **Developer** from the top menu + 2. Click on **Extrinsics** from the dropdown menu + + ![Extrinsics Section](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-1.webp) + +2. Choose the **`assetConversion`** pallet and click on the **`addLiquidity`** extrinsic + 1. Select the **`assetConversion`** pallet + 2. Choose the **`addLiquidity`** extrinsic from the list of available extrinsics + + ![Add Liquidity Extrinsic](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-5.webp) + +3. Fill in the required fields: + 1. **`asset1`** - the Multilocation of the first asset in the pool. In this case, it is the DOT token, which the following Multilocation represents: + ```javascript + { + parents: 0, + interior: Here + } + ``` + 2. **`asset2`** - the second asset's Multilocation within the pool. This refers to the PPM token, which the following Multilocation identifies: + ```javascript + { + parents: 0, + interior: { + X2: [{PalletInstance: 50}, {GeneralIndex: 1112}] + } + } + ``` + 3. **`amount1Desired`** - the amount of the first asset that will be contributed to the pool + 4. **`amount2Desired`** - the quantity of the second asset intended for pool contribution + 5. **`amount1Min`** - the minimum amount of the first asset that will be contributed + 6. **`amount2Min`** - the lowest acceptable quantity of the second asset for contribution + 7. **`mintTo`** - the account to which the liquidity tokens will be minted + 8. Click on **Submit Transaction** to add liquidity to the pool + + ![Add Liquidity Fields](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-6.webp) + + !!! warning + Ensure that the appropriate amount of tokens provided has been minted previously and is available in your account before adding liquidity to the pool. + + In this case, the liquidity provided to the pool is between DOT tokens and PPM tokens with the asset ID 1112 on Polkadot Asset Hub. The intention is to provide liquidity for 1 DOT token (`u128` value of 1000000000000 as it has ten decimals) and 1 PPM token (`u128` value of 1000000000000 as it also has ten decimals). + +Signing and submitting the transaction adds liquidity to the pool. To verify the liquidity addition, check the **Explorer** section on the Polkadot.js App interface and ensure that the **`LiquidityAdded`** event was emitted. + +![Liquidity Added Event](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-7.webp) + +## Swapping Assets + +### Swapping From an Exact Amount of Tokens + +The asset conversion pallet enables users to exchange a specific quantity of one asset for another in a designated liquidity pool by swapping them for an exact amount of tokens. It guarantees the user will receive at least a predetermined minimum amount of the second asset. This function increases trading predictability and allows users to conduct asset exchanges with confidence that they are assured a minimum return. + +To swap assets for an exact amount of tokens, follow these steps: + +1. Navigate to the **Extrinsics** section on the Polkadot.js App interface + 1. Select **Developer** from the top menu + 2. Click on **Extrinsics** from the dropdown menu + + ![Extrinsics Section](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-1.webp) + +2. Choose the **`AssetConversion`** pallet and click on the **`swapExactTokensForTokens`** extrinsic + 1. Select the **`AssetConversion`** pallet + 2. Choose the **`swapExactTokensForTokens`** extrinsic from the list of available extrinsics + + ![Swap From Exact Tokens Extrinsic](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-8.webp) + +3. Fill in the required fields: + 1. **`path:Vec<StagingXcmV3MultiLocation\>`** - an array of Multilocations representing the path of the swap. The first and last elements of the array are the input and output assets, respectively. In this case, the path consists of two elements: + - **`0: StagingXcmV3MultiLocation`** - the Multilocation of the first asset in the pool. In this case, it is the DOT token, which the following Multilocation represents: + ```javascript + { + parents: 0, + interior: Here + } + ``` + - **`1: StagingXcmV3MultiLocation`** - the second asset's Multilocation within the pool. This refers to the PPM token, which the following Multilocation identifies: + ```javascript + { + parents: 0, + interior: { + X2: [{PalletInstance: 50}, {GeneralIndex: 1112}] + } + } + ``` + 1. **`amountOut`** - the exact amount of the second asset that the user wants to receive + 2. **`amountInMax`** - the maximum amount of the first asset that the user is willing to swap + 3. **`sendTo`** - the account to which the swapped assets will be sent + 4. **`keepAlive`** - a boolean value that determines whether the pool should be kept alive after the swap + 5. Click on **Submit Transaction** to swap assets for an exact amount of tokens + + ![Swap For Exact Tokens Fields](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-9.webp) + + !!! warning + Ensure that the appropriate amount of tokens provided has been minted previously and is available in your account before adding liquidity to the pool. + + In this case, the intention is to swap 0.01 DOT token (u128 value of 100000000000 as it has ten decimals) for 0.04 PPM token (u128 value of 400000000000 as it also has ten decimals). + +Signing and submitting the transaction will execute the swap. To verify execution, check the **Explorer** section on the Polkadot.js App interface and make sure that the **`SwapExecuted`** event was emitted. + +![Swap From Exact Tokens Event](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-10.webp) + +### Swapping To an Exact Amount of Tokens + +Conversely, the Asset Conversion pallet comes with a function that allows users to trade a variable amount of one asset to acquire a precise quantity of another. It ensures that users stay within a set maximum of the initial asset to obtain the desired amount of the second asset. This provides a method to control transaction costs while achieving the intended result. + +To swap assets for an exact amount of tokens, follow these steps: + +1. Navigate to the **Extrinsics** section on the Polkadot.js App interface + 1. Select **Developer** from the top menu + 2. Click on **Extrinsics** from the dropdown menu + + ![Extrinsics Section](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-1.webp) + +2. Choose the **`AssetConversion`** pallet and click on the **`swapTokensForExactTokens`** extrinsic: + 1. Select the **`AssetConversion`** pallet + 2. Choose the **`swapTokensForExactTokens`** extrinsic from the list of available extrinsics + + ![Swap Tokens For Exact Tokens Extrinsic](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-11.webp) + +3. Fill in the required fields: + 1. **`path:Vec<StagingXcmV3MultiLocation\>`** - an array of Multilocations representing the path of the swap. The first and last elements of the array are the input and output assets, respectively. In this case, the path consists of two elements: + - **`0: StagingXcmV3MultiLocation`** - the Multilocation of the first asset in the pool. In this case, it is the PPM token, which the following Multilocation represents: + ```javascript + { + parents: 0, + interior: { + X2: [{PalletInstance: 50}, {GeneralIndex: 1112}] + } + } + ``` + - **`1: StagingXcmV3MultiLocation`** - the second asset's Multilocation within the pool. This refers to the DOT token, which the following Multilocation identifies: + ```javascript + { + parents: 0, + interior: Here + } + ``` + 1. **`amountOut`** - the exact amount of the second asset that the user wants to receive + 2. **`amountInMax`** - the maximum amount of the first asset that the user is willing to swap + 3. **`sendTo`** - the account to which the swapped assets will be sent + 4. **`keepAlive`** - a boolean value that determines whether the pool should be kept alive after the swap + 5. Click on **Submit Transaction** to swap assets for an exact amount of tokens + + ![Swap Tokens For Exact Tokens Fields](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-12.webp) + + !!! warning + Before swapping assets, ensure that the tokens provided have been minted previously and are available in your account. + + In this case, the intention is to swap 0.01 DOT token (`u128` value of 100000000000 as it has ten decimals) for 0.04 PPM token (`u128` value of 400000000000 as it also has ten decimals). + +Signing and submitting the transaction will execute the swap. To verify execution, check the **Explorer** section on the Polkadot.js App interface and make sure that the **`SwapExecuted`** event was emitted. + +![Swap Tokens For Exact Tokens Event](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-13.webp) + +## Withdrawing Liquidity from a Pool + +The Asset Conversion pallet provides the `removeLiquidity` extrinsic to remove liquidity from a pool. This function allows users to withdraw the liquidity they offered from a pool, returning the original assets. When calling this function, users specify the number of liquidity tokens (representing their share in the pool) they wish to burn. They also set minimum acceptable amounts for the assets they expect to receive back. This mechanism ensures that users can control the minimum value they receive, protecting against unfavorable price movements during the withdrawal process. + +To withdraw liquidity from a pool, follow these steps: + +1. Navigate to the **Extrinsics** section on the Polkadot.js App interface + 1. Select **Developer** from the top menu + 2. Click on **Extrinsics** from the dropdown menu + + ![Extrinsics Section](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-1.webp) + +2. Choose the **`AssetConversion`** pallet and click on the **`remove_liquidity`** extrinsic + 1. Select the **`AssetConversion`** pallet + 2. Choose the **`removeLiquidity`** extrinsic from the list of available extrinsics + + ![Remove Liquidity Extrinsic](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-14.webp) + +3. Fill in the required fields: + 1. **`asset1`** - the Multilocation of the first asset in the pool. In this case, it is the DOT token, which the following Multilocation represents: + ```javascript + { + parents: 0, + interior: Here + } + ``` + 2. **`asset2`** - the second asset's Multilocation within the pool. This refers to the PPM token, which the following Multilocation identifies: + ```javascript + { + parents: 0, + interior: { + X2: [{PalletInstance: 50}, {GeneralIndex: 1112}] + } + } + ``` + 3. **`lpTokenBurn`** - the number of liquidity tokens to burn + 4. **`amount1MinReceived`** - the minimum amount of the first asset that the user expects to receive + 5. **`amount2MinReceived`** - the minimum quantity of the second asset the user expects to receive + 6. **`withdrawTo`** - the account to which the withdrawn assets will be sent + 7. Click on **Submit Transaction** to withdraw liquidity from the pool + + ![Remove Liquidity Fields](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-15.webp) + + !!! warning + Ensure that the tokens provided have been minted previously and are available in your account before withdrawing liquidity from the pool. + + In this case, the intention is to withdraw 0.05 liquidity tokens from the pool, expecting to receive 0.004 DOT token (`u128` value of 40000000000 as it has ten decimals) and 0.04 PPM token (`u128` value of 400000000000 as it also has ten decimals). + +Signing and submitting the transaction will initiate the withdrawal of liquidity from the pool. To verify the withdrawal, check the **Explorer** section on the Polkadot.js App interface and ensure that the **`LiquidityRemoved`** event was emitted. + +![Remove Liquidity Event](/images/polkadot-protocol/system-parachains/asset-hub/asset-conversion/asset-conversion-16.webp) + +## Test Environment Setup + +To test the Asset Conversion pallet, you can set up a local test environment to simulate different scenarios. This guide uses Chopsticks to spin up an instance of Polkadot Asset Hub. For further details on using Chopsticks, please refer to the [Chopsticks documentation](./docs/dev-tools/chopsticks/overview.md){target=\_blank}. + +To set up a local test environment, execute the following command: + +```bash +npx @acala-network/chopsticks \ +--config=https://raw.githubusercontent.com/AcalaNetwork/chopsticks/master/configs/polkadot-asset-hub.yml +``` + +!!! note + This command initiates a lazy fork of Polkadot Asset Hub, including the most recent block information from the network. For Kusama Asset Hub testing, simply switch out `polkadot-asset-hub.yml` with `kusama-asset-hub.yml` in the command. + +You now have a local Asset Hub instance up and running, ready for you to test various asset conversion procedures. The process here mirrors what you'd do on MainNet. After completing a transaction on TestNet, you can apply the same steps to convert assets on MainNet. \ No newline at end of file diff --git a/polkadot-protocol/system-parachains/asset-hub/asset-hub-introduction.md b/polkadot-protocol/system-parachains/asset-hub/asset-hub-introduction.md new file mode 100644 index 000000000..b454d0079 --- /dev/null +++ b/polkadot-protocol/system-parachains/asset-hub/asset-hub-introduction.md @@ -0,0 +1,47 @@ +--- +title: Overview of Asset Hub +description: Guide to learn and implement Asset Hub parachain on Polkadot, a decentralized platform for the issuance, management, and trading of digital assets. +--- + +# Asset Hub + +## Introduction + +Asset Hub is a [System Parachain](https://wiki.polkadot.network/docs/learn-system-chains){target=\_blank} designed to manage and operate assets within the Polkadot network. It specializes in creating, managing, and using assets. It is considered the primary hub for asset operations in the network. + +The native token for the Polkadot Asset Hub is DOT, and for the Kusama Asset Hub, it is KSM. Both cases maintain a trusted relationship with the relay chain. + +You can refer to the [How to Teleport DOT or KSM to Asset Hub](https://support.polkadot.network/support/solutions/articles/65000181119){target=\_blank} guide to learn how to send native assets to Asset Hub. + +Some common use cases for Asset Hub include: + +- Creating and managing assets +- Transferring non-native tokens and creating NFTs +- Reducing transfer fees and [existential deposits](https://support.polkadot.network/support/solutions/articles/65000168651){target=\_blank} +- Meeting the existential deposit requirement for insufficient assets + +## Assets + +An asset on the blockchain is a digital representation of value, such as cryptocurrencies and tokens, that can be transferred and traded. Asset Hub stores assets as a map from an ID to information about the asset, including details about the management team, total supply, and other relevant information. + +The [Asset Pallet](https://paritytech.github.io/polkadot-sdk/master/pallet_assets/index.html){target=\_blank} facilitates the management of these assets by providing essential functions for handling them. + +Asset Hub acts as a management portal for asset creators, letting them mint and burn tokens and get an overview of the total issuance across the Polkadot network, including tokens sent elsewhere in the network. + +### Local Assets + +Instead of using custom contracts for each asset, Asset Hub incorporates built-in asset logic, treating them as primary primitives. All assets have identical functionality. + +These assets, identified by claimable, integer-based asset IDs, are known as `local assets`. This approach simplifies asset management, as users can interact with them using the same set of functions. + +The protocol ensures that each asset ID (an integer) is unique, enabling creators to assign metadata such as the asset symbol. Therefore, users should verify their assets to confirm they possess the correct ID. For instance, although anyone can label their asset as USDT, users will probably seek the one issued by [Tether](https://tether.to/en/){target=\_blank} (asset ID 1984). + +You can read the [What is Asset Hub and How Do I Use it?](https://support.polkadot.network/support/solutions/articles/65000181800){target=\_blank} article for more information on verifying an asset's legitimacy on Asset Hub. + +### Foreign Assets + +Asset Hub considers assets originating from a different blockchain to be foreign assets. These assets can be native tokens from various parachains or other consensus systems like Ethereum. Once a foreign asset is added to Asset Hub, users can transfer this token from its original blockchain to Asset Hub and utilize it like any other asset. + +A significant difference lies in the method used for their identification. Unlike the Assets pallet, foreign assets use [XCM Multilocation](https://wiki.polkadot.network/docs/learn/xcm/fundamentals/multilocation-summary){target=\_blank} instead of integers to identify assets, making asset identification much more versatile. + +Foreign assets are implemented as an [instance of Assets pallet](https://github.com/paseo-network/runtimes/blob/main/system-parachains/asset-hub-paseo/src/lib.rs#L363){target=\_blank}, but with a specialized configuration that enables support for XCM operations. \ No newline at end of file diff --git a/tutorials/.pages b/tutorials/.pages index ec33f0aca..1cf7ae532 100644 --- a/tutorials/.pages +++ b/tutorials/.pages @@ -1,3 +1,4 @@ title: Tutorials nav: - index.md + - polkadot-sdk diff --git a/tutorials/index.md b/tutorials/index.md index c5603acf8..24957bd8b 100644 --- a/tutorials/index.md +++ b/tutorials/index.md @@ -1,5 +1,5 @@ --- -title: Step-by-Step Tutorials +title: Tutorials description: TODO hide: - feedback diff --git a/tutorials/polkadot-sdk/.pages b/tutorials/polkadot-sdk/.pages new file mode 100644 index 000000000..7b15c3f08 --- /dev/null +++ b/tutorials/polkadot-sdk/.pages @@ -0,0 +1,5 @@ +title: Polkadot SDK +nav: + - index.md + - 'Build a Blockchain': build-a-blockchain + - 'Build a Parachain': build-a-parachain \ No newline at end of file diff --git a/tutorials/polkadot-sdk/build-a-blockchain/.pages b/tutorials/polkadot-sdk/build-a-blockchain/.pages new file mode 100644 index 000000000..7b94b8fa6 --- /dev/null +++ b/tutorials/polkadot-sdk/build-a-blockchain/.pages @@ -0,0 +1,6 @@ +title: Build a Blockchain +nav: + - index.md + - 'Build a Local Solochain': build-a-local-blockchain.md + - 'Simulate a Network': simulate-a-network.md + - 'Upgrade a Running Network': upgrade-a-running-network.md \ No newline at end of file diff --git a/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain.md b/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain.md new file mode 100644 index 000000000..0ef481013 --- /dev/null +++ b/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain.md @@ -0,0 +1,118 @@ +--- +title: Build a Local Solochain +description: Learn to compile and launch a local blockchain node using Polkadot SDK. Build, run, and interact with a pre-configured node template. +--- + +# Build a Local Solochain + +## Introduction + +[Polkadot SDK](https://github.com/paritytech/polkadot-sdk){target=\_blank} offers a versatile and extensible blockchain development framework, enabling you to create custom blockchains tailored to your specific application or business requirements. + +This tutorial guides you through compiling and launching a standalone blockchain node using the [Polkadot SDK Solochain Template](https://github.com/paritytech/polkadot-sdk-solochain-template){target=\_blank}. You'll create a fully functional chain that operates independently, without connections to a relay chain or parachain. + +The node template provides a pre-configured, functional single-node blockchain you can run in your local development environment. It includes several key components, such as user accounts and account balances. + +These predefined elements allow you to experiment with common blockchain operations without requiring initial template modifications. +In this tutorial, you will: + +- Build and start a local blockchain node using the node template +- Explore how to use a front-end interface to: + - View information about blockchain activity + - Submit a transaction + +By the end of this tutorial, you'll have a working local solochain and understand how to interact with it, setting the foundation for further customization and development. + +## Prerequisites + +To get started with the node template, you'll need to have the following set up on your development machine first: + +- Rust installation - the node template is written in [Rust](https://www.rust-lang.org/){target=\_blank}, so you'll need to have it installed and configured on your system. Refer to the [Installation]() section for step-by-step instructions on setting up your development environment + +## Compile a Node + +The [Polkadot SDK Solochain Template](https://github.com/paritytech/polkadot-sdk-solochain-template){target=\_blank} provides a ready-to-use development environment for building using the [Polkadot SDK](https://github.com/paritytech/polkadot-sdk){target=\_blank}. Follow these steps to compile the node: + +1. Clone the node template repository: + ```bash + git clone -b {{dependencies.polkadot_sdk_solochain_template.version}} {{dependencies.polkadot_sdk_solochain_template.repository_url}} + ``` + + !!!note + This tutorial uses version `{{dependencies.polkadot_sdk_solochain_template.version}}` of the Polkadot SDK Solochain Template. Make sure you're using the correct version to match these instructions. + +2. Navigate to the root of the node template directory: + ```bash + cd polkadot-sdk-solochain-template + ``` + +3. Compile the node template: + ```bash + cargo build --release + ``` + + !!!note + Initial compilation may take several minutes, depending on your machine specifications. Always use the `--release` flag to build optimized, production-ready artifacts. + +4. Upon successful compilation, you should see output similar to: + --8<-- 'code/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/compilation-output.html' + +## Start the Local Node + +After successfully compiling your node, you can run it and produce blocks. This process will start your local blockchain and allow you to interact. Follow these steps to launch your node in development mode: + +1. In the terminal where you compiled your node, start it in development mode: + ```bash + ./target/release/solochain-template-node --dev + ``` + The `--dev` option does the following: + - Specifies that the node runs using the predefined development chain specification + - Deletes all active data (keys, blockchain database, networking information) when stopped + - Ensures a clean working state each time you restart the node + +2. Verify that your node is running by reviewing the terminal output. You should see something similar to: + --8<-- 'code/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/node-output.html' + +3. Confirm that your blockchain is producing new blocks by checking if the number after `finalized` is increasing + --8<-- 'code/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/node-block-production.html' + + !!!note + The details of the log output will be explored in a later tutorial. For now, knowing that your node is running and producing blocks is sufficient. + +## Interact with the Node + +When running the template node, it's accessible by default at: + +```bash +ws://localhost:9944 +``` +To interact with your node using the [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer){target=\_blank} interface, follow these steps: + +1. Open [Polkadot.js Apps](https://polkadot.js.org/apps/#/explorer){target=\_blank} in your web browser and click the network icon in the top left corner + ![](/images/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/build-a-local-blockchain-1.webp) + +2. Connect to your local node: + 1. Scroll to the bottom and select **Development** + 2. Choose **Custom** + 3. Enter `ws://localhost:9944` in the input field + 4. Click the **Switch** button + ![](/images/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/build-a-local-blockchain-2.webp) + +3. Verify connection: + - Once connected, you should see **solochain-template-runtime** in the top left corner + - The interface will display information about your local blockchain + ![](/images/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain/build-a-local-blockchain-3.webp) + +You are now connected to your local node and can now interact with it through the Polkadot.js Apps interface. This tool enables you to explore blocks, execute transactions, and interact with your blockchain's features. For in-depth guidance on using the interface effectively, refer to the [Polkadot.js Guides](https://wiki.polkadot.network/docs/learn-polkadot-js-guides){target=\_blank} available on the Polkadot Wiki. + +<!-- TODO: Polkadot.js Apps guide --> + +## Stop the Node + +When you're done exploring your local node, you can stop it to remove any state changes you've made. Since you started the node with the `--dev` option, stopping the node will purge all persistent block data, allowing you to start fresh the next time. + +To stop the local node: + +1. Return to the terminal window where the node output is displayed +2. Press `Control-C` to stop the running process +3. Verify that your terminal returns to the prompt in the `polkadot-sdk-solochain-template` directory \ No newline at end of file diff --git a/tutorials/polkadot-sdk/build-a-blockchain/index.md b/tutorials/polkadot-sdk/build-a-blockchain/index.md new file mode 100644 index 000000000..60ab231fe --- /dev/null +++ b/tutorials/polkadot-sdk/build-a-blockchain/index.md @@ -0,0 +1,7 @@ +--- +title: Build a Blockchain +description: Learn to build and manage Polkadot SDK-based blockchain nodes. Covers setup, networking, authorization, monitoring, and upgrades. +hide: +- feedback +template: subsection-index-page.html +--- diff --git a/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network.md b/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network.md new file mode 100644 index 000000000..abd881a5c --- /dev/null +++ b/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network.md @@ -0,0 +1,200 @@ +--- +title: Simulate a Network +description: Create a private blockchain network with authorized validators using Polkadot SDK. Start nodes, connect peers and verify block production. +--- + +# Simulate a Network + +## Introduction + +This tutorial introduces you to the process of initiating a private blockchain network with a set of authorized validators. The [Polkadot SDK Solochain Template](https://github.com/paritytech/polkadot-sdk-solochain-template){target=\_blank} implements an authority consensus model to regulate block production. In this model, the creation of blocks is restricted to a predefined list of authorized accounts, known as "authorities," who operate in a round-robin fashion. + +To demonstrate this concept, you'll simulate a network environment using two nodes running on a single computer, each configured with different accounts and keys. Throughout this tutorial, you'll gain practical insight into the functionality of the authority consensus model by observing how these two predefined accounts, serving as authorities, enable the nodes to produce blocks. + +By completing this tutorial, you will accomplish the following objectives: + +- Start a blockchain node using a predefined account +- Learn the key command-line options used to start a node +- Determine if a node is running and producing blocks +- Connect a second node to a running network +- Verify peer computers produce and finalize blocks + +## Prerequisites + +Before proceeding, ensure you have the following prerequisites in place: + +- Installed and configured Rust on your system. Refer to the [Installation]() guide for detailed instructions on installing Rust and setting up your development environment +- Completed the [Build a Local Blockchain](#build-a-local-blockchain) guide and have the [Polkadot SDK Solochain Template](https://github.com/paritytech/polkadot-sdk-solochain-template){target=\_blank} installed on your local machine + +## Start the First Blockchain Node + +This tutorial demonstrates the fundamentals of a private network using a predefined chain specification called local and two preconfigured user accounts. You'll simulate a private network by running two nodes on a single local computer, using accounts named Alice and Bob. + +Follow these steps to start your first blockchain node: + +1. Navigate to the root directory where you compiled the Polkadot SDK Solochain Template + +2. Clear any existing chain data by executing the following: + ```bash + ./target/release/solochain-template-node purge-chain --base-path /tmp/alice --chain local + ``` + + When prompted to confirm, type `y` and press `Enter`. This step ensures a clean start for your new network + +3. Launch the first blockchain node using the Alice account: + ```bash + ./target/release/solochain-template-node \ + --base-path /tmp/alice \ + --chain local \ + --alice \ + --port 30333 \ + --rpc-port 9945 \ + --node-key 0000000000000000000000000000000000000000000000000000000000000001 \ + --validator + ``` + +### Review the Command-Line Options + +Before proceeding, examine the key command-line options used to start the node: + +- `--base-path` - specifies the directory for storing all chain-related data +- `--chain` - defines the chain specification to use +- `--alice` - adds the predefined keys for the Alice account to the node's keystore. This account is used for block production and finalization +- `--port` - sets the listening port for peer-to-peer (p2p) traffic. Different ports are necessary when running multiple nodes on the same machine +- `--rpc-port` - specifies the port for incoming JSON-RPC traffic via WebSocket and HTTP +- `--node-key` - defines the Ed25519 secret key for libp2p networking +- `--validator` - enables this node to participate in block production and finalization for the network + +For a comprehensive overview of all available command-line options for the node template, you can access the built-in help documentation. Execute the following command in your terminal: + +```bash +./target/release/solochain-template-node --help +``` + +## Review the Node Messages + +Upon successful node startup, the terminal displays messages detailing network operations and information relevant to the running node. This output includes details about the chain specification, system data, network status, and other crucial parameters. You should see output similar to this: + +--8<-- 'code/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network/node-output.html' + +Pay particular attention to the following key messages: + +- Genesis block initialization: + + ```plain + 2024-09-10 08:35:43 🔨 Initializing Genesis block/state (state: 0x074c…27bd, header-hash: 0x850f…951f) + ``` + + This message identifies the initial state or genesis block used by the node. When starting subsequent nodes, ensure these values match. + +- Node identity: + + ```plain + 2024-09-10 08:35:43 🏷 Local node identity is: 12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp + ``` + + This string uniquely identifies the node. It's determined by the `--node-key` used to start the node with the Alice account. Use this identifier when connecting additional nodes to the network. + +- Network status: + + ```plain + 2024-09-10 08:35:48 💤 Idle (0 peers), best: #0 (0x850f…951f), finalized #0 (0x850f…951f), ⬇ 0 ⬆ 0 + ``` + + This message indicates that: + + - No other nodes are currently in the network + - No blocks are being produced + - Block production will commence once another node joins the network + +## Add a Second Node to the Network + +After successfully running the first node with the Alice account keys, you can expand the network by adding a second node using the Bob account. This process involves connecting to the existing network using the running node as a reference point. The commands are similar to those used for the first node, with some key differences to ensure proper network integration. + +To add a node to the running blockchain: + +1. Open a new terminal shell on your computer + +2. Navigate to the root directory where you compiled the Polkadot SDK Solochain Template + +3. Clear any existing chain data for the new node: + + ```bash + ./target/release/solochain-template-node purge-chain --base-path /tmp/bob --chain local -y + ``` + + !!!note + The `-y` flag automatically confirms the operation without prompting. + +4. Start the second local blockchain node using the Bob account: + ```bash + ./target/release/solochain-template-node \ + --base-path /tmp/bob \ + --chain local \ + --bob \ + --port 30334 \ + --rpc-port 9946 \ + --node-key 0000000000000000000000000000000000000000000000000000000000000002 \ + --validator \ + --bootnodes /ip4/127.0.0.1/tcp/30333/p2p/12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp + ``` + + Key differences in this command: + + 1. Unique paths and ports - to avoid conflicts on the same machine, different values are used for: + - `--base-path` - set to `/tmp/bob` + - `--port` - set to `30334` + - `--rpc-port` - set to `9946` + + 2. Bootnode specification - the `--bootnodes` option is crucial for network discovery: + - Format - `/ip4/127.0.0.1/tcp/30333/p2p/12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp` + - Components: + - `ip4` - indicates IPv4 format + - `127.0.0.1` - IP address of the running node (localhost in this case) + - `tcp` - specifies TCP for peer-to-peer communication + - `30333` - port number for peer-to-peer TCP traffic + - `12D3KooWEyoppNCUx8Yx66oV9fJnriXwCcXwDDUA2kj6vnc6iDEp` - unique identifier of the Alice node + +## Verify Blocks are Produced and Finalized + +After starting the second node, both nodes should connect as peers and commence block production. + +Follow these steps to verify that blocks are being produced and finalized: + +1. Observe the output in the terminal of the first node (Alice): + + --8<-- 'code/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network/node-output-1.html' + + Key information in this output: + + - Second node discovery - `discovered: 12D3KooWHdiAxVd8uMQR1hGWXccidmfCwLqcMpGwR6QcTP6QRMuD` + - Peer count - `1 peers` + - Block production - `best: #4 (0xe176…0430)` + - Block finalization - `finalized #1 (0x75bb…e82d)` + +2. Check the terminal of the second node (Bob) for similar output + +3. Shut down one node using `Control-C` in its terminal. Observe the remaining node's output: + + --8<-- 'code/tutorials/polkadot-sdk/build-a-blockchain/simulate-a-network/node-shutdown.html' + + Note that the peer count drops to zero, and block production stops. + +4. Shut down the second node using `Control-C` in its terminal + +5. Clean up chain state from the simulated network by using the `purge-chain` subcommand: + + - For Alice's node: + ```bash + ./target/release/solochain-template-node purge-chain \ + --base-path /tmp/alice \ + --chain local \ + -y + ``` + - For Bob's node: + ```bash + ./target/release/solochain-template-node purge-chain \ + --base-path /tmp/bob \ + --chain local \ + -y + ``` \ No newline at end of file diff --git a/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network.md b/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network.md new file mode 100644 index 000000000..ca29c119b --- /dev/null +++ b/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network.md @@ -0,0 +1,233 @@ +--- +title: Upgrade a Running Network +description: Learn how to perform forkless runtime upgrades on a Polkadot SDK-based blockchain. Add features and modify parameters without network disruption. +--- + +# Upgrade a Running Network + +## Introduction + +One of the key advantages of the Polkadot SDK development framework is its support for forkless upgrades to the blockchain runtime, which forms the core logic of the chain. Unlike many other blockchains, where introducing new features or improving existing ones often requires a hard fork, Polkadot SDK enables seamless upgrades even when introducing breaking changes—without disrupting the network's operation. + +Polkadot SDK's design incorporates the runtime directly into the blockchain's state, allowing participants to upgrade the runtime by calling the `set_code` function within a transaction. This mechanism ensures that updates are validated using the blockchain's consensus and cryptographic guarantees, allowing runtime logic to be updated or extended without forking the chain or requiring a new blockchain client. + +In this tutorial, you'll learn how to upgrade the runtime of a Polkadot SDK-based blockchain without stopping the network or creating a fork. + +You'll make the following changes to a running network node's runtime: + +- Increase the `spec_version` +- Add the Utility pallet +- Increase the minimum balance for network accounts + +By the end of this tutorial, you’ll have the skills to upgrade the runtime and submit a transaction to deploy the modified runtime on a live network. + +## Prerequisites + +Before starting this tutorial, ensure you meet the following requirements: + +- Installed and configured Rust on your system. Refer to the [Installation]() guide for detailed instructions on installing Rust and setting up your development environment +- Completed the [Build a Local Blockchain]() tutorial and have the [Polkadot SDK Solochain Template](https://github.com/paritytech/polkadot-sdk-solochain-template){target=\_blank} installed on your machine + +## Start the Node + +To demonstrate how to update a running node, you first need to start the local node with the current runtime. + +1. Navigate to the root directory where you compiled the Polkadot SDK Solochain Template + +2. Start the local node in development mode by running the following command: + ```bash + ./target/release/solochain-template-node --dev + ``` + + !!!note + Keep the node running throughout this tutorial. You can modify and re-compile the runtime without stopping or restarting the node. + +3. Connect to your node using the same steps outlined in the [Interact with the Node]() section. Once connected, you’ll notice the node template is using the default version, `100`, displayed in the upper left + + ![](/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-1.webp) + +## Modify the Runtime + +### Add the Utility Pallet to the Dependencies + +First, you'll update the `Cargo.toml` file to include the Utility pallet as a dependency for the runtime. Follow these steps: + +1. Open the `runtime/Cargo.toml` file and locate the `[dependencies]` section. Add the Utility pallet by inserting the following line: + + ```toml + pallet-utility = { version = "37.0.0", default-features = false} + ``` + + Your `[dependencies]` section should now look something like this: + + ```toml + [dependencies] + codec = { features = ["derive"], workspace = true } + scale-info = { features = ["derive", "serde"], workspace = true } + frame-support = { features = ["experimental"], workspace = true } + ... + pallet-utility = { version = "37.0.0", default-features = false } + ``` + +2. In the `[features]` section, add the Utility pallet to the `std` feature list by including: + ```toml + [features] + default = ["std"] + std = [ + "codec/std", + "scale-info/std", + "frame-executive/std", + ... + "pallet-utility/std", + ] + ``` + +3. Save the changes and close the `Cargo.toml` file + +### Update the Runtime Configuration + +You'll now modify the `runtime/src/lib.rs` file to integrate the Utility pallet and make other necessary changes. In this section, you'll configure the Utility pallet by implementing its `Config` trait, update the runtime macro to include the new pallet, adjust the `EXISTENTIAL_DEPOSIT` value, and increment the runtime version. + +#### Configure the Utility Pallet + +To configure the Utility pallet, take the following steps: + +1. Implement the [`Config`](https://paritytech.github.io/polkadot-sdk/master/pallet_utility/pallet/trait.Config.html){target=\_blank} trait for the Utility pallet: + + ```rust + --8<-- 'code/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/config-trait-impl.rs' + ``` + +2. Locate the `#[frame_support::runtime]` macro and add the Utility pallet: + + ```rust + --8<-- 'code/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/fs-runtime-macro.rs' + ``` + +#### Update Existential Deposit Value + +To update the `EXISTENTIAL_DEPOSIT` in the Balances pallet, locate the constant and set the value to `1000`: + +```rust +... +/// Existential deposit +pub const EXISTENTIAL_DEPOSIT: u128 = 1000; +... +``` + +!!!note + This change increases the minimum balance required for accounts to remain active. No accounts with balances between `500` and `1000` will be removed. For account removal, a storage migration is needed. See [Storage Migration]() for details. + +#### Update Runtime Version + +Locate the `runtime_version` macro and increment the `spec_version` field from `100` to `101`: + +```rust +--8<-- 'code/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/runtime-version-macro.rs' +``` + +### Recompile the Runtime + +Once you've made all the necessary changes, recompile the runtime by running: + +```bash +cargo build --release +``` + +The build artifacts will be output to the `target/release` directory. The Wasm build artifacts can be found in the `target/release/wbuild/solochain-template-runtime` directory. You should see the following files: + +- `solochain_template_runtime.compact.compressed.wasm` +- `solochain_template_runtime.compact.wasm` +- `solochain_template_runtime.wasm` + +## Execute the Runtime Upgrade + +Now that you've generated the Wasm artifact for your modified runtime, it's time to upgrade the running network. This process involves submitting a transaction to load the new runtime logic. + +### Understand Runtime Upgrades + +#### Authorization with Sudo + +In production networks, runtime upgrades typically require community approval through governance. For this tutorial, the Sudo pallet will be used to simplify the process. The Sudo pallet allows a designated account (usually Alice in development environments) to perform privileged operations, including runtime upgrades. + +#### Resource Accounting + +Runtime upgrades use the `set_code` extrinsic, which is designed to consume an entire block's resources. This design prevents other transactions from executing on different runtime versions within the same block. The `set_code` extrinsic is classified as an Operational call, one of the variants of the [`DispatchClass`](https://paritytech.github.io/polkadot-sdk/master/frame_support/dispatch/enum.DispatchClass.html#){target=\_blank} enum. This classification means it: + +- Can use a block's entire weight limit +- Receives maximum priority +- Is exempt from transaction fees + +To bypass resource accounting safeguards, the `sudo_unchecked_weight` extrinsic will be used. This allows you to specify a weight of zero, ensuring the upgrade process has unlimited time to complete. + +### Perform the Upgrade + +Follow these steps to update your network with the new runtime: + +1. Open [Polkadot.js Apps](https://polkadot.js.org/apps/?rpc=ws%3A%2F%2Flocalhost%3A9944#/explorer){target=_blank} in your web browser and make sure you are connected to your local node + +2. Navigate to the **Developer** dropdown and select the **Extrinsics** option + + ![](/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-2.webp) + +3. Construct the `set_code` extrinsic call: + + 1. Select the **`sudo`** pallet + 2. Choose the **`sudoUncheckedWeight`** extrinsic + 3. Select the **`system`** pallet + 4. Choose the **`setCode`** extrinsic + 5. Fill in the parameters: + - **`code`** - the new runtime code + + !!!note + You can click the **file upload toggle** to upload a file instead of copying the hex string value. + + - **`weight`** - lave both parameters set to the default value of `0` + + 6. Click on **Submit Transaction** + + ![](/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-3.webp) + +4. Review the transaction details and click **Sign and Submit** to confirm the transaction + + ![](/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-4.webp) + + +### Verify the Upgrade + +#### Runtime Version Change + +Verify that the runtime version of your blockchain has been updated successfully. Follow these steps to ensure the upgrade was applied: + +1. Navigate to the **Network** dropdown and select the **Explorer** option + + ![](/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-5.webp) + +2. After the transaction is included in a block, check: + 1. There has been a successful `sudo.Sudid` event + 2. The indicator shows that the runtime version is now `101` + + ![](/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-6.webp) + +#### Utility Pallet Addition + +In the **Extrinsics** section, you should see that the Utility pallet has been added as an option. + +![](/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-7.webp) + +#### Existential Deposit Update + +Check the updated existential deposit value on your blockchain. Follow these steps to query and verify the new value: + +1. Navigate to the **Developer** dropdown and select the **Chain State** option + + ![](/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-8.webp) + +2. Query the existential deposit value + 1. Click on the **Constants** tab + 2. Select the **`balances`** pallet + 3. Choose the **`existentialDeposit`** constant + 4. Click the **+** button to execute the query + 5. Check the existential deposit value + + ![](/images/tutorials/polkadot-sdk/build-a-blockchain/upgrade-a-running-network/upgrade-a-running-network-9.webp) \ No newline at end of file diff --git a/tutorials/polkadot-sdk/build-a-parachain/.pages b/tutorials/polkadot-sdk/build-a-parachain/.pages new file mode 100644 index 000000000..0edb0f229 --- /dev/null +++ b/tutorials/polkadot-sdk/build-a-parachain/.pages @@ -0,0 +1,6 @@ +title: Build a Parachain Tutorials +nav: + - index.md + - 'Prepare a Relay Chain': prepare-relay-chain.md + - 'Connect a Parachain': connect-a-parachain.md + - 'Acquire a TestNet Slot': acquire-a-testnet-slot.md diff --git a/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot.md b/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot.md new file mode 100644 index 000000000..26079c010 --- /dev/null +++ b/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot.md @@ -0,0 +1,173 @@ +--- +title: Acquire a TestNet Slot +description: This guide walks you through the journey of securing a TestNet slot on Paseo for your parachain, detailing each step to a successful registration. +--- + +# Acquire a TestNet Slot + +## Introduction + +This tutorial demonstrates deploying a parachain on a public test network like the Paseo network. Public TestNets have a higher bar to entry than a private network but represent an essential step in preparing a parachain project to move into a production network. + +## Prerequisites + +Before you start, you need to have the following prerequisites: + +- You know how to generate and modify chain specification files as described in the [Add Trusted Nodes](TODO:update-path){target=\_blank} tutorial +- You know how to generate and store keys as described in the [Add Trusted Nodes](TODO:update-path){target=\_blank} tutorial +- You have completed the [Prepare a Local Relay Chain](/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain/){target=\_blank} and the [Connect a Local Parachain](/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain.md){target=\_blank} tutorials on your local computer + +## Get Started with an Account and Tokens + +To perform any action on Paseo, you need PAS tokens, which can be requested from the [Polkadot Faucet](https://faucet.polkadot.io/){target=\_blank}. Also, to store the tokens, you must have access to a Substrate-compatible digital currency wallet. You can't use [development keys and accounts](TODO:update-path){target=\_blank} for operations in any public setting. Many options are available for holding digital currency—including hardware wallets and browser-based applications—and some are more reputable than others. You should do your own research before selecting one. + +However, you can use the [Polkadot.js Apps](https://polkadot.js.org/apps/){target=\_blank} interface to get you started for testing purposes. + +To prepare an account, follow these steps: + +1. Open the [Polkadot.js Apps](https://polkadot.js.org/apps/){target=\_blank} interface and connect to the Paseo network + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-1.webp) + +2. Navigate to the **Accounts** section + 1. Click on the **Accounts** tab in the top menu + 2. Select the **Accounts** option from the dropdown menu + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-2.webp) + +3. Copy the address of the account you want to use for the parachain deployment + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-3.webp) + +4. Visit the [Polkadot Faucet](https://faucet.polkadot.io){target=\_blank} and paste the copied address in the input field. Ensure that the network is set to Paseo and click on the **Get some PASs** button + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-4.webp) + + After a few seconds, you will receive 100 PAS tokens in your account. + +## Reserve a Parachain Identifier + +You must reserve a parachain identifier before registering a parathread on Paseo. The steps are similar to the ones you followed in [Connect a Local Parachain](/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/){target=_\blank} to reserve an identifier on the local relay chain. However, for the public TestNet, you'll be assigned the next available identifier. + +To reserve a parachain identifier, follow these steps: + +1. Navigate to the **Parachains** section + 1. Click on the **Network** tab in the top menu + 2. Select the **Parachains** option from the dropdown menu + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-5.webp) + +2. Register a parathread + 1. Select the **Parathreads** tab + 2. Click on the **+ ParaId** button + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-6.webp) + +3. Review the transaction and click on the **+ Submit** button + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-7.webp) + + For this case, the next available parachain identifier is `4508`. + +4. After submitting the transaction, you can navigate to the **Explorer** tab and check the list of recent events for successful `registrar.Reserved` + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/acquire-a-testnet-slot-8.webp) + +## Modify the Chain Specification File + +The files required to register a parachain must specify the correct relay chain to connect to and the parachain identifier you have been assigned. To make these changes, you must build and modify the chain specification file for your parachain. In this tutorial, the relay chain is `paseo`, and the parachain identifier is `4508`. + +To modify the chain specification: + +1. Generate the plain text chain specification for the parachain template node by running the following command: + + ```bash + ./target/release/parachain-template-node build-spec \ + --disable-default-bootnode > plain-parachain-chainspec.json + ``` + +2. Open the plain text chain specification for the parachain template node in a text editor + +3. Set `relay_chain` to `paseo` and `para_id` to the identifier you've been assigned. For example, if your reserved identifier is 4508, set the `para_id` field to `4508`: + + ```json + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-1.json:1:4' + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-1.json:23:25' + ``` + +4. Set the `parachainId` to the parachain identifier that you previously reserved: + + ```json + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-1.json::2' + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-1.json:5:10' + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-1.json:22:25' + ``` + +5. Add the public key for your account to the session keys section. Each configured session key will require a running collator: + + ```json + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-1.json::2' + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-1.json:5:7' + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-1.json:11:25' + ``` + +6. Save your changes and close the plain text chain specification file + +7. Generate a raw chain specification file from the modified chain specification file: + + ```bash + ./target/release/parachain-template-node build-spec \ + --chain plain-parachain-chainspec.json \ + --disable-default-bootnode \ + --raw > raw-parachain-chainspec.json + ``` + + After running the command, you will see the following output: + + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/acquire-a-testnet-slot/testnet-slot-2.html' + +## Export Required Files + +To prepare the parachain collator to be registered on Paseo, follow these steps: + +1. Export the Wasm runtime for the parachain by running a command similar to the following: + + ```bash + ./target/release/parachain-template-node export-genesis-wasm \ + --chain raw-parachain-chainspec.json para-4508-wasm + ``` + +2. Export the genesis state for the parachain by running a command similar to the following: + + ```bash + ./target/release/parachain-template-node export-genesis-state \ + --chain raw-parachain-chainspec.json para-4508-state + ``` + +## Start the Collator Node + +You must have the ports for the collator publicly accessible and discoverable to enable parachain nodes to peer with Paseo validator nodes to produce blocks. You can specify the ports with the `--port` command-line option. For example, you can start the collator with a command similar to the following: + +```bash +./target/release/parachain-template-node --collator \ + --chain raw-parachain-chainspec.json \ + --base-path /tmp/parachain/pubs-demo \ + --port 50333 \ + --rpc-port 8855 \ + -- \ + --execution wasm \ + --chain paseo \ + --port 50343 \ + --rpc-port 9988 +``` + +In this example, the first `--port` setting specifies the port for the collator node and the second `--port` specifies the embedded relay chain node port. The first `--rpc-port` setting specifies the port you can connect to the collator. The second `--rpc-port` specifies the port for connecting to the embedded relay chain. + +## Obtain Coretime + +With your parachain collator operational, the next step is acquiring coretime. This is essential for ensuring your parachain's security through the relay chain. [Agile Coretime](https://wiki.polkadot.network/docs/learn-agile-coretime){target=\_blank} enhances Polkadot's resource management, offering developers greater economic adaptability. Once you have configured your parachain, you can follow two paths: + +- Bulk coretime is purchased via the Broker pallet on the respective coretime system parachain. You can purchase bulk coretime on the [coretime chain](TODO:update-path){target=\_blank} and assign the purchased core to the registered `ParaID` +- On-demand coretime is ordered via the `OnDemandAssignment` pallet, which is located on the respective relay chain + +For more information on coretime, refer to the [Coretime](TODO:update-path){target=\_blank} documentation. diff --git a/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain.md b/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain.md new file mode 100644 index 000000000..fc36aba48 --- /dev/null +++ b/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain.md @@ -0,0 +1,296 @@ +--- +title: Connect a Parachain +description: This tutorial will guide you through the comprehensive process of connecting a parachain to a relay chain, covering steps from setup to successful integration. +--- + +# Connect a Parachain + +## Introduction + +This tutorial illustrates reserving a parachain identifier with a local relay chain and connecting a local parachain to that relay chain. By completing this tutorial, you will accomplish the following objectives: + +- Compile a local parachain node +- Reserve a unique identifier with the local relay chain for the parachain to use +- Configure a chain specification for the parachain +- Export the runtime and genesis state for the parachain +- Start the local parachain and see that it connects to the local relay chain + +## Prerequisites + +Before you begin, ensure that you have the following prerequisites: + +- Configured a local relay chain with two validators as described in the [Prepare a Local Relay Chain](/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain/) tutorial +- You are aware that parachain versions and dependencies are tightly coupled with the version of the relay chain they connect to and know the software version you used to configure the relay chain + +## Build the Parachain Template + +This tutorial uses the [Polkadot SDK Parachain Template](https://github.com/paritytech/polkadot-sdk-parachain-template){target=\_blank} to illustrate launching a parachain that connects to a local relay chain. The parachain template is similar to the [Solochain Template](https://github.com/paritytech/polkadot-sdk-solochain-template){target=\_blank} used in development. You can also use the parachain template as the starting point for developing a custom parachain project. + +To build the parachain template, follow these steps: + +1. Clone the branch of the `polkadot-sdk-parachain-template` repository + + ```bash + git clone https://github.com/paritytech/polkadot-sdk-parachain-template.git + ``` + + !!! note + Ensure that you clone the correct branch of the repository that matches the version of the relay chain you are connecting to. + +2. Change the directory to the cloned repository + + ```bash + cd polkadot-sdk-solochain-template + ``` + +3. Build the parachain template collator + + ```bash + cargo build --release + ``` + + !!! note + Depending on your system’s performance, compiling the node can take a few minutes. + +## Reserve a Parachain Identifier + +Every parachain must reserve a unique `ParaID` identifier to connect to its specific relay chain. Each relay chain manages its own set of unique identifiers for the parachains that connect to it. The identifier is called a `ParaID` because the same identifier can be used to identify a slot occupied by a [parachain](https://wiki.polkadot.network/docs/learn-parachains){target=\_blank} or a [parathread](https://wiki.polkadot.network/docs/glossary#parathread){target=\_blank}. + +Note that you must have an account with sufficient funds to reserve a slot on a relay chain. You can determine the number of tokens a specific relay chain requires by checking the `ParaDeposit` configuration in the `paras_registrar` pallet for that relay chain. For example, [Rococo](https://github.com/paritytech/polkadot/blob/master/runtime/rococo/src/lib.rs#L1155){target=\_blank} requires 40 ROC to reserve an identifier: + +```rust +--8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-1.rs' +``` + +Each relay chain allows its identifiers by incrementing the identifier starting at `2000` for all chains that aren't [common good parachains](https://wiki.polkadot.network/docs/learn-system-chains){target=\_blank}. Common good chains use a different method to allocate slot identifiers. + +To reserve a parachain identifier, follow these steps: + +1. Ensure your local relay chain validators are running. For further information, refer to the [Prepare a Local Relay Chain](/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain/) tutorial + +2. Connect to a local relay chain node using the [Polkadot.js Apps](https://polkadot.js.org/apps/){target=_blank} interface. If you have followed the [Prepare a Local Relay Chain](/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain/) tutorial, you can access the Polkadot.js Apps interface at `ws://localhost:9944` + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-1.webp) + +3. Navigate to the **Parachains** section + + 1. Click on the **Network** tab + 2. Select **Parachains** from the dropdown menu + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.webp) + +4. Register a parathread + + 1. Select the **Parathreads** tab + 2. Click on the **+ ParaId** button + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-3.webp) + +5. Fill in the required fields and click on the **+ Submit** button + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-4.webp) + + !!! note + The account used to reserve the identifier will be the account charged for the transaction and the origin account for the parathread associated with the identifier. + +6. After submitting the transaction, you can navigate to the Explorer tab and check the list of recent events for successful `registrar.Reserved` + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-5.webp) + +You are now ready to prepare the chain specification and generate the files required for your parachain to connect to the relay chain using the reserved identifier (`paraId 2000`). + +## Modify the Default Chain Specification + +To register your parachain with the local relay chain, you must modify the default chain specification to use your reserved parachain identifier. + +To modify the default chain specification, follow these steps: + +1. Generate the plain text chain specification for the parachain template node by running the following command + + ```bash + ./target/release/parachain-template-node build-spec \ + --disable-default-bootnode > plain-parachain-chainspec.json + ``` + +2. Open the plain text chain specification for the parachain template node in a text editor + +3. Set the `para_id` to the parachain identifier that you previously reserved. For example, if your reserved identifier is `2000`, set the `para_id` field to `2000`: + + ```json + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.json:1:4' + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.json:6:6' + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.json:13:15' + ``` + +4. Set the `parachainId` to the parachain identifier that you previously reserved. For example, if your reserved identifier is `2000`, set the `parachainId` field to `2000` + + ```json + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.json:1:2' + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.json:6:15' + ``` + +5. If you complete this tutorial simultaneously as anyone on the same local network, an additional step is needed to prevent accidentally peering with their nodes. Find the following line and add characters to make your `protocolId` unique + + ```json + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.json:1:2' + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.json:5:6' + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-2.json:13:15' + ``` + +6. Save your changes and close the plain text chain specification file + +7. Generate a raw chain specification file from the modified chain specification file by running the following command + + ```bash + ./target/release/parachain-template-node build-spec \ + --chain plain-parachain-chainspec.json \ + --disable-default-bootnode \ + --raw > raw-parachain-chainspec.json + ``` + + After running the command, you will see the following output: + + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-3.html' + +## Prepare the Parachain Collator + +With the local relay chain running and the raw chain specification for the parachain template updated, you can start the parachain collator node and export information about its runtime and genesis state. + +To prepare the parachain collator to be registered: + +1. Export the Wasm runtime for the parachain + + The relay chain needs the parachain-specific runtime validation logic to validate parachain blocks. You can export the Wasm runtime for a parachain collator node by running a command similar to the following: + + ```bash + ./target/release/parachain-template-node export-genesis-wasm \ + --chain raw-parachain-chainspec.json para-2000-wasm + ``` + +2. Generate a parachain genesis state + + To register a parachain, the relay chain needs to know the genesis state of the parachain. You can export the entire genesis state—hex-encoded—to a file by running a command similar to the following: + + ```bash + ./target/release/parachain-template-node export-genesis-state \ + --chain raw-parachain-chainspec.json para-2000-genesis-state + ``` + + After running the command, you will see the following output: + + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-4.html' + + !!!note + You should note that the runtime and state you export must be for the genesis block. You can't connect a parachain with any previous state to a relay chain. All parachains must start from block 0 on the relay chain. See [Convert a Solo Chain](https://docs.substrate.io/reference/how-to-guides/parachains/convert-a-solo-chain/){target=\_blank} for details on how the parachain template was created and how to convert the chain logic—not its history or state migrations—to a parachain. + +3. Start a collator node with a command similar to the following + + ```bash + ./target/release/parachain-template-node \ + --charlie \ + --collator \ + --force-authoring \ + --chain raw-parachain-chainspec.json \ + --base-path /tmp/charlie-parachain/ \ + --unsafe-force-node-key-generation \ + --port 40333 \ + --rpc-port 8844 \ + -- \ + --chain INSERT_RELAY_CHAIN_PATH/local-raw-spec.json \ + --port 30333 \ + --rpc-port 9946 + ``` + + !!! note + Ensure that you replace `INSERT_RELAY_CHAIN_PATH` with the path to the raw chain specification for the local relay chain. + + After running the command, you will see the following output: + + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-5.html' + +## Register With the Local Relay Chain + +With the local relay chain and collator node running, you can register the parachain on the local relay chain. In a live public network, registration typically involves a [parachain auction](https://wiki.polkadot.network/docs/learn-auction){target=\_blank}. You can use a Sudo transaction and the Polkadot.js Apps interface for this tutorial and local testing. A Sudo transaction lets you bypass the steps required to acquire a parachain or parathread slot. This transaction should be executed in the relay chain. + +To register the parachain, follow these steps: + +1. Validate that your local relay chain validators are running +2. Navigate to the **Sudo** tab in the Polkadot.js Apps interface + + 1. Click on the **Developer** tab + 2. Select **Sudo** from the dropdown menu + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-6.webp) + +3. Submit a transaction with Sudo privileges + + 1. Select the **`paraSudoWrapper`** pallet + 2. Click on the **`sudoScheduleParaInitialize`** extrinsic from the list of available extrinsics + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-7.webp) + +4. Fill in the required fields + + 1. **`id`** - type the parachain identifier you reserved + 2. **`genesisHead`** - click the **file upload** button and select the `para-2000-genesis-state` file you exported + 3. **`validationCode`** - click the **file upload** button and select the `para-2000-wasm` file you exported + 4. **`paraKind`** - select **Yes** if you are registering a parachain or **No** if you are registering a parathread + 5. Click on the **Submit Transaction** button + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-8.webp) + +5. After submitting the transaction, you can navigate to the **Explorer** tab and check the list of recent events for successful `paras.PvfCheckAccepted` + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-9.webp) + + After the parachain is initialized, you can see it in **Parachains** section of the Polkadot.js Apps interface + +6. Click **Network** and select **Parachains** and wait for a new epoch to start + + ![](/images/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-10.webp) + + The relay chain tracks the latest block—the head—of each parachain. When a relay chain block is finalized, the parachain blocks that have completed the validation process are also finalized. This is how Polkadot achieves pooled, shared security for its parachains. + + After the parachain connects to the relay chain in the next epoch and finalizes its first block you can see information about it in the Polkadot/Substrate Portal. + + The terminal where the parachain is running also displays details similar to the following: + + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/connect-a-parachain-6.html' + +## Resetting the Blockchain State + +The parachain collator you connected to the relay chain in this tutorial contains all of the blockchain data for the parachain. There's only one node in this parachain network, so any transactions you submit are only stored on this node. Relay chains don't store any parachain state. The relay chain only stores header information for the parachains that connect to it. + +For testing purposes, you might want to purge the blockchain state to start over periodically. However, you should remember that if you purge the chain state or manually delete the database, you won’t be able to recover the data or restore the chain state. If you want to preserve data, you should ensure you have a copy before you purge the parachain state. + +If you want to start over with a clean environment for testing, you should completely remove the chain state for the local relay chain nodes and the parachain. + +To reset the blockchain state, follow these steps: + +1. In the terminal where the parachain template node is running, press `Control-C` + +2. Purge the parachain collator state by running the following command + + ```bash + ./target/release/parachain-template-node purge-chain \ + --chain raw-parachain-chainspec.json + ``` + +3. In the terminal where either the `alice` validator node or the `bob` validator node is running, press `Control-C` + +4. Purge the local relay chain state by running the following command + + ```bash + ./target/release/polkadot purge-chain \ + --chain local-raw-spec.json + ``` + +After purging the chain state, you can restart the local relay chain and parachain collator nodes to begin with a clean environment. + +!!! note + Note that to reset the network state and allow all the nodes to sync after the reset, each of them needs to purge their databases. Otherwise, the nodes won't be able to sync with each other effectively. + +Now that you have successfully connected a parachain to a relay chain, you can explore more advanced features and functionalities of parachains, such as: + +- [Opening HRMP Channels](TODO:update-path){target=\_blank} +- [Transfer Assets Between Parachains](TODO:update-path){target=\_blank} diff --git a/tutorials/polkadot-sdk/build-a-parachain/index.md b/tutorials/polkadot-sdk/build-a-parachain/index.md new file mode 100644 index 000000000..62b295b2d --- /dev/null +++ b/tutorials/polkadot-sdk/build-a-parachain/index.md @@ -0,0 +1,7 @@ +--- +title: Build a Parachain Tutorials +description: Tutorials for building a parachain on Polkadot. These tutorials are designed to help you get started with building a parachain on Polkadot. +hide: +- feedback +template: subsection-index-page.html +--- diff --git a/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain.md b/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain.md new file mode 100644 index 000000000..f1587ed4c --- /dev/null +++ b/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain.md @@ -0,0 +1,168 @@ +--- +title: Prepare a Relay Chain +description: This tutorial will guide you through preparing a relay chain so that you can connect a test parachain node to it for local testing. +--- + +# Prepare Relay Chain + +## Introduction + +This tutorial illustrates how to configure and spin up a local relay chain. The local relay chain is needed to set up a local testing environment to which a test parachain node can connect. Setting up a local relay chain is a crucial step in parachain development. It allows developers to test their parachains in a controlled environment, simulating the interaction between a parachain and the relay chain without needing a live network. This local setup facilitates faster development cycles and easier debugging. + +The scope of this tutorial includes: + +- Installing necessary components for a local relay chain +- Configuring the relay chain settings +- Starting and running the local relay chain +- Verifying the relay chain is operational + +## Prerequisites + +Before diving into this tutorial, it's recommended that you have a basic understanding of how adding trusted nodes works in Polkadot. For further information about this process, refer to the [Add Trusted Nodes](TODO: add the absolute path to the Add Trusted Nodes tutorial) tutorial. + +To complete this tutorial, ensure that you have: + +- Configured your environment for Substrate development by installing [Rust and the Rust toolchain](TODO: add path){target=\_blank} +- Completed [Build a Local Blockchain](/tutorials/polkadot-sdk/build-a-blockchain/build-a-local-blockchain){target=\_blank} tutorial and know how to compile and run a Polkadot SDK-based node + +## Build a Local Relay Chain + +To build a local relay chain, follow these steps: + +1. Clone the most recent release branch of the Polkadot SDK repository to prepare a stable working environment: + + ```bash + git clone --depth 1 --branch polkadot-stable2407-2 \ + https://github.com/paritytech/polkadot-sdk.git + ``` + + !!! note + The branch `polkadot-stable2407-2` is used in this tutorial since it is the branch that contains the latest stable release of the Polkadot SDK. You can find the latest release of the Polkadot SDK on the [Release](https://github.com/paritytech/polkadot-sdk/releases){target=\_blank} tab on the Polkadot GitHub repository. + + !!! note + Note that the `--depth 1` flag is used to clone only the latest commit of the branch, which speeds up the cloning process. + +2. Change the directory to the Polkadot SDK repository: + + ```bash + cd polkadot-sdk + ``` + +3. Build the relay chain node: + + ```bash + cargo build --release + ``` + + !!! note + Depending on your machine's specifications, the build process may take some time. + +4. Verify that the node is built correctly: + + ```bash + ./target/release/polkadot --version + ``` + +If command-line help is displayed, the node is ready to configure. + +## Relay Chain Configuration + +Every Substrate-based chain requires a [chain specification](TODO:update-path){target=\_blank}. The relay chain's chain specification provides the same configuration settings as the chain specification for other networks. Many of the chain specification file settings are critical for network operations. For example, the chain specification identifies peers participating in the network, keys for validators, bootnode addresses, and other information. + +### Sample Chain Configuration + +The local relay chain uses a sample chain specification file with two validator relay chain nodes—Alice and Bob—as authorities for this tutorial. Because a relay chain must have at least one more validator node running than the total number of connected parachain collators, you can only use the chain specification from this tutorial for a local relay chain network with a single parachain. + +If you wanted to connect two parachains with a single collator each, you must run three or more relay chain validator nodes. You must modify the chain specification and hard-code additional validators to set up a local test network for two or more parachains. + +### Plain and Raw Chain Specification + +The chain specification file is available in two formats: a JSON file in plain text and a JSON file in SCALE-encoded raw format. + +You can read and edit the plain text version of the chain specification file. However, the chain specification file must be converted to the SCALE-encoded raw format before you can use it to start a node. For information about converting a chain specification to the raw format, see [Customize a Chain Specification](TODO: add path){target=\_blank}. + +The sample chain specification is only valid for a single parachain with two validator nodes. If you add other validators, add additional parachains to your relay chain, or want to use custom account keys instead of the predefined account, you'll need to create a custom chain specification file. + +Suppose you are completing this tutorial simultaneously as anyone on the same local network. In that case, you must download and modify the plain sample relay chain spec to prevent accidentally peering with their nodes. Find the following line in the plain chain spec and add characters to make the `protocolId` field unique: + +```json +"protocolId": "dot", +``` + +## Start the Relay Chain Node + +Before starting block production for a parachain, you need to start a relay chain for them to connect. + +To start the validator nodes, follow these steps: + +1. Generate the chain specification file in the plain text format and use it to create the raw chain specification file. Save the raw chain specification file in a local working directory + + 1. Generate the plain text chain specification file: + + ```bash + ./target/release/polkadot build-spec \ + --chain rococo-local-testnet > /tmp/plain-local-chainspec.json + ``` + + !!! note + Note that the network values are set to the default when generating the chain specification file with the `build-spec`. You can customize the network values by editing the chain specification file for production networks. + + 2. Convert the plain text chain specification file to the raw format: + + ```bash + ./target/release/polkadot build-spec \ + --chain plain-local-chainspec.json \ + --raw > /tmp/raw-local-chainspec.json + ``` + +2. Start the first validator using the `alice` account by running the following command: + + ```bash + ./target/release/polkadot \ + --alice \ + --validator \ + --base-path /tmp/alice \ + --chain /tmp/raw-local-chainspec.json \ + --port 30333 \ + --rpc-port 9944 \ + --insecure-validator-i-know-what-i-do \ + --force-authoring + ``` + + This command uses `/tmp/raw-local-chainspec.json` as the location of the sample chain specification file. Ensure the `--chain` command line specifies the path to your generated raw chain specification. This command also uses the default values for the port (`port`) and WebSocket port (`ws-port`). The values are explicitly included here as a reminder to always check these settings. After the node starts, no other nodes on the same local machine can use these ports. + +3. Review log messages as the node starts and take note of the `Local node identity` value. This value is the node's peer ID, which you need to connect the parachain to the relay chain: + + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain/relay-chain-1.html' + + !!! note + You need to specify this identifier to enable other nodes to connect. In this case, the `Local node identity` is `12D3KooWG393uX82rR3QgDkZpb7U8StzuRx9BQUXCvWsP1ctgygp`. + +4. Open a new terminal and start the second validator using the `bob` account. The command is similar to the command used to start the first node, with a few crucial differences: + + ```bash + ./target/release/polkadot \ + --bob \ + --validator \ + --base-path /tmp/bob \ + --chain /tmp/raw-local-chainspec.json \ + --port 30334 \ + --rpc-port 9945 + ``` + + Notice that this command uses a different base path (`/tmp/relay/bob`), validator key (`--bob`), and ports (`30334` and `9945`). + + Because both validators are running on a single local computer, it isn't necessary to specify the `--bootnodes` command-line option and the first node's IP address and peer identifier. The `--bootnodes` option is required to connect nodes outside the local network or not identified in the chain specification file. + + If you don't see the relay chain producing blocks, try disabling your firewall or adding the bootnodes command-line option with the address of Alice's node to start the node. Adding the bootnodes option looks like this (with the node identity of Alice's node): + + ```bash + --bootnodes \ + /ip4/127.0.0.1/tcp/30333/p2p/12D3KooWG393uX82rR3QgDkZpb7U8StzuRx9BQUXCvWsP1ctgygp + ``` + +5. Verify that the relay chain nodes are running by checking the logs for each node. The logs should show that the nodes are connected and producing blocks. For example, Bob's logs will be displayed as follows: + + --8<-- 'code/tutorials/polkadot-sdk/build-a-parachain/prepare-relay-chain/relay-chain-2.html' + +Once the relay chain nodes are running, you can proceed to the next tutorial to [set up a test parachain node and connect it](/tutorials/polkadot-sdk/build-a-parachain/connect-a-parachain/) to the relay chain. diff --git a/tutorials/polkadot-sdk/index.md b/tutorials/polkadot-sdk/index.md new file mode 100644 index 000000000..40962881c --- /dev/null +++ b/tutorials/polkadot-sdk/index.md @@ -0,0 +1,7 @@ +--- +title: Polkadot SDK +description: Learn how to build and customize blockchains with Polkadot SDK. Explore flexible tools, pre-built modules, and tutorials for efficient blockchain development. +hide: +- feedback +template: subsection-index-page.html +--- diff --git a/variables.yml b/variables.yml index ac9b46d9f..7a8aa3f75 100644 --- a/variables.yml +++ b/variables.yml @@ -8,8 +8,11 @@ dependencies: version: 0.13.1 zombienet: repository_url: https://github.com/paritytech/zombienet - version: 1.3.106 + version: v1.3.106 architecture: macos-arm64 asset_transfer_api: repository_url: https://github.com/paritytech/asset-transfer-api - version: 0.3.1 \ No newline at end of file + version: v0.3.1 + polkadot_sdk_solochain_template: + repository_url: https://github.com/paritytech/polkadot-sdk-solochain-template + version: v0.0.2 \ No newline at end of file