Skip to content

Commit 45f18cf

Browse files
raymondkfcheungbkontur
raymondkfcheung
and
bkontur
authored
Improve README on Local Examples (#107)
* Update for local only * Improve README.md * Improve README.md * Update scripts * Revert minor changes * Update scripts * Apply suggestions from code review * Apply suggestions from code review * Update examples/README.md --------- Co-authored-by: Branislav Kontur <[email protected]>
1 parent c029f4e commit 45f18cf

File tree

3 files changed

+155
-63
lines changed

3 files changed

+155
-63
lines changed

‎examples/README.md‎

Lines changed: 127 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,107 +1,179 @@
1-
# How to run
1+
# How to Run
22

3-
### Build Bulletin
4-
```
5-
git clone https://github.com/paritytech/polkadot-bulletin-chain.git
6-
cd polkadot-bulletin-chain
7-
cargo build --release -p polkadot-bulletin-chain
8-
```
93

10-
### Download Zombienet
11-
```
12-
cd polkadot-bulletin-chain - make sure we are within the folder
4+
```shell
5+
cd polkadot-bulletin-chain # make you are inside the project directory for the following steps
136
```
147

15-
#### Linux
16-
```
17-
wget https://github.com/paritytech/zombienet/releases/download/v1.3.133/zombienet-linux-x64
18-
chmod +x zombienet-linux-x64
19-
```
8+
## Download Zombienet
209

21-
#### Mac OS
22-
`zombienet-macos-arm64` or `zombienet-macos-x64`
10+
```shell
11+
OS="$(uname -s)"
12+
ARCH="$(uname -m)"
2313

24-
```
25-
curl -L -o zombienet-macos-arm64 https://github.com/paritytech/zombienet/releases/download/v1.3.133/zombienet-macos-arm64
26-
chmod +x zombienet-macos-arm64
27-
```
14+
if [ "$OS" = "Linux" ]; then
15+
zb_os=linux
16+
else
17+
zb_os=macos
18+
fi
2819

29-
### Run Kubo locally
20+
if [ "$ARCH" = "arm64" ] || [ "$ARCH" = "aarch64" ]; then
21+
zb_arch=arm64
22+
else
23+
zb_arch=x64
24+
fi
3025

31-
#### Either locally
32-
```
33-
wget https://dist.ipfs.tech/kubo/v0.38.1/kubo_v0.38.1_linux-amd64.tar.gz
34-
tar -xvzf kubo_v0.38.1_linux-amd64.tar.gz
35-
cd kubo
36-
sudo bash install.sh
37-
ipfs version
38-
ipfs init
39-
ipfs daemon & # run in background
26+
zb_bin="zombienet-${zb_os}-${zb_arch}"
27+
28+
wget "https://github.com/paritytech/zombienet/releases/download/v1.3.133/${zb_bin}"
29+
chmod +x "${zb_bin}"
4030
```
4131

42-
#### Or use docker (uses 172.17.0.1 or host.docker.internal for swarm connect)
32+
## Run Kubo
33+
34+
#### Execute Locally
4335

36+
```shell
37+
wget https://dist.ipfs.tech/kubo/v0.38.1/kubo_v0.38.1_darwin-arm64.tar.gz
38+
tar -xvzf kubo_v0.38.1_darwin-arm64.tar.gz
39+
./kubo/ipfs version
40+
./kubo/ipfs init
41+
./kubo/ipfs daemon & # run in the background
4442
```
43+
44+
#### Use Docker
45+
46+
* Use `172.17.0.1` or `host.docker.internal` for swarm connections
47+
48+
```shell
4549
docker pull ipfs/kubo:latest
46-
docker run -d --name ipfs-node -v ipfs-data:/data/ipfs -p 4001:4001 -p 8080:8080 -p 5001:5001 ipfs/kubo:latest
50+
docker run -d --name ipfs-node -v ipfs-data:/data/ipfs -p 4001:4001 -p 8080:8080 -p 5001:5001 ipfs/kubo:latest
4751
docker logs -f ipfs-node
4852
```
4953

50-
## Run Bulletin solochain with `--ipfs-server`
51-
```
54+
## Run Bulletin Solochain with `--ipfs-server`
55+
56+
```shell
5257
# Bulletin Solochain
53-
POLKADOT_BULLETIN_BINARY_PATH=./target/release/polkadot-bulletin-chain ./zombienet-linux-x64 -p native spawn ./zombienet/bulletin-polkadot-local.toml
5458

55-
# Connect nodes
56-
ipfs swarm connect /ip4/127.0.0.1/tcp/10001/ws/p2p/12D3KooWQCkBm1BYtkHpocxCwMgR8yjitEeHGx8spzcDLGt2gkBm
59+
```shell
60+
# cd polkadot-bulletin-chain # make you are in this directory
61+
cargo build --release -p polkadot-bulletin-chain
62+
63+
POLKADOT_BULLETIN_BINARY_PATH=./target/release/polkadot-bulletin-chain \
64+
./$(ls zombienet-*-*) -p native spawn ./zombienet/bulletin-polkadot-local.toml
65+
66+
### Connect IPFS Nodes
67+
68+
```shell
69+
# Uses Kubo
70+
./kubo/ipfs swarm connect /ip4/127.0.0.1/tcp/10001/ws/p2p/12D3KooWQCkBm1BYtkHpocxCwMgR8yjitEeHGx8spzcDLGt2gkBm
5771
# connect 12D3KooWQCkBm1BYtkHpocxCwMgR8yjitEeHGx8spzcDLGt2gkBm success
58-
ipfs swarm connect /ip4/127.0.0.1/tcp/12347/ws/p2p/12D3KooWRkZhiRhsqmrQ28rt73K7V3aCBpqKrLGSXmZ99PTcTZby
72+
73+
./kubo/ipfs swarm connect /ip4/127.0.0.1/tcp/12347/ws/p2p/12D3KooWRkZhiRhsqmrQ28rt73K7V3aCBpqKrLGSXmZ99PTcTZby
5974
# connect 12D3KooWRkZhiRhsqmrQ28rt73K7V3aCBpqKrLGSXmZ99PTcTZby success
75+
```
6076

61-
# Or docker (change 127.0.0.1 -> 172.17.0.1)
77+
```shell
78+
# Uses Docker (replace 127.0.0.1 with 172.17.0.1)
6279
docker exec -it ipfs-node ipfs swarm connect /ip4/172.17.0.1/tcp/10001/ws/p2p/12D3KooWQCkBm1BYtkHpocxCwMgR8yjitEeHGx8spzcDLGt2gkBm
6380
docker exec -it ipfs-node ipfs swarm connect /ip4/172.17.0.1/tcp/12347/ws/p2p/12D3KooWRkZhiRhsqmrQ28rt73K7V3aCBpqKrLGSXmZ99PTcTZby
81+
```
6482

65-
# Or run script which reconnects every 2 seconds
83+
```shell
84+
# Runs a script that reconnects every 2 seconds
85+
# Defaults to Docker; use 'local' to use the local Kubo instance
6686
./scripts/ipfs-reconnect-solo.sh
6787
```
6888

69-
## Run Bulletin (Westend) parachain with `--ipfs-server`
89+
## Run Bulletin (Westend) Parachain with `--ipfs-server`
90+
91+
### Prerequisites
92+
93+
```shell
94+
mkdir -p ~/local_bridge_testing/bin
95+
96+
# Ensures `polkadot` and `polkadot-parachain` exist
97+
git clone https://github.com/paritytech/polkadot-sdk.git
98+
# TODO: unless not merged: https://github.com/paritytech/polkadot-sdk/pull/10370
99+
git reset --hard origin/bko-bulletin-para-support
100+
cd polkadot-sdk
101+
102+
cargo build -p polkadot -r
103+
ls -la target/release/polkadot
104+
cp target/release/polkadot ~/local_bridge_testing/bin
105+
cp target/release/polkadot-prepare-worker ~/local_bridge_testing/bin
106+
cp target/release/polkadot-execute-worker ~/local_bridge_testing/bin
107+
~/local_bridge_testing/bin/polkadot --version
108+
# polkadot 1.20.2-165ba47dc91 or higher
109+
110+
cargo build -p polkadot-parachain-bin -r
111+
ls -la target/release/polkadot-parachain
112+
cp target/release/polkadot-parachain ~/local_bridge_testing/bin
113+
~/local_bridge_testing/bin/polkadot-parachain --version
114+
# polkadot-parachain 1.20.2-165ba47dc91 or higher
70115
```
71-
# Bulletin parachain (Westend)
116+
117+
### Launch Parachain
118+
119+
```shell
120+
# Bulletin Parachain (Westend)
72121
./scripts/create_bulletin_westend_spec.sh
73-
POLKADOT_BINARY_PATH=~/local_bridge_testing/bin/polkadot POLKADOT_PARACHAIN_BINARY_PATH=~/local_bridge_testing/bin/polkadot-parachain ./zombienet-linux-x64 -p native spawn ./zombienet/bulletin-westend-local.toml
122+
POLKADOT_BINARY_PATH=~/local_bridge_testing/bin/polkadot \
123+
POLKADOT_PARACHAIN_BINARY_PATH=~/local_bridge_testing/bin/polkadot-parachain \
124+
./$(ls zombienet-*-*) -p native spawn ./zombienet/bulletin-westend-local.toml
125+
```
126+
127+
### Connect IPFS Nodes
128+
129+
```shell
130+
# Uses Kubo
131+
./kubo/ipfs swarm connect /ip4/127.0.0.1/tcp/10001/ws/p2p/12D3KooWJKVVNYByvML4Pgx1GWAYryYo6exA68jQX9Mw3AJ6G5gQ
132+
# connect 12D3KooWJKVVNYByvML4Pgx1GWAYryYo6exA68jQX9Mw3AJ6G5gQ success
74133

75-
# For docker (change 127.0.0.1 -> 172.17.0.1)
134+
./kubo/ipfs swarm connect /ip4/127.0.0.1/tcp/12347/ws/p2p/12D3KooWJ8sqAYtMBX3z3jy2iM98XGLFVzVfUPtmgDzxXSPkVpZZ
135+
# connect 12D3KooWJ8sqAYtMBX3z3jy2iM98XGLFVzVfUPtmgDzxXSPkVpZZ success
136+
```
137+
138+
```shell
139+
# Uses Docker (replace 127.0.0.1 with 172.17.0.1)
76140
docker exec -it ipfs-node ipfs swarm connect /ip4/172.17.0.1/tcp/10001/ws/p2p/12D3KooWJKVVNYByvML4Pgx1GWAYryYo6exA68jQX9Mw3AJ6G5gQ
77141
docker exec -it ipfs-node ipfs swarm connect /ip4/172.17.0.1/tcp/12347/ws/p2p/12D3KooWJ8sqAYtMBX3z3jy2iM98XGLFVzVfUPtmgDzxXSPkVpZZ
142+
```
78143

79-
# Or run script which reconnects every 2 seconds
144+
```shell
145+
# Runs a script that reconnects every 2 seconds
146+
# Defaults to Docker; use 'local' to use the local Kubo instance
80147
./scripts/ipfs-reconnect-westend.sh
81148
```
82149

83-
## Trigger authorize, store and IPFS get
84-
```
85-
# cd polkadot-bulletin-chain - make sure we are here
150+
## Trigger Authorize, Store and IPFS Get
151+
152+
```shell
153+
# cd polkadot-bulletin-chain # make you are in this directory
86154
cd examples
87155
npm install @polkadot/api @polkadot/keyring @polkadot/util-crypto @polkadot/util multiformats ipfs-http-client ipfs-unixfs
88156
```
89157

90-
### Example for simple authorizing and store
91-
```
158+
### Example for Simple Authorizing and Store
159+
160+
```shell
92161
node authorize_and_store.js
93162
```
94163

95-
### Example for multipart / chunked content / big files
96-
The code stores one file, splits into chunks and then uploads those chunks to the Bulletin.
97-
It collects all the partial CIDs for each chunk and saves them as a custom metadata JSON file in the Bulletin.
164+
### Example for Multipart / Chunked Content / Big Files
165+
166+
The code stores one file, splits it into chunks, and then uploads those chunks to Bulletin.
167+
168+
It collects all the partial CIDs for each chunk and saves them as a custom metadata JSON file in Bulletin.
98169

99170
Now we have two examples:
100171
1. **Manual reconstruction** — return the metadata and chunk CIDs, then reconstruct the original file manually.
101172
2. **IPFS DAG feature** —
102173
* converts the metadata into a DAG-PB descriptor,
103174
* stores it directly in IPFS,
104175
* and allows fetching the entire file using a single root CID from an IPFS HTTP gateway (for example: `http://localhost:8080/ipfs/QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ`).
105-
```
176+
177+
```shell
106178
node store_chunked_data.js
107179
```

‎scripts/ipfs-reconnect-solo.sh‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,30 @@
11
#!/bin/bash
22

3+
# Choose mode based on argument
4+
mode="${1:-docker}"
5+
if [ "$mode" = "docker" ]; then
6+
check_cmd="docker exec ipfs-node ipfs"
7+
check_host="172.17.0.1"
8+
else
9+
check_cmd="./kubo/ipfs"
10+
check_host="127.0.0.1"
11+
fi
12+
313
# Peers to monitor
414
PEERS_TO_CHECK=(
5-
"/ip4/172.17.0.1/tcp/10001/ws/p2p/12D3KooWQCkBm1BYtkHpocxCwMgR8yjitEeHGx8spzcDLGt2gkBm"
6-
"/ip4/172.17.0.1/tcp/12347/ws/p2p/12D3KooWRkZhiRhsqmrQ28rt73K7V3aCBpqKrLGSXmZ99PTcTZby"
15+
"/ip4/${check_host}/tcp/10001/ws/p2p/12D3KooWQCkBm1BYtkHpocxCwMgR8yjitEeHGx8spzcDLGt2gkBm"
16+
"/ip4/${check_host}/tcp/12347/ws/p2p/12D3KooWRkZhiRhsqmrQ28rt73K7V3aCBpqKrLGSXmZ99PTcTZby"
717
)
818

919
while true; do
1020
# Read all current connections once
11-
PEERS=$(docker exec ipfs-node ipfs swarm peers)
21+
PEERS="$($check_cmd swarm peers)"
1222

1323
for PEER in "${PEERS_TO_CHECK[@]}"; do
1424
echo "$PEERS" | grep -q "$PEER"
1525
if [ $? -ne 0 ]; then
1626
echo "$(date) - $PEER disconnected. Reconnecting..."
17-
docker exec ipfs-node ipfs swarm connect "$PEER"
27+
$check_cmd swarm connect "$PEER"
1828
else
1929
echo "$(date) - $PEER connected."
2030
fi

‎scripts/ipfs-reconnect-westend.sh‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,30 @@
11
#!/bin/bash
22

3+
# Choose mode based on argument
4+
mode="${1:-docker}"
5+
if [ "$mode" = "docker" ]; then
6+
check_cmd="docker exec ipfs-node ipfs"
7+
check_host="172.17.0.1"
8+
else
9+
check_cmd="./kubo/ipfs"
10+
check_host="127.0.0.1"
11+
fi
12+
313
# Peers to monitor
414
PEERS_TO_CHECK=(
5-
"/ip4/172.17.0.1/tcp/10001/ws/p2p/12D3KooWJKVVNYByvML4Pgx1GWAYryYo6exA68jQX9Mw3AJ6G5gQ"
6-
"/ip4/172.17.0.1/tcp/12347/ws/p2p/12D3KooWJ8sqAYtMBX3z3jy2iM98XGLFVzVfUPtmgDzxXSPkVpZZ"
15+
"/ip4/${check_host}/tcp/10001/ws/p2p/12D3KooWJKVVNYByvML4Pgx1GWAYryYo6exA68jQX9Mw3AJ6G5gQ"
16+
"/ip4/${check_host}/tcp/12347/ws/p2p/12D3KooWJ8sqAYtMBX3z3jy2iM98XGLFVzVfUPtmgDzxXSPkVpZZ"
717
)
818

919
while true; do
1020
# Read all current connections once
11-
PEERS=$(docker exec ipfs-node ipfs swarm peers)
21+
PEERS="$($check_cmd swarm peers)"
1222

1323
for PEER in "${PEERS_TO_CHECK[@]}"; do
1424
echo "$PEERS" | grep -q "$PEER"
1525
if [ $? -ne 0 ]; then
1626
echo "$(date) - $PEER disconnected. Reconnecting..."
17-
docker exec ipfs-node ipfs swarm connect "$PEER"
27+
$check_cmd swarm connect "$PEER"
1828
else
1929
echo "$(date) - $PEER connected."
2030
fi

0 commit comments

Comments
 (0)