astarnetwork / astar-docs

Website

Welcome to Astar Docs GitHub Repo.

This website is built using Docusaurus, a modern static website generator.

How to contribute to Astar Docs using a local instance of the Docusaurus engine

Prerequisites

• Method 1: Make sure git and yarn exist as commands in your terminal or VS Code: https://yarnpkg.com/ (NOTE: Please make sure you use yarn 1 (classic) by using command yarn set version classic

• Git/Github: understand what the following commands do

  • managing branches (git checkout main and git checkout -b feat/your-new-branch
  • Commits (git add . and git commit, git push -u origin feat/your-new-branch)
  • Creating PR in Github
  • maybe: stashing (git stash and git stash pop are your best friends)

• Markdown basics

  • titles, subtitles
  • lists
  • hyperlinks

• Method 2: Make sure yarn exists as a command in your terminal or VS Code and Github Desktop is installed. All the git operations described below can also be found within the menu of the desktop application, and common operations are clearly visible on launch.

Setup: First time only

• Clone repo git clone https://github.com/astarnetwork/astar-docs
• Install dependencies by running yarn (cd astar-docs , yarn )
• yarn start - spin up a realtime website that updates dynamically based on your changes to the code.

New document / Modify existing document --> Submit a PR

• Get latest version of docs locally
  • Make sure you’re on the main branch (git checkout main)
  • Pull the latest version of the docs (git pull)
  • Create a new branch (git checkout -b feat/new-feature-name-here)
• Create/update the docs as you please
  • Spin up live docs (yarn start)
    • If you are working on a translation of a document use yarn start --locale IT (example for Italian) (checkout Docusaurus docs or further reference
  • Add new page/tweaks/etc
  • When you’re happy with it, ensure yarn build runs without errors
• PR and staging environment
  • Commit your changes and push the new branch up to Github (git add . and git commit, git push -u origin feat/your-new-branch)
  • Create a new PR on Github (https://github.com/astarnetwork/astar-docs)
  • Once PR is up, CICD will automatically build you a unique staging link. You can view the progress of this on the Actions tab on Github
  • Wait for feedback from the team

Working with images

• Please import and use the <Figure/> tag instead of ![image] as this enables smoother translation of docs to other languages (automatic reference to original images, no need to copy images to translated subfolders) and automatically applies some styling such as line breaks.

  • Example - as seen here:

    top of file:

    import Figure from "/src/components/figure"
    

    within the file:

    <Figure caption="Tokenomics Model" src={require('/docs/about/token-economics/img/tokenomics_1.png').default } width="100%" /> 
    

  • Please use absolute path to image (e.g. /docs/about/token-economics/img/tokenomics_1.png instead of img/tokenomics_1.png

Deploy to production

• When a PR is ready for merge, click the button at the bottom saying Merge and Close and then Confirm
• After a few minutes you should see your changes updated on the production site at [https://docs.astar.network](https://docs.astar.network)

HELP SOMETHING IS BROKEN

• Likely, a broken build got pushed to main somehow. Remove the commit from main and force push to main, reopen PR in a new PR.

astar-docs's Issues

Need Links to API Documentation

Lots of references to thing like the pallet-contracts API, but no link to them.

See here.

I still haven't found a link to those API docs, or I would start editing each page and adding it myself as a PR.

Found a unnecessary character in docs

Perhaps injectedWeb3 is correct

astar-docs/docs/integrations/wallets/subwallet.md

Line 9 in ef42d5e

SubWallet, Polkadot{.js} and Talisman extension allow DApp to connect with them by public their interaction in object injectedW`eb3 of window browser.

I tried to send a pull request, but I didn't have permission to git push, so I'll leave the issue as is.

Double smart contract verification documents

Move verification doc from builders guide to evm/infra. Delete existing (almost no info)

Duplicate external links on docs/xcm/index.md

A nit-pick, I found that link of two items on this XCM page are the same, as shown below.

• Sub0 - Getting Started with XCM
• How to make a cross-chain transfer

Add page "How to migrate from EVM compatible to Astar zkEVM"

This page should be a "one stop shop" for any existing project interested to join Astar zkEVM in the context of

• building
• moving liquidity
• etc

Need to update the astar-collator options

According to astar-collator latest version,
I found that some command options are replaced.

paritytech/substrate#13384

we should update below the document for RasPi.

https://docs.astar.network/docs/nodes/rpi-cheat-sheet/

for example, "--ws-external" can not use with v5.15.

@meganskye

Specify Rust version 1.69.0 rather than nightly

In ink environment doc, it's better to specify 1.69.0 rather than a nightly channel:

[toolchain]
channel = "1.69.0"
components = [ "rustfmt", "rust-src" ]
targets = [ "wasm32-unknown-unknown" ]
profile = "minimal"

Repeated sentence in Ecosystem-> Polkadot section

https://docs.astar.network/docs/ecosystem/polkadot

The sentence "Astar Network is built on Parity Substrate making it one of the first SCALABLE smart contract Polkadot Parachains." is written twice in a sequence.

MIssing EVM interaction with smart contract

https://docs.astar.network/docs/build/EVM/interact/

Investigate Docusaurus/markdown linting possibilities

Missing images in chapter building-with-xcm

https://docs.astar.network/docs/xcm/building-with-xcm/native-transactions#initial-state

link in the tutorial using openbrush doesn't work

I was trying the tutorial for the psp22 and psp34 as a part of Astar university but the project generated by the openbrush has issues and doesn't compile
https://docs.astar.network/docs/build/wasm/from-zero-to-ink-hero/nft/Wizard/#use-the-wizard-to-generate-generic-psp34-code

Update Docs After zkEVM mainnet is live (TODO Dev Team)

TODO Dev Team

• Update RPC endpoint data here https://docs.astar.network/docs/build/zkEVM/quickstart#connecting-to-zkevm
• Add note or update screenshots here https://docs.astar.network/docs/build/zkEVM/bridge-to-zkevm
• Update Faucet info to reflect zKatana (e.g. "Testnet Faucet" as no faucet for mainnet) https://docs.astar.network/docs/build/zkEVM/zkevm-faucet
• Review if Node setup is feasible for DAC Validium (https://docs.astar.network/docs/build/zkEVM/zk-node/) - check with DevOps/Core team
• Update Fee Calculation Example https://docs.astar.network/docs/build/zkEVM/fee

Marketing team should cover

• [] https://docs.astar.network/docs/build/zkEVM/faq/zkevm-general-faq
• [] https://docs.astar.network/docs/learn/zkEVM/faq

Build a Quickstart Guide

The docs as they stand don't give developers a great "in" to just get started building.

As of right now, I have to dig pretty deep to find the tutorials, for example:
Build > WASM Smart Contracts > Tutorials > Your First Flipper Contract

I would recommend splitting the information that explains how Astar works, from simple quickstarts and tutorials that get them in and developing as fast as possible. That's what most people want and will need to get started.

Implement URL redirects (server side ideally)

TODO create some redirects which will do the following

forward https://docs.astar.network/docs/learn/build2earn to https://docs.astar.network/docs/learn/dapp-staking/
forward https://docs.astar.network/docs/build/dappstaking to https://docs.astar.network/docs/learn/dapp-staking or https://docs.astar.network/docs/use/dapp-staking

One way is client redirecs, but Docusaurus docs suggest this should be only alternative to hosting redirects
https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-client-redirects

Deploy shell Fix

Thank you for your continuous development of Astar. I used zKEVM right away. There was a mistake in the deploy shell in the documentation, so this will become an issue with proposed corrections.

File
https://github.com/AstarNetwork/astar-docs/blob/main/docs/build/zkEVM/smart-contracts/using-hardhat.md

Before

const ACCOUNT_PRIVATE_KEY = process.env.PRIVATE_KEY || "";

After

const ACCOUNT_PRIVATE_KEY = process.env.ACCOUNT_PRIVATE_KEY || "";

Reorganize dAppStaking content in docs to reflect dAppStaking v3 across the whole content.

This is a follow up issue to do some reorganization of dAppStaking content in general:

Situation:

• new dAppStaking v3 master doc is present now #554
• There is Build2Earn content in the Learn section - https://docs.astar.network/docs/learn/build2earn
• There is dAppStaking content in the Build section - https://docs.astar.network/docs/build/dapp-staking/

First time reader should be able to relevant information in the Learn section (avoid overwhelming details)
Advanced user or a Builder should have a place to get in depth info about protocol.

TODO

• consolidate docs
• don't kill URLs or make sure links are updated (e.g. on Astar Homepage Build2Earn or other places)

Update Cannonical zkEVM Contracts with info about testnet

on this page - docs/build/zkEVM/cannonical-zkevm-contracts.md

Dead link

astar-docs/docs/quickstart/index.md

Line 25 in e07a120

Astar is the only smart-contract parachain in the Polkadot ecosystem that supports multi-virtual machines (Wasm and EVM). Resultingly, managing multiple types of accounts can be non-trivial. Read more about [Astar's account structure](https://astarnetwork.github.io/astar-docs/docs/quickstart/addresses) in our documentation.

Add Claim rewards section and mention using "private" browser browser or clearing cache if doesn't work

Mention that if when claiming your rewards after signing the transaction the loading icon doesn't appear and the transaction doesn't get processed and you get an error in the browser console like in this issue AstarNetwork/astar-apps#870, then a mitigation measure is to clear their browser cache, or to claim the rewards in a "private" browser window (where permissions have been granted to the polkadot.js extension or another wallet extension to be used in a "private" browser window).

Cross-link Tokenomics 2.0 and dAppStaking v3 content

After both PRs are merged, content should be cross-linked

#553

and

#554

Astar.js cookbook on 2 places

There is PR to introduce Astar.js for Wasm and there is this document under XWM/WASM
https://docs.astar.network/docs/build/builder-guides/xvm_wasm/interact_with_wasm_contract

Make it unified and relevant

Missing guide on how to interact with Shibuya <> Shinjuku environment

There is a diagram which indicates a "Token Parachain Testnet" which is in fact Shinjuku but there is no more detail on how would a person interact with it and in which situations.
https://docs.astar.network/docs/build/Introduction/astar_family

Shinjuku <> Shibuya testnet environment is important as a place to test XCM interactions and smart contract interactions in future (when XCM Chain Extension becomes available)

containers zkevm-rpc and zkevm-sync are restarting

Hi,
I am trying to setup Astar zkEVM Mainnet Permissionless RPC Node following the docs https://docs.astar.network/docs/build/zkEVM/zk-node/setup-mainnet-rpc-node/ . The containers created and started but the containers zkevm-rpc, zkevm-sync and zkevm-prover looks not ok , they are restarting.
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
3bcd8f386ed9 staketechnologies/cdk-validium-node:v0.5.13-CDK2 "/bin/sh -c '/app/zk…" 6 hours ago Up About a minute 0.0.0.0:8545->8545/tcp, :::8545->8545/tcp, 8123/tcp, 0.0.0.0:9091->9091/tcp, :::9091->9091/tcp zkevm-rpc
e15e50a13d69 staketechnologies/zkevm-prover:v4.0.19 "zkProver -c /usr/sr…" 6 hours ago Up About a minute 0.0.0.0:50061->50061/tcp, :::50061->50061/tcp, 0.0.0.0:50071->50071/tcp, :::50071->50071/tcp zkevm-prover
64b3669008db staketechnologies/cdk-validium-node:v0.5.13-CDK2 "/bin/sh -c '/app/zk…" 6 hours ago Up About a minute 8123/tcp, 0.0.0.0:9092->9091/tcp, :::9092->9091/tcp zkevm-sync
66685835e947 postgres:15 "docker-entrypoint.s…" 6 hours ago Up 6 hours (healthy) 0.0.0.0:5433->5432/tcp, :::5433->5432/tcp zkevm-pool-db
7495fcd120eb postgres:15 "docker-entrypoint.s…" 6 hours ago Up 6 hours (healthy) 0.0.0.0:5432->5432/tcp, :::5432->5432/tcp zkevm-state-db
root@astarzkevm:/etc/zkevm#

The logs for zkevm-rpc and zkevm-sync are same as below

{"level":"info","ts":1711124757.5284636,"caller":"cmd/run.go:73","msg":"Running DB migrations host: zkevm-state-db:5432 db:state_db user:state_user","pid":1,"version":"v0.5.13+cdk.2"}
{"level":"info","ts":1711124757.5285015,"caller":"cmd/run.go:285","msg":"running migrations for zkevm-state-db","pid":1,"version":"v0.5.13+cdk.2"}
{"level":"info","ts":1711124757.528511,"caller":"db/db.go:47","msg":"running migrations up","pid":1,"version":"v0.5.13+cdk.2"}
{"level":"fatal","ts":1711125019.0802724,"caller":"cmd/run.go:288","msg":"failed to connect to host=zkevm-state-db user=state_user database=state_db: dial error (timeout: dial tcp 172.25.0.2:5432: connect: connection timed out)\n/src/log/log.go:142 github.com/0xPolygonHermez/zkevm-node/log.appendStackTraceMaybeArgs()\n/src/log/log.go:223 github.com/0xPolygonHermez/zkevm-node/log.Fatal()\n/src/cmd/run.go:288 main.runMigrations()\n/src/cmd/run.go:270 main.runStateMigrations()\n/src/cmd/run.go:74 main.start()\n/go/pkg/mod/github.com/urfave/cli/[email protected]/command.go:277 github.com/urfave/cli/v2.(*Command).Run()\n/go/pkg/mod/github.com/urfave/cli/[email protected]/command.go:270 github.com/urfave/cli/v2.(*Command).Run()\n/go/pkg/mod/github.com/urfave/cli/[email protected]/app.go:335 github.com/urfave/cli/v2.(*App).RunContext()\n/go/pkg/mod/github.com/urfave/cli/[email protected]/app.go:309 github.com/urfave/cli/v2.(*App).Run()\n/src/cmd/main.go:198 main.main()\n/usr/local/go/src/runtime/proc.go:267 runtime.main()\n","pid":1,"version":"v0.5.13+cdk.2","stacktrace":"main.runMigrations\n\t/src/cmd/run.go:288\nmain.runStateMigrations\n\t/src/cmd/run.go:270\nmain.start\n\t/src/cmd/run.go:74\ngithub.com/urfave/cli/v2.(*Command).Run\n\t/go/pkg/mod/github.com/urfave/cli/[email protected]/command.go:277\ngithub.com/urfave/cli/v2.(*Command).Run\n\t/go/pkg/mod/github.com/urfave/cli/[email protected]/command.go:270\ngithub.com/urfave/cli/v2.(*App).RunContext\n\t/go/pkg/mod/github.com/urfave/cli/[email protected]/app.go:335\ngithub.com/urfave/cli/v2.(*App).Run\n\t/go/pkg/mod/github.com/urfave/cli/[email protected]/app.go:309\nmain.main\n\t/src/cmd/main.go:198\nruntime.main\n\t/usr/local/go/src/runtime/proc.go:267"}

where as I am able to connect to all the postgresql db using there corresponding user and password from outside the docker container. Not sure what am I missing, need your help.
Thank you
Tapas Jana

Create a Glossary

The first step to understanding any new system is to first know the vocabulary.

Right now, the documentation has a simple vocab list in the Ecosystem area, but it is by no means comprehensive, nor does it dive into the deeper tools and resources I would need to understand each piece of Astar and work with it.

Some examples of questions I would really like the answer to:
what is Shiden? How is it related to Astar?
You have a definition of substrate, and I'm assuming that Astar has used it to build their blockchain, but is that it? Does it do anything else for Astar? How has it influenced Astar?
What is Ink! and eDSL? I don't know rust yet, so these questions may be stupid.

For each layer deeper, I would recommend creating a glossary for the information you will need to understand the guides/tutorials/content that is written at that layer, and provide links to outside resources in the glossary. Ink! is an example of where this would be helpful.

Broken Subquery link for zKatana

Please visit the quickstart guide here
@meganskye

curl: (56) Recv failure: Connection reset by peer for zkEVM RPC Node

I was trying to setup Astar zkEVM Permissionless RPC Node by reading the Astar docs(https://docs.astar.network/docs/build/zkEVM/zk-node/setup-rpc-node).

After starting docker container and then testing RPC request. There was an error below

tk@zkevm:~$ curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "eth_chainId", "params": []}' http://localhost:8545
curl: (56) Recv failure: Connection reset by peer

The issue was identified in the docker-compose.yml file. Specifically, I found an error in the options for launching the zkevm-rpc container within this file. The mistake lay in the fact that the --components specification was not set to "rpc." Instead, it inexplicably specified "synchronizer." Upon closer inspection, I noticed that the port 8545, crucial for the zkevm-rpc container, was not being listened to, leading me to the realization of an error in the startup options for the zkevm-node.

Consequently, I believe that the docker-compose.yml file within zkatana.tar.gz needs to be corrected.
I suggest that you modify it as follows:

$ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml

# current setting of L34
       - "/app/zkevm-node run --http.api=eth,net,debug,zkevm,txpool,web3 --network custom --custom-network-file /app/genesis.json --cfg /app/config.toml --components synchronizer"

# update setting of L34
       - "/app/zkevm-node run --http.api=eth,net,debug,zkevm,txpool,web3 --network custom --custom-network-file /app/genesis.json --cfg /app/config.toml --components rpc"

Best Regards

Some problems on "Integrations > Indexers > The Graph" page

Hi !!
I found some small problems on "The Graph" page (https://docs.astar.network/docs/integrations/indexers/thegraph)

• The script in "One-line startup script" that no longer exists (https://raw.githubusercontent.com/AstarNetwork/Astar/rpc-script/scripts/graph.sh)
  

• Typo problems in the "Running Graph node" in the github link to clone the repo --> git clone <https://github.com/graphprotocol/graph-node/> instead of git clone https://github.com/graphprotocol/graph-node/
  

• I suggest to use https in the complete example of the docker-compose.yml for the consistency (I was tricked into copying and pasting ahah)
  

I hope this issue is relevant ;)

Problems Astar Solves is Unhelpful

This page is unhelpful.

Everyone says their blockchain does this.

I would recommend fleshing it out a bit more and perhaps linking your whitepaper so people can understand how you're tackling those problems and why your solution will actually work.

Refactor folder names to conform to kebab-case

Current folder naming scheme is inconsistent.

astar.js pkgs versions should be removed from docs

the version update in docs is hard to maintain and easy to forget. Move it to github or some other place

https://docs.astar.network/docs/build/wasm/interact/astarjs

Add reference to aWASoMe in astar docs

A reference to https://github.com/AstarNetwork/aWASoMe should be added to astar docs. Just not sure where to put it at the moment.

The Discord invite link is invalid from the faucet docs

astar-docs/docs/build/environment/faucet.md

Line 27 in 707121f

Once you join the [Discord Server](https://discord.com/invite/kvRRnvBbQn), you will be able to see the **#shibuya-faucet** channel.

Hi guys, just tried to join the Discord channel using this link from the docs but is invalid.

Update unbonding link

Since we're migrating to v3, many ledger users would want to unbound their tokens so that they're ready to start earning rewards upon launch of v3.

For ease of use, it's nice to have the link to the unbonding document directly in the ledger page. I have added this PR for the same #584