Skip to content

Commit 8884058

Browse files
dannywillemsdannywillems
committed
Website/infrastructure: add documentation with o1Labs infra
1 parent eaba042 commit 8884058

18 files changed

+796
-0
lines changed

‎.github/workflows/test-docs-infrastructure.yaml‎

Lines changed: 367 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,367 @@
1+
name: Test Documentation Scripts - Infrastructure
2+
3+
# Test infrastructure connectivity and infrastructure scripts
4+
on:
5+
schedule:
6+
# Run daily at 6 AM UTC to catch infrastructure issues early
7+
- cron: '0 6 * * *'
8+
workflow_dispatch:
9+
# Allow manual triggering for testing
10+
pull_request:
11+
# Always run on pull requests
12+
push:
13+
branches: [ main, develop ]
14+
15+
jobs:
16+
test-seed-nodes:
17+
name: Test Seed Node Connectivity
18+
runs-on: ubuntu-latest
19+
20+
steps:
21+
- name: Checkout repository
22+
uses: actions/checkout@v5
23+
24+
- name: Test seed node connectivity
25+
run: |
26+
echo "🔍 Testing o1Labs seed node connectivity..."
27+
28+
# Read seed nodes from file
29+
seed_file="website/docs/developers/scripts/infrastructure/seed-nodes.txt"
30+
31+
if [ ! -f "$seed_file" ]; then
32+
echo "❌ Seed nodes file not found: $seed_file"
33+
exit 1
34+
fi
35+
36+
failed=0
37+
38+
# Extract hostnames from multiaddress format and test connectivity
39+
while IFS= read -r seed_address; do
40+
# Extract hostname from multiaddress: /peer-id/https/hostname/port
41+
hostname=$(echo "$seed_address" | cut -d'/' -f4)
42+
43+
if [ -z "$hostname" ]; then
44+
echo "❌ Could not extract hostname from: $seed_address"
45+
failed=$((failed + 1))
46+
continue
47+
fi
48+
49+
echo "Testing connectivity to $hostname (from $seed_address)..."
50+
51+
# Test HTTPS connectivity (port 443)
52+
if curl -s --connect-timeout 10 --max-time 30 "https://$hostname" > /dev/null 2>&1; then
53+
echo "✅ $hostname is reachable via HTTPS"
54+
else
55+
echo "❌ $hostname is not reachable via HTTPS"
56+
failed=$((failed + 1))
57+
fi
58+
59+
# Test basic DNS resolution (non-fatal for now)
60+
if nslookup "$hostname" > /dev/null 2>&1; then
61+
echo "✅ $hostname DNS resolution successful"
62+
else
63+
echo "⚠️ $hostname DNS resolution failed (may be environment-specific)"
64+
fi
65+
66+
echo "---"
67+
done < "$seed_file"
68+
69+
if [ $failed -gt 0 ]; then
70+
echo "💥 $failed connectivity tests failed"
71+
echo "Infrastructure issues detected. Please check seed node status."
72+
exit 1
73+
else
74+
echo "🎉 All seed nodes are healthy and reachable"
75+
fi
76+
77+
- name: Test seed node response headers
78+
run: |
79+
echo "🔍 Testing seed node HTTP response headers..."
80+
81+
# Read seed nodes from file
82+
seed_file="website/docs/developers/scripts/infrastructure/seed-nodes.txt"
83+
84+
if [ ! -f "$seed_file" ]; then
85+
echo "❌ Seed nodes file not found: $seed_file"
86+
exit 1
87+
fi
88+
89+
# Extract hostnames from multiaddress format and test headers
90+
while IFS= read -r seed_address; do
91+
# Extract hostname from multiaddress: /peer-id/https/hostname/port
92+
hostname=$(echo "$seed_address" | cut -d'/' -f4)
93+
94+
if [ -z "$hostname" ]; then
95+
echo "❌ Could not extract hostname from: $seed_address"
96+
continue
97+
fi
98+
99+
echo "Checking headers for $hostname (from $seed_address)..."
100+
101+
# Get response headers (ignore cert issues for now)
102+
if headers=$(curl -s -I --connect-timeout 10 --max-time 30 "https://$hostname" 2>/dev/null); then
103+
echo "✅ $hostname returned headers:"
104+
echo "$headers" | head -5 | sed 's/^/ /'
105+
else
106+
echo "⚠️ $hostname did not return headers (may be expected for WebRTC endpoints)"
107+
fi
108+
109+
echo "---"
110+
done < "$seed_file"
111+
112+
verify-seed-node-format:
113+
name: Verify Seed Node Address Format
114+
runs-on: ubuntu-latest
115+
116+
steps:
117+
- name: Checkout repository
118+
uses: actions/checkout@v5
119+
120+
- name: Verify seed nodes are subset of official seeds
121+
run: |
122+
echo "🔍 Verifying seed nodes are subset of official o1Labs seeds..."
123+
124+
# Download official seeds list
125+
official_seeds_url="https://raw.githubusercontent.com/o1-labs/seeds/main/networks/devnet-webrtc.txt"
126+
curl -s "$official_seeds_url" > /tmp/official-seeds.txt
127+
128+
if [ ! -s /tmp/official-seeds.txt ]; then
129+
echo "❌ Failed to download official seeds list"
130+
exit 1
131+
fi
132+
133+
echo "Downloaded official seeds list"
134+
135+
# Read our seed nodes
136+
seed_file="website/docs/developers/scripts/infrastructure/seed-nodes.txt"
137+
our_seeds=$(cat "$seed_file")
138+
139+
# Check each of our seeds exists in official list
140+
missing=0
141+
while IFS= read -r seed; do
142+
if grep -Fxq "$seed" /tmp/official-seeds.txt; then
143+
echo "✅ Found in official list: $seed"
144+
else
145+
echo "❌ Missing from official list: $seed"
146+
missing=$((missing + 1))
147+
fi
148+
done <<< "$our_seeds"
149+
150+
if [ $missing -gt 0 ]; then
151+
echo "💥 $missing seed node(s) not found in official seeds"
152+
echo "Official seeds list:"
153+
cat /tmp/official-seeds.txt
154+
exit 1
155+
else
156+
echo "🎉 All seed nodes are present in official seeds list"
157+
fi
158+
159+
test-plain-nodes:
160+
name: Test Plain Node Connectivity
161+
strategy:
162+
matrix:
163+
os: [ubuntu-latest, macos-latest]
164+
runs-on: ${{ matrix.os }}
165+
166+
steps:
167+
- name: Checkout repository
168+
uses: actions/checkout@v5
169+
170+
- name: Test plain node GraphQL endpoints
171+
run: |
172+
echo "🔍 Testing plain node GraphQL connectivity..."
173+
174+
# Read plain nodes from file
175+
plain_nodes_file="website/docs/developers/scripts/infrastructure/plain-nodes.txt"
176+
177+
if [ ! -f "$plain_nodes_file" ]; then
178+
echo "❌ Plain nodes file not found: $plain_nodes_file"
179+
exit 1
180+
fi
181+
182+
plain_nodes=$(cat "$plain_nodes_file")
183+
failed=0
184+
185+
for node_url in $plain_nodes; do
186+
echo "Testing GraphQL endpoint: $node_url"
187+
188+
# Test basic HTTP connectivity
189+
if curl -s --connect-timeout 10 --max-time 30 "$node_url" > /dev/null 2>&1; then
190+
echo "✅ $node_url is reachable via HTTP"
191+
else
192+
echo "❌ $node_url is not reachable via HTTP"
193+
failed=$((failed + 1))
194+
continue
195+
fi
196+
197+
# Test GraphQL endpoint using website scripts
198+
graphql_url="${node_url}graphql"
199+
200+
# Test daemon status query using the website script
201+
if response=$(bash website/docs/developers/scripts/graphql-api/queries/curl/daemon-status.sh "$graphql_url" 2>/dev/null); then
202+
# Extract JSON response (skip curl progress output)
203+
json_response=$(echo "$response" | grep "^{")
204+
205+
# Check if it's valid JSON
206+
if echo "$json_response" | jq . > /dev/null 2>&1; then
207+
# Check for GraphQL errors
208+
if echo "$json_response" | jq -e '.errors' > /dev/null 2>&1; then
209+
echo "⚠️ $graphql_url returned GraphQL error:"
210+
echo "$json_response" | jq '.errors'
211+
# Check for valid data
212+
elif echo "$json_response" | jq -e '.data.daemonStatus' > /dev/null 2>&1; then
213+
echo "✅ $graphql_url GraphQL query successful"
214+
sync_status=$(echo "$json_response" | jq -r '.data.daemonStatus.syncStatus // "unknown"')
215+
chain_id=$(echo "$json_response" | jq -r '.data.daemonStatus.chainId // "unknown"')
216+
echo " Sync Status: $sync_status, Chain ID: ${chain_id:0:16}..."
217+
else
218+
echo "⚠️ $graphql_url unexpected response format"
219+
fi
220+
else
221+
echo "⚠️ $graphql_url did not return valid JSON: $(echo "$response" | head -c 100)..."
222+
fi
223+
else
224+
echo "❌ $graphql_url GraphQL query failed"
225+
failed=$((failed + 1))
226+
fi
227+
228+
echo "---"
229+
done
230+
231+
if [ $failed -gt 0 ]; then
232+
echo "💥 $failed plain node tests failed"
233+
echo "Infrastructure issues detected. Please check plain node status."
234+
exit 1
235+
else
236+
echo "🎉 All plain nodes are healthy and responding"
237+
fi
238+
239+
- name: Test plain node API capabilities
240+
run: |
241+
echo "🔍 Testing plain node API capabilities..."
242+
243+
# Read plain nodes from file
244+
plain_nodes_file="website/docs/developers/scripts/infrastructure/plain-nodes.txt"
245+
plain_nodes=$(cat "$plain_nodes_file")
246+
247+
# Test with first available node
248+
for node_url in $plain_nodes; do
249+
graphql_url="${node_url}graphql"
250+
251+
echo "Testing API capabilities on: $graphql_url"
252+
253+
# Test network ID query using website script
254+
network_success=false
255+
if network_response=$(bash website/docs/developers/scripts/graphql-api/queries/curl/network-id.sh "$graphql_url" 2>/dev/null); then
256+
network_json=$(echo "$network_response" | grep "^{")
257+
if echo "$network_json" | jq -e '.data.networkID' > /dev/null 2>&1; then
258+
network_id=$(echo "$network_json" | jq -r '.data.networkID')
259+
echo "✅ Network ID query successful: $network_id"
260+
network_success=true
261+
else
262+
echo "⚠️ Network ID query failed or unexpected response"
263+
fi
264+
else
265+
echo "⚠️ Network ID query script failed"
266+
fi
267+
268+
# Test best chain query using website script
269+
chain_success=false
270+
if chain_response=$(bash website/docs/developers/scripts/graphql-api/queries/curl/best-chain.sh "$graphql_url" 2>/dev/null); then
271+
chain_json=$(echo "$chain_response" | grep "^{")
272+
if echo "$chain_json" | jq -e '.data.bestChain[0].stateHash' > /dev/null 2>&1; then
273+
state_hash=$(echo "$chain_json" | jq -r '.data.bestChain[0].stateHash')
274+
echo "✅ Best chain query successful: ${state_hash:0:16}..."
275+
chain_success=true
276+
else
277+
echo "⚠️ Best chain query failed or unexpected response"
278+
fi
279+
else
280+
echo "⚠️ Best chain query script failed"
281+
fi
282+
283+
# We only need to test one working node
284+
if [ "$network_success" = true ] && [ "$chain_success" = true ]; then
285+
echo "🎉 Plain node API capabilities verified"
286+
break
287+
fi
288+
done
289+
290+
- name: Test infrastructure scripts
291+
run: |
292+
echo "🔍 Testing infrastructure command scripts..."
293+
294+
# Dynamically discover all bash scripts in the infrastructure directory
295+
script_dir="website/docs/developers/scripts/infrastructure"
296+
297+
if [ ! -d "$script_dir" ]; then
298+
echo "❌ Script directory not found: $script_dir"
299+
exit 1
300+
fi
301+
302+
# Get all .sh files in the infrastructure directory
303+
script_files=$(ls "$script_dir"/*.sh 2>/dev/null)
304+
305+
if [ -z "$script_files" ]; then
306+
echo "❌ No bash scripts found in $script_dir"
307+
exit 1
308+
fi
309+
310+
failed=0
311+
312+
# Use first plain node for testing infrastructure scripts
313+
plain_nodes_file="website/docs/developers/scripts/infrastructure/plain-nodes.txt"
314+
test_endpoint=""
315+
if [ -f "$plain_nodes_file" ]; then
316+
first_node=$(head -n 1 "$plain_nodes_file")
317+
test_endpoint="${first_node}graphql"
318+
else
319+
# Fallback endpoint if file not found
320+
test_endpoint="http://mina-rust-plain-1.gcp.o1test.net/graphql"
321+
fi
322+
323+
for script_file in $script_files; do
324+
if [ ! -f "$script_file" ]; then
325+
echo "❌ Script file not found: $script_file"
326+
failed=$((failed + 1))
327+
continue
328+
fi
329+
330+
echo "Testing script: $script_file"
331+
332+
# Execute the script with test endpoint and capture output
333+
if output=$(timeout 30 bash "$script_file" "$test_endpoint" 2>&1); then
334+
echo "✅ Script executed successfully"
335+
336+
# Try to parse output as JSON using jq
337+
if json_response=$(echo "$output" | jq . 2>/dev/null); then
338+
# Valid JSON response - check for GraphQL errors
339+
if echo "$json_response" | jq -e '.errors' > /dev/null 2>&1; then
340+
echo "❌ Script returned GraphQL errors:"
341+
echo "$json_response" | jq '.errors'
342+
failed=$((failed + 1))
343+
elif echo "$json_response" | jq -e '.data' > /dev/null 2>&1; then
344+
echo "✅ Script response contains valid data: $(echo "$json_response" | head -c 100)..."
345+
else
346+
echo "⚠️ Unexpected JSON response format: $(echo "$json_response" | head -c 100)..."
347+
fi
348+
else
349+
# Non-JSON output - just validate it looks reasonable
350+
echo "✅ Script response (non-JSON): $(echo "$output" | head -c 100)..."
351+
fi
352+
else
353+
echo "❌ Script execution failed: $script_file"
354+
failed=$((failed + 1))
355+
fi
356+
357+
echo "---"
358+
done
359+
360+
if [ $failed -gt 0 ]; then
361+
echo "💥 $failed infrastructure script tests failed"
362+
echo "Some infrastructure scripts may need updates."
363+
exit 1
364+
else
365+
echo "🎉 All infrastructure command scripts are working"
366+
fi
367+

‎website/docs/developers/getting-started.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -218,6 +218,18 @@ state machine pattern, and component organization, please see the
218218
./target/release/mina node --network devnet
219219
```
220220

221+
<!-- prettier-ignore-start -->
222+
223+
:::tip Connect to o1Labs Infrastructure
224+
225+
For reliable network connectivity, you can connect to o1Labs maintained seed
226+
nodes. See the [Seed Nodes](../node-operators/infrastructure/seed-nodes)
227+
documentation for official seed node addresses and connection instructions.
228+
229+
:::
230+
231+
<!-- prettier-ignore-stop -->
232+
221233
### Archive Node
222234

223235
```bash

‎website/docs/developers/scripts/infrastructure/plain-nodes.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
http://mina-rust-plain-1.gcp.o1test.net/
2+
http://mina-rust-plain-2.gcp.o1test.net/
3+
http://mina-rust-plain-3.gcp.o1test.net/

‎website/docs/developers/scripts/infrastructure/queries/block-height.graphql‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{ bestChain(maxLength: 1) { protocolState { consensusState { blockHeight } } } }

‎website/docs/developers/scripts/infrastructure/queries/daemon-status.graphql‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{ daemonStatus { blockchainLength chainId } }

0 commit comments

Comments
 (0)