Skip to content

to add polkadot.md #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bumblefudge merged 9 commits into from
Feb 21, 2023
Merged

to add polkadot.md #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
56a8bf2
init polkadot.md
bumblefudge Mar 5, 2022
66212fa
to add caip-2 regex
bumblefudge Mar 5, 2022
6699fc3
to folderize
bumblefudge Mar 26, 2022
f7028b8
to simplify readme frontmatter
bumblefudge Mar 26, 2022
2784e96
slight reorg for MD Header uniformity
bumblefudge Mar 26, 2022
bf9da5e
to fix frontmatter
bumblefudge Mar 27, 2022
9e53ac7
tweak CAIP-2 rationale
Feb 21, 2023
8fd3e3c
add newb-orientation graf to readme
Feb 21, 2023
c60ba9e
refine caip-10 language
Feb 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 63 additions & 0 deletions polkadot/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
namespace-identifier: polkadot
title: Polkadot Namespace
author: ["Pedro Gomes (@pedrouid)", "Joshua Mir (@joshua-mir)", "Shawn Tabrizi (@shawntabrizi)", "Juan Caballero (@bumblefudge)"]
status: Draft
type: Informational
created: 2020-04-01
updated: 2022-03-27
replaces: CAIP-13
---

# Polkadot Namespace

## Introduction

These documents defines the syntax and canonical references of the CASA URI schemes
for the Polkadot namespace.

It is important for developers new to the ecosystem to know that unlike other
namespaces, the exact execution environment, RPC methods, block sizes and other
core features of a blockchain vary widely in a very layered and modular
architecture based on "pallets" (Rust crates that extend the virtual machine and
consensus). This creates an environment for complex "cross-chain" development
between polkadots chains that may have shared security or common resources via
coordination chains but also may not. Within the framework of the
Cross-Consensus Messaging [XCM][], cross-chain interactions are enabled but a
polkadot-wide meta-chain data model; moving beyond the "relative addressing" of
earlier forms of the Polkadot-wide `Multilocation` type, addressing in the
"absolute mode" introduced by XCM v3 is the starting point for CASA-style
addressing.

## References

- [Polkadot documentation][]: Homepage for ecosystem-wide developer documentation
- [Polkadot-ENS tutorial][]: A tutorial for native Kusama address support in the ENS front-end
- [Polkadot public RPC endpoints][]: for dev/testing purposes
- [Polkadot identity system][]: Introduction to on-chain identity registrars
- [Polkadot address explainer][]: A quick overview of how network-specific,
self-describing addresses can derive from the same private key
- [Polkadot subscan tool][]: A tool for transforming addresses according to SS58 across polkadot networks
- [XCM]: Cross Consensus Messaging defies an addressing network across

[Polkadot address explainer]: https://www.quora.com/How-do-different-wallet-addresses-work-on-Polkadot-and-Kusama
[Polkadot identity system]: https://wiki.polkadot.network/docs/learn-identity
[Polkadot public RPC endpoints]: https://wiki.polkadot.network/docs/maintain-endpoints
[Polkadot documentation]: https://wiki.polkadot.network/
[Polkadot subscan tool]: https://polkadot.subscan.io/tools/ss58_transform?
[Polkadot-ENS tutorial]: https://wiki.polkadot.network/docs/ens
[SS58]: https://docs.substrate.io/v3/advanced/ss58/
[SS58 registry]: https://github.com/paritytech/ss58-registry/blob/main/ss58-registry.json
[multiaddress]: https://github.com/multiformats/multiaddr#specification
[CAIP-2]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md
[CAIP-10]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-10.md
[CAIP-19]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-19.md
[CAIP-21]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-21.md
[CAIP-22]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-22.md
[EIP155]: https://eips.ethereum.org/EIPS/eip-155
[ERC20]: https://eips.ethereum.org/EIPS/eip-20
[ERC721]: https://eips.ethereum.org/EIPS/eip-721

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
106 changes: 106 additions & 0 deletions polkadot/caip10.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
---
namespace-identifier: polkadot-caip10
title: Polkadot Namespace - Addresses
author: ["Pedro Gomes (@pedrouid)", "Joshua Mir (@joshua-mir)", "Shawn Tabrizi (@shawntabrizi)", "Juan Caballero (@bumblefudge)"]
discussions-to: https://github.com/ChainAgnostic/CAIPs/issues/13
status: Draft
type: Standard
created: 2020-04-01
updated: 2022-03-27
requires: ["CAIP-2", "CAIP-10"]
replaces: CAIP-13
---

# CAIP-10

*For context, see the [CAIP-10][] specification.*

## Rationale

Polkadot wallets can be expressed a number of ways, but the canonical expression
in polkadot development is a base58 [multiaddress][] with a human-readable
prefix of one or more characters. The specification defining these across the
entire Polkadot namespace is [SS58][]; this specification summarizes the
calculation of an address as `base58encode ( concat ( <address-type>, <address>,
<checksum> ) )`, where `<address-type>` is a prefix registered in the [SS58
registry][] and where `<checksum>` options are constrained by targeted
output-length.

While the above describes a given keypair as generating many addresses per
network, a 47-character multiaddress is the default expression, unique per
chain. Note that a single private key will thus produce different
multiaddresses on each chain where it is used, so de-duplicating Polkadot
accounts in a multi-chain context may require implementing full support for
advanced SS58 functions.

As the default multi-address was used to express individual addresses in
CAIP-10, other possible expressions are out of scope of this specification.
Similarly, recovery of chain ID from account type or validation of addresses
using the included checksum are out of scope, although both are specified in
[SS58][].

## Syntax

As the default/standard expression of an address in Polkadot is a 47-character
base58 string, the following regular expression can be used for validating
addresses:

```
[1-9A-HJ-NP-Za-km-z]{47}
```

## Test Cases

This is a list of examples composed using the [polkadot.subscan tool][]:

```
# Kusama
//example address from [Polkadot-ENS tutorial][]:
polkadot:b0a8d493285c2df73290dfb7e61f870f:CpjsLDC1JFyrhm3ftC9Gs4QoyrkHKhZKtK7YqGTRFtTafgp

//one address in multiple network-specific expressions, taken from the [Polkadot address explainer][]:

# Underlying Public Key:
0x54a0lf789elcflcf69da4010f7001dfaea8e4166656f332ebb5b38ec85704811

# Kusama (coordination chain; address-type prefix 0)
polkadot:b0a8d493285c2df73290dfb7e61f870f:EVH78gP5ATklKjHonVpxM8c1W6rWPKn5cAS14fXn4Ry5NxK

# Edgeware (address-type prefix 7)
polkadot:742a2ca70c2fda6cee4f8df98d64c4c6:jRaQ6PPzcqNnckcLStwqrTjEvpKnJUP2Jw65Ut36LQQUycd

# Kulupu (address-type prefix 16)
polkadot:37e1f8125397a98630013a4dff89b54c:2dWWj2G2TEhvC9PnVEpAExrZ4J6yGx94imvGcdfkG2ko1u6x
```

## References

- [Polkadot documentation][]: Homepage for ecosystem-wide developer documentation
- [Polkadot-ENS tutorial][]: A tutorial for native Kusama address support in the ENS front-end
- [Polkadot public RPC endpoints][]: for dev/testing purposes
- [Polkadot identity system][]: Introduction to on-chain identity registrars
- [Polkadot address explainer][]: A quick overview of how network-specific,
self-describing addresses can derive from the same private key
- [Polkadot subscan tool][]: A tool for transforming addresses according to SS58 across polkadot networks

[Polkadot address explainer]: https://www.quora.com/How-do-different-wallet-addresses-work-on-Polkadot-and-Kusama
[Polkadot identity system]: https://wiki.polkadot.network/docs/learn-identity
[Polkadot public RPC endpoints]: https://wiki.polkadot.network/docs/maintain-endpoints
[Polkadot documentation]: https://wiki.polkadot.network/
[Polkadot subscan tool]: https://polkadot.subscan.io/tools/ss58_transform?
[Polkadot-ENS tutorial]: https://wiki.polkadot.network/docs/ens
[SS58]: https://docs.substrate.io/v3/advanced/ss58/
[SS58 registry]: https://github.com/paritytech/ss58-registry/blob/main/ss58-registry.json
[multiaddress]: https://github.com/multiformats/multiaddr#specification
[CAIP-2]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md
[CAIP-10]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-10.md
[CAIP-19]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-19.md
[CAIP-21]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-21.md
[CAIP-22]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-22.md
[EIP155]: https://eips.ethereum.org/EIPS/eip-155
[ERC20]: https://eips.ethereum.org/EIPS/eip-20
[ERC721]: https://eips.ethereum.org/EIPS/eip-721

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
112 changes: 112 additions & 0 deletions polkadot/caip2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
---
namespace-identifier: polkadot-caip2
title: Polkadot Namespace - Chains
author: ["Pedro Gomes (@pedrouid)", "Joshua Mir (@joshua-mir)", "Shawn Tabrizi (@shawntabrizi)", "Juan Caballero (@bumblefudge)"]
discussions-to: https://github.com/ChainAgnostic/CAIPs/issues/13
status: Draft
type: Standard
created: 2020-04-01
updated: 2022-03-27
requires: CAIP-2
replaces: CAIP-13
---

# CAIP-2

*For context, see the [CAIP-2][] specification.*

## Rationale

The namespace is called "polkadot" to encompass all chains in the polkadot
ecosystem, allowing actors and entities to be addressable from core Polkadot
"relay" chains, indepedent "solo" chains, and L2-like "parachains" coordinated
by the Polkadot relay chains.

The rationale behind the use of block hash from the genesis block stems from its
usage in the Polkadot architecture in network and consensus.

## Syntax

The definition for this namespace will use the `genesis-hash` as an indentifier
for different Polkadot chains. The format is a 32 character prefix of the block
hash (lower case SHA256 hex).

As CAIP-2 references for this namespace are 32-byte SHA256 hashes in lowercase
hex, they can be validated with the simple regular expression: `[0-9a-f]{32}`

### Resolution Method

To resolve a blockchain reference for the Polkadot namespace, make a JSON-RPC
request to the blockchain node with method `chain_getBlockHash`, for example:

```jsonc
// Request
{
"id": 1,
"jsonrpc": "2.0",
"method": "chain_getBlockHash",
"params": [0]
}

// Response
{
"id": 1,
"jsonrpc": "2.0",
"result": "0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3"
}
```
The response will return as a value for the result a hash for the block with
height 0 that should be sliced to its first 16 bytes (32 characters for base 16)
to be CAIP-2/CAIP-10 compatible.

### Backwards Compatibility

Not applicable

## Test Cases

This is a list of manually composed examples

```
# Kusama
polkadot:b0a8d493285c2df73290dfb7e61f870f

# Edgeware
polkadot:742a2ca70c2fda6cee4f8df98d64c4c6

# Kulupu
polkadot:37e1f8125397a98630013a4dff89b54c
```
Comment on lines +68 to +79
Copy link

@joepetrowski joepetrowski May 31, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"The namespace is called "polkadot" to refer to Polkadot-like "parachains,""

None of these are parachains :). Ideally namespaces would anchor at consensus systems, so e.g.:

polkadot:<statemint-genesis-hash>
kusama:<statemine-genesis-hash>

Or, if you wanted to express that Kusama and Polkadot are connected, perhaps add another "relational" namespace in the path, like:

polkadot:canary:<kusama-genesis-hash>
polkadot:para:<statemint-genesis-hash>
polkadot:solo:<kulupu-genesis-hash>

The problem that will come up is migrations. For example, Centrifuge and Integritee (maybe some others, these two off the top of my head) were solo chains that became parachains. So if these identifiers are meant to last forever, there could be issues, but I'm really not that familiar with CAIP. You could also decide that migrated chains are two different chains, and have resources of one point to the other for the complete history.

Or, if you want to avoid migration issues entirely, just change the docs from "The namespace is called "polkadot" to refer to Polkadot-like "parachains,"" to something like, "The namespace is called "polkadot" to refer to blockchains whose state transition functions can execute on the Polkadot host API, for example parachains or Kusama."

Copy link
Contributor

@ntn-x2 ntn-x2 May 31, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the latter example, would all chains then still use the polkadot namespace? I saw a comment about the MultiLocation struct that mentions forks also for (para)chains in the Polkadot space. If that is the case, I think having a genesis hash as a way to identify chains (as is the case now) is definitely not sufficient, as two forked chains would be identified by the same hash. To this point, would a combination of genesis hash and SS58 prefix be sufficient to uniquely identify all chains, including forks and migrated ones?

Copy link

@joepetrowski joepetrowski May 31, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the latter example, would all chains then still use the polkadot namespace?

Yes, as they are chains that execute on top of the Polkadot host API (which is not just expressed in Substrate, but also in other implementations like ChainSafe's Gossamer).

I saw a comment about the MultiLocation struct that mentions forks also for (para)chains in the Polkadot space. If that is the case, I think having a genesis hash as a way to identify chains (as is the case now) is definitely not sufficient, as two forked chains would be identified by the same hash.

How do you define a fork? A parachain should never fork, unless someone starts a new chain with a modified chainspec/runtime, but then that's just a new genesis. MultiLocations in general are relative location paths but don't actually know about a / location (although in practice it would be the governing consensus system). Since CAIP does seem to have a / location (the first namespace), MultiLocation could be mapped onto it from one chain ID to another.

would a combination of genesis hash and SS58 prefix be sufficient to uniquely identify all chains, including forks and migrated ones?

No, SS58 should probably not even come near this conversation. It's 99% for front end, there is no guarantee that it's unique (already, Polkadot and Statemint both use a prefix of 0), nor that it will stay the same in a chain's lifetime.

Copy link
Contributor

@ntn-x2 ntn-x2 May 31, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, my mistake. Forks could nevertheless still exist for standalone chains, and if they would be identified with the same polkadot namespace, then using the sole genesis hash would not be sufficient anymore.

No, SS58 should probably not even come near this conversation. It's 99% for front end, there is no guarantee that it's unique (already, Polkadot and Statemint both use a prefix of 0), nor that it will stay the same in a chain's lifetime.

Yeah that's what I thought. I wanted to make it clear as there has been conversation up above about using those to identify chains.

Copy link

@joepetrowski joepetrowski May 31, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Forks could nevertheless still exist for standalone chains, and if they would be identified with the same polkadot namespace, then using the sole genesis hash would not be sufficient anymore.

Do you have any examples? I mean, the Polkadot host API assumes that you have some storage item called :code that contains a Wasm executable, and the chain defined by the genesis hash is the one that at each block height has executed that state transition function. To fork a chain, someone needs to manually force change that storage item and start a new chain, that's a new genesis hash.

That said, chain specs normally have an "id": "polkadot", entry that gets changed when a chain is restarted to avoid any confusion. This id is also something that a CLI would typically match on to start the correct chain. I'd probably go in this direction for a non-genesis-hash identifier. (Polkadot chain spec)

Copy link
Collaborator Author

@bumblefudge bumblefudge Sep 23, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

some time next month I'll devote a big bloc of time to overhauling all this and tag you both in the PR-- I clearly need to go back to the drawing board to map the CAIP mental model onto this VM!

Copy link
Collaborator Author

@bumblefudge bumblefudge Feb 21, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Going to merge a straw man and invite PRs to improve, will return to this discussion


## References

- [Polkadot documentation][]: Homepage for ecosystem-wide developer documentation
- [Polkadot-ENS tutorial][]: A tutorial for native Kusama address support in the ENS front-end
- [Polkadot public RPC endpoints][]: for dev/testing purposes
- [Polkadot identity system][]: Introduction to on-chain identity registrars
- [Polkadot address explainer][]: A quick overview of how network-specific,
self-describing addresses can derive from the same private key
- [Polkadot subscan tool][]: A tool for transforming addresses according to SS58 across polkadot networks
-

[Polkadot address explainer]: https://www.quora.com/How-do-different-wallet-addresses-work-on-Polkadot-and-Kusama
[Polkadot identity system]: https://wiki.polkadot.network/docs/learn-identity
[Polkadot public RPC endpoints]: https://wiki.polkadot.network/docs/maintain-endpoints
[Polkadot documentation]: https://wiki.polkadot.network/
[Polkadot subscan tool]: https://polkadot.subscan.io/tools/ss58_transform?
[Polkadot-ENS tutorial]: https://wiki.polkadot.network/docs/ens
[SS58]: https://docs.substrate.io/v3/advanced/ss58/
[SS58 registry]: https://github.com/paritytech/ss58-registry/blob/main/ss58-registry.json
[multiaddress]: https://github.com/multiformats/multiaddr#specification
[CAIP-2]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md
[CAIP-10]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-10.md
[CAIP-19]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-19.md
[CAIP-21]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-21.md
[CAIP-22]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-22.md
[EIP155]: https://eips.ethereum.org/EIPS/eip-155
[ERC20]: https://eips.ethereum.org/EIPS/eip-20
[ERC721]: https://eips.ethereum.org/EIPS/eip-721

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).