Skip to content

Commit aa28714

Browse files
update readme: archived repo (#3049)
* Update README.md * Update README.md
1 parent 8111891 commit aa28714

File tree

1 file changed

+7
-259
lines changed

1 file changed

+7
-259
lines changed

cumulus/README.md

Lines changed: 7 additions & 259 deletions
Original file line numberDiff line numberDiff line change
@@ -1,265 +1,13 @@
1-
# Cumulus ☁️
1+
Dear contributors and users,
22

3-
[![Doc](https://img.shields.io/badge/cumulus%20docs-master-brightgreen)](https://paritytech.github.io/cumulus/)
3+
We would like to inform you that we have recently made significant changes to our repository structure. In order to streamline our development process and foster better contributions, we have merged three separate repositories Cumulus, Substrate and Polkadot into a single new repository: [the Polkadot SDK](https://github.com/paritytech/polkadot-sdk). Go ahead and make sure to support us by giving a star ⭐️ to the new repo.
44

5-
This repository contains both the Cumulus SDK and also specific chains implemented
6-
on top of this SDK.
5+
By consolidating our codebase, we aim to enhance collaboration and provide a more efficient platform for future development.
76

8-
If you only want to run a **Polkadot Parachain Node**, check out our [container section](./docs/container.md).
7+
If you currently have an open pull request in any of the merged repositories, we kindly request that you resubmit your PR in the new repository. This will ensure that your contributions are considered within the updated context and enable us to review and merge them more effectively.
98

10-
## Cumulus SDK
9+
We appreciate your understanding and ongoing support throughout this transition. Should you have any questions or require further assistance, please don't hesitate to [reach out to us](https://forum.polkadot.network/t/psa-parity-is-currently-working-on-merging-the-polkadot-stack-repositories-into-one-single-repository/2883).
1110

12-
A set of tools for writing [Substrate](https://substrate.io/)-based
13-
[Polkadot](https://wiki.polkadot.network/en/)
14-
[parachains](https://wiki.polkadot.network/docs/en/learn-parachains). Refer to the included
15-
[overview](docs/overview.md) for architectural details, and the
16-
[Connect to a relay chain how-to guide](https://docs.substrate.io/reference/how-to-guides/parachains/connect-to-a-relay-chain/) for a
17-
guided walk-through of using these tools.
11+
Best Regards,
1812

19-
It's easy to write blockchains using Substrate, and the overhead of writing parachains'
20-
distribution, p2p, database, and synchronization layers should be just as low. This project aims to
21-
make it easy to write parachains for Polkadot by leveraging the power of Substrate.
22-
23-
Cumulus clouds are shaped sort of like dots; together they form a system that is intricate,
24-
beautiful and functional.
25-
26-
### Consensus
27-
28-
[`parachain-consensus`](https://github.com/paritytech/cumulus/blob/master/client/consensus/common/src/parachain_consensus.rs) is a
29-
[consensus engine](https://docs.substrate.io/v3/advanced/consensus) for Substrate
30-
that follows a Polkadot
31-
[relay chain](https://wiki.polkadot.network/docs/en/learn-architecture#relay-chain). This will run
32-
a Polkadot node internally, and dictate to the client and synchronization algorithms which chain
33-
to follow,
34-
[finalize](https://wiki.polkadot.network/docs/en/learn-consensus#probabilistic-vs-provable-finality),
35-
and treat as best.
36-
37-
### Collator
38-
39-
A Polkadot [collator](https://wiki.polkadot.network/docs/en/learn-collator) for the parachain is
40-
implemented by the `polkadot-parachain` binary (previously called `polkadot-collator`).
41-
42-
You may run `polkadot-parachain` locally after building it or using one of the container option described [here](./docs/container.md).
43-
44-
### Relay Chain Interaction
45-
To operate a parachain node, a connection to the corresponding relay chain is necessary. This can be
46-
achieved in one of three ways:
47-
1. Run a full relay chain node within the parachain node (default)
48-
2. Connect to an external relay chain node via WebSocket RPC
49-
3. Run a light client for the relay chain
50-
51-
#### In-process Relay Chain Node
52-
If an external relay chain node is not specified (default behavior), then a full relay chain node is
53-
spawned within the same process.
54-
55-
This node has all of the typical components of a regular Polkadot node and will have to fully sync
56-
with the relay chain to work.
57-
58-
##### Example command
59-
```bash
60-
polkadot-parachain \
61-
--chain parachain-chainspec.json \
62-
--tmp \
63-
-- \
64-
--chain relaychain-chainspec.json
65-
```
66-
67-
#### External Relay Chain Node
68-
An external relay chain node is connected via WebsSocket RPC by using the `--relay-chain-rpc-urls`
69-
command line argument. This option accepts one or more space-separated WebSocket URLs to a full relay
70-
chain node. By default, only the first URL will be used, with the rest as a backup in case the
71-
connection to the first node is lost.
72-
73-
Parachain nodes using this feature won't have to fully sync with the relay chain to work, so in general
74-
they will use fewer system resources.
75-
76-
**Note:** At this time, any parachain nodes using this feature will still spawn a significantly cut-down
77-
relay chain node in-process. Even though they lack the majority of normal Polkadot subsystems, they
78-
will still need to connect directly to the relay chain network.
79-
##### Example command
80-
```bash
81-
polkadot-parachain \
82-
--chain parachain-chainspec.json \
83-
--tmp \
84-
--relay-chain-rpc-urls \
85-
"ws://relaychain-rpc-endpoint:9944" \
86-
"ws://relaychain-rpc-endpoint-backup:9944" \
87-
-- \
88-
--chain relaychain-chainspec.json
89-
```
90-
91-
#### Relay Chain Light Client
92-
An internal relay chain light client provides a fast and lightweight approach for connecting to the relay chain network.
93-
It provides relay chain notifications and facilitates runtime calls.
94-
95-
To specify which chain the light client should connect to, users need to supply a relay chain chain-spec as part of the relay chain arguments.
96-
97-
**Note:** At this time, any parachain nodes using this feature will still spawn a significantly cut-down
98-
relay chain node in-process. Even though they lack the majority of normal Polkadot subsystems, they
99-
will still need to connect directly to the relay chain network.
100-
101-
##### Example command
102-
```bash
103-
polkadot-parachain \
104-
--chain parachain-chainspec.json \
105-
--tmp \
106-
--relay-chain-light-client \
107-
-- \
108-
--chain relaychain-chainspec.json
109-
```
110-
111-
## Installation and Setup
112-
Before building Cumulus SDK based nodes / runtimes prepare your environment by following Substrate
113-
[installation instructions](https://docs.substrate.io/main-docs/install/).
114-
115-
To launch a local network, you can use [zombienet](https://github.com/paritytech/zombienet) for
116-
quick setup and experimentation or follow the [manual setup](#manual-setup).
117-
118-
### Zombienet
119-
We use Zombienet to spin up networks for integration tests and local networks.
120-
Follow [these installation steps](https://github.com/paritytech/zombienet#requirements-by-provider)
121-
to set it up on your machine. A simple network specification with two relay chain nodes and one collator is
122-
located at [zombienet/examples/small_network.toml](zombienet/examples/small_network.toml).
123-
124-
125-
#### Which provider should I use?
126-
Zombienet offers multiple providers to run networks. Choose the one that best fits your needs:
127-
- **Podman:** Choose this if you want to spin up a network quick and easy.
128-
- **Native:** Choose this if you want to develop and deploy your changes. Requires compilation
129-
of the binaries.
130-
- **Kubernetes:** Choose this for advanced use-cases or running on cloud-infrastructure.
131-
132-
#### How to run
133-
To run the example network, use the following commands:
134-
135-
```bash
136-
# Podman provider
137-
zombienet --provider podman spawn ./zombienet/examples/small_network.toml
138-
139-
# Native provider, assumes polkadot and polkadot-parachains binary in $PATH
140-
zombienet --provider native spawn ./zombienet/examples/small_network.toml
141-
```
142-
143-
### Manual Setup
144-
#### Launch the Relay Chain
145-
146-
```bash
147-
# Clone
148-
git clone https://github.com/paritytech/polkadot
149-
cd polkadot
150-
151-
# Compile Polkadot with the real overseer feature
152-
cargo build --release --bin polkadot
153-
154-
# Generate a raw chain spec
155-
./target/release/polkadot build-spec --chain rococo-local --disable-default-bootnode --raw > rococo-local-cfde.json
156-
157-
# Alice
158-
./target/release/polkadot --chain rococo-local-cfde.json --alice --tmp
159-
160-
# Bob (In a separate terminal)
161-
./target/release/polkadot --chain rococo-local-cfde.json --bob --tmp --port 30334
162-
```
163-
164-
#### Launch the Parachain
165-
166-
```bash
167-
# Clone
168-
git clone https://github.com/paritytech/cumulus
169-
cd cumulus
170-
171-
# Compile
172-
cargo build --release --bin polkadot-parachain
173-
174-
# Export genesis state
175-
./target/release/polkadot-parachain export-genesis-state > genesis-state
176-
177-
# Export genesis wasm
178-
./target/release/polkadot-parachain export-genesis-wasm > genesis-wasm
179-
180-
# Collator1
181-
./target/release/polkadot-parachain --collator --alice --force-authoring --tmp --port 40335 --rpc-port 9946 -- --chain ../polkadot/rococo-local-cfde.json --port 30335
182-
183-
# Collator2
184-
./target/release/polkadot-parachain --collator --bob --force-authoring --tmp --port 40336 --rpc-port 9947 -- --chain ../polkadot/rococo-local-cfde.json --port 30336
185-
186-
# Parachain Full Node 1
187-
./target/release/polkadot-parachain --tmp --port 40337 --rpc-port 9948 -- --chain ../polkadot/rococo-local-cfde.json --port 30337
188-
```
189-
190-
#### Register the parachain
191-
192-
![image](https://user-images.githubusercontent.com/2915325/99548884-1be13580-2987-11eb-9a8b-20be658d34f9.png)
193-
194-
195-
## Asset Hub 🪙
196-
197-
This repository also contains the Asset Hub runtimes. Asset Hub is a system parachain providing an
198-
asset store for the Polkadot ecosystem.
199-
200-
### Build & Launch a Node
201-
202-
To run an Asset Hub node, you will need to compile the `polkadot-parachain` binary:
203-
204-
```bash
205-
cargo build --release --locked --bin polkadot-parachain
206-
```
207-
208-
Once the executable is built, launch the parachain node via:
209-
210-
```bash
211-
CHAIN=asset-hub-westend # or asset-hub-kusama
212-
./target/release/polkadot-parachain --chain $CHAIN
213-
```
214-
215-
Refer to the [setup instructions](#manual-setup) to run a local network for development.
216-
217-
## Contracts 📝
218-
219-
See [the `contracts-rococo` readme](parachains/runtimes/contracts/contracts-rococo/README.md) for details.
220-
221-
## Bridge-hub 📝
222-
223-
See [the `bridge-hubs` readme](parachains/runtimes/bridge-hubs/README.md) for details.
224-
225-
## Rococo 👑
226-
227-
[Rococo](https://polkadot.js.org/apps/?rpc=wss://rococo-rpc.polkadot.io) is becoming a
228-
[Community Parachain Testbed](https://polkadot.network/blog/rococo-revamp-becoming-a-community-parachain-testbed/)
229-
for parachain teams in the Polkadot ecosystem. It supports multiple parachains with the
230-
differentiation of long-term connections and recurring short-term connections, to see which
231-
parachains are currently connected and how long they will be connected for
232-
[see here](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frococo-rpc.polkadot.io#/parachains).
233-
234-
Rococo is an elaborate style of design and the name describes the painstaking effort that has gone
235-
into this project.
236-
237-
### Build & Launch Rococo Collators
238-
239-
Collators are similar to validators in the relay chain. These nodes build the blocks that will
240-
eventually be included by the relay chain for a parachain.
241-
242-
To run a Rococo collator you will need to compile the following binary:
243-
244-
```bash
245-
cargo build --release --locked --bin polkadot-parachain
246-
```
247-
248-
Once the executable is built, launch collators for each parachain (repeat once each for chain
249-
`tick`, `trick`, `track`):
250-
251-
```bash
252-
./target/release/polkadot-parachain --chain $CHAIN --validator
253-
```
254-
255-
You can also build [using a container](./docs/container.md).
256-
257-
### Parachains
258-
259-
* [Asset Hub](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frococo-statemint-rpc.polkadot.io#/explorer)
260-
* [Contracts on Rococo](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frococo-contracts-rpc.polkadot.io#/explorer)
261-
* [RILT](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frococo.kilt.io#/explorer)
262-
263-
The network uses horizontal message passing (HRMP) to enable communication between parachains and
264-
the relay chain and, in turn, between parachains. This means that every message is sent to the relay
265-
chain, and from the relay chain to its destination parachain.
13+
Parity Technologies

0 commit comments

Comments
 (0)