From 320053e2c25e2da3cb96250b880ecd86db3b377d Mon Sep 17 00:00:00 2001 From: Jotatavo <100889564+Jotatavo@users.noreply.github.com> Date: Wed, 12 Aug 2026 08:38:20 -0300 Subject: [PATCH 1/5] docs: add Solana onboarding runbooks for the MCP, kept off the site nav. --- docs/runbooks.md | 22 ++++ docs/solana-ibrl-runbook.md | 160 ++++++++++++++++++++++++ docs/solana-shreds-publisher-runbook.md | 88 +++++++++++++ docs/solana-shreds-runbook.md | 145 +++++++++++++++++++++ mkdocs.yml | 7 ++ 5 files changed, 422 insertions(+) create mode 100644 docs/runbooks.md create mode 100644 docs/solana-ibrl-runbook.md create mode 100644 docs/solana-shreds-publisher-runbook.md create mode 100644 docs/solana-shreds-runbook.md diff --git a/docs/runbooks.md b/docs/runbooks.md new file mode 100644 index 0000000..49fcc56 --- /dev/null +++ b/docs/runbooks.md @@ -0,0 +1,22 @@ +--- +description: Machine-readable index of onboarding runbooks for the DoubleZero MCP. Not published on the docs site. +--- + +# Runbooks + +The DoubleZero MCP loads this file from GitHub raw +(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`) +to discover walkthroughs. Humans use [Connect your AI](mcp.md); do not add this +page to the site nav. + +To register a runbook, add a list item under **Index** in this shape: + +```markdown +- `service-id` — [Human title](page-slug.md) +``` + +## Index + +- `solana-ibrl` — [Connect validator (IBRL Mainnet)](solana-ibrl-runbook.md) +- `solana-shreds-publisher` — [Publish shreds (Edge)](solana-shreds-publisher-runbook.md) +- `solana-shreds` — [Subscribe to shreds (Edge)](solana-shreds-runbook.md) diff --git a/docs/solana-ibrl-runbook.md b/docs/solana-ibrl-runbook.md new file mode 100644 index 0000000..947afff --- /dev/null +++ b/docs/solana-ibrl-runbook.md @@ -0,0 +1,160 @@ +--- +description: LLM-oriented runbook — connect a Solana Mainnet-Beta validator to DoubleZero in IBRL mode. Served to the MCP via GitHub raw; not published on the docs site. +--- + +# Connect validator (IBRL Mainnet) — runbook + +This page is for the DoubleZero MCP (`get_onboarding_runbook`) via GitHub raw. It is +not published on the docs site. + +1. Connect the [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Tell it this is a **Solana Mainnet-Beta validator**, the Linux host (or SSH), and where the validator identity keypair lives. +3. Walk the steps below in order. Prefer to do it by hand? Use the [human guide](DZ Mainnet-beta Connection.md). + +**What success looks like:** `doublezero status` shows tunnel **up**, User Type **IBRL**, Network **mainnet-beta**. `Tunnel src` and `Doublezero IP` match the host public IPv4. + +IBRL does not require restarting validator clients; it uses the existing public IP. + +--- + +## Prerequisites + +| Need | Notes | +|------|--------| +| Linux/amd64 host | Install DoubleZero **on the validator host**, not in a container. | +| Public IPv4, no NAT | Gossip IP must match this host. | +| Solana CLI on `$PATH` | For `solana sign-offchain-message`. | +| Validator identity keypair | Readable by the user running the commands (often under the `sol` user). | +| ≥1 SOL on the identity | Passport / onchain request. | +| GRE (IP proto 47) + BGP | BGP on `169.254.0.0/16` tcp/179. | +| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` (or distro equivalent). | + +The Validator ID is checked against Solana gossip to determine the target IP. A junk ID on the same IP is ignored; only the primary ID in gossip is used. + +--- + +## Steps + +### 1. Install the client + +Follow [setup](setup.md) if `doublezero` is not installed. Mainnet packages: + +```bash +curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash +sudo apt-get install doublezero +``` + +Rocky / RHEL: use `setup.rpm.sh` and `sudo yum install doublezero`. + +**Verify:** `sudo systemctl status doublezerod` is active. Back up `~/.config/doublezero/id.json`. + +### 2. Point the daemon at mainnet-beta + +```bash +DESIRED_DOUBLEZERO_ENV=mainnet-beta \ + && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ + && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ + && sudo systemctl daemon-reload \ + && sudo systemctl restart doublezerod \ + && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ + && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" +``` + +Wait ~30s, then `doublezero latency` should list mainnet devices. + +### 3. Open UDP 44880 on `doublezero0` + +```bash +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +UFW: `sudo ufw allow in on doublezero0 to any port 44880 proto udp` and the matching `out` rule. Also allow GRE and BGP as in [setup](setup.md). + +### 4. Confirm DoubleZero ID and primary validator + +The DoubleZero ID from setup on the **primary** must be on every backup (`~/.config/doublezero/id.json`). + +```bash +doublezero address +doublezero-solana passport find-validator -u mainnet-beta +``` + +Expect the primary: in gossip, in the leader schedule, “can connect as a primary”. On backups, run the same `find-validator`; they should **not** be leader-scheduled. + +One machine only: omit `--backup-validator-ids` / `backup_ids=` from later commands. + +### 5. Prepare the access message (primary) + +On the primary (active stake, identity in gossip): + +```bash +doublezero-solana passport prepare-validator-access -u mainnet-beta \ + --doublezero-address \ + --primary-validator-id \ + --backup-validator-ids ,, +``` + +Drop `--backup-validator-ids` if there are no backups (max 3). Copy the `solana sign-offchain-message …` line from the output. + +### 6. Sign with the validator identity key + +On the primary, run the printed command (identity keypair, **not** only the DoubleZero key): + +```bash +solana sign-offchain-message \ + service_key=,backup_ids=,, \ + -k +``` + +**Produces:** a signature string. Carry it into the next step. + +### 7. Request validator access + +```bash +doublezero-solana passport request-validator-access -k -u mainnet-beta \ + --primary-validator-id \ + --backup-validator-ids ,, \ + --signature \ + --doublezero-address +``` + +Wait for Sentinel to validate and create the access pass. Optional: the agent can call **`check_edge_access`** with `pubkey` (`doublezero address`) and the host public IP until the pass is present. + +### 8. Connect IBRL + +```bash +doublezero connect ibrl +``` + +Wait ~1 minute for GRE. Until then, status may be `down` / `Unknown`. + +```bash +doublezero status +``` + +**Pass:** `up`, User Type `IBRL`, Network `mainnet-beta`, tunnel typically `doublezero0`. + +```bash +ip route +``` + +Expect BGP-learned routes via `doublezero0`. + +--- + +## Gotchas + +1. **Wrong env.** Testnet packages / `DESIRED_DOUBLEZERO_ENV=testnet` will not land on mainnet-beta. +2. **Identity not in gossip.** Junk IDs on the same IP cannot register the machine. +3. **Backups must share the primary DoubleZero ID.** Copy `id.json`; do not keygen a second identity. +4. **Sign with the validator identity**, not the DoubleZero key. +5. **Status down for ~1 minute** after `connect ibrl` is normal while GRE comes up. + +--- + +## See also + +- [Validator Mainnet-Beta Connection](DZ Mainnet-beta Connection.md) +- [Setup](setup.md) +- Next: [Publish shreds (Edge)](solana-shreds-publisher-runbook.md) diff --git a/docs/solana-shreds-publisher-runbook.md b/docs/solana-shreds-publisher-runbook.md new file mode 100644 index 0000000..2bda63c --- /dev/null +++ b/docs/solana-shreds-publisher-runbook.md @@ -0,0 +1,88 @@ +--- +description: LLM-oriented runbook — configure a connected Solana validator to publish leader shreds to DoubleZero Edge. Served to the MCP via GitHub raw; not published on the docs site. +--- + +# Publish shreds (Edge) — runbook + +This page is for the DoubleZero MCP (`get_onboarding_runbook`) via GitHub raw. It is +not published on the docs site. + +1. Connect the [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Confirm the validator is **already on DoubleZero IBRL** (mainnet-beta). If not, finish [Connect validator (IBRL Mainnet)](solana-ibrl-runbook.md) first. +3. Walk the steps below. Human guide: [Validator Multicast Connection](Validator Multicast Connection.md). + +**What success looks like:** validator sends leader shreds to `233.84.178.1:7733`, multicast publish on `edge-solana-shreds` is up, and [publisher-check](https://data.doublezero.xyz/dz/publisher-check) shows publishing after at least one leader slot. + +This path is for **validators**. Trading firms that want to *subscribe* use [Subscribe to shreds](solana-shreds-runbook.md). + +--- + +## Prerequisites + +| Need | Notes | +|------|--------| +| IBRL tunnel already up | [IBRL Mainnet runbook](solana-ibrl-runbook.md) / [human guide](DZ Mainnet-beta Connection.md). | +| Supported client | Jito-Agave **3.1.9+**, JitoBam 3.1.9+, Frankendancer, or Harmonic **3.1.11+**. Other versions will not publish. | +| Restart window | Adding the shred destination requires a validator restart. | + +--- + +## Steps + +### 1. Point the client at the Edge shred group + +**Jito-Agave (v3.1.9+) and Harmonic (3.1.11+)** — in the validator start script add: + +```text +--shred-receiver-address 233.84.178.1:7733 +``` + +You can send to Jito and `edge-solana-shreds` at the same time. Restart the validator. + +**Frankendancer** — in `config.toml`: + +```toml +[tiles.shred] +additional_shred_destinations_leader = [ "233.84.178.1:7733", ] +``` + +Restart the validator. + +### 2. Publish on the multicast group + +```bash +doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds +``` + +**Verify:** `doublezero status` still IBRL/up, and the user is a publisher on `edge-solana-shreds`. + +Live group IPs: `doublezero multicast group list`. All shred feeds use UDP **`7733`**; the IP selects the feed. + +| Feed | Address | +|------|---------| +| `edge-solana-shreds` (leader) | `233.84.178.1:7733` | +| `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +### 3. Confirm publishing + +Open [publisher-check](https://data.doublezero.xyz/dz/publisher-check). You will not see confirmation until the validator has published leader shreds for **at least one slot**. + +Healthy: outbound spikes aligned with leader slots (sawtooth). Steady outbound with no slot pattern is **retransmit** (bad). + +--- + +## Gotchas + +1. **Wrong client version.** Not 3.1.9+ / 3.1.11+ → nothing useful on the wire. +2. **Retransmit flag left on.** Remove `--shred-retransmit-receiver-address` from Jito-Agave. Check the **No Retransmit Shreds** column on publisher-check (2-epoch vs recent-slot views). +3. **Not yet a leader.** Dashboard stays empty until a leader slot. +4. **IBRL not up.** Do not start here; finish IBRL first. + +--- + +## See also + +- [Validator Multicast Connection](Validator Multicast Connection.md) +- [Validator Rewards](Validator Rewards.md) diff --git a/docs/solana-shreds-runbook.md b/docs/solana-shreds-runbook.md new file mode 100644 index 0000000..a54f5ed --- /dev/null +++ b/docs/solana-shreds-runbook.md @@ -0,0 +1,145 @@ +--- +description: LLM-oriented runbook — buy an Edge shreds seat and receive Solana shred multicast on doublezero1. Served to the MCP via GitHub raw; not published on the docs site. +--- + +# Subscribe to shreds (Edge) — runbook + +This page is for the DoubleZero MCP (`get_onboarding_runbook`) via GitHub raw. It is +not published on the docs site. + +1. Connect the [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Tell it the Linux host that will **receive** shreds (or SSH), the wallet/keypair for `doublezero-solana`, and which feed (leader vs retransmit). +3. Walk the steps below in order. Human guide: [Edge Subscriber Connection](Edge Subscriber Connection.md). + +**What success looks like:** seat allocated for the current epoch, `doublezero status` shows the tunnel up, UDP shreds on `doublezero1` port `7733` (leader group `233.84.178.1`). + +By connecting, the user agrees to the [DoubleZero Terms of Use](https://doublezero.xyz/terms-protocol). Data is for internal use and may not be retransmitted. + +--- + +## Prerequisites + +| Need | Notes | +|------|--------| +| Linux/amd64 host | Public IPv4, no NAT. On AWS: disable ENI source/dest check. | +| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | +| Wallet | `~/.config/solana/id.json` (or `--keypair`). Needs **SOL** (fees) + **USDC** (seat escrow). | +| USDC mint | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | +| Firewall | GRE, BGP (`169.254.0.0/16` tcp/179), PIM, UDP `7733` on `doublezero1`, UDP `44880` on `doublezero0`. | + +--- + +## Steps + +### 1. Install client + packages + +Follow [setup](setup.md), then: + +```bash +sudo apt update && sudo apt install doublezero-solana +``` + +Back up `~/.config/doublezero/id.json`. + +### 2. Firewall + +```bash +sudo iptables -A OUTPUT -p gre -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +UFW variants: human guide. + +### 3. Enable the reconciler + +Required so seats auto-provision the tunnel. + +```bash +doublezero enable +``` + +### 4. Wallet + +```bash +solana-keygen new # if needed — writes ~/.config/solana/id.json; back it up +solana address +``` + +Fund SOL and USDC. + +### 5. Pick device + price + +```bash +doublezero latency +doublezero-solana shreds price +doublezero-solana shreds price --device-code +``` + +Note lowest-latency **device code** and epoch price (base + premium). Prefer funding **>1 epoch**. Pricing UI: [devices](https://data.doublezero.xyz/dz/shreds/devices). + +### 6. Buy a seat (blocking) + +On the receiving host: + +```bash +curl -4 -s ifconfig.me; echo +``` + +```bash +doublezero-solana shreds pay \ + --device-code \ + --client-ip \ + --amount +``` + +`--client-ip` must be the public IPv4 of the machine that will receive shreds. `--amount` is USDC decimal (e.g. `100`) and must meet the epoch price. + +If less than 10% of the epoch remains, the CLI warns. `--accept-partial-epoch` takes the remainder now; otherwise wait. Underfunded escrow at settlement → seat gone, tunnel torn down, **tenure lost**. + +Once allocated, the daemon brings the GRE tunnel up. + +```bash +doublezero status +doublezero-solana shreds list +``` + +### 7. Confirm shreds + +Leader shreds: `233.84.178.1:7733` on `doublezero1`. Discover groups with `doublezero multicast group list`. + +| Feed | Group | Address | +|------|-------|---------| +| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | +| Root | `edge-solana-root` | `233.84.178.16:7733` | +| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +Port `5765` is a publisher heartbeat — not shreds. Traffic is GRE-encapsulated; some pipelines (XDP deshredders) must strip GRE. + +```bash +sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 +``` + +--- + +## Gotchas + +1. **Reconciler off.** Without `doublezero enable`, paying does not bring the tunnel up. +2. **`--client-ip` ≠ daemon IP.** Auto-discovery must match the seat. +3. **`Multicast user already exists`.** Disconnect first: `doublezero disconnect`, then retry `shreds pay`. +4. **Amount below current price.** Re-check `shreds price` and increase `--amount`. +5. **Seat not allocated after pay.** Late epoch (next epoch), device full (higher tenure), or withdraw before settlement. +6. **Keep escrow funded.** Top up with another `shreds pay`; do not let balance drop below epoch price. + +--- + +## See also + +- [Edge Subscriber Connection](Edge Subscriber Connection.md) +- [Support](support.md) +- Scoreboard / seats: [data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) diff --git a/mkdocs.yml b/mkdocs.yml index 9fc9210..e040b16 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,6 +4,13 @@ site_description: >- Documentation for connecting to and operating on the Malbec Labs / DoubleZero network — validator and tenant setup, multicast, rewards, geolocation, and contributor operations. +# Machine-oriented runbooks stay in git for MCP / GitHub raw, but are not built +# into the public docs site. +exclude_docs: | + runbooks.md + solana-ibrl-runbook.md + solana-shreds-runbook.md + solana-shreds-publisher-runbook.md theme: name: material custom_dir: overrides From 63e2108864d328202bf6ffcb703318cc1cb9c42b Mon Sep 17 00:00:00 2001 From: Jotatavo <100889564+Jotatavo@users.noreply.github.com> Date: Wed, 12 Aug 2026 08:39:50 -0300 Subject: [PATCH 2/5] Restore the original runbooks index description. --- docs/runbooks.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/runbooks.md b/docs/runbooks.md index 49fcc56..1eb4b09 100644 --- a/docs/runbooks.md +++ b/docs/runbooks.md @@ -1,5 +1,7 @@ --- -description: Machine-readable index of onboarding runbooks for the DoubleZero MCP. Not published on the docs site. +description: Machine-readable index of onboarding runbooks for the DoubleZero MCP. Not linked in the docs nav. +search: + exclude: true --- # Runbooks From 5bd567447cb7fa7bbe7057ee94b9cd122e9d5ede Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 12 Aug 2026 11:52:14 +0000 Subject: [PATCH 3/5] chore: auto-translate docs --- docs/runbooks.es.md | 24 ++++ docs/runbooks.fr.md | 24 ++++ docs/runbooks.it.md | 24 ++++ docs/runbooks.ja.md | 23 +++ docs/runbooks.ko.md | 23 +++ docs/runbooks.pt.md | 24 ++++ docs/runbooks.zh.md | 23 +++ docs/solana-ibrl-runbook.es.md | 159 ++++++++++++++++++++ docs/solana-ibrl-runbook.fr.md | 160 +++++++++++++++++++++ docs/solana-ibrl-runbook.it.md | 160 +++++++++++++++++++++ docs/solana-ibrl-runbook.ja.md | 159 ++++++++++++++++++++ docs/solana-ibrl-runbook.ko.md | 159 ++++++++++++++++++++ docs/solana-ibrl-runbook.pt.md | 160 +++++++++++++++++++++ docs/solana-ibrl-runbook.zh.md | 159 ++++++++++++++++++++ docs/solana-shreds-publisher-runbook.es.md | 88 ++++++++++++ docs/solana-shreds-publisher-runbook.fr.md | 88 ++++++++++++ docs/solana-shreds-publisher-runbook.it.md | 88 ++++++++++++ docs/solana-shreds-publisher-runbook.ja.md | 87 +++++++++++ docs/solana-shreds-publisher-runbook.ko.md | 87 +++++++++++ docs/solana-shreds-publisher-runbook.pt.md | 88 ++++++++++++ docs/solana-shreds-publisher-runbook.zh.md | 87 +++++++++++ docs/solana-shreds-runbook.es.md | 144 +++++++++++++++++++ docs/solana-shreds-runbook.fr.md | 145 +++++++++++++++++++ docs/solana-shreds-runbook.it.md | 145 +++++++++++++++++++ docs/solana-shreds-runbook.ja.md | 144 +++++++++++++++++++ docs/solana-shreds-runbook.ko.md | 144 +++++++++++++++++++ docs/solana-shreds-runbook.pt.md | 145 +++++++++++++++++++ docs/solana-shreds-runbook.zh.md | 144 +++++++++++++++++++ 28 files changed, 2905 insertions(+) create mode 100644 docs/runbooks.es.md create mode 100644 docs/runbooks.fr.md create mode 100644 docs/runbooks.it.md create mode 100644 docs/runbooks.ja.md create mode 100644 docs/runbooks.ko.md create mode 100644 docs/runbooks.pt.md create mode 100644 docs/runbooks.zh.md create mode 100644 docs/solana-ibrl-runbook.es.md create mode 100644 docs/solana-ibrl-runbook.fr.md create mode 100644 docs/solana-ibrl-runbook.it.md create mode 100644 docs/solana-ibrl-runbook.ja.md create mode 100644 docs/solana-ibrl-runbook.ko.md create mode 100644 docs/solana-ibrl-runbook.pt.md create mode 100644 docs/solana-ibrl-runbook.zh.md create mode 100644 docs/solana-shreds-publisher-runbook.es.md create mode 100644 docs/solana-shreds-publisher-runbook.fr.md create mode 100644 docs/solana-shreds-publisher-runbook.it.md create mode 100644 docs/solana-shreds-publisher-runbook.ja.md create mode 100644 docs/solana-shreds-publisher-runbook.ko.md create mode 100644 docs/solana-shreds-publisher-runbook.pt.md create mode 100644 docs/solana-shreds-publisher-runbook.zh.md create mode 100644 docs/solana-shreds-runbook.es.md create mode 100644 docs/solana-shreds-runbook.fr.md create mode 100644 docs/solana-shreds-runbook.it.md create mode 100644 docs/solana-shreds-runbook.ja.md create mode 100644 docs/solana-shreds-runbook.ko.md create mode 100644 docs/solana-shreds-runbook.pt.md create mode 100644 docs/solana-shreds-runbook.zh.md diff --git a/docs/runbooks.es.md b/docs/runbooks.es.md new file mode 100644 index 0000000..1212702 --- /dev/null +++ b/docs/runbooks.es.md @@ -0,0 +1,24 @@ +--- +description: Índice legible por máquinas de runbooks de incorporación para el DoubleZero MCP. No está vinculado en la navegación de la documentación. +search: + exclude: true +--- + +# Runbooks + +El DoubleZero MCP carga este archivo desde GitHub raw +(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`) +para descubrir guías paso a paso. Los usuarios utilizan [Conecta tu IA](mcp.md); no agregue esta +página a la navegación del sitio. + +Para registrar un runbook, agregue un elemento de lista bajo **Índice** con esta estructura: + +```markdown +- `service-id` — [Título legible](page-slug.md) +``` + +## Índice + +- `solana-ibrl` — [Conectar validador (IBRL Mainnet)](solana-ibrl-runbook.md) +- `solana-shreds-publisher` — [Publicar shreds (Edge)](solana-shreds-publisher-runbook.md) +- `solana-shreds` — [Suscribirse a shreds (Edge)](solana-shreds-runbook.md) \ No newline at end of file diff --git a/docs/runbooks.fr.md b/docs/runbooks.fr.md new file mode 100644 index 0000000..3521b9e --- /dev/null +++ b/docs/runbooks.fr.md @@ -0,0 +1,24 @@ +--- +description: Index lisible par machine des runbooks d'intégration pour le MCP DoubleZero. Non lié dans la navigation de la documentation. +search: + exclude: true +--- + +# Runbooks + +Le MCP DoubleZero charge ce fichier depuis GitHub raw +(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`) +pour découvrir les guides pas à pas. Les utilisateurs consultent [Connecter votre IA](mcp.md) ; n'ajoutez pas cette +page à la navigation du site. + +Pour enregistrer un runbook, ajoutez un élément de liste sous **Index** dans ce format : + +```markdown +- `service-id` — [Titre lisible](page-slug.md) +``` + +## Index + +- `solana-ibrl` — [Connecter un validateur (IBRL Mainnet)](solana-ibrl-runbook.md) +- `solana-shreds-publisher` — [Publier des shreds (Edge)](solana-shreds-publisher-runbook.md) +- `solana-shreds` — [S'abonner aux shreds (Edge)](solana-shreds-runbook.md) \ No newline at end of file diff --git a/docs/runbooks.it.md b/docs/runbooks.it.md new file mode 100644 index 0000000..47489d1 --- /dev/null +++ b/docs/runbooks.it.md @@ -0,0 +1,24 @@ +--- +description: Indice leggibile dalle macchine dei runbook di onboarding per il DoubleZero MCP. Non collegato nella navigazione della documentazione. +search: + exclude: true +--- + +# Runbook + +Il DoubleZero MCP carica questo file dal raw di GitHub +(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`) +per individuare le procedure guidate. Gli utenti utilizzano [Connetti la tua AI](mcp.md); non aggiungere questa +pagina alla navigazione del sito. + +Per registrare un runbook, aggiungi un elemento alla lista sotto **Indice** con questa struttura: + +```markdown +- `service-id` — [Titolo leggibile](page-slug.md) +``` + +## Indice + +- `solana-ibrl` — [Connetti il validatore (IBRL Mainnet)](solana-ibrl-runbook.md) +- `solana-shreds-publisher` — [Pubblica shreds (Edge)](solana-shreds-publisher-runbook.md) +- `solana-shreds` — [Iscriviti agli shreds (Edge)](solana-shreds-runbook.md) \ No newline at end of file diff --git a/docs/runbooks.ja.md b/docs/runbooks.ja.md new file mode 100644 index 0000000..3690a20 --- /dev/null +++ b/docs/runbooks.ja.md @@ -0,0 +1,23 @@ +--- +description: DoubleZero MCP のオンボーディングランブックの機械可読インデックス。ドキュメントナビゲーションにはリンクされていません。 +search: + exclude: true +--- + +# ランブック + +DoubleZero MCP は GitHub raw からこのファイルを読み込みます +(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`)。 +これによりウォークスルーを検出します。人間の方は [AI を接続する](mcp.md) をご利用ください。このページをサイトナビゲーションに追加しないでください。 + +ランブックを登録するには、**Index** の下に以下の形式でリスト項目を追加してください： + +```markdown +- `service-id` — [Human title](page-slug.md) +``` + +## インデックス + +- `solana-ibrl` — [バリデーターを接続する (IBRL Mainnet)](solana-ibrl-runbook.md) +- `solana-shreds-publisher` — [シュレッドを公開する (Edge)](solana-shreds-publisher-runbook.md) +- `solana-shreds` — [シュレッドを購読する (Edge)](solana-shreds-runbook.md) \ No newline at end of file diff --git a/docs/runbooks.ko.md b/docs/runbooks.ko.md new file mode 100644 index 0000000..8af7593 --- /dev/null +++ b/docs/runbooks.ko.md @@ -0,0 +1,23 @@ +--- +description: DoubleZero MCP용 온보딩 런북의 기계 판독 가능 인덱스. 문서 탐색에 링크되지 않습니다. +search: + exclude: true +--- + +# 런북 + +DoubleZero MCP는 GitHub raw에서 이 파일을 로드합니다 +(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`) +워크스루를 검색하기 위해 사용됩니다. 사용자는 [AI 연결하기](mcp.md)를 이용하세요; 이 페이지를 사이트 탐색에 추가하지 마세요. + +런북을 등록하려면 **인덱스** 아래에 다음 형식으로 목록 항목을 추가하세요: + +```markdown +- `service-id` — [사람이 읽을 수 있는 제목](page-slug.md) +``` + +## 인덱스 + +- `solana-ibrl` — [밸리데이터 연결 (IBRL Mainnet)](solana-ibrl-runbook.md) +- `solana-shreds-publisher` — [Shreds 발행 (Edge)](solana-shreds-publisher-runbook.md) +- `solana-shreds` — [Shreds 구독 (Edge)](solana-shreds-runbook.md) \ No newline at end of file diff --git a/docs/runbooks.pt.md b/docs/runbooks.pt.md new file mode 100644 index 0000000..7b380f3 --- /dev/null +++ b/docs/runbooks.pt.md @@ -0,0 +1,24 @@ +--- +description: Índice legível por máquina de runbooks de integração para o DoubleZero MCP. Não vinculado na navegação da documentação. +search: + exclude: true +--- + +# Runbooks + +O DoubleZero MCP carrega este arquivo a partir do GitHub raw +(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`) +para descobrir tutoriais passo a passo. Humanos usam [Conecte sua IA](mcp.md); não adicione esta +página à navegação do site. + +Para registrar um runbook, adicione um item de lista em **Índice** neste formato: + +```markdown +- `service-id` — [Título legível](page-slug.md) +``` + +## Índice + +- `solana-ibrl` — [Conectar validador (IBRL Mainnet)](solana-ibrl-runbook.md) +- `solana-shreds-publisher` — [Publicar shreds (Edge)](solana-shreds-publisher-runbook.md) +- `solana-shreds` — [Inscrever-se em shreds (Edge)](solana-shreds-runbook.md) \ No newline at end of file diff --git a/docs/runbooks.zh.md b/docs/runbooks.zh.md new file mode 100644 index 0000000..27c65de --- /dev/null +++ b/docs/runbooks.zh.md @@ -0,0 +1,23 @@ +--- +description: DoubleZero MCP 入门运行手册的机器可读索引。未在文档导航中链接。 +search: + exclude: true +--- + +# 运行手册 + +DoubleZero MCP 从 GitHub raw 加载此文件 +(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`) +以发现操作指南。用户请使用 [连接你的 AI](mcp.md)；请勿将此页面添加到站点导航中。 + +要注册一个运行手册，请在 **索引** 下按以下格式添加一个列表项： + +```markdown +- `service-id` — [Human title](page-slug.md) +``` + +## 索引 + +- `solana-ibrl` — [连接验证者（IBRL 主网）](solana-ibrl-runbook.md) +- `solana-shreds-publisher` — [发布 shreds（Edge）](solana-shreds-publisher-runbook.md) +- `solana-shreds` — [订阅 shreds（Edge）](solana-shreds-runbook.md) \ No newline at end of file diff --git a/docs/solana-ibrl-runbook.es.md b/docs/solana-ibrl-runbook.es.md new file mode 100644 index 0000000..18acbab --- /dev/null +++ b/docs/solana-ibrl-runbook.es.md @@ -0,0 +1,159 @@ +--- +description: Runbook orientado a LLM — conectar un validador de Solana Mainnet-Beta a DoubleZero en modo IBRL. Servido al MCP a través de GitHub raw; no se publica en el sitio de documentación. +--- + +# Conectar validador (IBRL Mainnet) — runbook + +Esta página es para el MCP de DoubleZero (`get_onboarding_runbook`) a través de GitHub raw. No se publica en el sitio de documentación. + +1. Conecta el [MCP de DoubleZero](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Indícale que se trata de un **validador de Solana Mainnet-Beta**, el host Linux (o SSH), y dónde se encuentra el keypair de identidad del validador. +3. Sigue los pasos a continuación en orden. ¿Prefieres hacerlo manualmente? Usa la [guía para humanos](DZ Mainnet-beta Connection.md). + +**Cómo se ve el éxito:** `doublezero status` muestra el túnel **up**, User Type **IBRL**, Network **mainnet-beta**. `Tunnel src` y `Doublezero IP` coinciden con la IPv4 pública del host. + +IBRL no requiere reiniciar los clientes del validador; utiliza la IP pública existente. + +--- + +## Requisitos previos + +| Necesario | Notas | +|------|--------| +| Host Linux/amd64 | Instala DoubleZero **en el host del validador**, no en un contenedor. | +| IPv4 pública, sin NAT | La IP de gossip debe coincidir con este host. | +| Solana CLI en `$PATH` | Para `solana sign-offchain-message`. | +| Keypair de identidad del validador | Legible por el usuario que ejecuta los comandos (a menudo bajo el usuario `sol`). | +| ≥1 SOL en la identidad | Passport / solicitud onchain. | +| GRE (protocolo IP 47) + BGP | BGP en `169.254.0.0/16` tcp/179. | +| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` (o equivalente de la distribución). | + +El Validator ID se verifica contra el gossip de Solana para determinar la IP de destino. Un ID inválido en la misma IP se ignora; solo se utiliza el ID primario en gossip. + +--- + +## Pasos + +### 1. Instalar el cliente + +Sigue [setup](setup.md) si `doublezero` no está instalado. Paquetes para mainnet: + +```bash +curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash +sudo apt-get install doublezero +``` + +Rocky / RHEL: usa `setup.rpm.sh` y `sudo yum install doublezero`. + +**Verificar:** `sudo systemctl status doublezerod` está activo. Haz una copia de seguridad de `~/.config/doublezero/id.json`. + +### 2. Apuntar el daemon a mainnet-beta + +```bash +DESIRED_DOUBLEZERO_ENV=mainnet-beta \ + && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ + && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ + && sudo systemctl daemon-reload \ + && sudo systemctl restart doublezerod \ + && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ + && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" +``` + +Espera ~30s, luego `doublezero latency` debería listar los dispositivos de mainnet. + +### 3. Abrir UDP 44880 en `doublezero0` + +```bash +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +UFW: `sudo ufw allow in on doublezero0 to any port 44880 proto udp` y la regla `out` correspondiente. También permite GRE y BGP como se indica en [setup](setup.md). + +### 4. Confirmar el ID de DoubleZero y el validador primario + +El ID de DoubleZero del setup en el **primario** debe estar en cada respaldo (`~/.config/doublezero/id.json`). + +```bash +doublezero address +doublezero-solana passport find-validator -u mainnet-beta +``` + +Se espera del primario: en gossip, en el leader schedule, "can connect as a primary". En los respaldos, ejecuta el mismo `find-validator`; **no** deberían estar programados como leader. + +Si solo hay una máquina: omite `--backup-validator-ids` / `backup_ids=` en los comandos posteriores. + +### 5. Preparar el mensaje de acceso (primario) + +En el primario (con stake activo, identidad en gossip): + +```bash +doublezero-solana passport prepare-validator-access -u mainnet-beta \ + --doublezero-address \ + --primary-validator-id \ + --backup-validator-ids ,, +``` + +Omite `--backup-validator-ids` si no hay respaldos (máximo 3). Copia la línea `solana sign-offchain-message …` de la salida. + +### 6. Firmar con la clave de identidad del validador + +En el primario, ejecuta el comando impreso (keypair de identidad, **no** solo la clave de DoubleZero): + +```bash +solana sign-offchain-message \ + service_key=,backup_ids=,, \ + -k +``` + +**Produce:** una cadena de firma. Llévala al siguiente paso. + +### 7. Solicitar acceso de validador + +```bash +doublezero-solana passport request-validator-access -k -u mainnet-beta \ + --primary-validator-id \ + --backup-validator-ids ,, \ + --signature \ + --doublezero-address +``` + +Espera a que Sentinel valide y cree el pase de acceso. Opcional: el agente puede llamar a **`check_edge_access`** con `pubkey` (`doublezero address`) y la IP pública del host hasta que el pase esté presente. + +### 8. Conectar IBRL + +```bash +doublezero connect ibrl +``` + +Espera ~1 minuto para GRE. Hasta entonces, el estado puede ser `down` / `Unknown`. + +```bash +doublezero status +``` + +**Correcto:** `up`, User Type `IBRL`, Network `mainnet-beta`, túnel típicamente `doublezero0`. + +```bash +ip route +``` + +Se esperan rutas aprendidas por BGP a través de `doublezero0`. + +--- + +## Problemas comunes + +1. **Entorno incorrecto.** Los paquetes de testnet / `DESIRED_DOUBLEZERO_ENV=testnet` no funcionarán en mainnet-beta. +2. **La identidad no está en gossip.** Los IDs inválidos en la misma IP no pueden registrar la máquina. +3. **Los respaldos deben compartir el ID de DoubleZero del primario.** Copia `id.json`; no generes una segunda identidad con keygen. +4. **Firma con la identidad del validador**, no con la clave de DoubleZero. +5. **Estado down durante ~1 minuto** después de `connect ibrl` es normal mientras GRE se establece. + +--- + +## Ver también + +- [Conexión de Validador a Mainnet-Beta](DZ Mainnet-beta Connection.md) +- [Setup](setup.md) +- Siguiente: [Publicar shreds (Edge)](solana-shreds-publisher-runbook.md) \ No newline at end of file diff --git a/docs/solana-ibrl-runbook.fr.md b/docs/solana-ibrl-runbook.fr.md new file mode 100644 index 0000000..a8e03d8 --- /dev/null +++ b/docs/solana-ibrl-runbook.fr.md @@ -0,0 +1,160 @@ +--- +description: Runbook orienté LLM — connecter un validateur Solana Mainnet-Beta à DoubleZero en mode IBRL. Servi au MCP via GitHub raw ; non publié sur le site de documentation. +--- + +# Connecter un validateur (IBRL Mainnet) — runbook + +Cette page est destinée au DoubleZero MCP (`get_onboarding_runbook`) via GitHub raw. Elle n'est +pas publiée sur le site de documentation. + +1. Connectez le [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Indiquez-lui qu'il s'agit d'un **validateur Solana Mainnet-Beta**, l'hôte Linux (ou SSH), et l'emplacement du keypair d'identité du validateur. +3. Suivez les étapes ci-dessous dans l'ordre. Vous préférez le faire manuellement ? Utilisez le [guide pour humains](DZ Mainnet-beta Connection.md). + +**À quoi ressemble le succès :** `doublezero status` affiche le tunnel **up**, User Type **IBRL**, Network **mainnet-beta**. `Tunnel src` et `Doublezero IP` correspondent à l'IPv4 publique de l'hôte. + +IBRL ne nécessite pas de redémarrer les clients validateurs ; il utilise l'IP publique existante. + +--- + +## Prérequis + +| Besoin | Notes | +|--------|--------| +| Hôte Linux/amd64 | Installez DoubleZero **sur l'hôte du validateur**, pas dans un conteneur. | +| IPv4 publique, pas de NAT | L'IP de gossip doit correspondre à cet hôte. | +| Solana CLI dans le `$PATH` | Pour `solana sign-offchain-message`. | +| Keypair d'identité du validateur | Lisible par l'utilisateur exécutant les commandes (souvent sous l'utilisateur `sol`). | +| ≥1 SOL sur l'identité | Passport / requête onchain. | +| GRE (protocole IP 47) + BGP | BGP sur `169.254.0.0/16` tcp/179. | +| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` (ou équivalent pour votre distribution). | + +Le Validator ID est vérifié par rapport au gossip Solana pour déterminer l'IP cible. Un ID invalide sur la même IP est ignoré ; seul l'ID principal dans le gossip est utilisé. + +--- + +## Étapes + +### 1. Installer le client + +Suivez [setup](setup.md) si `doublezero` n'est pas installé. Paquets mainnet : + +```bash +curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash +sudo apt-get install doublezero +``` + +Rocky / RHEL : utilisez `setup.rpm.sh` et `sudo yum install doublezero`. + +**Vérification :** `sudo systemctl status doublezerod` est actif. Sauvegardez `~/.config/doublezero/id.json`. + +### 2. Pointer le daemon vers mainnet-beta + +```bash +DESIRED_DOUBLEZERO_ENV=mainnet-beta \ + && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ + && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ + && sudo systemctl daemon-reload \ + && sudo systemctl restart doublezerod \ + && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ + && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" +``` + +Attendez ~30s, puis `doublezero latency` devrait lister les appareils mainnet. + +### 3. Ouvrir le port UDP 44880 sur `doublezero0` + +```bash +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +UFW : `sudo ufw allow in on doublezero0 to any port 44880 proto udp` et la règle `out` correspondante. Autorisez également GRE et BGP comme indiqué dans [setup](setup.md). + +### 4. Confirmer l'ID DoubleZero et le validateur principal + +L'ID DoubleZero issu du setup sur le **principal** doit être présent sur chaque backup (`~/.config/doublezero/id.json`). + +```bash +doublezero address +doublezero-solana passport find-validator -u mainnet-beta +``` + +Résultat attendu pour le principal : présent dans le gossip, dans le planning de leader, "can connect as a primary". Sur les backups, exécutez le même `find-validator` ; ils ne devraient **pas** être dans le planning de leader. + +Machine unique : omettez `--backup-validator-ids` / `backup_ids=` des commandes suivantes. + +### 5. Préparer le message d'accès (principal) + +Sur le principal (stake actif, identité dans le gossip) : + +```bash +doublezero-solana passport prepare-validator-access -u mainnet-beta \ + --doublezero-address \ + --primary-validator-id \ + --backup-validator-ids ,, +``` + +Omettez `--backup-validator-ids` s'il n'y a pas de backups (max 3). Copiez la ligne `solana sign-offchain-message …` depuis la sortie. + +### 6. Signer avec la clé d'identité du validateur + +Sur le principal, exécutez la commande affichée (keypair d'identité, **pas** uniquement la clé DoubleZero) : + +```bash +solana sign-offchain-message \ + service_key=,backup_ids=,, \ + -k +``` + +**Produit :** une chaîne de signature. Conservez-la pour l'étape suivante. + +### 7. Demander l'accès validateur + +```bash +doublezero-solana passport request-validator-access -k -u mainnet-beta \ + --primary-validator-id \ + --backup-validator-ids ,, \ + --signature \ + --doublezero-address +``` + +Attendez que Sentinel valide et crée le pass d'accès. Optionnel : l'agent peut appeler **`check_edge_access`** avec `pubkey` (`doublezero address`) et l'IP publique de l'hôte jusqu'à ce que le pass soit présent. + +### 8. Connecter IBRL + +```bash +doublezero connect ibrl +``` + +Attendez ~1 minute pour le GRE. Jusque-là, le statut peut être `down` / `Unknown`. + +```bash +doublezero status +``` + +**Succès :** `up`, User Type `IBRL`, Network `mainnet-beta`, tunnel typiquement `doublezero0`. + +```bash +ip route +``` + +Attendez-vous à voir des routes apprises par BGP via `doublezero0`. + +--- + +## Pièges courants + +1. **Mauvais environnement.** Les paquets testnet / `DESIRED_DOUBLEZERO_ENV=testnet` ne fonctionneront pas sur mainnet-beta. +2. **Identité absente du gossip.** Les IDs invalides sur la même IP ne peuvent pas enregistrer la machine. +3. **Les backups doivent partager l'ID DoubleZero du principal.** Copiez `id.json` ; ne générez pas une seconde identité avec keygen. +4. **Signez avec l'identité du validateur**, pas avec la clé DoubleZero. +5. **Statut down pendant ~1 minute** après `connect ibrl` est normal pendant que le GRE s'établit. + +--- + +## Voir aussi + +- [Connexion Validateur Mainnet-Beta](DZ Mainnet-beta Connection.md) +- [Setup](setup.md) +- Suivant : [Publier des shreds (Edge)](solana-shreds-publisher-runbook.md) \ No newline at end of file diff --git a/docs/solana-ibrl-runbook.it.md b/docs/solana-ibrl-runbook.it.md new file mode 100644 index 0000000..3a95838 --- /dev/null +++ b/docs/solana-ibrl-runbook.it.md @@ -0,0 +1,160 @@ +--- +description: Runbook orientato agli LLM — collegare un validatore Solana Mainnet-Beta a DoubleZero in modalità IBRL. Fornito all'MCP tramite GitHub raw; non pubblicato sul sito della documentazione. +--- + +# Collegare un validatore (IBRL Mainnet) — runbook + +Questa pagina è destinata al DoubleZero MCP (`get_onboarding_runbook`) tramite GitHub raw. Non è +pubblicata sul sito della documentazione. + +1. Collegare il [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Indicare che si tratta di un **validatore Solana Mainnet-Beta**, l'host Linux (o SSH) e dove si trova il keypair dell'identità del validatore. +3. Seguire i passaggi sottostanti in ordine. Si preferisce procedere manualmente? Utilizzare la [guida per operatori](DZ Mainnet-beta Connection.md). + +**Come si presenta il successo:** `doublezero status` mostra il tunnel **up**, User Type **IBRL**, Network **mainnet-beta**. `Tunnel src` e `Doublezero IP` corrispondono all'IPv4 pubblico dell'host. + +IBRL non richiede il riavvio dei client del validatore; utilizza l'IP pubblico esistente. + +--- + +## Prerequisiti + +| Necessario | Note | +|------|--------| +| Host Linux/amd64 | Installare DoubleZero **sull'host del validatore**, non in un container. | +| IPv4 pubblico, senza NAT | L'IP di gossip deve corrispondere a questo host. | +| Solana CLI nel `$PATH` | Per `solana sign-offchain-message`. | +| Keypair dell'identità del validatore | Leggibile dall'utente che esegue i comandi (spesso sotto l'utente `sol`). | +| ≥1 SOL sull'identità | Passport / richiesta onchain. | +| GRE (protocollo IP 47) + BGP | BGP su `169.254.0.0/16` tcp/179. | +| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` (o equivalente per la distribuzione). | + +L'ID del Validatore viene verificato rispetto al gossip di Solana per determinare l'IP di destinazione. Un ID fasullo sullo stesso IP viene ignorato; solo l'ID primario nel gossip viene utilizzato. + +--- + +## Passaggi + +### 1. Installare il client + +Seguire [setup](setup.md) se `doublezero` non è installato. Pacchetti mainnet: + +```bash +curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash +sudo apt-get install doublezero +``` + +Rocky / RHEL: utilizzare `setup.rpm.sh` e `sudo yum install doublezero`. + +**Verifica:** `sudo systemctl status doublezerod` è attivo. Effettuare un backup di `~/.config/doublezero/id.json`. + +### 2. Configurare il daemon per mainnet-beta + +```bash +DESIRED_DOUBLEZERO_ENV=mainnet-beta \ + && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ + && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ + && sudo systemctl daemon-reload \ + && sudo systemctl restart doublezerod \ + && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ + && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" +``` + +Attendere ~30 secondi, poi `doublezero latency` dovrebbe elencare i dispositivi mainnet. + +### 3. Aprire la porta UDP 44880 su `doublezero0` + +```bash +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +UFW: `sudo ufw allow in on doublezero0 to any port 44880 proto udp` e la corrispondente regola `out`. Consentire anche GRE e BGP come indicato in [setup](setup.md). + +### 4. Confermare l'ID DoubleZero e il validatore primario + +L'ID DoubleZero dal setup sul **primario** deve essere presente su ogni backup (`~/.config/doublezero/id.json`). + +```bash +doublezero address +doublezero-solana passport find-validator -u mainnet-beta +``` + +Aspettarsi il primario: presente nel gossip, nella schedule dei leader, "can connect as a primary". Sui backup, eseguire lo stesso `find-validator`; **non** dovrebbero essere nella schedule dei leader. + +Una sola macchina: omettere `--backup-validator-ids` / `backup_ids=` dai comandi successivi. + +### 5. Preparare il messaggio di accesso (primario) + +Sul primario (stake attivo, identità nel gossip): + +```bash +doublezero-solana passport prepare-validator-access -u mainnet-beta \ + --doublezero-address \ + --primary-validator-id \ + --backup-validator-ids ,, +``` + +Omettere `--backup-validator-ids` se non ci sono backup (massimo 3). Copiare la riga `solana sign-offchain-message …` dall'output. + +### 6. Firmare con la chiave di identità del validatore + +Sul primario, eseguire il comando stampato (keypair dell'identità, **non** solo la chiave DoubleZero): + +```bash +solana sign-offchain-message \ + service_key=,backup_ids=,, \ + -k +``` + +**Produce:** una stringa di firma. Portarla nel passaggio successivo. + +### 7. Richiedere l'accesso validatore + +```bash +doublezero-solana passport request-validator-access -k -u mainnet-beta \ + --primary-validator-id \ + --backup-validator-ids ,, \ + --signature \ + --doublezero-address +``` + +Attendere che Sentinel validi e crei il pass di accesso. Facoltativo: l'agente può chiamare **`check_edge_access`** con `pubkey` (`doublezero address`) e l'IP pubblico dell'host finché il pass non è presente. + +### 8. Connettere IBRL + +```bash +doublezero connect ibrl +``` + +Attendere ~1 minuto per il GRE. Fino ad allora, lo stato potrebbe essere `down` / `Unknown`. + +```bash +doublezero status +``` + +**Superato:** `up`, User Type `IBRL`, Network `mainnet-beta`, tunnel tipicamente `doublezero0`. + +```bash +ip route +``` + +Aspettarsi route apprese tramite BGP via `doublezero0`. + +--- + +## Insidie comuni + +1. **Ambiente errato.** Pacchetti testnet / `DESIRED_DOUBLEZERO_ENV=testnet` non funzioneranno su mainnet-beta. +2. **Identità non nel gossip.** ID fasulli sullo stesso IP non possono registrare la macchina. +3. **I backup devono condividere l'ID DoubleZero del primario.** Copiare `id.json`; non generare una seconda identità con keygen. +4. **Firmare con l'identità del validatore**, non con la chiave DoubleZero. +5. **Stato down per ~1 minuto** dopo `connect ibrl` è normale mentre il GRE si avvia. + +--- + +## Vedi anche + +- [Connessione Validatore Mainnet-Beta](DZ Mainnet-beta Connection.md) +- [Setup](setup.md) +- Successivo: [Pubblicare shred (Edge)](solana-shreds-publisher-runbook.md) \ No newline at end of file diff --git a/docs/solana-ibrl-runbook.ja.md b/docs/solana-ibrl-runbook.ja.md new file mode 100644 index 0000000..9b45914 --- /dev/null +++ b/docs/solana-ibrl-runbook.ja.md @@ -0,0 +1,159 @@ +--- +description: LLM向けランブック — Solana Mainnet-BetaバリデーターをIBRLモードでDoubleZeroに接続します。GitHub raw経由でMCPに提供されます。ドキュメントサイトには公開されません。 +--- + +# バリデーター接続 (IBRL Mainnet) — ランブック + +このページはDoubleZero MCP (`get_onboarding_runbook`) 向けにGitHub raw経由で提供されています。ドキュメントサイトには公開されません。 + +1. [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`) を接続します。 +2. これが **Solana Mainnet-Beta バリデーター** であること、Linuxホスト（またはSSH）、およびバリデーターIDキーペアの場所を伝えてください。 +3. 以下のステップを順番に実行してください。手動で行いたい場合は、[人間向けガイド](DZ Mainnet-beta Connection.md)を使用してください。 + +**成功の基準:** `doublezero status` でトンネルが **up**、User Type が **IBRL**、Network が **mainnet-beta** と表示されること。`Tunnel src` と `Doublezero IP` がホストのパブリックIPv4と一致すること。 + +IBRLはバリデータークライアントの再起動を必要としません。既存のパブリックIPを使用します。 + +--- + +## 前提条件 + +| 必要なもの | 備考 | +|------|--------| +| Linux/amd64 ホスト | DoubleZeroはコンテナ内ではなく、**バリデーターホスト上に**インストールしてください。 | +| パブリックIPv4、NATなし | ゴシップIPがこのホストと一致する必要があります。 | +| `$PATH` 上のSolana CLI | `solana sign-offchain-message` に必要です。 | +| バリデーターIDキーペア | コマンドを実行するユーザーが読み取り可能であること（多くの場合 `sol` ユーザー配下）。 | +| ID上に1 SOL以上 | パスポート / オンチェーンリクエスト用。 | +| GRE (IPプロトコル47) + BGP | BGPは `169.254.0.0/16` tcp/179。 | +| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana`（またはディストリビューション相当のコマンド）。 | + +バリデーターIDはSolanaゴシップと照合され、ターゲットIPが決定されます。同じIP上のダミーIDは無視されます。ゴシップ内のプライマリIDのみが使用されます。 + +--- + +## ステップ + +### 1. クライアントのインストール + +`doublezero` がインストールされていない場合は、[セットアップ](setup.md)に従ってください。Mainnetパッケージ： + +```bash +curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash +sudo apt-get install doublezero +``` + +Rocky / RHEL: `setup.rpm.sh` を使用し、`sudo yum install doublezero` を実行してください。 + +**確認:** `sudo systemctl status doublezerod` がactiveであること。`~/.config/doublezero/id.json` をバックアップしてください。 + +### 2. デーモンをmainnet-betaに向ける + +```bash +DESIRED_DOUBLEZERO_ENV=mainnet-beta \ + && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ + && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ + && sudo systemctl daemon-reload \ + && sudo systemctl restart doublezerod \ + && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ + && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" +``` + +約30秒待ってから、`doublezero latency` でmainnetデバイスが一覧表示されるはずです。 + +### 3. `doublezero0` でUDP 44880を開放する + +```bash +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +UFWの場合: `sudo ufw allow in on doublezero0 to any port 44880 proto udp` および対応する `out` ルール。[セットアップ](setup.md)に記載のとおり、GREとBGPも許可してください。 + +### 4. DoubleZero IDとプライマリバリデーターの確認 + +セットアップ時の DoubleZero ID は、**プライマリ**のものがすべてのバックアップにも存在する必要があります（`~/.config/doublezero/id.json`）。 + +```bash +doublezero address +doublezero-solana passport find-validator -u mainnet-beta +``` + +プライマリについて以下を確認してください：ゴシップに存在する、リーダースケジュールに含まれている、「can connect as a primary」であること。バックアップでは同じ `find-validator` を実行し、リーダースケジュールに含まれて**いない**ことを確認してください。 + +マシンが1台のみの場合：以降のコマンドで `--backup-validator-ids` / `backup_ids=` を省略してください。 + +### 5. アクセスメッセージの準備（プライマリ） + +プライマリ上で実行してください（アクティブなステーク、ゴシップ内にIDが存在）： + +```bash +doublezero-solana passport prepare-validator-access -u mainnet-beta \ + --doublezero-address \ + --primary-validator-id \ + --backup-validator-ids ,, +``` + +バックアップがない場合は `--backup-validator-ids` を省略してください（最大3つ）。出力から `solana sign-offchain-message …` の行をコピーしてください。 + +### 6. バリデーターIDキーで署名する + +プライマリ上で、出力されたコマンドを実行してください（IDキーペアを使用し、DoubleZeroキー**だけ**ではありません）： + +```bash +solana sign-offchain-message \ + service_key=,backup_ids=,, \ + -k +``` + +**出力:** 署名文字列。次のステップに使用してください。 + +### 7. バリデーターアクセスのリクエスト + +```bash +doublezero-solana passport request-validator-access -k -u mainnet-beta \ + --primary-validator-id \ + --backup-validator-ids ,, \ + --signature \ + --doublezero-address +``` + +Sentinelが検証しアクセスパスを作成するのを待ちます。オプション：エージェントは `pubkey`（`doublezero address`）とホストのパブリックIPを使用して、パスが存在するまで **`check_edge_access`** を呼び出すことができます。 + +### 8. IBRL接続 + +```bash +doublezero connect ibrl +``` + +GREが確立するまで約1分待ちます。それまでステータスは `down` / `Unknown` と表示される場合があります。 + +```bash +doublezero status +``` + +**合格:** `up`、User Type `IBRL`、Network `mainnet-beta`、トンネルは通常 `doublezero0`。 + +```bash +ip route +``` + +`doublezero0` 経由のBGPで学習されたルートが表示されるはずです。 + +--- + +## 注意事項 + +1. **環境の間違い。** テストネットパッケージ / `DESIRED_DOUBLEZERO_ENV=testnet` ではmainnet-betaに接続できません。 +2. **IDがゴシップに存在しない。** 同じIP上のダミーIDではマシンを登録できません。 +3. **バックアップはプライマリのDoubleZero IDを共有する必要があります。** `id.json` をコピーしてください。2つ目のIDをkeygenしないでください。 +4. **バリデーターIDで署名してください。** DoubleZeroキーではありません。 +5. **`connect ibrl` 後の約1分間のステータスdown** はGREが確立するまでの正常な動作です。 + +--- + +## 関連項目 + +- [バリデーター Mainnet-Beta 接続](DZ Mainnet-beta Connection.md) +- [セットアップ](setup.md) +- 次へ: [シュレッド公開 (Edge)](solana-shreds-publisher-runbook.md) \ No newline at end of file diff --git a/docs/solana-ibrl-runbook.ko.md b/docs/solana-ibrl-runbook.ko.md new file mode 100644 index 0000000..9226200 --- /dev/null +++ b/docs/solana-ibrl-runbook.ko.md @@ -0,0 +1,159 @@ +--- +description: LLM 지향 런북 — Solana Mainnet-Beta 밸리데이터를 IBRL 모드로 DoubleZero에 연결합니다. GitHub raw를 통해 MCP에 제공되며, 문서 사이트에는 게시되지 않습니다. +--- + +# 밸리데이터 연결 (IBRL Mainnet) — 런북 + +이 페이지는 GitHub raw를 통해 DoubleZero MCP(`get_onboarding_runbook`)용으로 작성되었습니다. 문서 사이트에는 게시되지 않습니다. + +1. [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`)를 연결합니다. +2. **Solana Mainnet-Beta 밸리데이터**, Linux 호스트(또는 SSH), 밸리데이터 아이덴티티 키페어의 위치를 알려줍니다. +3. 아래 단계를 순서대로 진행합니다. 수동으로 하고 싶으신가요? [사람용 가이드](DZ Mainnet-beta Connection.md)를 사용하세요. + +**성공 시 모습:** `doublezero status`에서 터널 **up**, User Type **IBRL**, Network **mainnet-beta**가 표시됩니다. `Tunnel src`와 `Doublezero IP`가 호스트의 공인 IPv4와 일치합니다. + +IBRL은 밸리데이터 클라이언트 재시작이 필요 없으며, 기존 공인 IP를 사용합니다. + +--- + +## 사전 요구 사항 + +| 필요 항목 | 참고 | +|------|--------| +| Linux/amd64 호스트 | DoubleZero를 컨테이너가 아닌 **밸리데이터 호스트에** 설치합니다. | +| 공인 IPv4, NAT 없음 | Gossip IP가 이 호스트와 일치해야 합니다. | +| `$PATH`에 Solana CLI | `solana sign-offchain-message`용. | +| 밸리데이터 아이덴티티 키페어 | 명령을 실행하는 사용자가 읽을 수 있어야 합니다(보통 `sol` 사용자 아래). | +| 아이덴티티에 ≥1 SOL | Passport / 온체인 요청용. | +| GRE (IP proto 47) + BGP | BGP는 `169.254.0.0/16` tcp/179에서. | +| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` (또는 배포판에 맞는 동등 명령). | + +Validator ID는 Solana gossip과 대조하여 대상 IP를 결정합니다. 같은 IP에 있는 잘못된 ID는 무시됩니다. gossip에 있는 기본 ID만 사용됩니다. + +--- + +## 단계 + +### 1. 클라이언트 설치 + +`doublezero`가 설치되지 않은 경우 [설정](setup.md)을 따르세요. Mainnet 패키지: + +```bash +curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash +sudo apt-get install doublezero +``` + +Rocky / RHEL: `setup.rpm.sh`와 `sudo yum install doublezero`를 사용합니다. + +**확인:** `sudo systemctl status doublezerod`가 active 상태입니다. `~/.config/doublezero/id.json`을 백업하세요. + +### 2. 데몬을 mainnet-beta로 설정 + +```bash +DESIRED_DOUBLEZERO_ENV=mainnet-beta \ + && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ + && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ + && sudo systemctl daemon-reload \ + && sudo systemctl restart doublezerod \ + && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ + && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" +``` + +약 30초 대기 후 `doublezero latency`에서 mainnet 장치 목록이 표시되어야 합니다. + +### 3. `doublezero0`에서 UDP 44880 열기 + +```bash +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +UFW: `sudo ufw allow in on doublezero0 to any port 44880 proto udp` 및 일치하는 `out` 규칙을 추가합니다. [설정](setup.md)에 따라 GRE 및 BGP도 허용하세요. + +### 4. DoubleZero ID 및 기본 밸리데이터 확인 + +설정 시 생성된 DoubleZero ID가 **기본** 머신의 것이어야 하며, 모든 백업에 동일하게 존재해야 합니다(`~/.config/doublezero/id.json`). + +```bash +doublezero address +doublezero-solana passport find-validator -u mainnet-beta +``` + +기본 밸리데이터에서 예상되는 결과: gossip에 존재, 리더 스케줄에 포함, "can connect as a primary". 백업에서 동일한 `find-validator`를 실행하면 리더 스케줄에 포함되지 **않아야** 합니다. + +단일 머신인 경우: 이후 명령에서 `--backup-validator-ids` / `backup_ids=`를 생략합니다. + +### 5. 접근 메시지 준비 (기본) + +기본 밸리데이터(활성 스테이크, gossip에 아이덴티티 있음)에서: + +```bash +doublezero-solana passport prepare-validator-access -u mainnet-beta \ + --doublezero-address \ + --primary-validator-id \ + --backup-validator-ids ,, +``` + +백업이 없는 경우 `--backup-validator-ids`를 생략합니다(최대 3개). 출력에서 `solana sign-offchain-message …` 줄을 복사합니다. + +### 6. 밸리데이터 아이덴티티 키로 서명 + +기본 밸리데이터에서 출력된 명령을 실행합니다(아이덴티티 키페어, DoubleZero 키만이 **아닙니다**): + +```bash +solana sign-offchain-message \ + service_key=,backup_ids=,, \ + -k +``` + +**결과:** 서명 문자열이 생성됩니다. 다음 단계로 가져가세요. + +### 7. 밸리데이터 접근 요청 + +```bash +doublezero-solana passport request-validator-access -k -u mainnet-beta \ + --primary-validator-id \ + --backup-validator-ids ,, \ + --signature \ + --doublezero-address +``` + +Sentinel이 검증하고 접근 패스를 생성할 때까지 대기합니다. 선택 사항: 에이전트가 패스가 존재할 때까지 `pubkey`(`doublezero address`)와 호스트 공인 IP로 **`check_edge_access`**를 호출할 수 있습니다. + +### 8. IBRL 연결 + +```bash +doublezero connect ibrl +``` + +GRE가 올라올 때까지 약 1분 대기합니다. 그때까지 상태가 `down` / `Unknown`일 수 있습니다. + +```bash +doublezero status +``` + +**통과 조건:** `up`, User Type `IBRL`, Network `mainnet-beta`, 터널은 일반적으로 `doublezero0`. + +```bash +ip route +``` + +`doublezero0`를 통한 BGP 학습 경로가 표시되어야 합니다. + +--- + +## 주의 사항 + +1. **잘못된 환경.** Testnet 패키지 / `DESIRED_DOUBLEZERO_ENV=testnet`으로는 mainnet-beta에 연결되지 않습니다. +2. **gossip에 아이덴티티 없음.** 같은 IP에 있는 잘못된 ID로는 머신을 등록할 수 없습니다. +3. **백업은 기본 DoubleZero ID를 공유해야 합니다.** `id.json`을 복사하세요. 두 번째 아이덴티티를 keygen하지 마세요. +4. **밸리데이터 아이덴티티로 서명하세요**, DoubleZero 키가 아닙니다. +5. `connect ibrl` 후 **약 1분간 상태 down**은 GRE가 올라오는 동안 정상입니다. + +--- + +## 참고 + +- [밸리데이터 Mainnet-Beta 연결](DZ Mainnet-beta Connection.md) +- [설정](setup.md) +- 다음: [슈레드 퍼블리시 (Edge)](solana-shreds-publisher-runbook.md) \ No newline at end of file diff --git a/docs/solana-ibrl-runbook.pt.md b/docs/solana-ibrl-runbook.pt.md new file mode 100644 index 0000000..46255f4 --- /dev/null +++ b/docs/solana-ibrl-runbook.pt.md @@ -0,0 +1,160 @@ +--- +description: Runbook orientado a LLM — conectar um validador Solana Mainnet-Beta ao DoubleZero em modo IBRL. Servido ao MCP via GitHub raw; não publicado no site de documentação. +--- + +# Conectar validador (IBRL Mainnet) — runbook + +Esta página é para o MCP do DoubleZero (`get_onboarding_runbook`) via GitHub raw. Ela +não é publicada no site de documentação. + +1. Conecte o [MCP do DoubleZero](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Informe que se trata de um **validador Solana Mainnet-Beta**, o host Linux (ou SSH), e onde está o keypair de identidade do validador. +3. Siga os passos abaixo em ordem. Prefere fazer manualmente? Use o [guia para humanos](DZ Mainnet-beta Connection.md). + +**Como é o sucesso:** `doublezero status` mostra o túnel como **up**, User Type **IBRL**, Network **mainnet-beta**. `Tunnel src` e `Doublezero IP` correspondem ao IPv4 público do host. + +IBRL não requer reiniciar os clientes do validador; ele usa o IP público existente. + +--- + +## Pré-requisitos + +| Necessário | Observações | +|------|--------| +| Host Linux/amd64 | Instale o DoubleZero **no host do validador**, não em um container. | +| IPv4 público, sem NAT | O IP de gossip deve corresponder a este host. | +| Solana CLI no `$PATH` | Para `solana sign-offchain-message`. | +| Keypair de identidade do validador | Legível pelo usuário que executa os comandos (geralmente sob o usuário `sol`). | +| ≥1 SOL na identidade | Passport / solicitação onchain. | +| GRE (protocolo IP 47) + BGP | BGP em `169.254.0.0/16` tcp/179. | +| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` (ou equivalente da distribuição). | + +O Validator ID é verificado contra o gossip da Solana para determinar o IP de destino. Um ID inválido no mesmo IP é ignorado; apenas o ID primário no gossip é utilizado. + +--- + +## Passos + +### 1. Instalar o cliente + +Siga o [setup](setup.md) se o `doublezero` não estiver instalado. Pacotes para mainnet: + +```bash +curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash +sudo apt-get install doublezero +``` + +Rocky / RHEL: use `setup.rpm.sh` e `sudo yum install doublezero`. + +**Verificação:** `sudo systemctl status doublezerod` está ativo. Faça backup de `~/.config/doublezero/id.json`. + +### 2. Apontar o daemon para mainnet-beta + +```bash +DESIRED_DOUBLEZERO_ENV=mainnet-beta \ + && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ + && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ + && sudo systemctl daemon-reload \ + && sudo systemctl restart doublezerod \ + && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ + && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" +``` + +Aguarde ~30s, então `doublezero latency` deve listar os dispositivos da mainnet. + +### 3. Abrir UDP 44880 em `doublezero0` + +```bash +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +UFW: `sudo ufw allow in on doublezero0 to any port 44880 proto udp` e a regra `out` correspondente. Também permita GRE e BGP conforme o [setup](setup.md). + +### 4. Confirmar o ID do DoubleZero e o validador primário + +O ID do DoubleZero obtido no setup do **primário** deve estar em cada backup (`~/.config/doublezero/id.json`). + +```bash +doublezero address +doublezero-solana passport find-validator -u mainnet-beta +``` + +Espere o primário: no gossip, no leader schedule, "can connect as a primary". Nos backups, execute o mesmo `find-validator`; eles **não** devem estar no leader schedule. + +Apenas uma máquina: omita `--backup-validator-ids` / `backup_ids=` dos comandos seguintes. + +### 5. Preparar a mensagem de acesso (primário) + +No primário (com stake ativo, identidade no gossip): + +```bash +doublezero-solana passport prepare-validator-access -u mainnet-beta \ + --doublezero-address \ + --primary-validator-id \ + --backup-validator-ids ,, +``` + +Omita `--backup-validator-ids` se não houver backups (máximo 3). Copie a linha `solana sign-offchain-message …` da saída. + +### 6. Assinar com a chave de identidade do validador + +No primário, execute o comando exibido (keypair de identidade, **não** apenas a chave do DoubleZero): + +```bash +solana sign-offchain-message \ + service_key=,backup_ids=,, \ + -k +``` + +**Produz:** uma string de assinatura. Leve-a para o próximo passo. + +### 7. Solicitar acesso de validador + +```bash +doublezero-solana passport request-validator-access -k -u mainnet-beta \ + --primary-validator-id \ + --backup-validator-ids ,, \ + --signature \ + --doublezero-address +``` + +Aguarde o Sentinel validar e criar o passe de acesso. Opcional: o agente pode chamar **`check_edge_access`** com `pubkey` (`doublezero address`) e o IP público do host até que o passe esteja presente. + +### 8. Conectar IBRL + +```bash +doublezero connect ibrl +``` + +Aguarde ~1 minuto para o GRE. Até lá, o status pode ser `down` / `Unknown`. + +```bash +doublezero status +``` + +**Sucesso:** `up`, User Type `IBRL`, Network `mainnet-beta`, túnel tipicamente `doublezero0`. + +```bash +ip route +``` + +Espere rotas aprendidas via BGP através de `doublezero0`. + +--- + +## Armadilhas + +1. **Ambiente errado.** Pacotes de testnet / `DESIRED_DOUBLEZERO_ENV=testnet` não funcionarão na mainnet-beta. +2. **Identidade não está no gossip.** IDs inválidos no mesmo IP não conseguem registrar a máquina. +3. **Backups devem compartilhar o ID do DoubleZero do primário.** Copie `id.json`; não gere uma segunda identidade com keygen. +4. **Assine com a identidade do validador**, não com a chave do DoubleZero. +5. **Status down por ~1 minuto** após `connect ibrl` é normal enquanto o GRE está sendo estabelecido. + +--- + +## Veja também + +- [Conexão de Validador Mainnet-Beta](DZ Mainnet-beta Connection.md) +- [Setup](setup.md) +- Próximo: [Publicar shreds (Edge)](solana-shreds-publisher-runbook.md) \ No newline at end of file diff --git a/docs/solana-ibrl-runbook.zh.md b/docs/solana-ibrl-runbook.zh.md new file mode 100644 index 0000000..08e67c7 --- /dev/null +++ b/docs/solana-ibrl-runbook.zh.md @@ -0,0 +1,159 @@ +--- +description: 面向 LLM 的操作手册 — 以 IBRL 模式将 Solana Mainnet-Beta 验证者连接到 DoubleZero。通过 GitHub raw 提供给 MCP；不在文档站点上发布。 +--- + +# 连接验证者（IBRL Mainnet）— 操作手册 + +本页面供 DoubleZero MCP（`get_onboarding_runbook`）通过 GitHub raw 使用。不在文档站点上发布。 + +1. 连接 [DoubleZero MCP](mcp.md)（`https://data.doublezero.xyz/api/mcp`）。 +2. 告诉它这是一个 **Solana Mainnet-Beta 验证者**、Linux 主机（或 SSH），以及验证者身份密钥对的存放位置。 +3. 按顺序执行以下步骤。更倾向于手动操作？请使用[人工指南](DZ Mainnet-beta Connection.md)。 + +**成功的标志：** `doublezero status` 显示隧道为 **up**，User Type 为 **IBRL**，Network 为 **mainnet-beta**。`Tunnel src` 和 `Doublezero IP` 与主机的公网 IPv4 匹配。 + +IBRL 不需要重启验证者客户端；它使用现有的公网 IP。 + +--- + +## 前提条件 + +| 需求 | 备注 | +|------|--------| +| Linux/amd64 主机 | 在**验证者主机上**安装 DoubleZero，不要在容器中安装。 | +| 公网 IPv4，无 NAT | Gossip IP 必须与此主机匹配。 | +| `$PATH` 中有 Solana CLI | 用于 `solana sign-offchain-message`。 | +| 验证者身份密钥对 | 运行命令的用户可读（通常在 `sol` 用户下）。 | +| 身份账户上 ≥1 SOL | Passport / 链上请求所需。 | +| GRE（IP 协议 47）+ BGP | BGP 在 `169.254.0.0/16` tcp/179 上。 | +| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana`（或对应发行版的等效命令）。 | + +验证者 ID 会通过 Solana gossip 进行检查以确定目标 IP。同一 IP 上的无效 ID 会被忽略；仅使用 gossip 中的主 ID。 + +--- + +## 步骤 + +### 1. 安装客户端 + +如果尚未安装 `doublezero`，请参照 [setup](setup.md)。Mainnet 软件包： + +```bash +curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash +sudo apt-get install doublezero +``` + +Rocky / RHEL：使用 `setup.rpm.sh` 和 `sudo yum install doublezero`。 + +**验证：** `sudo systemctl status doublezerod` 状态为 active。备份 `~/.config/doublezero/id.json`。 + +### 2. 将守护进程指向 mainnet-beta + +```bash +DESIRED_DOUBLEZERO_ENV=mainnet-beta \ + && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ + && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ + && sudo systemctl daemon-reload \ + && sudo systemctl restart doublezerod \ + && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ + && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" +``` + +等待约 30 秒，然后 `doublezero latency` 应列出 mainnet 设备。 + +### 3. 在 `doublezero0` 上开放 UDP 44880 + +```bash +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +UFW：`sudo ufw allow in on doublezero0 to any port 44880 proto udp` 以及对应的 `out` 规则。同时按照 [setup](setup.md) 中的说明允许 GRE 和 BGP。 + +### 4. 确认 DoubleZero ID 和主验证者 + +setup 阶段在**主节点**上生成的 DoubleZero ID 必须存在于每个备用节点上（`~/.config/doublezero/id.json`）。 + +```bash +doublezero address +doublezero-solana passport find-validator -u mainnet-beta +``` + +预期主节点：在 gossip 中、在出块时间表中、"can connect as a primary"。在备用节点上运行相同的 `find-validator`；它们**不应该**在出块时间表中。 + +仅一台机器的情况：在后续命令中省略 `--backup-validator-ids` / `backup_ids=`。 + +### 5. 准备访问消息（主节点） + +在主节点（有活跃质押，身份在 gossip 中）上： + +```bash +doublezero-solana passport prepare-validator-access -u mainnet-beta \ + --doublezero-address \ + --primary-validator-id \ + --backup-validator-ids ,, +``` + +如果没有备用节点则省略 `--backup-validator-ids`（最多 3 个）。复制输出中的 `solana sign-offchain-message …` 行。 + +### 6. 使用验证者身份密钥签名 + +在主节点上运行输出的命令（身份密钥对，**不是**仅 DoubleZero 密钥）： + +```bash +solana sign-offchain-message \ + service_key=,backup_ids=,, \ + -k +``` + +**产出：** 一个签名字符串。将其带入下一步。 + +### 7. 请求验证者访问权限 + +```bash +doublezero-solana passport request-validator-access -k -u mainnet-beta \ + --primary-validator-id \ + --backup-validator-ids ,, \ + --signature \ + --doublezero-address +``` + +等待 Sentinel 验证并创建访问通行证。可选：代理可以使用 `pubkey`（`doublezero address`）和主机公网 IP 调用 **`check_edge_access`**，直到通行证出现。 + +### 8. 连接 IBRL + +```bash +doublezero connect ibrl +``` + +等待约 1 分钟以建立 GRE。在此之前，状态可能显示为 `down` / `Unknown`。 + +```bash +doublezero status +``` + +**通过标志：** `up`，User Type 为 `IBRL`，Network 为 `mainnet-beta`，隧道通常为 `doublezero0`。 + +```bash +ip route +``` + +预期看到通过 `doublezero0` 学习到的 BGP 路由。 + +--- + +## 常见问题 + +1. **环境错误。** Testnet 软件包 / `DESIRED_DOUBLEZERO_ENV=testnet` 不会连接到 mainnet-beta。 +2. **身份不在 gossip 中。** 同一 IP 上的无效 ID 无法注册该机器。 +3. **备用节点必须共享主节点的 DoubleZero ID。** 复制 `id.json`；不要用 keygen 生成第二个身份。 +4. **使用验证者身份密钥签名**，不是 DoubleZero 密钥。 +5. **`connect ibrl` 后状态 down 约 1 分钟**是正常的，GRE 正在建立中。 + +--- + +## 另请参阅 + +- [验证者 Mainnet-Beta 连接](DZ Mainnet-beta Connection.md) +- [安装配置](setup.md) +- 下一步：[发布 shreds（Edge）](solana-shreds-publisher-runbook.md) \ No newline at end of file diff --git a/docs/solana-shreds-publisher-runbook.es.md b/docs/solana-shreds-publisher-runbook.es.md new file mode 100644 index 0000000..38c9a58 --- /dev/null +++ b/docs/solana-shreds-publisher-runbook.es.md @@ -0,0 +1,88 @@ +--- +description: Runbook orientado a LLM — configurar un validador de Solana conectado para publicar leader shreds en DoubleZero Edge. Se sirve al MCP a través de GitHub raw; no se publica en el sitio de documentación. +--- + +# Publicar shreds (Edge) — runbook + +Esta página es para el MCP de DoubleZero (`get_onboarding_runbook`) a través de GitHub raw. No se +publica en el sitio de documentación. + +1. Conectar el [MCP de DoubleZero](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Confirmar que el validador **ya está en DoubleZero IBRL** (mainnet-beta). Si no lo está, completar primero [Conectar validador (IBRL Mainnet)](solana-ibrl-runbook.md). +3. Seguir los pasos a continuación. Guía para humanos: [Validator Multicast Connection](Validator Multicast Connection.md). + +**Cómo se ve el éxito:** el validador envía leader shreds a `233.84.178.1:7733`, la publicación multicast en `edge-solana-shreds` está activa, y [publisher-check](https://data.doublezero.xyz/dz/publisher-check) muestra publicación después de al menos un leader slot. + +Esta ruta es para **validadores**. Las firmas de trading que desean *suscribirse* deben usar [Suscribirse a shreds](solana-shreds-runbook.md). + +--- + +## Requisitos previos + +| Necesario | Notas | +|-----------|-------| +| Túnel IBRL ya activo | [Runbook de IBRL Mainnet](solana-ibrl-runbook.md) / [guía para humanos](DZ Mainnet-beta Connection.md). | +| Cliente compatible | Jito-Agave **3.1.9+**, JitoBam 3.1.9+, Frankendancer, o Harmonic **3.1.11+**. Otras versiones no publicarán. | +| Ventana de reinicio | Agregar el destino de shreds requiere un reinicio del validador. | + +--- + +## Pasos + +### 1. Apuntar el cliente al grupo de shreds de Edge + +**Jito-Agave (v3.1.9+) y Harmonic (3.1.11+)** — en el script de inicio del validador agregar: + +```text +--shred-receiver-address 233.84.178.1:7733 +``` + +Se puede enviar a Jito y a `edge-solana-shreds` al mismo tiempo. Reiniciar el validador. + +**Frankendancer** — en `config.toml`: + +```toml +[tiles.shred] +additional_shred_destinations_leader = [ "233.84.178.1:7733", ] +``` + +Reiniciar el validador. + +### 2. Publicar en el grupo multicast + +```bash +doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds +``` + +**Verificar:** `doublezero status` sigue mostrando IBRL/up, y el usuario es publisher en `edge-solana-shreds`. + +IPs de grupos activos: `doublezero multicast group list`. Todos los feeds de shreds usan UDP **`7733`**; la IP selecciona el feed. + +| Feed | Dirección | +|------|-----------| +| `edge-solana-shreds` (leader) | `233.84.178.1:7733` | +| `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +### 3. Confirmar la publicación + +Abrir [publisher-check](https://data.doublezero.xyz/dz/publisher-check). No se verá confirmación hasta que el validador haya publicado leader shreds durante **al menos un slot**. + +Saludable: picos de salida alineados con los leader slots (diente de sierra). Salida constante sin patrón de slots es **retransmit** (malo). + +--- + +## Problemas comunes + +1. **Versión incorrecta del cliente.** No es 3.1.9+ / 3.1.11+ → nada útil en el cable. +2. **Flag de retransmit dejado activo.** Eliminar `--shred-retransmit-receiver-address` de Jito-Agave. Verificar la columna **No Retransmit Shreds** en publisher-check (vistas de 2 épocas vs slot reciente). +3. **Aún no es leader.** El dashboard permanece vacío hasta un leader slot. +4. **IBRL no está activo.** No comenzar aquí; completar IBRL primero. + +--- + +## Ver también + +- [Validator Multicast Connection](Validator Multicast Connection.md) +- [Validator Rewards](Validator Rewards.md) \ No newline at end of file diff --git a/docs/solana-shreds-publisher-runbook.fr.md b/docs/solana-shreds-publisher-runbook.fr.md new file mode 100644 index 0000000..02cd27f --- /dev/null +++ b/docs/solana-shreds-publisher-runbook.fr.md @@ -0,0 +1,88 @@ +--- +description: Runbook orienté LLM — configurer un validateur Solana connecté pour publier les shreds leader vers DoubleZero Edge. Servi au MCP via GitHub raw ; non publié sur le site de documentation. +--- + +# Publier des shreds (Edge) — runbook + +Cette page est destinée au MCP DoubleZero (`get_onboarding_runbook`) via GitHub raw. Elle n'est +pas publiée sur le site de documentation. + +1. Connectez le [MCP DoubleZero](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Confirmez que le validateur est **déjà sur DoubleZero IBRL** (mainnet-beta). Si ce n'est pas le cas, terminez d'abord [Connecter un validateur (IBRL Mainnet)](solana-ibrl-runbook.md). +3. Suivez les étapes ci-dessous. Guide utilisateur : [Validator Multicast Connection](Validator Multicast Connection.md). + +**À quoi ressemble le succès :** le validateur envoie les shreds leader vers `233.84.178.1:7733`, la publication multicast sur `edge-solana-shreds` est active, et [publisher-check](https://data.doublezero.xyz/dz/publisher-check) indique la publication après au moins un slot leader. + +Ce parcours est destiné aux **validateurs**. Les sociétés de trading qui souhaitent *s'abonner* utilisent [S'abonner aux shreds](solana-shreds-runbook.md). + +--- + +## Prérequis + +| Besoin | Notes | +|--------|--------| +| Tunnel IBRL déjà actif | [Runbook IBRL Mainnet](solana-ibrl-runbook.md) / [guide utilisateur](DZ Mainnet-beta Connection.md). | +| Client supporté | Jito-Agave **3.1.9+**, JitoBam 3.1.9+, Frankendancer, ou Harmonic **3.1.11+**. Les autres versions ne publieront pas. | +| Fenêtre de redémarrage | L'ajout de la destination shred nécessite un redémarrage du validateur. | + +--- + +## Étapes + +### 1. Pointer le client vers le groupe shred Edge + +**Jito-Agave (v3.1.9+) et Harmonic (3.1.11+)** — dans le script de démarrage du validateur, ajoutez : + +```text +--shred-receiver-address 233.84.178.1:7733 +``` + +Vous pouvez envoyer vers Jito et `edge-solana-shreds` en même temps. Redémarrez le validateur. + +**Frankendancer** — dans `config.toml` : + +```toml +[tiles.shred] +additional_shred_destinations_leader = [ "233.84.178.1:7733", ] +``` + +Redémarrez le validateur. + +### 2. Publier sur le groupe multicast + +```bash +doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds +``` + +**Vérification :** `doublezero status` indique toujours IBRL/up, et l'utilisateur est bien un publisher sur `edge-solana-shreds`. + +IP des groupes en direct : `doublezero multicast group list`. Tous les flux shred utilisent UDP **`7733`** ; l'IP sélectionne le flux. + +| Flux | Adresse | +|------|---------| +| `edge-solana-shreds` (leader) | `233.84.178.1:7733` | +| `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +### 3. Confirmer la publication + +Ouvrez [publisher-check](https://data.doublezero.xyz/dz/publisher-check). Vous ne verrez pas de confirmation tant que le validateur n'aura pas publié de shreds leader pendant **au moins un slot**. + +Normal : pics sortants alignés avec les slots leader (en dents de scie). Un flux sortant constant sans motif de slot est du **retransmit** (mauvais). + +--- + +## Pièges courants + +1. **Mauvaise version du client.** Pas 3.1.9+ / 3.1.11+ → rien d'utile sur le réseau. +2. **Flag retransmit laissé actif.** Supprimez `--shred-retransmit-receiver-address` de Jito-Agave. Vérifiez la colonne **No Retransmit Shreds** sur publisher-check (vues 2-epoch vs recent-slot). +3. **Pas encore leader.** Le tableau de bord reste vide jusqu'à un slot leader. +4. **IBRL non actif.** Ne commencez pas ici ; terminez d'abord IBRL. + +--- + +## Voir aussi + +- [Validator Multicast Connection](Validator Multicast Connection.md) +- [Validator Rewards](Validator Rewards.md) \ No newline at end of file diff --git a/docs/solana-shreds-publisher-runbook.it.md b/docs/solana-shreds-publisher-runbook.it.md new file mode 100644 index 0000000..cc1148f --- /dev/null +++ b/docs/solana-shreds-publisher-runbook.it.md @@ -0,0 +1,88 @@ +--- +description: Runbook orientato agli LLM — configurare un validatore Solana connesso per pubblicare leader shred su DoubleZero Edge. Servito all'MCP tramite GitHub raw; non pubblicato sul sito della documentazione. +--- + +# Pubblicare shred (Edge) — runbook + +Questa pagina è destinata al DoubleZero MCP (`get_onboarding_runbook`) tramite GitHub raw. Non è +pubblicata sul sito della documentazione. + +1. Connettere il [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Verificare che il validatore sia **già su DoubleZero IBRL** (mainnet-beta). In caso contrario, completare prima [Connetti il validatore (IBRL Mainnet)](solana-ibrl-runbook.md). +3. Seguire i passaggi sottostanti. Guida per utenti: [Validator Multicast Connection](Validator Multicast Connection.md). + +**Risultato atteso in caso di successo:** il validatore invia leader shred a `233.84.178.1:7733`, la pubblicazione multicast su `edge-solana-shreds` è attiva, e [publisher-check](https://data.doublezero.xyz/dz/publisher-check) mostra la pubblicazione dopo almeno uno slot da leader. + +Questo percorso è per i **validatori**. Le società di trading che desiderano *sottoscrivere* utilizzano [Sottoscrivere gli shred](solana-shreds-runbook.md). + +--- + +## Prerequisiti + +| Necessario | Note | +|------|--------| +| Tunnel IBRL già attivo | [Runbook IBRL Mainnet](solana-ibrl-runbook.md) / [guida per utenti](DZ Mainnet-beta Connection.md). | +| Client supportato | Jito-Agave **3.1.9+**, JitoBam 3.1.9+, Frankendancer, o Harmonic **3.1.11+**. Altre versioni non pubblicheranno. | +| Finestra di riavvio | L'aggiunta della destinazione shred richiede un riavvio del validatore. | + +--- + +## Passaggi + +### 1. Puntare il client al gruppo shred di Edge + +**Jito-Agave (v3.1.9+) e Harmonic (3.1.11+)** — nello script di avvio del validatore aggiungere: + +```text +--shred-receiver-address 233.84.178.1:7733 +``` + +È possibile inviare contemporaneamente a Jito e a `edge-solana-shreds`. Riavviare il validatore. + +**Frankendancer** — in `config.toml`: + +```toml +[tiles.shred] +additional_shred_destinations_leader = [ "233.84.178.1:7733", ] +``` + +Riavviare il validatore. + +### 2. Pubblicare sul gruppo multicast + +```bash +doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds +``` + +**Verifica:** `doublezero status` mostra ancora IBRL/up, e l'utente è un publisher su `edge-solana-shreds`. + +IP dei gruppi attivi: `doublezero multicast group list`. Tutti i feed shred utilizzano UDP **`7733`**; l'IP seleziona il feed. + +| Feed | Indirizzo | +|------|---------| +| `edge-solana-shreds` (leader) | `233.84.178.1:7733` | +| `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +### 3. Confermare la pubblicazione + +Aprire [publisher-check](https://data.doublezero.xyz/dz/publisher-check). La conferma non sarà visibile finché il validatore non avrà pubblicato leader shred per **almeno uno slot**. + +Stato sano: picchi in uscita allineati con gli slot da leader (a dente di sega). Un flusso in uscita costante senza schema legato agli slot indica **retransmit** (anomalo). + +--- + +## Insidie comuni + +1. **Versione del client errata.** Non 3.1.9+ / 3.1.11+ → nessun dato utile sul filo. +2. **Flag di retransmit lasciato attivo.** Rimuovere `--shred-retransmit-receiver-address` da Jito-Agave. Controllare la colonna **No Retransmit Shreds** su publisher-check (viste 2-epoch vs slot recenti). +3. **Non ancora leader.** La dashboard resta vuota fino a uno slot da leader. +4. **IBRL non attivo.** Non iniziare da qui; completare prima IBRL. + +--- + +## Vedi anche + +- [Validator Multicast Connection](Validator Multicast Connection.md) +- [Validator Rewards](Validator Rewards.md) \ No newline at end of file diff --git a/docs/solana-shreds-publisher-runbook.ja.md b/docs/solana-shreds-publisher-runbook.ja.md new file mode 100644 index 0000000..ec9e381 --- /dev/null +++ b/docs/solana-shreds-publisher-runbook.ja.md @@ -0,0 +1,87 @@ +--- +description: LLM 向けランブック — 接続済みの Solana バリデーターを設定し、リーダーシュレッドを DoubleZero Edge にパブリッシュします。GitHub raw 経由で MCP に提供されます。ドキュメントサイトには公開されません。 +--- + +# シュレッドのパブリッシュ (Edge) — ランブック + +このページは GitHub raw 経由で DoubleZero MCP (`get_onboarding_runbook`) 向けに提供されています。ドキュメントサイトには公開されません。 + +1. [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`) に接続します。 +2. バリデーターが**既に DoubleZero IBRL** (mainnet-beta) に接続されていることを確認します。まだの場合は、先に [バリデーター接続 (IBRL Mainnet)](solana-ibrl-runbook.md) を完了してください。 +3. 以下の手順を実行します。ヒューマンガイド: [Validator Multicast Connection](Validator Multicast Connection.md)。 + +**成功の状態:** バリデーターがリーダーシュレッドを `233.84.178.1:7733` に送信し、`edge-solana-shreds` でのマルチキャストパブリッシュが稼働しており、少なくとも1つのリーダースロット後に [publisher-check](https://data.doublezero.xyz/dz/publisher-check) でパブリッシュが確認できること。 + +このパスは**バリデーター**向けです。シュレッドを*サブスクライブ*したいトレーディングファームは [シュレッドのサブスクライブ](solana-shreds-runbook.md) を使用してください。 + +--- + +## 前提条件 + +| 必要なもの | 備考 | +|------|--------| +| IBRL トンネルが既に稼働していること | [IBRL Mainnet ランブック](solana-ibrl-runbook.md) / [ヒューマンガイド](DZ Mainnet-beta Connection.md)。 | +| サポートされているクライアント | Jito-Agave **3.1.9+**、JitoBam 3.1.9+、Frankendancer、または Harmonic **3.1.11+**。それ以外のバージョンではパブリッシュされません。 | +| 再起動ウィンドウ | シュレッド送信先の追加にはバリデーターの再起動が必要です。 | + +--- + +## 手順 + +### 1. クライアントを Edge シュレッドグループに向ける + +**Jito-Agave (v3.1.9+) および Harmonic (3.1.11+)** — バリデーター起動スクリプトに以下を追加します: + +```text +--shred-receiver-address 233.84.178.1:7733 +``` + +Jito と `edge-solana-shreds` に同時に送信できます。バリデーターを再起動してください。 + +**Frankendancer** — `config.toml` に以下を追加します: + +```toml +[tiles.shred] +additional_shred_destinations_leader = [ "233.84.178.1:7733", ] +``` + +バリデーターを再起動してください。 + +### 2. マルチキャストグループでパブリッシュする + +```bash +doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds +``` + +**確認:** `doublezero status` が引き続き IBRL/up であること、およびユーザーが `edge-solana-shreds` のパブリッシャーになっていること。 + +ライブグループ IP: `doublezero multicast group list`。すべてのシュレッドフィードは UDP **`7733`** を使用し、IP でフィードを選択します。 + +| フィード | アドレス | +|------|---------| +| `edge-solana-shreds` (リーダー) | `233.84.178.1:7733` | +| `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +### 3. パブリッシュを確認する + +[publisher-check](https://data.doublezero.xyz/dz/publisher-check) を開きます。バリデーターが**少なくとも1スロット分**のリーダーシュレッドをパブリッシュするまで、確認は表示されません。 + +正常な状態: リーダースロットに合わせたアウトバウンドのスパイク（のこぎり波形）。スロットパターンのない一定のアウトバウンドは**リトランスミット**（不正）です。 + +--- + +## 注意事項 + +1. **クライアントバージョンの誤り。** 3.1.9+ / 3.1.11+ でない場合 → ワイヤー上に有用なデータが流れません。 +2. **リトランスミットフラグが残っている。** Jito-Agave から `--shred-retransmit-receiver-address` を削除してください。publisher-check の **No Retransmit Shreds** 列（2エポック vs 最近のスロットビュー）を確認してください。 +3. **まだリーダーになっていない。** リーダースロットが来るまでダッシュボードは空のままです。 +4. **IBRL が稼働していない。** ここから始めないでください。まず IBRL を完了してください。 + +--- + +## 関連項目 + +- [Validator Multicast Connection](Validator Multicast Connection.md) +- [Validator Rewards](Validator Rewards.md) \ No newline at end of file diff --git a/docs/solana-shreds-publisher-runbook.ko.md b/docs/solana-shreds-publisher-runbook.ko.md new file mode 100644 index 0000000..43fdf9d --- /dev/null +++ b/docs/solana-shreds-publisher-runbook.ko.md @@ -0,0 +1,87 @@ +--- +description: LLM 지향 런북 — 연결된 Solana 밸리데이터가 리더 shred를 DoubleZero Edge로 퍼블리시하도록 구성합니다. GitHub raw를 통해 MCP에 제공되며, 문서 사이트에는 게시되지 않습니다. +--- + +# Shred 퍼블리시 (Edge) — 런북 + +이 페이지는 GitHub raw를 통해 DoubleZero MCP(`get_onboarding_runbook`)를 위한 것입니다. 문서 사이트에는 게시되지 않습니다. + +1. [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`)를 연결합니다. +2. 밸리데이터가 **이미 DoubleZero IBRL**(mainnet-beta)에 연결되어 있는지 확인합니다. 연결되어 있지 않다면, 먼저 [밸리데이터 연결 (IBRL Mainnet)](solana-ibrl-runbook.md)을 완료하세요. +3. 아래 단계를 따릅니다. 사람용 가이드: [Validator Multicast Connection](Validator Multicast Connection.md). + +**성공 상태:** 밸리데이터가 리더 shred를 `233.84.178.1:7733`으로 전송하고, `edge-solana-shreds`에서 멀티캐스트 퍼블리시가 작동 중이며, [publisher-check](https://data.doublezero.xyz/dz/publisher-check)에서 최소 한 번의 리더 슬롯 이후 퍼블리싱이 표시됩니다. + +이 경로는 **밸리데이터**를 위한 것입니다. *구독*하려는 트레이딩 회사는 [Shred 구독](solana-shreds-runbook.md)을 사용하세요. + +--- + +## 전제 조건 + +| 필요 사항 | 참고 | +|------|--------| +| IBRL 터널이 이미 가동 중 | [IBRL Mainnet 런북](solana-ibrl-runbook.md) / [사람용 가이드](DZ Mainnet-beta Connection.md). | +| 지원되는 클라이언트 | Jito-Agave **3.1.9+**, JitoBam 3.1.9+, Frankendancer, 또는 Harmonic **3.1.11+**. 다른 버전은 퍼블리시되지 않습니다. | +| 재시작 시간 | shred 대상 추가 시 밸리데이터 재시작이 필요합니다. | + +--- + +## 단계 + +### 1. 클라이언트를 Edge shred 그룹으로 지정 + +**Jito-Agave (v3.1.9+) 및 Harmonic (3.1.11+)** — 밸리데이터 시작 스크립트에 다음을 추가합니다: + +```text +--shred-receiver-address 233.84.178.1:7733 +``` + +Jito와 `edge-solana-shreds`에 동시에 전송할 수 있습니다. 밸리데이터를 재시작합니다. + +**Frankendancer** — `config.toml`에서: + +```toml +[tiles.shred] +additional_shred_destinations_leader = [ "233.84.178.1:7733", ] +``` + +밸리데이터를 재시작합니다. + +### 2. 멀티캐스트 그룹에서 퍼블리시 + +```bash +doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds +``` + +**확인:** `doublezero status`가 여전히 IBRL/up이고, 사용자가 `edge-solana-shreds`의 퍼블리셔인지 확인합니다. + +라이브 그룹 IP: `doublezero multicast group list`. 모든 shred 피드는 UDP **`7733`**을 사용하며, IP로 피드를 선택합니다. + +| 피드 | 주소 | +|------|---------| +| `edge-solana-shreds` (리더) | `233.84.178.1:7733` | +| `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +### 3. 퍼블리싱 확인 + +[publisher-check](https://data.doublezero.xyz/dz/publisher-check)를 엽니다. 밸리데이터가 **최소 한 슬롯** 동안 리더 shred를 퍼블리시할 때까지 확인이 표시되지 않습니다. + +정상 상태: 아웃바운드 스파이크가 리더 슬롯과 일치합니다(톱니파 형태). 슬롯 패턴 없이 일정한 아웃바운드는 **재전송**(비정상)입니다. + +--- + +## 주의 사항 + +1. **잘못된 클라이언트 버전.** 3.1.9+ / 3.1.11+가 아니면 → 유효한 데이터가 전송되지 않습니다. +2. **재전송 플래그가 남아 있음.** Jito-Agave에서 `--shred-retransmit-receiver-address`를 제거하세요. publisher-check의 **No Retransmit Shreds** 열을 확인하세요(2-에포크 vs 최근 슬롯 뷰). +3. **아직 리더가 아님.** 리더 슬롯이 올 때까지 대시보드가 비어 있습니다. +4. **IBRL이 가동되지 않음.** 여기서 시작하지 마세요; 먼저 IBRL을 완료하세요. + +--- + +## 참고 자료 + +- [Validator Multicast Connection](Validator Multicast Connection.md) +- [Validator Rewards](Validator Rewards.md) \ No newline at end of file diff --git a/docs/solana-shreds-publisher-runbook.pt.md b/docs/solana-shreds-publisher-runbook.pt.md new file mode 100644 index 0000000..c5868ea --- /dev/null +++ b/docs/solana-shreds-publisher-runbook.pt.md @@ -0,0 +1,88 @@ +--- +description: Runbook orientado a LLM — configure um validador Solana conectado para publicar leader shreds no DoubleZero Edge. Servido ao MCP via GitHub raw; não publicado no site de documentação. +--- + +# Publicar shreds (Edge) — runbook + +Esta página é para o DoubleZero MCP (`get_onboarding_runbook`) via GitHub raw. Ela +não é publicada no site de documentação. + +1. Conecte o [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Confirme que o validador **já está no DoubleZero IBRL** (mainnet-beta). Caso contrário, conclua primeiro [Conectar validador (IBRL Mainnet)](solana-ibrl-runbook.md). +3. Siga os passos abaixo. Guia humano: [Validator Multicast Connection](Validator Multicast Connection.md). + +**Como é o sucesso:** o validador envia leader shreds para `233.84.178.1:7733`, a publicação multicast em `edge-solana-shreds` está ativa, e o [publisher-check](https://data.doublezero.xyz/dz/publisher-check) mostra publicação após pelo menos um leader slot. + +Este caminho é para **validadores**. Empresas de trading que desejam *se inscrever* devem usar [Inscrever-se em shreds](solana-shreds-runbook.md). + +--- + +## Pré-requisitos + +| Necessário | Notas | +|------------|-------| +| Túnel IBRL já ativo | [Runbook IBRL Mainnet](solana-ibrl-runbook.md) / [guia humano](DZ Mainnet-beta Connection.md). | +| Cliente suportado | Jito-Agave **3.1.9+**, JitoBam 3.1.9+, Frankendancer, ou Harmonic **3.1.11+**. Outras versões não publicarão. | +| Janela de reinício | Adicionar o destino de shred requer um reinício do validador. | + +--- + +## Passos + +### 1. Aponte o cliente para o grupo de shred do Edge + +**Jito-Agave (v3.1.9+) e Harmonic (3.1.11+)** — no script de inicialização do validador adicione: + +```text +--shred-receiver-address 233.84.178.1:7733 +``` + +Você pode enviar para o Jito e `edge-solana-shreds` ao mesmo tempo. Reinicie o validador. + +**Frankendancer** — em `config.toml`: + +```toml +[tiles.shred] +additional_shred_destinations_leader = [ "233.84.178.1:7733", ] +``` + +Reinicie o validador. + +### 2. Publique no grupo multicast + +```bash +doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds +``` + +**Verifique:** `doublezero status` ainda IBRL/up, e o usuário é um publicador em `edge-solana-shreds`. + +IPs de grupo ao vivo: `doublezero multicast group list`. Todos os feeds de shred usam UDP **`7733`**; o IP seleciona o feed. + +| Feed | Endereço | +|------|----------| +| `edge-solana-shreds` (leader) | `233.84.178.1:7733` | +| `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +### 3. Confirme a publicação + +Abra o [publisher-check](https://data.doublezero.xyz/dz/publisher-check). Você não verá confirmação até que o validador tenha publicado leader shreds por **pelo menos um slot**. + +Saudável: picos de saída alinhados com leader slots (dente de serra). Saída constante sem padrão de slot é **retransmit** (ruim). + +--- + +## Armadilhas + +1. **Versão errada do cliente.** Não é 3.1.9+ / 3.1.11+ → nada útil na rede. +2. **Flag de retransmit deixada ativa.** Remova `--shred-retransmit-receiver-address` do Jito-Agave. Verifique a coluna **No Retransmit Shreds** no publisher-check (visualizações de 2 epochs vs slot recente). +3. **Ainda não é leader.** O dashboard permanece vazio até um leader slot. +4. **IBRL não está ativo.** Não comece por aqui; conclua o IBRL primeiro. + +--- + +## Veja também + +- [Validator Multicast Connection](Validator Multicast Connection.md) +- [Validator Rewards](Validator Rewards.md) \ No newline at end of file diff --git a/docs/solana-shreds-publisher-runbook.zh.md b/docs/solana-shreds-publisher-runbook.zh.md new file mode 100644 index 0000000..13d2164 --- /dev/null +++ b/docs/solana-shreds-publisher-runbook.zh.md @@ -0,0 +1,87 @@ +--- +description: 面向 LLM 的运行手册 — 配置已连接的 Solana 验证器，将 leader shreds 发布到 DoubleZero Edge。通过 GitHub raw 提供给 MCP；不在文档站点上发布。 +--- + +# 发布 shreds (Edge) — 运行手册 + +本页面通过 GitHub raw 提供给 DoubleZero MCP (`get_onboarding_runbook`)。不在文档站点上发布。 + +1. 连接 [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`)。 +2. 确认验证器**已接入 DoubleZero IBRL**（mainnet-beta）。如果尚未接入，请先完成[连接验证器 (IBRL Mainnet)](solana-ibrl-runbook.md)。 +3. 按照以下步骤操作。人工指南：[Validator Multicast Connection](Validator Multicast Connection.md)。 + +**成功的标志：** 验证器向 `233.84.178.1:7733` 发送 leader shreds，`edge-solana-shreds` 上的多播发布已启动，且 [publisher-check](https://data.doublezero.xyz/dz/publisher-check) 在至少一个 leader slot 之后显示正在发布。 + +此路径适用于**验证器**。希望*订阅*的交易公司请使用[订阅 shreds](solana-shreds-runbook.md)。 + +--- + +## 前提条件 + +| 需求 | 备注 | +|------|--------| +| IBRL 隧道已建立 | [IBRL Mainnet 运行手册](solana-ibrl-runbook.md) / [人工指南](DZ Mainnet-beta Connection.md)。 | +| 支持的客户端 | Jito-Agave **3.1.9+**、JitoBam 3.1.9+、Frankendancer 或 Harmonic **3.1.11+**。其他版本将无法发布。 | +| 重启窗口 | 添加 shred 目标地址需要重启验证器。 | + +--- + +## 步骤 + +### 1. 将客户端指向 Edge shred 组 + +**Jito-Agave (v3.1.9+) 和 Harmonic (3.1.11+)** — 在验证器启动脚本中添加： + +```text +--shred-receiver-address 233.84.178.1:7733 +``` + +您可以同时向 Jito 和 `edge-solana-shreds` 发送。重启验证器。 + +**Frankendancer** — 在 `config.toml` 中： + +```toml +[tiles.shred] +additional_shred_destinations_leader = [ "233.84.178.1:7733", ] +``` + +重启验证器。 + +### 2. 在多播组上发布 + +```bash +doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds +``` + +**验证：** `doublezero status` 仍显示 IBRL/up，且用户是 `edge-solana-shreds` 的发布者。 + +实时组 IP：`doublezero multicast group list`。所有 shred feed 使用 UDP **`7733`**；IP 地址选择对应的 feed。 + +| Feed | 地址 | +|------|---------| +| `edge-solana-shreds`（leader） | `233.84.178.1:7733` | +| `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +### 3. 确认发布状态 + +打开 [publisher-check](https://data.doublezero.xyz/dz/publisher-check)。在验证器发布了**至少一个 slot** 的 leader shreds 之前，您不会看到确认信息。 + +健康状态：出站流量峰值与 leader slot 对齐（锯齿形）。稳定的出站流量且无 slot 模式则为 **retransmit**（异常）。 + +--- + +## 常见问题 + +1. **客户端版本错误。** 不是 3.1.9+ / 3.1.11+ → 线路上不会有有用的数据。 +2. **retransmit 标志未移除。** 从 Jito-Agave 中移除 `--shred-retransmit-receiver-address`。在 publisher-check 上检查 **No Retransmit Shreds** 列（2-epoch 与 recent-slot 视图）。 +3. **尚未成为 leader。** 在获得 leader slot 之前，仪表盘保持空白。 +4. **IBRL 未启动。** 不要从这里开始；请先完成 IBRL 配置。 + +--- + +## 另请参阅 + +- [Validator Multicast Connection](Validator Multicast Connection.md) +- [Validator Rewards](Validator Rewards.md) \ No newline at end of file diff --git a/docs/solana-shreds-runbook.es.md b/docs/solana-shreds-runbook.es.md new file mode 100644 index 0000000..4040b8b --- /dev/null +++ b/docs/solana-shreds-runbook.es.md @@ -0,0 +1,144 @@ +--- +description: Runbook orientado a LLM — comprar un asiento de shreds en Edge y recibir multicast de shreds de Solana en doublezero1. Servido al MCP a través de GitHub raw; no publicado en el sitio de documentación. +--- + +# Suscribirse a shreds (Edge) — runbook + +Esta página es para el MCP de DoubleZero (`get_onboarding_runbook`) a través de GitHub raw. No está publicada en el sitio de documentación. + +1. Conectar el [MCP de DoubleZero](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Indicarle el host Linux que **recibirá** shreds (o SSH), la wallet/keypair para `doublezero-solana`, y qué feed (leader vs retransmit). +3. Seguir los pasos a continuación en orden. Guía para humanos: [Edge Subscriber Connection](Edge Subscriber Connection.md). + +**Cómo se ve el éxito:** asiento asignado para la época actual, `doublezero status` muestra el túnel activo, shreds UDP en `doublezero1` puerto `7733` (grupo leader `233.84.178.1`). + +Al conectarse, el usuario acepta los [Términos de Uso de DoubleZero](https://doublezero.xyz/terms-protocol). Los datos son para uso interno y no pueden ser retransmitidos. + +--- + +## Prerrequisitos + +| Necesario | Notas | +|-----------|-------| +| Host Linux/amd64 | IPv4 pública, sin NAT. En AWS: deshabilitar la verificación de origen/destino del ENI. | +| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | +| Wallet | `~/.config/solana/id.json` (o `--keypair`). Necesita **SOL** (comisiones) + **USDC** (escrow del asiento). | +| Mint de USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | +| Firewall | GRE, BGP (`169.254.0.0/16` tcp/179), PIM, UDP `7733` en `doublezero1`, UDP `44880` en `doublezero0`. | + +--- + +## Pasos + +### 1. Instalar cliente + paquetes + +Seguir [setup](setup.md), luego: + +```bash +sudo apt update && sudo apt install doublezero-solana +``` + +Respaldar `~/.config/doublezero/id.json`. + +### 2. Firewall + +```bash +sudo iptables -A OUTPUT -p gre -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +Variantes con UFW: ver guía para humanos. + +### 3. Habilitar el reconciliador + +Necesario para que los asientos aprovisionen automáticamente el túnel. + +```bash +doublezero enable +``` + +### 4. Wallet + +```bash +solana-keygen new # si es necesario — escribe en ~/.config/solana/id.json; respaldarlo +solana address +``` + +Fondear SOL y USDC. + +### 5. Elegir dispositivo + precio + +```bash +doublezero latency +doublezero-solana shreds price +doublezero-solana shreds price --device-code +``` + +Anotar el **código de dispositivo** con menor latencia y el precio por época (base + premium). Se recomienda fondear **>1 época**. Interfaz de precios: [devices](https://data.doublezero.xyz/dz/shreds/devices). + +### 6. Comprar un asiento (bloqueante) + +En el host receptor: + +```bash +curl -4 -s ifconfig.me; echo +``` + +```bash +doublezero-solana shreds pay \ + --device-code \ + --client-ip \ + --amount +``` + +`--client-ip` debe ser la IPv4 pública de la máquina que recibirá shreds. `--amount` es USDC en decimal (ej. `100`) y debe cumplir el precio de la época. + +Si queda menos del 10% de la época, el CLI advierte. `--accept-partial-epoch` toma el remanente ahora; de lo contrario, esperar. Escrow sin fondos suficientes al momento de la liquidación → asiento perdido, túnel eliminado, **tenencia perdida**. + +Una vez asignado, el daemon levanta el túnel GRE. + +```bash +doublezero status +doublezero-solana shreds list +``` + +### 7. Confirmar shreds + +Shreds de leader: `233.84.178.1:7733` en `doublezero1`. Descubrir grupos con `doublezero multicast group list`. + +| Feed | Grupo | Dirección | +|------|-------|-----------| +| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | +| Root | `edge-solana-root` | `233.84.178.16:7733` | +| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +El puerto `5765` es un heartbeat del publicador — no shreds. El tráfico está encapsulado en GRE; algunos pipelines (deshredders XDP) deben eliminar el encapsulado GRE. + +```bash +sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 +``` + +--- + +## Problemas comunes + +1. **Reconciliador desactivado.** Sin `doublezero enable`, pagar no levanta el túnel. +2. **`--client-ip` ≠ IP del daemon.** La auto-detección debe coincidir con el asiento. +3. **`Multicast user already exists`.** Desconectar primero: `doublezero disconnect`, luego reintentar `shreds pay`. +4. **Monto por debajo del precio actual.** Verificar nuevamente `shreds price` y aumentar `--amount`. +5. **Asiento no asignado después del pago.** Época tardía (siguiente época), dispositivo lleno (mayor tenencia), o retiro antes de la liquidación. +6. **Mantener el escrow fondeado.** Recargar con otro `shreds pay`; no permitir que el saldo caiga por debajo del precio de la época. + +--- + +## Ver también + +- [Edge Subscriber Connection](Edge Subscriber Connection.md) +- [Soporte](support.md) +- Scoreboard / asientos: [data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) \ No newline at end of file diff --git a/docs/solana-shreds-runbook.fr.md b/docs/solana-shreds-runbook.fr.md new file mode 100644 index 0000000..8aacd9c --- /dev/null +++ b/docs/solana-shreds-runbook.fr.md @@ -0,0 +1,145 @@ +--- +description: Runbook orienté LLM — acheter un siège Edge shreds et recevoir le multicast Solana shreds sur doublezero1. Servi au MCP via GitHub raw ; non publié sur le site de documentation. +--- + +# S'abonner aux shreds (Edge) — runbook + +Cette page est destinée au DoubleZero MCP (`get_onboarding_runbook`) via GitHub raw. Elle +n'est pas publiée sur le site de documentation. + +1. Connectez le [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Indiquez-lui l'hôte Linux qui va **recevoir** les shreds (ou SSH), le wallet/keypair pour `doublezero-solana`, et quel flux (leader vs retransmit). +3. Suivez les étapes ci-dessous dans l'ordre. Guide utilisateur : [Edge Subscriber Connection](Edge Subscriber Connection.md). + +**À quoi ressemble le succès :** siège alloué pour l'époque en cours, `doublezero status` montre le tunnel actif, shreds UDP sur `doublezero1` port `7733` (groupe leader `233.84.178.1`). + +En se connectant, l'utilisateur accepte les [Conditions d'utilisation DoubleZero](https://doublezero.xyz/terms-protocol). Les données sont à usage interne et ne peuvent pas être retransmises. + +--- + +## Prérequis + +| Besoin | Notes | +|--------|--------| +| Hôte Linux/amd64 | IPv4 publique, pas de NAT. Sur AWS : désactiver la vérification source/dest de l'ENI. | +| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | +| Wallet | `~/.config/solana/id.json` (ou `--keypair`). Nécessite du **SOL** (frais) + **USDC** (escrow du siège). | +| Mint USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | +| Pare-feu | GRE, BGP (`169.254.0.0/16` tcp/179), PIM, UDP `7733` sur `doublezero1`, UDP `44880` sur `doublezero0`. | + +--- + +## Étapes + +### 1. Installer le client + les paquets + +Suivez la [configuration](setup.md), puis : + +```bash +sudo apt update && sudo apt install doublezero-solana +``` + +Sauvegardez `~/.config/doublezero/id.json`. + +### 2. Pare-feu + +```bash +sudo iptables -A OUTPUT -p gre -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +Variantes UFW : voir le guide utilisateur. + +### 3. Activer le réconcilieur + +Nécessaire pour que les sièges provisionnent automatiquement le tunnel. + +```bash +doublezero enable +``` + +### 4. Wallet + +```bash +solana-keygen new # si nécessaire — écrit ~/.config/solana/id.json ; sauvegardez-le +solana address +``` + +Approvisionnez en SOL et USDC. + +### 5. Choisir le dispositif + le prix + +```bash +doublezero latency +doublezero-solana shreds price +doublezero-solana shreds price --device-code +``` + +Notez le **code du dispositif** à la latence la plus faible et le prix par époque (base + premium). Préférez un financement de **>1 époque**. Interface des prix : [devices](https://data.doublezero.xyz/dz/shreds/devices). + +### 6. Acheter un siège (bloquant) + +Sur l'hôte récepteur : + +```bash +curl -4 -s ifconfig.me; echo +``` + +```bash +doublezero-solana shreds pay \ + --device-code \ + --client-ip \ + --amount +``` + +`--client-ip` doit être l'IPv4 publique de la machine qui recevra les shreds. `--amount` est en décimal USDC (par ex. `100`) et doit atteindre le prix de l'époque. + +S'il reste moins de 10 % de l'époque, le CLI émet un avertissement. `--accept-partial-epoch` prend le reste maintenant ; sinon attendez. Un escrow sous-financé au moment du règlement → siège perdu, tunnel démonté, **ancienneté perdue**. + +Une fois alloué, le daemon établit le tunnel GRE. + +```bash +doublezero status +doublezero-solana shreds list +``` + +### 7. Confirmer les shreds + +Shreds leader : `233.84.178.1:7733` sur `doublezero1`. Découvrez les groupes avec `doublezero multicast group list`. + +| Flux | Groupe | Adresse | +|------|--------|---------| +| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | +| Root | `edge-solana-root` | `233.84.178.16:7733` | +| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +Le port `5765` est un heartbeat de l'éditeur — pas des shreds. Le trafic est encapsulé en GRE ; certains pipelines (deshredders XDP) doivent retirer le GRE. + +```bash +sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 +``` + +--- + +## Pièges courants + +1. **Réconcilieur désactivé.** Sans `doublezero enable`, le paiement n'établit pas le tunnel. +2. **`--client-ip` ≠ IP du daemon.** La découverte automatique doit correspondre au siège. +3. **`Multicast user already exists`.** Déconnectez d'abord : `doublezero disconnect`, puis réessayez `shreds pay`. +4. **Montant inférieur au prix actuel.** Revérifiez `shreds price` et augmentez `--amount`. +5. **Siège non alloué après le paiement.** Époque tardive (époque suivante), dispositif complet (ancienneté plus élevée), ou retrait avant le règlement. +6. **Maintenez l'escrow financé.** Rechargez avec un autre `shreds pay` ; ne laissez pas le solde descendre en dessous du prix de l'époque. + +--- + +## Voir aussi + +- [Edge Subscriber Connection](Edge Subscriber Connection.md) +- [Support](support.md) +- Tableau de bord / sièges : [data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) \ No newline at end of file diff --git a/docs/solana-shreds-runbook.it.md b/docs/solana-shreds-runbook.it.md new file mode 100644 index 0000000..e08702d --- /dev/null +++ b/docs/solana-shreds-runbook.it.md @@ -0,0 +1,145 @@ +--- +description: Runbook orientato agli LLM — acquistare un seat Edge per gli shred e ricevere il multicast degli shred Solana su doublezero1. Servito all'MCP tramite GitHub raw; non pubblicato sul sito della documentazione. +--- + +# Sottoscrivere gli shred (Edge) — runbook + +Questa pagina è destinata al DoubleZero MCP (`get_onboarding_runbook`) tramite GitHub raw. Non è +pubblicata sul sito della documentazione. + +1. Connettere il [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Indicare l'host Linux che **riceverà** gli shred (o SSH), il wallet/keypair per `doublezero-solana` e quale feed (leader vs retransmit). +3. Seguire i passaggi sottostanti in ordine. Guida per operatori: [Edge Subscriber Connection](Edge Subscriber Connection.md). + +**Come si presenta il successo:** seat allocato per l'epoca corrente, `doublezero status` mostra il tunnel attivo, shred UDP su `doublezero1` porta `7733` (gruppo leader `233.84.178.1`). + +Connettendosi, l'utente accetta i [Termini di Utilizzo di DoubleZero](https://doublezero.xyz/terms-protocol). I dati sono per uso interno e non possono essere ritrasmessi. + +--- + +## Prerequisiti + +| Necessario | Note | +|------|--------| +| Host Linux/amd64 | IPv4 pubblico, senza NAT. Su AWS: disabilitare il controllo source/dest dell'ENI. | +| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | +| Wallet | `~/.config/solana/id.json` (oppure `--keypair`). Necessari **SOL** (commissioni) + **USDC** (escrow del seat). | +| Mint USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | +| Firewall | GRE, BGP (`169.254.0.0/16` tcp/179), PIM, UDP `7733` su `doublezero1`, UDP `44880` su `doublezero0`. | + +--- + +## Passaggi + +### 1. Installare client e pacchetti + +Seguire il [setup](setup.md), poi: + +```bash +sudo apt update && sudo apt install doublezero-solana +``` + +Eseguire il backup di `~/.config/doublezero/id.json`. + +### 2. Firewall + +```bash +sudo iptables -A OUTPUT -p gre -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +Varianti UFW: consultare la guida per operatori. + +### 3. Abilitare il reconciler + +Necessario affinché i seat provisionino automaticamente il tunnel. + +```bash +doublezero enable +``` + +### 4. Wallet + +```bash +solana-keygen new # se necessario — scrive ~/.config/solana/id.json; eseguire il backup +solana address +``` + +Finanziare con SOL e USDC. + +### 5. Scegliere device e prezzo + +```bash +doublezero latency +doublezero-solana shreds price +doublezero-solana shreds price --device-code +``` + +Annotare il **device code** con latenza più bassa e il prezzo dell'epoca (base + premium). È preferibile finanziare **>1 epoca**. Interfaccia prezzi: [devices](https://data.doublezero.xyz/dz/shreds/devices). + +### 6. Acquistare un seat (bloccante) + +Sull'host ricevente: + +```bash +curl -4 -s ifconfig.me; echo +``` + +```bash +doublezero-solana shreds pay \ + --device-code \ + --client-ip \ + --amount +``` + +`--client-ip` deve essere l'IPv4 pubblico della macchina che riceverà gli shred. `--amount` è in decimali USDC (es. `100`) e deve soddisfare il prezzo dell'epoca. + +Se rimane meno del 10% dell'epoca, la CLI avvisa. `--accept-partial-epoch` prende il residuo immediatamente; altrimenti attendere. Escrow sottofinanziato al momento del settlement → seat perso, tunnel abbattuto, **tenure persa**. + +Una volta allocato, il daemon attiva il tunnel GRE. + +```bash +doublezero status +doublezero-solana shreds list +``` + +### 7. Verificare gli shred + +Shred leader: `233.84.178.1:7733` su `doublezero1`. Scoprire i gruppi con `doublezero multicast group list`. + +| Feed | Gruppo | Indirizzo | +|------|-------|---------| +| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | +| Root | `edge-solana-root` | `233.84.178.16:7733` | +| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +La porta `5765` è un heartbeat del publisher — non shred. Il traffico è incapsulato in GRE; alcune pipeline (deshredder XDP) devono rimuovere il GRE. + +```bash +sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 +``` + +--- + +## Problemi comuni + +1. **Reconciler disattivato.** Senza `doublezero enable`, il pagamento non attiva il tunnel. +2. **`--client-ip` ≠ IP del daemon.** L'auto-discovery deve corrispondere al seat. +3. **`Multicast user already exists`.** Disconnettersi prima: `doublezero disconnect`, poi riprovare `shreds pay`. +4. **Importo inferiore al prezzo corrente.** Ricontrollare `shreds price` e aumentare `--amount`. +5. **Seat non allocato dopo il pagamento.** Epoca tardiva (epoca successiva), device pieno (tenure più alta), o prelievo prima del settlement. +6. **Mantenere l'escrow finanziato.** Ricaricare con un altro `shreds pay`; non lasciare che il saldo scenda sotto il prezzo dell'epoca. + +--- + +## Vedi anche + +- [Edge Subscriber Connection](Edge Subscriber Connection.md) +- [Supporto](support.md) +- Scoreboard / seat: [data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) \ No newline at end of file diff --git a/docs/solana-shreds-runbook.ja.md b/docs/solana-shreds-runbook.ja.md new file mode 100644 index 0000000..3232bd6 --- /dev/null +++ b/docs/solana-shreds-runbook.ja.md @@ -0,0 +1,144 @@ +--- +description: LLM向けランブック — Edge シュレッド シートを購入し、doublezero1 上で Solana シュレッド マルチキャストを受信します。GitHub raw 経由で MCP に提供されます。ドキュメントサイトには公開されません。 +--- + +# シュレッドのサブスクライブ（Edge）— ランブック + +このページは DoubleZero MCP（`get_onboarding_runbook`）向けに GitHub raw 経由で提供されています。ドキュメントサイトには公開されません。 + +1. [DoubleZero MCP](mcp.md)（`https://data.doublezero.xyz/api/mcp`）に接続します。 +2. シュレッドを**受信**する Linux ホスト（または SSH）、`doublezero-solana` 用のウォレット/キーペア、および希望するフィード（leader または retransmit）を指定します。 +3. 以下の手順を順番に実施します。ヒューマンガイド：[Edge Subscriber Connection](Edge Subscriber Connection.md)。 + +**成功した場合の状態：** 現在のエポックにシートが割り当てられ、`doublezero status` でトンネルがアップと表示され、`doublezero1` のポート `7733` で UDP シュレッドが受信される（leader グループ `233.84.178.1`）。 + +接続することにより、ユーザーは [DoubleZero Terms of Use](https://doublezero.xyz/terms-protocol) に同意したものとみなされます。データは内部利用のみを目的とし、再送信は禁止されています。 + +--- + +## 前提条件 + +| 必要なもの | 備考 | +|------|--------| +| Linux/amd64 ホスト | パブリック IPv4、NAT なし。AWS の場合：ENI の送信元/送信先チェックを無効化。 | +| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | +| ウォレット | `~/.config/solana/id.json`（または `--keypair`）。**SOL**（手数料）+ **USDC**（シート エスクロー）が必要。 | +| USDC ミント | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | +| ファイアウォール | GRE、BGP（`169.254.0.0/16` tcp/179）、PIM、`doublezero1` 上の UDP `7733`、`doublezero0` 上の UDP `44880`。 | + +--- + +## 手順 + +### 1. クライアントとパッケージのインストール + +[セットアップ](setup.md) に従い、次を実行します： + +```bash +sudo apt update && sudo apt install doublezero-solana +``` + +`~/.config/doublezero/id.json` をバックアップしてください。 + +### 2. ファイアウォール + +```bash +sudo iptables -A OUTPUT -p gre -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +UFW の設定方法についてはヒューマンガイドを参照してください。 + +### 3. リコンサイラーの有効化 + +シートがトンネルを自動プロビジョニングするために必要です。 + +```bash +doublezero enable +``` + +### 4. ウォレット + +```bash +solana-keygen new # 必要に応じて — ~/.config/solana/id.json に書き込まれます。バックアップしてください +solana address +``` + +SOL と USDC を入金してください。 + +### 5. デバイスと価格の選択 + +```bash +doublezero latency +doublezero-solana shreds price +doublezero-solana shreds price --device-code +``` + +最低レイテンシの**デバイスコード**とエポック価格（ベース + プレミアム）を確認します。**1 エポック以上**の資金を用意することを推奨します。価格 UI：[devices](https://data.doublezero.xyz/dz/shreds/devices)。 + +### 6. シートの購入（ブロッキング） + +受信ホスト上で： + +```bash +curl -4 -s ifconfig.me; echo +``` + +```bash +doublezero-solana shreds pay \ + --device-code \ + --client-ip \ + --amount +``` + +`--client-ip` はシュレッドを受信するマシンのパブリック IPv4 である必要があります。`--amount` は USDC の10進数値（例：`100`）で、エポック価格を満たす必要があります。 + +エポックの残りが 10% 未満の場合、CLI が警告を表示します。`--accept-partial-epoch` を使用すると残りの期間を今すぐ取得します。それ以外の場合は次のエポックまで待ちます。精算時にエスクローの資金が不足していると → シート喪失、トンネル切断、**テニュア喪失**となります。 + +割り当てが完了すると、デーモンが GRE トンネルを起動します。 + +```bash +doublezero status +doublezero-solana shreds list +``` + +### 7. シュレッドの確認 + +Leader シュレッド：`doublezero1` 上の `233.84.178.1:7733`。グループの確認には `doublezero multicast group list` を使用します。 + +| フィード | グループ | アドレス | +|------|-------|---------| +| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | +| Root | `edge-solana-root` | `233.84.178.16:7733` | +| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +ポート `5765` はパブリッシャーのハートビートであり、シュレッドではありません。トラフィックは GRE カプセル化されています。一部のパイプライン（XDP デシュレッダー）では GRE の除去が必要です。 + +```bash +sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 +``` + +--- + +## よくある問題 + +1. **リコンサイラーがオフ。** `doublezero enable` なしでは、支払いを行ってもトンネルは起動しません。 +2. **`--client-ip` ≠ デーモン IP。** 自動検出がシートと一致する必要があります。 +3. **`Multicast user already exists`。** まず切断してください：`doublezero disconnect`、その後 `shreds pay` を再試行します。 +4. **金額が現在の価格を下回っている。** `shreds price` を再確認し、`--amount` を増額してください。 +5. **支払い後にシートが割り当てられない。** エポック終盤（次のエポック）、デバイスが満席（テニュアが高い）、または精算前に引き出した場合。 +6. **エスクローの資金を維持する。** 追加の `shreds pay` で補充してください。残高がエポック価格を下回らないようにしてください。 + +--- + +## 関連情報 + +- [Edge Subscriber Connection](Edge Subscriber Connection.md) +- [サポート](support.md) +- スコアボード / シート：[data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) \ No newline at end of file diff --git a/docs/solana-shreds-runbook.ko.md b/docs/solana-shreds-runbook.ko.md new file mode 100644 index 0000000..842a1b2 --- /dev/null +++ b/docs/solana-shreds-runbook.ko.md @@ -0,0 +1,144 @@ +--- +description: LLM 지향 런북 — Edge shreds 시트를 구매하고 doublezero1에서 Solana shred 멀티캐스트를 수신합니다. GitHub raw를 통해 MCP에 제공되며, 문서 사이트에는 게시되지 않습니다. +--- + +# shreds 구독 (Edge) — 런북 + +이 페이지는 GitHub raw를 통해 DoubleZero MCP(`get_onboarding_runbook`)를 위한 것입니다. 문서 사이트에는 게시되지 않습니다. + +1. [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`)에 연결합니다. +2. shreds를 **수신**할 Linux 호스트(또는 SSH), `doublezero-solana`용 지갑/키페어, 그리고 어떤 피드(leader vs retransmit)를 사용할지 알려줍니다. +3. 아래 단계를 순서대로 진행합니다. 사람용 가이드: [Edge Subscriber Connection](Edge Subscriber Connection.md). + +**성공 시 확인 사항:** 현재 에포크에 시트가 할당되고, `doublezero status`에서 터널이 활성 상태로 표시되며, `doublezero1` 포트 `7733`에서 UDP shreds 수신(leader 그룹 `233.84.178.1`). + +연결함으로써 사용자는 [DoubleZero 이용약관](https://doublezero.xyz/terms-protocol)에 동의합니다. 데이터는 내부 사용 목적이며 재전송할 수 없습니다. + +--- + +## 사전 요구 사항 + +| 필요 항목 | 참고 사항 | +|------|--------| +| Linux/amd64 호스트 | 공용 IPv4, NAT 없음. AWS의 경우: ENI source/dest 검사를 비활성화합니다. | +| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | +| 지갑 | `~/.config/solana/id.json` (또는 `--keypair`). **SOL**(수수료) + **USDC**(시트 에스크로)가 필요합니다. | +| USDC 민트 | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | +| 방화벽 | GRE, BGP (`169.254.0.0/16` tcp/179), PIM, `doublezero1`에서 UDP `7733`, `doublezero0`에서 UDP `44880`. | + +--- + +## 단계 + +### 1. 클라이언트 + 패키지 설치 + +[설정](setup.md)을 따른 후: + +```bash +sudo apt update && sudo apt install doublezero-solana +``` + +`~/.config/doublezero/id.json`을 백업합니다. + +### 2. 방화벽 + +```bash +sudo iptables -A OUTPUT -p gre -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +UFW 대안: 사람용 가이드를 참조하세요. + +### 3. 리컨실러 활성화 + +시트가 터널을 자동 프로비저닝하려면 필수입니다. + +```bash +doublezero enable +``` + +### 4. 지갑 + +```bash +solana-keygen new # 필요한 경우 — ~/.config/solana/id.json에 기록됩니다; 백업하세요 +solana address +``` + +SOL과 USDC를 충전합니다. + +### 5. 장치 + 가격 선택 + +```bash +doublezero latency +doublezero-solana shreds price +doublezero-solana shreds price --device-code +``` + +최저 지연 시간의 **장치 코드**와 에포크 가격(기본 + 프리미엄)을 기록합니다. **1 에포크 이상** 충전하는 것을 권장합니다. 가격 UI: [devices](https://data.doublezero.xyz/dz/shreds/devices). + +### 6. 시트 구매 (블로킹) + +수신 호스트에서: + +```bash +curl -4 -s ifconfig.me; echo +``` + +```bash +doublezero-solana shreds pay \ + --device-code \ + --client-ip \ + --amount +``` + +`--client-ip`는 shreds를 수신할 머신의 공용 IPv4여야 합니다. `--amount`는 USDC 소수점 값(예: `100`)이며 에포크 가격을 충족해야 합니다. + +에포크의 10% 미만이 남은 경우 CLI가 경고합니다. `--accept-partial-epoch`는 남은 기간을 즉시 사용합니다; 그렇지 않으면 기다리세요. 정산 시 에스크로 잔액 부족 → 시트 상실, 터널 해제, **테뉴어 손실**. + +할당되면 데몬이 GRE 터널을 활성화합니다. + +```bash +doublezero status +doublezero-solana shreds list +``` + +### 7. shreds 확인 + +Leader shreds: `doublezero1`의 `233.84.178.1:7733`. `doublezero multicast group list`로 그룹을 검색합니다. + +| 피드 | 그룹 | 주소 | +|------|-------|---------| +| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | +| Root | `edge-solana-root` | `233.84.178.16:7733` | +| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +포트 `5765`는 퍼블리셔 하트비트이며 — shreds가 아닙니다. 트래픽은 GRE 캡슐화되어 있습니다; 일부 파이프라인(XDP deshredder)은 GRE를 제거해야 합니다. + +```bash +sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 +``` + +--- + +## 주의 사항 + +1. **리컨실러 비활성화.** `doublezero enable` 없이 결제해도 터널이 활성화되지 않습니다. +2. **`--client-ip` ≠ 데몬 IP.** 자동 검색이 시트와 일치해야 합니다. +3. **`Multicast user already exists`.** 먼저 연결 해제: `doublezero disconnect`, 그런 다음 `shreds pay`를 재시도합니다. +4. **금액이 현재 가격 미만.** `shreds price`를 다시 확인하고 `--amount`를 높이세요. +5. **결제 후 시트가 할당되지 않음.** 에포크 후반(다음 에포크), 장치 만석(더 높은 테뉴어), 또는 정산 전 출금. +6. **에스크로 잔액을 유지하세요.** 추가 `shreds pay`로 충전하고, 잔액이 에포크 가격 이하로 떨어지지 않도록 하세요. + +--- + +## 참고 자료 + +- [Edge Subscriber Connection](Edge Subscriber Connection.md) +- [지원](support.md) +- 스코어보드 / 시트: [data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) \ No newline at end of file diff --git a/docs/solana-shreds-runbook.pt.md b/docs/solana-shreds-runbook.pt.md new file mode 100644 index 0000000..3245792 --- /dev/null +++ b/docs/solana-shreds-runbook.pt.md @@ -0,0 +1,145 @@ +--- +description: Runbook orientado a LLM — compre um seat de Edge shreds e receba multicast de shreds Solana no doublezero1. Servido ao MCP via GitHub raw; não publicado no site de documentação. +--- + +# Subscrever shreds (Edge) — runbook + +Esta página é para o DoubleZero MCP (`get_onboarding_runbook`) via GitHub raw. Não é +publicada no site de documentação. + +1. Conecte o [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). +2. Informe o host Linux que irá **receber** shreds (ou SSH), a wallet/keypair para `doublezero-solana`, e qual feed (leader vs retransmit). +3. Siga os passos abaixo em ordem. Guia humano: [Edge Subscriber Connection](Edge Subscriber Connection.md). + +**Como é o sucesso:** seat alocado para o epoch atual, `doublezero status` mostra o túnel ativo, shreds UDP em `doublezero1` porta `7733` (grupo leader `233.84.178.1`). + +Ao conectar, o usuário concorda com os [Termos de Uso do DoubleZero](https://doublezero.xyz/terms-protocol). Os dados são para uso interno e não podem ser retransmitidos. + +--- + +## Pré-requisitos + +| Necessário | Notas | +|------------|-------| +| Host Linux/amd64 | IPv4 público, sem NAT. Na AWS: desabilitar verificação de source/dest da ENI. | +| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | +| Wallet | `~/.config/solana/id.json` (ou `--keypair`). Precisa de **SOL** (taxas) + **USDC** (escrow do seat). | +| USDC mint | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | +| Firewall | GRE, BGP (`169.254.0.0/16` tcp/179), PIM, UDP `7733` em `doublezero1`, UDP `44880` em `doublezero0`. | + +--- + +## Passos + +### 1. Instalar cliente + pacotes + +Siga o [setup](setup.md), depois: + +```bash +sudo apt update && sudo apt install doublezero-solana +``` + +Faça backup de `~/.config/doublezero/id.json`. + +### 2. Firewall + +```bash +sudo iptables -A OUTPUT -p gre -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +Variantes UFW: guia humano. + +### 3. Habilitar o reconciler + +Necessário para que os seats provisionem automaticamente o túnel. + +```bash +doublezero enable +``` + +### 4. Wallet + +```bash +solana-keygen new # se necessário — grava em ~/.config/solana/id.json; faça backup +solana address +``` + +Financie com SOL e USDC. + +### 5. Escolher device + preço + +```bash +doublezero latency +doublezero-solana shreds price +doublezero-solana shreds price --device-code +``` + +Anote o **device code** de menor latência e o preço do epoch (base + premium). Prefira financiar **>1 epoch**. Interface de preços: [devices](https://data.doublezero.xyz/dz/shreds/devices). + +### 6. Comprar um seat (bloqueante) + +No host receptor: + +```bash +curl -4 -s ifconfig.me; echo +``` + +```bash +doublezero-solana shreds pay \ + --device-code \ + --client-ip \ + --amount +``` + +`--client-ip` deve ser o IPv4 público da máquina que receberá shreds. `--amount` é em USDC decimal (ex.: `100`) e deve atender o preço do epoch. + +Se restarem menos de 10% do epoch, o CLI avisa. `--accept-partial-epoch` aceita o restante agora; caso contrário, aguarde. Escrow insuficiente no settlement → seat perdido, túnel derrubado, **tenure perdido**. + +Uma vez alocado, o daemon ativa o túnel GRE. + +```bash +doublezero status +doublezero-solana shreds list +``` + +### 7. Confirmar shreds + +Shreds leader: `233.84.178.1:7733` em `doublezero1`. Descubra grupos com `doublezero multicast group list`. + +| Feed | Grupo | Endereço | +|------|-------|----------| +| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | +| Root | `edge-solana-root` | `233.84.178.16:7733` | +| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +A porta `5765` é um heartbeat do publisher — não são shreds. O tráfego é encapsulado em GRE; alguns pipelines (XDP deshredders) precisam remover o GRE. + +```bash +sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 +``` + +--- + +## Armadilhas + +1. **Reconciler desligado.** Sem `doublezero enable`, pagar não ativa o túnel. +2. **`--client-ip` ≠ IP do daemon.** A auto-descoberta deve corresponder ao seat. +3. **`Multicast user already exists`.** Desconecte primeiro: `doublezero disconnect`, depois tente `shreds pay` novamente. +4. **Valor abaixo do preço atual.** Verifique novamente `shreds price` e aumente `--amount`. +5. **Seat não alocado após pagamento.** Epoch tardio (próximo epoch), device cheio (tenure mais alto), ou saque antes do settlement. +6. **Mantenha o escrow financiado.** Recarregue com outro `shreds pay`; não deixe o saldo cair abaixo do preço do epoch. + +--- + +## Veja também + +- [Edge Subscriber Connection](Edge Subscriber Connection.md) +- [Suporte](support.md) +- Scoreboard / seats: [data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) \ No newline at end of file diff --git a/docs/solana-shreds-runbook.zh.md b/docs/solana-shreds-runbook.zh.md new file mode 100644 index 0000000..6183e75 --- /dev/null +++ b/docs/solana-shreds-runbook.zh.md @@ -0,0 +1,144 @@ +--- +description: 面向 LLM 的运行手册 — 购买 Edge shreds 席位并在 doublezero1 上接收 Solana shred 组播。通过 GitHub raw 提供给 MCP；不在文档站点上发布。 +--- + +# 订阅 shreds (Edge) — 运行手册 + +本页面通过 GitHub raw 为 DoubleZero MCP (`get_onboarding_runbook`) 提供。不在文档站点上发布。 + +1. 连接 [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`)。 +2. 告知它将**接收** shreds 的 Linux 主机（或 SSH）、用于 `doublezero-solana` 的钱包/密钥对，以及所需的 feed 类型（leader 或 retransmit）。 +3. 按顺序完成以下步骤。人工指南：[Edge Subscriber Connection](Edge Subscriber Connection.md)。 + +**成功标志：** 当前 epoch 已分配席位，`doublezero status` 显示隧道已建立，`doublezero1` 端口 `7733` 上有 UDP shreds（leader 组 `233.84.178.1`）。 + +连接即表示用户同意 [DoubleZero 使用条款](https://doublezero.xyz/terms-protocol)。数据仅供内部使用，不得转发。 + +--- + +## 前提条件 + +| 需求 | 说明 | +|------|--------| +| Linux/amd64 主机 | 公网 IPv4，无 NAT。在 AWS 上：禁用 ENI source/dest 检查。 | +| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | +| 钱包 | `~/.config/solana/id.json`（或 `--keypair`）。需要 **SOL**（手续费）+ **USDC**（席位托管）。 | +| USDC 铸币地址 | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | +| 防火墙 | GRE、BGP（`169.254.0.0/16` tcp/179）、PIM、`doublezero1` 上的 UDP `7733`、`doublezero0` 上的 UDP `44880`。 | + +--- + +## 步骤 + +### 1. 安装客户端和软件包 + +按照 [设置](setup.md) 操作，然后： + +```bash +sudo apt update && sudo apt install doublezero-solana +``` + +备份 `~/.config/doublezero/id.json`。 + +### 2. 防火墙 + +```bash +sudo iptables -A OUTPUT -p gre -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT +sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT +sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT +sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT +``` + +UFW 变体：参见人工指南。 + +### 3. 启用 reconciler + +必须启用，以便席位自动配置隧道。 + +```bash +doublezero enable +``` + +### 4. 钱包 + +```bash +solana-keygen new # 如需要 — 写入 ~/.config/solana/id.json；请备份 +solana address +``` + +充值 SOL 和 USDC。 + +### 5. 选择设备和价格 + +```bash +doublezero latency +doublezero-solana shreds price +doublezero-solana shreds price --device-code +``` + +记下最低延迟的 **device code** 和 epoch 价格（基础 + 溢价）。建议充值 **超过 1 个 epoch** 的金额。定价界面：[devices](https://data.doublezero.xyz/dz/shreds/devices)。 + +### 6. 购买席位（阻塞操作） + +在接收主机上： + +```bash +curl -4 -s ifconfig.me; echo +``` + +```bash +doublezero-solana shreds pay \ + --device-code \ + --client-ip \ + --amount +``` + +`--client-ip` 必须是将接收 shreds 的机器的公网 IPv4。`--amount` 为 USDC 十进制数（例如 `100`），且必须满足 epoch 价格。 + +如果当前 epoch 剩余不足 10%，CLI 会发出警告。`--accept-partial-epoch` 会立即获取剩余时间；否则请等待。结算时托管资金不足 → 席位丢失、隧道拆除、**任期中断**。 + +分配完成后，守护进程会启动 GRE 隧道。 + +```bash +doublezero status +doublezero-solana shreds list +``` + +### 7. 确认 shreds + +Leader shreds：`doublezero1` 上的 `233.84.178.1:7733`。使用 `doublezero multicast group list` 发现组播组。 + +| Feed | 组 | 地址 | +|------|-------|---------| +| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | +| Root | `edge-solana-root` | `233.84.178.16:7733` | +| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | +| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | +| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | + +端口 `5765` 是发布者心跳 — 不是 shreds。流量经过 GRE 封装；某些管道（XDP deshredder）需要剥离 GRE。 + +```bash +sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 +``` + +--- + +## 常见问题 + +1. **Reconciler 未开启。** 未执行 `doublezero enable` 时，付款不会启动隧道。 +2. **`--client-ip` ≠ 守护进程 IP。** 自动发现必须与席位匹配。 +3. **`Multicast user already exists`。** 先断开连接：`doublezero disconnect`，然后重试 `shreds pay`。 +4. **金额低于当前价格。** 重新检查 `shreds price` 并增加 `--amount`。 +5. **付款后席位未分配。** epoch 末期（下一 epoch 生效）、设备已满（需要更高任期）、或结算前已提取。 +6. **保持托管资金充足。** 通过另一次 `shreds pay` 充值；不要让余额低于 epoch 价格。 + +--- + +## 另请参阅 + +- [Edge Subscriber Connection](Edge Subscriber Connection.md) +- [支持](support.md) +- 记分板 / 席位：[data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) \ No newline at end of file From 5153d136381cb59107d06697e07cbead1a517ef0 Mon Sep 17 00:00:00 2001 From: Jotatavo <100889564+Jotatavo@users.noreply.github.com> Date: Wed, 12 Aug 2026 09:07:14 -0300 Subject: [PATCH 4/5] Keep MCP runbooks out of i18n locale builds so link-check does not fail. --- hooks/exclude_runbooks.py | 25 +++++++++++++++++++++++++ mkdocs.yml | 5 +++++ 2 files changed, 30 insertions(+) create mode 100644 hooks/exclude_runbooks.py diff --git a/hooks/exclude_runbooks.py b/hooks/exclude_runbooks.py new file mode 100644 index 0000000..8cbeb76 --- /dev/null +++ b/hooks/exclude_runbooks.py @@ -0,0 +1,25 @@ +"""Keep MCP runbook markdown in git (GitHub raw) but out of the MkDocs site. + +mkdocs-static-i18n copies unsuffixed English pages into each locale as +``runbooks.zh.md`` (etc.). Those copies do not match ``exclude_docs: runbooks.md``, +so they would still be built and fail link-check. Drop every locale variant here. +""" + +from __future__ import annotations + + +def _is_mcp_runbook(src_uri: str) -> bool: + name = src_uri.replace("\\", "/").rsplit("/", 1)[-1] + if not name.endswith(".md"): + return False + stem = name[:-3] + if stem == "runbooks" or stem.startswith("runbooks."): + return True + return "-runbook" in stem + + +def on_files(files, config): + for file in list(files): + if _is_mcp_runbook(file.src_uri): + files.remove(file) + return files diff --git a/mkdocs.yml b/mkdocs.yml index e040b16..22b4437 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,9 +8,13 @@ site_description: >- # into the public docs site. exclude_docs: | runbooks.md + runbooks.*.md solana-ibrl-runbook.md + solana-ibrl-runbook.*.md solana-shreds-runbook.md + solana-shreds-runbook.*.md solana-shreds-publisher-runbook.md + solana-shreds-publisher-runbook.*.md theme: name: material custom_dir: overrides @@ -143,5 +147,6 @@ extra_javascript: - javascripts/mathjax.js - path: https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js hooks: + - hooks/exclude_runbooks.py - hooks/emit_markdown.py - hooks/emit_well_known.py From 6db7c10f81cc2e1cc84c6f2df0782cc0ab000225 Mon Sep 17 00:00:00 2001 From: Jotatavo <100889564+Jotatavo@users.noreply.github.com> Date: Wed, 12 Aug 2026 09:09:26 -0300 Subject: [PATCH 5/5] Skip MCP runbooks in auto-translate and drop the locale copies. --- .github/workflows/translate.yml | 2 + docs/runbooks.es.md | 24 ---- docs/runbooks.fr.md | 24 ---- docs/runbooks.it.md | 24 ---- docs/runbooks.ja.md | 23 --- docs/runbooks.ko.md | 23 --- docs/runbooks.pt.md | 24 ---- docs/runbooks.zh.md | 23 --- docs/solana-ibrl-runbook.es.md | 159 -------------------- docs/solana-ibrl-runbook.fr.md | 160 --------------------- docs/solana-ibrl-runbook.it.md | 160 --------------------- docs/solana-ibrl-runbook.ja.md | 159 -------------------- docs/solana-ibrl-runbook.ko.md | 159 -------------------- docs/solana-ibrl-runbook.pt.md | 160 --------------------- docs/solana-ibrl-runbook.zh.md | 159 -------------------- docs/solana-shreds-publisher-runbook.es.md | 88 ------------ docs/solana-shreds-publisher-runbook.fr.md | 88 ------------ docs/solana-shreds-publisher-runbook.it.md | 88 ------------ docs/solana-shreds-publisher-runbook.ja.md | 87 ----------- docs/solana-shreds-publisher-runbook.ko.md | 87 ----------- docs/solana-shreds-publisher-runbook.pt.md | 88 ------------ docs/solana-shreds-publisher-runbook.zh.md | 87 ----------- docs/solana-shreds-runbook.es.md | 144 ------------------- docs/solana-shreds-runbook.fr.md | 145 ------------------- docs/solana-shreds-runbook.it.md | 145 ------------------- docs/solana-shreds-runbook.ja.md | 144 ------------------- docs/solana-shreds-runbook.ko.md | 144 ------------------- docs/solana-shreds-runbook.pt.md | 145 ------------------- docs/solana-shreds-runbook.zh.md | 144 ------------------- scripts/translate.py | 6 + 30 files changed, 8 insertions(+), 2905 deletions(-) delete mode 100644 docs/runbooks.es.md delete mode 100644 docs/runbooks.fr.md delete mode 100644 docs/runbooks.it.md delete mode 100644 docs/runbooks.ja.md delete mode 100644 docs/runbooks.ko.md delete mode 100644 docs/runbooks.pt.md delete mode 100644 docs/runbooks.zh.md delete mode 100644 docs/solana-ibrl-runbook.es.md delete mode 100644 docs/solana-ibrl-runbook.fr.md delete mode 100644 docs/solana-ibrl-runbook.it.md delete mode 100644 docs/solana-ibrl-runbook.ja.md delete mode 100644 docs/solana-ibrl-runbook.ko.md delete mode 100644 docs/solana-ibrl-runbook.pt.md delete mode 100644 docs/solana-ibrl-runbook.zh.md delete mode 100644 docs/solana-shreds-publisher-runbook.es.md delete mode 100644 docs/solana-shreds-publisher-runbook.fr.md delete mode 100644 docs/solana-shreds-publisher-runbook.it.md delete mode 100644 docs/solana-shreds-publisher-runbook.ja.md delete mode 100644 docs/solana-shreds-publisher-runbook.ko.md delete mode 100644 docs/solana-shreds-publisher-runbook.pt.md delete mode 100644 docs/solana-shreds-publisher-runbook.zh.md delete mode 100644 docs/solana-shreds-runbook.es.md delete mode 100644 docs/solana-shreds-runbook.fr.md delete mode 100644 docs/solana-shreds-runbook.it.md delete mode 100644 docs/solana-shreds-runbook.ja.md delete mode 100644 docs/solana-shreds-runbook.ko.md delete mode 100644 docs/solana-shreds-runbook.pt.md delete mode 100644 docs/solana-shreds-runbook.zh.md diff --git a/.github/workflows/translate.yml b/.github/workflows/translate.yml index d631c13..21983fd 100644 --- a/.github/workflows/translate.yml +++ b/.github/workflows/translate.yml @@ -39,9 +39,11 @@ jobs: run: | BASE="${{ github.event.pull_request.base.sha }}" # Only source .md files — exclude already-translated ones (e.g. index.es.md) + # and MCP runbooks (git/raw only, not on the public site). CHANGED=$(git diff --name-only "$BASE" HEAD -- docs/ \ | grep '\.md$' \ | grep -vE '\.[a-z]{2,3}\.md$' \ + | grep -vE '(^|/)runbooks\.md$|(^|/).*-runbook\.md$' \ || true) echo "Source files changed:" echo "$CHANGED" diff --git a/docs/runbooks.es.md b/docs/runbooks.es.md deleted file mode 100644 index 1212702..0000000 --- a/docs/runbooks.es.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -description: Índice legible por máquinas de runbooks de incorporación para el DoubleZero MCP. No está vinculado en la navegación de la documentación. -search: - exclude: true ---- - -# Runbooks - -El DoubleZero MCP carga este archivo desde GitHub raw -(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`) -para descubrir guías paso a paso. Los usuarios utilizan [Conecta tu IA](mcp.md); no agregue esta -página a la navegación del sitio. - -Para registrar un runbook, agregue un elemento de lista bajo **Índice** con esta estructura: - -```markdown -- `service-id` — [Título legible](page-slug.md) -``` - -## Índice - -- `solana-ibrl` — [Conectar validador (IBRL Mainnet)](solana-ibrl-runbook.md) -- `solana-shreds-publisher` — [Publicar shreds (Edge)](solana-shreds-publisher-runbook.md) -- `solana-shreds` — [Suscribirse a shreds (Edge)](solana-shreds-runbook.md) \ No newline at end of file diff --git a/docs/runbooks.fr.md b/docs/runbooks.fr.md deleted file mode 100644 index 3521b9e..0000000 --- a/docs/runbooks.fr.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -description: Index lisible par machine des runbooks d'intégration pour le MCP DoubleZero. Non lié dans la navigation de la documentation. -search: - exclude: true ---- - -# Runbooks - -Le MCP DoubleZero charge ce fichier depuis GitHub raw -(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`) -pour découvrir les guides pas à pas. Les utilisateurs consultent [Connecter votre IA](mcp.md) ; n'ajoutez pas cette -page à la navigation du site. - -Pour enregistrer un runbook, ajoutez un élément de liste sous **Index** dans ce format : - -```markdown -- `service-id` — [Titre lisible](page-slug.md) -``` - -## Index - -- `solana-ibrl` — [Connecter un validateur (IBRL Mainnet)](solana-ibrl-runbook.md) -- `solana-shreds-publisher` — [Publier des shreds (Edge)](solana-shreds-publisher-runbook.md) -- `solana-shreds` — [S'abonner aux shreds (Edge)](solana-shreds-runbook.md) \ No newline at end of file diff --git a/docs/runbooks.it.md b/docs/runbooks.it.md deleted file mode 100644 index 47489d1..0000000 --- a/docs/runbooks.it.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -description: Indice leggibile dalle macchine dei runbook di onboarding per il DoubleZero MCP. Non collegato nella navigazione della documentazione. -search: - exclude: true ---- - -# Runbook - -Il DoubleZero MCP carica questo file dal raw di GitHub -(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`) -per individuare le procedure guidate. Gli utenti utilizzano [Connetti la tua AI](mcp.md); non aggiungere questa -pagina alla navigazione del sito. - -Per registrare un runbook, aggiungi un elemento alla lista sotto **Indice** con questa struttura: - -```markdown -- `service-id` — [Titolo leggibile](page-slug.md) -``` - -## Indice - -- `solana-ibrl` — [Connetti il validatore (IBRL Mainnet)](solana-ibrl-runbook.md) -- `solana-shreds-publisher` — [Pubblica shreds (Edge)](solana-shreds-publisher-runbook.md) -- `solana-shreds` — [Iscriviti agli shreds (Edge)](solana-shreds-runbook.md) \ No newline at end of file diff --git a/docs/runbooks.ja.md b/docs/runbooks.ja.md deleted file mode 100644 index 3690a20..0000000 --- a/docs/runbooks.ja.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: DoubleZero MCP のオンボーディングランブックの機械可読インデックス。ドキュメントナビゲーションにはリンクされていません。 -search: - exclude: true ---- - -# ランブック - -DoubleZero MCP は GitHub raw からこのファイルを読み込みます -(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`)。 -これによりウォークスルーを検出します。人間の方は [AI を接続する](mcp.md) をご利用ください。このページをサイトナビゲーションに追加しないでください。 - -ランブックを登録するには、**Index** の下に以下の形式でリスト項目を追加してください： - -```markdown -- `service-id` — [Human title](page-slug.md) -``` - -## インデックス - -- `solana-ibrl` — [バリデーターを接続する (IBRL Mainnet)](solana-ibrl-runbook.md) -- `solana-shreds-publisher` — [シュレッドを公開する (Edge)](solana-shreds-publisher-runbook.md) -- `solana-shreds` — [シュレッドを購読する (Edge)](solana-shreds-runbook.md) \ No newline at end of file diff --git a/docs/runbooks.ko.md b/docs/runbooks.ko.md deleted file mode 100644 index 8af7593..0000000 --- a/docs/runbooks.ko.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: DoubleZero MCP용 온보딩 런북의 기계 판독 가능 인덱스. 문서 탐색에 링크되지 않습니다. -search: - exclude: true ---- - -# 런북 - -DoubleZero MCP는 GitHub raw에서 이 파일을 로드합니다 -(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`) -워크스루를 검색하기 위해 사용됩니다. 사용자는 [AI 연결하기](mcp.md)를 이용하세요; 이 페이지를 사이트 탐색에 추가하지 마세요. - -런북을 등록하려면 **인덱스** 아래에 다음 형식으로 목록 항목을 추가하세요: - -```markdown -- `service-id` — [사람이 읽을 수 있는 제목](page-slug.md) -``` - -## 인덱스 - -- `solana-ibrl` — [밸리데이터 연결 (IBRL Mainnet)](solana-ibrl-runbook.md) -- `solana-shreds-publisher` — [Shreds 발행 (Edge)](solana-shreds-publisher-runbook.md) -- `solana-shreds` — [Shreds 구독 (Edge)](solana-shreds-runbook.md) \ No newline at end of file diff --git a/docs/runbooks.pt.md b/docs/runbooks.pt.md deleted file mode 100644 index 7b380f3..0000000 --- a/docs/runbooks.pt.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -description: Índice legível por máquina de runbooks de integração para o DoubleZero MCP. Não vinculado na navegação da documentação. -search: - exclude: true ---- - -# Runbooks - -O DoubleZero MCP carrega este arquivo a partir do GitHub raw -(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`) -para descobrir tutoriais passo a passo. Humanos usam [Conecte sua IA](mcp.md); não adicione esta -página à navegação do site. - -Para registrar um runbook, adicione um item de lista em **Índice** neste formato: - -```markdown -- `service-id` — [Título legível](page-slug.md) -``` - -## Índice - -- `solana-ibrl` — [Conectar validador (IBRL Mainnet)](solana-ibrl-runbook.md) -- `solana-shreds-publisher` — [Publicar shreds (Edge)](solana-shreds-publisher-runbook.md) -- `solana-shreds` — [Inscrever-se em shreds (Edge)](solana-shreds-runbook.md) \ No newline at end of file diff --git a/docs/runbooks.zh.md b/docs/runbooks.zh.md deleted file mode 100644 index 27c65de..0000000 --- a/docs/runbooks.zh.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: DoubleZero MCP 入门运行手册的机器可读索引。未在文档导航中链接。 -search: - exclude: true ---- - -# 运行手册 - -DoubleZero MCP 从 GitHub raw 加载此文件 -(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`) -以发现操作指南。用户请使用 [连接你的 AI](mcp.md)；请勿将此页面添加到站点导航中。 - -要注册一个运行手册，请在 **索引** 下按以下格式添加一个列表项： - -```markdown -- `service-id` — [Human title](page-slug.md) -``` - -## 索引 - -- `solana-ibrl` — [连接验证者（IBRL 主网）](solana-ibrl-runbook.md) -- `solana-shreds-publisher` — [发布 shreds（Edge）](solana-shreds-publisher-runbook.md) -- `solana-shreds` — [订阅 shreds（Edge）](solana-shreds-runbook.md) \ No newline at end of file diff --git a/docs/solana-ibrl-runbook.es.md b/docs/solana-ibrl-runbook.es.md deleted file mode 100644 index 18acbab..0000000 --- a/docs/solana-ibrl-runbook.es.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -description: Runbook orientado a LLM — conectar un validador de Solana Mainnet-Beta a DoubleZero en modo IBRL. Servido al MCP a través de GitHub raw; no se publica en el sitio de documentación. ---- - -# Conectar validador (IBRL Mainnet) — runbook - -Esta página es para el MCP de DoubleZero (`get_onboarding_runbook`) a través de GitHub raw. No se publica en el sitio de documentación. - -1. Conecta el [MCP de DoubleZero](mcp.md) (`https://data.doublezero.xyz/api/mcp`). -2. Indícale que se trata de un **validador de Solana Mainnet-Beta**, el host Linux (o SSH), y dónde se encuentra el keypair de identidad del validador. -3. Sigue los pasos a continuación en orden. ¿Prefieres hacerlo manualmente? Usa la [guía para humanos](DZ Mainnet-beta Connection.md). - -**Cómo se ve el éxito:** `doublezero status` muestra el túnel **up**, User Type **IBRL**, Network **mainnet-beta**. `Tunnel src` y `Doublezero IP` coinciden con la IPv4 pública del host. - -IBRL no requiere reiniciar los clientes del validador; utiliza la IP pública existente. - ---- - -## Requisitos previos - -| Necesario | Notas | -|------|--------| -| Host Linux/amd64 | Instala DoubleZero **en el host del validador**, no en un contenedor. | -| IPv4 pública, sin NAT | La IP de gossip debe coincidir con este host. | -| Solana CLI en `$PATH` | Para `solana sign-offchain-message`. | -| Keypair de identidad del validador | Legible por el usuario que ejecuta los comandos (a menudo bajo el usuario `sol`). | -| ≥1 SOL en la identidad | Passport / solicitud onchain. | -| GRE (protocolo IP 47) + BGP | BGP en `169.254.0.0/16` tcp/179. | -| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` (o equivalente de la distribución). | - -El Validator ID se verifica contra el gossip de Solana para determinar la IP de destino. Un ID inválido en la misma IP se ignora; solo se utiliza el ID primario en gossip. - ---- - -## Pasos - -### 1. Instalar el cliente - -Sigue [setup](setup.md) si `doublezero` no está instalado. Paquetes para mainnet: - -```bash -curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash -sudo apt-get install doublezero -``` - -Rocky / RHEL: usa `setup.rpm.sh` y `sudo yum install doublezero`. - -**Verificar:** `sudo systemctl status doublezerod` está activo. Haz una copia de seguridad de `~/.config/doublezero/id.json`. - -### 2. Apuntar el daemon a mainnet-beta - -```bash -DESIRED_DOUBLEZERO_ENV=mainnet-beta \ - && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ - && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ - && sudo systemctl daemon-reload \ - && sudo systemctl restart doublezerod \ - && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ - && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" -``` - -Espera ~30s, luego `doublezero latency` debería listar los dispositivos de mainnet. - -### 3. Abrir UDP 44880 en `doublezero0` - -```bash -sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT -``` - -UFW: `sudo ufw allow in on doublezero0 to any port 44880 proto udp` y la regla `out` correspondiente. También permite GRE y BGP como se indica en [setup](setup.md). - -### 4. Confirmar el ID de DoubleZero y el validador primario - -El ID de DoubleZero del setup en el **primario** debe estar en cada respaldo (`~/.config/doublezero/id.json`). - -```bash -doublezero address -doublezero-solana passport find-validator -u mainnet-beta -``` - -Se espera del primario: en gossip, en el leader schedule, "can connect as a primary". En los respaldos, ejecuta el mismo `find-validator`; **no** deberían estar programados como leader. - -Si solo hay una máquina: omite `--backup-validator-ids` / `backup_ids=` en los comandos posteriores. - -### 5. Preparar el mensaje de acceso (primario) - -En el primario (con stake activo, identidad en gossip): - -```bash -doublezero-solana passport prepare-validator-access -u mainnet-beta \ - --doublezero-address \ - --primary-validator-id \ - --backup-validator-ids ,, -``` - -Omite `--backup-validator-ids` si no hay respaldos (máximo 3). Copia la línea `solana sign-offchain-message …` de la salida. - -### 6. Firmar con la clave de identidad del validador - -En el primario, ejecuta el comando impreso (keypair de identidad, **no** solo la clave de DoubleZero): - -```bash -solana sign-offchain-message \ - service_key=,backup_ids=,, \ - -k -``` - -**Produce:** una cadena de firma. Llévala al siguiente paso. - -### 7. Solicitar acceso de validador - -```bash -doublezero-solana passport request-validator-access -k -u mainnet-beta \ - --primary-validator-id \ - --backup-validator-ids ,, \ - --signature \ - --doublezero-address -``` - -Espera a que Sentinel valide y cree el pase de acceso. Opcional: el agente puede llamar a **`check_edge_access`** con `pubkey` (`doublezero address`) y la IP pública del host hasta que el pase esté presente. - -### 8. Conectar IBRL - -```bash -doublezero connect ibrl -``` - -Espera ~1 minuto para GRE. Hasta entonces, el estado puede ser `down` / `Unknown`. - -```bash -doublezero status -``` - -**Correcto:** `up`, User Type `IBRL`, Network `mainnet-beta`, túnel típicamente `doublezero0`. - -```bash -ip route -``` - -Se esperan rutas aprendidas por BGP a través de `doublezero0`. - ---- - -## Problemas comunes - -1. **Entorno incorrecto.** Los paquetes de testnet / `DESIRED_DOUBLEZERO_ENV=testnet` no funcionarán en mainnet-beta. -2. **La identidad no está en gossip.** Los IDs inválidos en la misma IP no pueden registrar la máquina. -3. **Los respaldos deben compartir el ID de DoubleZero del primario.** Copia `id.json`; no generes una segunda identidad con keygen. -4. **Firma con la identidad del validador**, no con la clave de DoubleZero. -5. **Estado down durante ~1 minuto** después de `connect ibrl` es normal mientras GRE se establece. - ---- - -## Ver también - -- [Conexión de Validador a Mainnet-Beta](DZ Mainnet-beta Connection.md) -- [Setup](setup.md) -- Siguiente: [Publicar shreds (Edge)](solana-shreds-publisher-runbook.md) \ No newline at end of file diff --git a/docs/solana-ibrl-runbook.fr.md b/docs/solana-ibrl-runbook.fr.md deleted file mode 100644 index a8e03d8..0000000 --- a/docs/solana-ibrl-runbook.fr.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -description: Runbook orienté LLM — connecter un validateur Solana Mainnet-Beta à DoubleZero en mode IBRL. Servi au MCP via GitHub raw ; non publié sur le site de documentation. ---- - -# Connecter un validateur (IBRL Mainnet) — runbook - -Cette page est destinée au DoubleZero MCP (`get_onboarding_runbook`) via GitHub raw. Elle n'est -pas publiée sur le site de documentation. - -1. Connectez le [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). -2. Indiquez-lui qu'il s'agit d'un **validateur Solana Mainnet-Beta**, l'hôte Linux (ou SSH), et l'emplacement du keypair d'identité du validateur. -3. Suivez les étapes ci-dessous dans l'ordre. Vous préférez le faire manuellement ? Utilisez le [guide pour humains](DZ Mainnet-beta Connection.md). - -**À quoi ressemble le succès :** `doublezero status` affiche le tunnel **up**, User Type **IBRL**, Network **mainnet-beta**. `Tunnel src` et `Doublezero IP` correspondent à l'IPv4 publique de l'hôte. - -IBRL ne nécessite pas de redémarrer les clients validateurs ; il utilise l'IP publique existante. - ---- - -## Prérequis - -| Besoin | Notes | -|--------|--------| -| Hôte Linux/amd64 | Installez DoubleZero **sur l'hôte du validateur**, pas dans un conteneur. | -| IPv4 publique, pas de NAT | L'IP de gossip doit correspondre à cet hôte. | -| Solana CLI dans le `$PATH` | Pour `solana sign-offchain-message`. | -| Keypair d'identité du validateur | Lisible par l'utilisateur exécutant les commandes (souvent sous l'utilisateur `sol`). | -| ≥1 SOL sur l'identité | Passport / requête onchain. | -| GRE (protocole IP 47) + BGP | BGP sur `169.254.0.0/16` tcp/179. | -| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` (ou équivalent pour votre distribution). | - -Le Validator ID est vérifié par rapport au gossip Solana pour déterminer l'IP cible. Un ID invalide sur la même IP est ignoré ; seul l'ID principal dans le gossip est utilisé. - ---- - -## Étapes - -### 1. Installer le client - -Suivez [setup](setup.md) si `doublezero` n'est pas installé. Paquets mainnet : - -```bash -curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash -sudo apt-get install doublezero -``` - -Rocky / RHEL : utilisez `setup.rpm.sh` et `sudo yum install doublezero`. - -**Vérification :** `sudo systemctl status doublezerod` est actif. Sauvegardez `~/.config/doublezero/id.json`. - -### 2. Pointer le daemon vers mainnet-beta - -```bash -DESIRED_DOUBLEZERO_ENV=mainnet-beta \ - && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ - && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ - && sudo systemctl daemon-reload \ - && sudo systemctl restart doublezerod \ - && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ - && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" -``` - -Attendez ~30s, puis `doublezero latency` devrait lister les appareils mainnet. - -### 3. Ouvrir le port UDP 44880 sur `doublezero0` - -```bash -sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT -``` - -UFW : `sudo ufw allow in on doublezero0 to any port 44880 proto udp` et la règle `out` correspondante. Autorisez également GRE et BGP comme indiqué dans [setup](setup.md). - -### 4. Confirmer l'ID DoubleZero et le validateur principal - -L'ID DoubleZero issu du setup sur le **principal** doit être présent sur chaque backup (`~/.config/doublezero/id.json`). - -```bash -doublezero address -doublezero-solana passport find-validator -u mainnet-beta -``` - -Résultat attendu pour le principal : présent dans le gossip, dans le planning de leader, "can connect as a primary". Sur les backups, exécutez le même `find-validator` ; ils ne devraient **pas** être dans le planning de leader. - -Machine unique : omettez `--backup-validator-ids` / `backup_ids=` des commandes suivantes. - -### 5. Préparer le message d'accès (principal) - -Sur le principal (stake actif, identité dans le gossip) : - -```bash -doublezero-solana passport prepare-validator-access -u mainnet-beta \ - --doublezero-address \ - --primary-validator-id \ - --backup-validator-ids ,, -``` - -Omettez `--backup-validator-ids` s'il n'y a pas de backups (max 3). Copiez la ligne `solana sign-offchain-message …` depuis la sortie. - -### 6. Signer avec la clé d'identité du validateur - -Sur le principal, exécutez la commande affichée (keypair d'identité, **pas** uniquement la clé DoubleZero) : - -```bash -solana sign-offchain-message \ - service_key=,backup_ids=,, \ - -k -``` - -**Produit :** une chaîne de signature. Conservez-la pour l'étape suivante. - -### 7. Demander l'accès validateur - -```bash -doublezero-solana passport request-validator-access -k -u mainnet-beta \ - --primary-validator-id \ - --backup-validator-ids ,, \ - --signature \ - --doublezero-address -``` - -Attendez que Sentinel valide et crée le pass d'accès. Optionnel : l'agent peut appeler **`check_edge_access`** avec `pubkey` (`doublezero address`) et l'IP publique de l'hôte jusqu'à ce que le pass soit présent. - -### 8. Connecter IBRL - -```bash -doublezero connect ibrl -``` - -Attendez ~1 minute pour le GRE. Jusque-là, le statut peut être `down` / `Unknown`. - -```bash -doublezero status -``` - -**Succès :** `up`, User Type `IBRL`, Network `mainnet-beta`, tunnel typiquement `doublezero0`. - -```bash -ip route -``` - -Attendez-vous à voir des routes apprises par BGP via `doublezero0`. - ---- - -## Pièges courants - -1. **Mauvais environnement.** Les paquets testnet / `DESIRED_DOUBLEZERO_ENV=testnet` ne fonctionneront pas sur mainnet-beta. -2. **Identité absente du gossip.** Les IDs invalides sur la même IP ne peuvent pas enregistrer la machine. -3. **Les backups doivent partager l'ID DoubleZero du principal.** Copiez `id.json` ; ne générez pas une seconde identité avec keygen. -4. **Signez avec l'identité du validateur**, pas avec la clé DoubleZero. -5. **Statut down pendant ~1 minute** après `connect ibrl` est normal pendant que le GRE s'établit. - ---- - -## Voir aussi - -- [Connexion Validateur Mainnet-Beta](DZ Mainnet-beta Connection.md) -- [Setup](setup.md) -- Suivant : [Publier des shreds (Edge)](solana-shreds-publisher-runbook.md) \ No newline at end of file diff --git a/docs/solana-ibrl-runbook.it.md b/docs/solana-ibrl-runbook.it.md deleted file mode 100644 index 3a95838..0000000 --- a/docs/solana-ibrl-runbook.it.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -description: Runbook orientato agli LLM — collegare un validatore Solana Mainnet-Beta a DoubleZero in modalità IBRL. Fornito all'MCP tramite GitHub raw; non pubblicato sul sito della documentazione. ---- - -# Collegare un validatore (IBRL Mainnet) — runbook - -Questa pagina è destinata al DoubleZero MCP (`get_onboarding_runbook`) tramite GitHub raw. Non è -pubblicata sul sito della documentazione. - -1. Collegare il [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). -2. Indicare che si tratta di un **validatore Solana Mainnet-Beta**, l'host Linux (o SSH) e dove si trova il keypair dell'identità del validatore. -3. Seguire i passaggi sottostanti in ordine. Si preferisce procedere manualmente? Utilizzare la [guida per operatori](DZ Mainnet-beta Connection.md). - -**Come si presenta il successo:** `doublezero status` mostra il tunnel **up**, User Type **IBRL**, Network **mainnet-beta**. `Tunnel src` e `Doublezero IP` corrispondono all'IPv4 pubblico dell'host. - -IBRL non richiede il riavvio dei client del validatore; utilizza l'IP pubblico esistente. - ---- - -## Prerequisiti - -| Necessario | Note | -|------|--------| -| Host Linux/amd64 | Installare DoubleZero **sull'host del validatore**, non in un container. | -| IPv4 pubblico, senza NAT | L'IP di gossip deve corrispondere a questo host. | -| Solana CLI nel `$PATH` | Per `solana sign-offchain-message`. | -| Keypair dell'identità del validatore | Leggibile dall'utente che esegue i comandi (spesso sotto l'utente `sol`). | -| ≥1 SOL sull'identità | Passport / richiesta onchain. | -| GRE (protocollo IP 47) + BGP | BGP su `169.254.0.0/16` tcp/179. | -| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` (o equivalente per la distribuzione). | - -L'ID del Validatore viene verificato rispetto al gossip di Solana per determinare l'IP di destinazione. Un ID fasullo sullo stesso IP viene ignorato; solo l'ID primario nel gossip viene utilizzato. - ---- - -## Passaggi - -### 1. Installare il client - -Seguire [setup](setup.md) se `doublezero` non è installato. Pacchetti mainnet: - -```bash -curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash -sudo apt-get install doublezero -``` - -Rocky / RHEL: utilizzare `setup.rpm.sh` e `sudo yum install doublezero`. - -**Verifica:** `sudo systemctl status doublezerod` è attivo. Effettuare un backup di `~/.config/doublezero/id.json`. - -### 2. Configurare il daemon per mainnet-beta - -```bash -DESIRED_DOUBLEZERO_ENV=mainnet-beta \ - && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ - && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ - && sudo systemctl daemon-reload \ - && sudo systemctl restart doublezerod \ - && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ - && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" -``` - -Attendere ~30 secondi, poi `doublezero latency` dovrebbe elencare i dispositivi mainnet. - -### 3. Aprire la porta UDP 44880 su `doublezero0` - -```bash -sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT -``` - -UFW: `sudo ufw allow in on doublezero0 to any port 44880 proto udp` e la corrispondente regola `out`. Consentire anche GRE e BGP come indicato in [setup](setup.md). - -### 4. Confermare l'ID DoubleZero e il validatore primario - -L'ID DoubleZero dal setup sul **primario** deve essere presente su ogni backup (`~/.config/doublezero/id.json`). - -```bash -doublezero address -doublezero-solana passport find-validator -u mainnet-beta -``` - -Aspettarsi il primario: presente nel gossip, nella schedule dei leader, "can connect as a primary". Sui backup, eseguire lo stesso `find-validator`; **non** dovrebbero essere nella schedule dei leader. - -Una sola macchina: omettere `--backup-validator-ids` / `backup_ids=` dai comandi successivi. - -### 5. Preparare il messaggio di accesso (primario) - -Sul primario (stake attivo, identità nel gossip): - -```bash -doublezero-solana passport prepare-validator-access -u mainnet-beta \ - --doublezero-address \ - --primary-validator-id \ - --backup-validator-ids ,, -``` - -Omettere `--backup-validator-ids` se non ci sono backup (massimo 3). Copiare la riga `solana sign-offchain-message …` dall'output. - -### 6. Firmare con la chiave di identità del validatore - -Sul primario, eseguire il comando stampato (keypair dell'identità, **non** solo la chiave DoubleZero): - -```bash -solana sign-offchain-message \ - service_key=,backup_ids=,, \ - -k -``` - -**Produce:** una stringa di firma. Portarla nel passaggio successivo. - -### 7. Richiedere l'accesso validatore - -```bash -doublezero-solana passport request-validator-access -k -u mainnet-beta \ - --primary-validator-id \ - --backup-validator-ids ,, \ - --signature \ - --doublezero-address -``` - -Attendere che Sentinel validi e crei il pass di accesso. Facoltativo: l'agente può chiamare **`check_edge_access`** con `pubkey` (`doublezero address`) e l'IP pubblico dell'host finché il pass non è presente. - -### 8. Connettere IBRL - -```bash -doublezero connect ibrl -``` - -Attendere ~1 minuto per il GRE. Fino ad allora, lo stato potrebbe essere `down` / `Unknown`. - -```bash -doublezero status -``` - -**Superato:** `up`, User Type `IBRL`, Network `mainnet-beta`, tunnel tipicamente `doublezero0`. - -```bash -ip route -``` - -Aspettarsi route apprese tramite BGP via `doublezero0`. - ---- - -## Insidie comuni - -1. **Ambiente errato.** Pacchetti testnet / `DESIRED_DOUBLEZERO_ENV=testnet` non funzioneranno su mainnet-beta. -2. **Identità non nel gossip.** ID fasulli sullo stesso IP non possono registrare la macchina. -3. **I backup devono condividere l'ID DoubleZero del primario.** Copiare `id.json`; non generare una seconda identità con keygen. -4. **Firmare con l'identità del validatore**, non con la chiave DoubleZero. -5. **Stato down per ~1 minuto** dopo `connect ibrl` è normale mentre il GRE si avvia. - ---- - -## Vedi anche - -- [Connessione Validatore Mainnet-Beta](DZ Mainnet-beta Connection.md) -- [Setup](setup.md) -- Successivo: [Pubblicare shred (Edge)](solana-shreds-publisher-runbook.md) \ No newline at end of file diff --git a/docs/solana-ibrl-runbook.ja.md b/docs/solana-ibrl-runbook.ja.md deleted file mode 100644 index 9b45914..0000000 --- a/docs/solana-ibrl-runbook.ja.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -description: LLM向けランブック — Solana Mainnet-BetaバリデーターをIBRLモードでDoubleZeroに接続します。GitHub raw経由でMCPに提供されます。ドキュメントサイトには公開されません。 ---- - -# バリデーター接続 (IBRL Mainnet) — ランブック - -このページはDoubleZero MCP (`get_onboarding_runbook`) 向けにGitHub raw経由で提供されています。ドキュメントサイトには公開されません。 - -1. [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`) を接続します。 -2. これが **Solana Mainnet-Beta バリデーター** であること、Linuxホスト（またはSSH）、およびバリデーターIDキーペアの場所を伝えてください。 -3. 以下のステップを順番に実行してください。手動で行いたい場合は、[人間向けガイド](DZ Mainnet-beta Connection.md)を使用してください。 - -**成功の基準:** `doublezero status` でトンネルが **up**、User Type が **IBRL**、Network が **mainnet-beta** と表示されること。`Tunnel src` と `Doublezero IP` がホストのパブリックIPv4と一致すること。 - -IBRLはバリデータークライアントの再起動を必要としません。既存のパブリックIPを使用します。 - ---- - -## 前提条件 - -| 必要なもの | 備考 | -|------|--------| -| Linux/amd64 ホスト | DoubleZeroはコンテナ内ではなく、**バリデーターホスト上に**インストールしてください。 | -| パブリックIPv4、NATなし | ゴシップIPがこのホストと一致する必要があります。 | -| `$PATH` 上のSolana CLI | `solana sign-offchain-message` に必要です。 | -| バリデーターIDキーペア | コマンドを実行するユーザーが読み取り可能であること（多くの場合 `sol` ユーザー配下）。 | -| ID上に1 SOL以上 | パスポート / オンチェーンリクエスト用。 | -| GRE (IPプロトコル47) + BGP | BGPは `169.254.0.0/16` tcp/179。 | -| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana`（またはディストリビューション相当のコマンド）。 | - -バリデーターIDはSolanaゴシップと照合され、ターゲットIPが決定されます。同じIP上のダミーIDは無視されます。ゴシップ内のプライマリIDのみが使用されます。 - ---- - -## ステップ - -### 1. クライアントのインストール - -`doublezero` がインストールされていない場合は、[セットアップ](setup.md)に従ってください。Mainnetパッケージ： - -```bash -curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash -sudo apt-get install doublezero -``` - -Rocky / RHEL: `setup.rpm.sh` を使用し、`sudo yum install doublezero` を実行してください。 - -**確認:** `sudo systemctl status doublezerod` がactiveであること。`~/.config/doublezero/id.json` をバックアップしてください。 - -### 2. デーモンをmainnet-betaに向ける - -```bash -DESIRED_DOUBLEZERO_ENV=mainnet-beta \ - && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ - && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ - && sudo systemctl daemon-reload \ - && sudo systemctl restart doublezerod \ - && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ - && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" -``` - -約30秒待ってから、`doublezero latency` でmainnetデバイスが一覧表示されるはずです。 - -### 3. `doublezero0` でUDP 44880を開放する - -```bash -sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT -``` - -UFWの場合: `sudo ufw allow in on doublezero0 to any port 44880 proto udp` および対応する `out` ルール。[セットアップ](setup.md)に記載のとおり、GREとBGPも許可してください。 - -### 4. DoubleZero IDとプライマリバリデーターの確認 - -セットアップ時の DoubleZero ID は、**プライマリ**のものがすべてのバックアップにも存在する必要があります（`~/.config/doublezero/id.json`）。 - -```bash -doublezero address -doublezero-solana passport find-validator -u mainnet-beta -``` - -プライマリについて以下を確認してください：ゴシップに存在する、リーダースケジュールに含まれている、「can connect as a primary」であること。バックアップでは同じ `find-validator` を実行し、リーダースケジュールに含まれて**いない**ことを確認してください。 - -マシンが1台のみの場合：以降のコマンドで `--backup-validator-ids` / `backup_ids=` を省略してください。 - -### 5. アクセスメッセージの準備（プライマリ） - -プライマリ上で実行してください（アクティブなステーク、ゴシップ内にIDが存在）： - -```bash -doublezero-solana passport prepare-validator-access -u mainnet-beta \ - --doublezero-address \ - --primary-validator-id \ - --backup-validator-ids ,, -``` - -バックアップがない場合は `--backup-validator-ids` を省略してください（最大3つ）。出力から `solana sign-offchain-message …` の行をコピーしてください。 - -### 6. バリデーターIDキーで署名する - -プライマリ上で、出力されたコマンドを実行してください（IDキーペアを使用し、DoubleZeroキー**だけ**ではありません）： - -```bash -solana sign-offchain-message \ - service_key=,backup_ids=,, \ - -k -``` - -**出力:** 署名文字列。次のステップに使用してください。 - -### 7. バリデーターアクセスのリクエスト - -```bash -doublezero-solana passport request-validator-access -k -u mainnet-beta \ - --primary-validator-id \ - --backup-validator-ids ,, \ - --signature \ - --doublezero-address -``` - -Sentinelが検証しアクセスパスを作成するのを待ちます。オプション：エージェントは `pubkey`（`doublezero address`）とホストのパブリックIPを使用して、パスが存在するまで **`check_edge_access`** を呼び出すことができます。 - -### 8. IBRL接続 - -```bash -doublezero connect ibrl -``` - -GREが確立するまで約1分待ちます。それまでステータスは `down` / `Unknown` と表示される場合があります。 - -```bash -doublezero status -``` - -**合格:** `up`、User Type `IBRL`、Network `mainnet-beta`、トンネルは通常 `doublezero0`。 - -```bash -ip route -``` - -`doublezero0` 経由のBGPで学習されたルートが表示されるはずです。 - ---- - -## 注意事項 - -1. **環境の間違い。** テストネットパッケージ / `DESIRED_DOUBLEZERO_ENV=testnet` ではmainnet-betaに接続できません。 -2. **IDがゴシップに存在しない。** 同じIP上のダミーIDではマシンを登録できません。 -3. **バックアップはプライマリのDoubleZero IDを共有する必要があります。** `id.json` をコピーしてください。2つ目のIDをkeygenしないでください。 -4. **バリデーターIDで署名してください。** DoubleZeroキーではありません。 -5. **`connect ibrl` 後の約1分間のステータスdown** はGREが確立するまでの正常な動作です。 - ---- - -## 関連項目 - -- [バリデーター Mainnet-Beta 接続](DZ Mainnet-beta Connection.md) -- [セットアップ](setup.md) -- 次へ: [シュレッド公開 (Edge)](solana-shreds-publisher-runbook.md) \ No newline at end of file diff --git a/docs/solana-ibrl-runbook.ko.md b/docs/solana-ibrl-runbook.ko.md deleted file mode 100644 index 9226200..0000000 --- a/docs/solana-ibrl-runbook.ko.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -description: LLM 지향 런북 — Solana Mainnet-Beta 밸리데이터를 IBRL 모드로 DoubleZero에 연결합니다. GitHub raw를 통해 MCP에 제공되며, 문서 사이트에는 게시되지 않습니다. ---- - -# 밸리데이터 연결 (IBRL Mainnet) — 런북 - -이 페이지는 GitHub raw를 통해 DoubleZero MCP(`get_onboarding_runbook`)용으로 작성되었습니다. 문서 사이트에는 게시되지 않습니다. - -1. [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`)를 연결합니다. -2. **Solana Mainnet-Beta 밸리데이터**, Linux 호스트(또는 SSH), 밸리데이터 아이덴티티 키페어의 위치를 알려줍니다. -3. 아래 단계를 순서대로 진행합니다. 수동으로 하고 싶으신가요? [사람용 가이드](DZ Mainnet-beta Connection.md)를 사용하세요. - -**성공 시 모습:** `doublezero status`에서 터널 **up**, User Type **IBRL**, Network **mainnet-beta**가 표시됩니다. `Tunnel src`와 `Doublezero IP`가 호스트의 공인 IPv4와 일치합니다. - -IBRL은 밸리데이터 클라이언트 재시작이 필요 없으며, 기존 공인 IP를 사용합니다. - ---- - -## 사전 요구 사항 - -| 필요 항목 | 참고 | -|------|--------| -| Linux/amd64 호스트 | DoubleZero를 컨테이너가 아닌 **밸리데이터 호스트에** 설치합니다. | -| 공인 IPv4, NAT 없음 | Gossip IP가 이 호스트와 일치해야 합니다. | -| `$PATH`에 Solana CLI | `solana sign-offchain-message`용. | -| 밸리데이터 아이덴티티 키페어 | 명령을 실행하는 사용자가 읽을 수 있어야 합니다(보통 `sol` 사용자 아래). | -| 아이덴티티에 ≥1 SOL | Passport / 온체인 요청용. | -| GRE (IP proto 47) + BGP | BGP는 `169.254.0.0/16` tcp/179에서. | -| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` (또는 배포판에 맞는 동등 명령). | - -Validator ID는 Solana gossip과 대조하여 대상 IP를 결정합니다. 같은 IP에 있는 잘못된 ID는 무시됩니다. gossip에 있는 기본 ID만 사용됩니다. - ---- - -## 단계 - -### 1. 클라이언트 설치 - -`doublezero`가 설치되지 않은 경우 [설정](setup.md)을 따르세요. Mainnet 패키지: - -```bash -curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash -sudo apt-get install doublezero -``` - -Rocky / RHEL: `setup.rpm.sh`와 `sudo yum install doublezero`를 사용합니다. - -**확인:** `sudo systemctl status doublezerod`가 active 상태입니다. `~/.config/doublezero/id.json`을 백업하세요. - -### 2. 데몬을 mainnet-beta로 설정 - -```bash -DESIRED_DOUBLEZERO_ENV=mainnet-beta \ - && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ - && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ - && sudo systemctl daemon-reload \ - && sudo systemctl restart doublezerod \ - && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ - && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" -``` - -약 30초 대기 후 `doublezero latency`에서 mainnet 장치 목록이 표시되어야 합니다. - -### 3. `doublezero0`에서 UDP 44880 열기 - -```bash -sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT -``` - -UFW: `sudo ufw allow in on doublezero0 to any port 44880 proto udp` 및 일치하는 `out` 규칙을 추가합니다. [설정](setup.md)에 따라 GRE 및 BGP도 허용하세요. - -### 4. DoubleZero ID 및 기본 밸리데이터 확인 - -설정 시 생성된 DoubleZero ID가 **기본** 머신의 것이어야 하며, 모든 백업에 동일하게 존재해야 합니다(`~/.config/doublezero/id.json`). - -```bash -doublezero address -doublezero-solana passport find-validator -u mainnet-beta -``` - -기본 밸리데이터에서 예상되는 결과: gossip에 존재, 리더 스케줄에 포함, "can connect as a primary". 백업에서 동일한 `find-validator`를 실행하면 리더 스케줄에 포함되지 **않아야** 합니다. - -단일 머신인 경우: 이후 명령에서 `--backup-validator-ids` / `backup_ids=`를 생략합니다. - -### 5. 접근 메시지 준비 (기본) - -기본 밸리데이터(활성 스테이크, gossip에 아이덴티티 있음)에서: - -```bash -doublezero-solana passport prepare-validator-access -u mainnet-beta \ - --doublezero-address \ - --primary-validator-id \ - --backup-validator-ids ,, -``` - -백업이 없는 경우 `--backup-validator-ids`를 생략합니다(최대 3개). 출력에서 `solana sign-offchain-message …` 줄을 복사합니다. - -### 6. 밸리데이터 아이덴티티 키로 서명 - -기본 밸리데이터에서 출력된 명령을 실행합니다(아이덴티티 키페어, DoubleZero 키만이 **아닙니다**): - -```bash -solana sign-offchain-message \ - service_key=,backup_ids=,, \ - -k -``` - -**결과:** 서명 문자열이 생성됩니다. 다음 단계로 가져가세요. - -### 7. 밸리데이터 접근 요청 - -```bash -doublezero-solana passport request-validator-access -k -u mainnet-beta \ - --primary-validator-id \ - --backup-validator-ids ,, \ - --signature \ - --doublezero-address -``` - -Sentinel이 검증하고 접근 패스를 생성할 때까지 대기합니다. 선택 사항: 에이전트가 패스가 존재할 때까지 `pubkey`(`doublezero address`)와 호스트 공인 IP로 **`check_edge_access`**를 호출할 수 있습니다. - -### 8. IBRL 연결 - -```bash -doublezero connect ibrl -``` - -GRE가 올라올 때까지 약 1분 대기합니다. 그때까지 상태가 `down` / `Unknown`일 수 있습니다. - -```bash -doublezero status -``` - -**통과 조건:** `up`, User Type `IBRL`, Network `mainnet-beta`, 터널은 일반적으로 `doublezero0`. - -```bash -ip route -``` - -`doublezero0`를 통한 BGP 학습 경로가 표시되어야 합니다. - ---- - -## 주의 사항 - -1. **잘못된 환경.** Testnet 패키지 / `DESIRED_DOUBLEZERO_ENV=testnet`으로는 mainnet-beta에 연결되지 않습니다. -2. **gossip에 아이덴티티 없음.** 같은 IP에 있는 잘못된 ID로는 머신을 등록할 수 없습니다. -3. **백업은 기본 DoubleZero ID를 공유해야 합니다.** `id.json`을 복사하세요. 두 번째 아이덴티티를 keygen하지 마세요. -4. **밸리데이터 아이덴티티로 서명하세요**, DoubleZero 키가 아닙니다. -5. `connect ibrl` 후 **약 1분간 상태 down**은 GRE가 올라오는 동안 정상입니다. - ---- - -## 참고 - -- [밸리데이터 Mainnet-Beta 연결](DZ Mainnet-beta Connection.md) -- [설정](setup.md) -- 다음: [슈레드 퍼블리시 (Edge)](solana-shreds-publisher-runbook.md) \ No newline at end of file diff --git a/docs/solana-ibrl-runbook.pt.md b/docs/solana-ibrl-runbook.pt.md deleted file mode 100644 index 46255f4..0000000 --- a/docs/solana-ibrl-runbook.pt.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -description: Runbook orientado a LLM — conectar um validador Solana Mainnet-Beta ao DoubleZero em modo IBRL. Servido ao MCP via GitHub raw; não publicado no site de documentação. ---- - -# Conectar validador (IBRL Mainnet) — runbook - -Esta página é para o MCP do DoubleZero (`get_onboarding_runbook`) via GitHub raw. Ela -não é publicada no site de documentação. - -1. Conecte o [MCP do DoubleZero](mcp.md) (`https://data.doublezero.xyz/api/mcp`). -2. Informe que se trata de um **validador Solana Mainnet-Beta**, o host Linux (ou SSH), e onde está o keypair de identidade do validador. -3. Siga os passos abaixo em ordem. Prefere fazer manualmente? Use o [guia para humanos](DZ Mainnet-beta Connection.md). - -**Como é o sucesso:** `doublezero status` mostra o túnel como **up**, User Type **IBRL**, Network **mainnet-beta**. `Tunnel src` e `Doublezero IP` correspondem ao IPv4 público do host. - -IBRL não requer reiniciar os clientes do validador; ele usa o IP público existente. - ---- - -## Pré-requisitos - -| Necessário | Observações | -|------|--------| -| Host Linux/amd64 | Instale o DoubleZero **no host do validador**, não em um container. | -| IPv4 público, sem NAT | O IP de gossip deve corresponder a este host. | -| Solana CLI no `$PATH` | Para `solana sign-offchain-message`. | -| Keypair de identidade do validador | Legível pelo usuário que executa os comandos (geralmente sob o usuário `sol`). | -| ≥1 SOL na identidade | Passport / solicitação onchain. | -| GRE (protocolo IP 47) + BGP | BGP em `169.254.0.0/16` tcp/179. | -| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` (ou equivalente da distribuição). | - -O Validator ID é verificado contra o gossip da Solana para determinar o IP de destino. Um ID inválido no mesmo IP é ignorado; apenas o ID primário no gossip é utilizado. - ---- - -## Passos - -### 1. Instalar o cliente - -Siga o [setup](setup.md) se o `doublezero` não estiver instalado. Pacotes para mainnet: - -```bash -curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash -sudo apt-get install doublezero -``` - -Rocky / RHEL: use `setup.rpm.sh` e `sudo yum install doublezero`. - -**Verificação:** `sudo systemctl status doublezerod` está ativo. Faça backup de `~/.config/doublezero/id.json`. - -### 2. Apontar o daemon para mainnet-beta - -```bash -DESIRED_DOUBLEZERO_ENV=mainnet-beta \ - && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ - && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ - && sudo systemctl daemon-reload \ - && sudo systemctl restart doublezerod \ - && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ - && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" -``` - -Aguarde ~30s, então `doublezero latency` deve listar os dispositivos da mainnet. - -### 3. Abrir UDP 44880 em `doublezero0` - -```bash -sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT -``` - -UFW: `sudo ufw allow in on doublezero0 to any port 44880 proto udp` e a regra `out` correspondente. Também permita GRE e BGP conforme o [setup](setup.md). - -### 4. Confirmar o ID do DoubleZero e o validador primário - -O ID do DoubleZero obtido no setup do **primário** deve estar em cada backup (`~/.config/doublezero/id.json`). - -```bash -doublezero address -doublezero-solana passport find-validator -u mainnet-beta -``` - -Espere o primário: no gossip, no leader schedule, "can connect as a primary". Nos backups, execute o mesmo `find-validator`; eles **não** devem estar no leader schedule. - -Apenas uma máquina: omita `--backup-validator-ids` / `backup_ids=` dos comandos seguintes. - -### 5. Preparar a mensagem de acesso (primário) - -No primário (com stake ativo, identidade no gossip): - -```bash -doublezero-solana passport prepare-validator-access -u mainnet-beta \ - --doublezero-address \ - --primary-validator-id \ - --backup-validator-ids ,, -``` - -Omita `--backup-validator-ids` se não houver backups (máximo 3). Copie a linha `solana sign-offchain-message …` da saída. - -### 6. Assinar com a chave de identidade do validador - -No primário, execute o comando exibido (keypair de identidade, **não** apenas a chave do DoubleZero): - -```bash -solana sign-offchain-message \ - service_key=,backup_ids=,, \ - -k -``` - -**Produz:** uma string de assinatura. Leve-a para o próximo passo. - -### 7. Solicitar acesso de validador - -```bash -doublezero-solana passport request-validator-access -k -u mainnet-beta \ - --primary-validator-id \ - --backup-validator-ids ,, \ - --signature \ - --doublezero-address -``` - -Aguarde o Sentinel validar e criar o passe de acesso. Opcional: o agente pode chamar **`check_edge_access`** com `pubkey` (`doublezero address`) e o IP público do host até que o passe esteja presente. - -### 8. Conectar IBRL - -```bash -doublezero connect ibrl -``` - -Aguarde ~1 minuto para o GRE. Até lá, o status pode ser `down` / `Unknown`. - -```bash -doublezero status -``` - -**Sucesso:** `up`, User Type `IBRL`, Network `mainnet-beta`, túnel tipicamente `doublezero0`. - -```bash -ip route -``` - -Espere rotas aprendidas via BGP através de `doublezero0`. - ---- - -## Armadilhas - -1. **Ambiente errado.** Pacotes de testnet / `DESIRED_DOUBLEZERO_ENV=testnet` não funcionarão na mainnet-beta. -2. **Identidade não está no gossip.** IDs inválidos no mesmo IP não conseguem registrar a máquina. -3. **Backups devem compartilhar o ID do DoubleZero do primário.** Copie `id.json`; não gere uma segunda identidade com keygen. -4. **Assine com a identidade do validador**, não com a chave do DoubleZero. -5. **Status down por ~1 minuto** após `connect ibrl` é normal enquanto o GRE está sendo estabelecido. - ---- - -## Veja também - -- [Conexão de Validador Mainnet-Beta](DZ Mainnet-beta Connection.md) -- [Setup](setup.md) -- Próximo: [Publicar shreds (Edge)](solana-shreds-publisher-runbook.md) \ No newline at end of file diff --git a/docs/solana-ibrl-runbook.zh.md b/docs/solana-ibrl-runbook.zh.md deleted file mode 100644 index 08e67c7..0000000 --- a/docs/solana-ibrl-runbook.zh.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -description: 面向 LLM 的操作手册 — 以 IBRL 模式将 Solana Mainnet-Beta 验证者连接到 DoubleZero。通过 GitHub raw 提供给 MCP；不在文档站点上发布。 ---- - -# 连接验证者（IBRL Mainnet）— 操作手册 - -本页面供 DoubleZero MCP（`get_onboarding_runbook`）通过 GitHub raw 使用。不在文档站点上发布。 - -1. 连接 [DoubleZero MCP](mcp.md)（`https://data.doublezero.xyz/api/mcp`）。 -2. 告诉它这是一个 **Solana Mainnet-Beta 验证者**、Linux 主机（或 SSH），以及验证者身份密钥对的存放位置。 -3. 按顺序执行以下步骤。更倾向于手动操作？请使用[人工指南](DZ Mainnet-beta Connection.md)。 - -**成功的标志：** `doublezero status` 显示隧道为 **up**，User Type 为 **IBRL**，Network 为 **mainnet-beta**。`Tunnel src` 和 `Doublezero IP` 与主机的公网 IPv4 匹配。 - -IBRL 不需要重启验证者客户端；它使用现有的公网 IP。 - ---- - -## 前提条件 - -| 需求 | 备注 | -|------|--------| -| Linux/amd64 主机 | 在**验证者主机上**安装 DoubleZero，不要在容器中安装。 | -| 公网 IPv4，无 NAT | Gossip IP 必须与此主机匹配。 | -| `$PATH` 中有 Solana CLI | 用于 `solana sign-offchain-message`。 | -| 验证者身份密钥对 | 运行命令的用户可读（通常在 `sol` 用户下）。 | -| 身份账户上 ≥1 SOL | Passport / 链上请求所需。 | -| GRE（IP 协议 47）+ BGP | BGP 在 `169.254.0.0/16` tcp/179 上。 | -| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana`（或对应发行版的等效命令）。 | - -验证者 ID 会通过 Solana gossip 进行检查以确定目标 IP。同一 IP 上的无效 ID 会被忽略；仅使用 gossip 中的主 ID。 - ---- - -## 步骤 - -### 1. 安装客户端 - -如果尚未安装 `doublezero`，请参照 [setup](setup.md)。Mainnet 软件包： - -```bash -curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash -sudo apt-get install doublezero -``` - -Rocky / RHEL：使用 `setup.rpm.sh` 和 `sudo yum install doublezero`。 - -**验证：** `sudo systemctl status doublezerod` 状态为 active。备份 `~/.config/doublezero/id.json`。 - -### 2. 将守护进程指向 mainnet-beta - -```bash -DESIRED_DOUBLEZERO_ENV=mainnet-beta \ - && sudo mkdir -p /etc/systemd/system/doublezerod.service.d \ - && echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \ - && sudo systemctl daemon-reload \ - && sudo systemctl restart doublezerod \ - && doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \ - && echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV" -``` - -等待约 30 秒，然后 `doublezero latency` 应列出 mainnet 设备。 - -### 3. 在 `doublezero0` 上开放 UDP 44880 - -```bash -sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT -``` - -UFW：`sudo ufw allow in on doublezero0 to any port 44880 proto udp` 以及对应的 `out` 规则。同时按照 [setup](setup.md) 中的说明允许 GRE 和 BGP。 - -### 4. 确认 DoubleZero ID 和主验证者 - -setup 阶段在**主节点**上生成的 DoubleZero ID 必须存在于每个备用节点上（`~/.config/doublezero/id.json`）。 - -```bash -doublezero address -doublezero-solana passport find-validator -u mainnet-beta -``` - -预期主节点：在 gossip 中、在出块时间表中、"can connect as a primary"。在备用节点上运行相同的 `find-validator`；它们**不应该**在出块时间表中。 - -仅一台机器的情况：在后续命令中省略 `--backup-validator-ids` / `backup_ids=`。 - -### 5. 准备访问消息（主节点） - -在主节点（有活跃质押，身份在 gossip 中）上： - -```bash -doublezero-solana passport prepare-validator-access -u mainnet-beta \ - --doublezero-address \ - --primary-validator-id \ - --backup-validator-ids ,, -``` - -如果没有备用节点则省略 `--backup-validator-ids`（最多 3 个）。复制输出中的 `solana sign-offchain-message …` 行。 - -### 6. 使用验证者身份密钥签名 - -在主节点上运行输出的命令（身份密钥对，**不是**仅 DoubleZero 密钥）： - -```bash -solana sign-offchain-message \ - service_key=,backup_ids=,, \ - -k -``` - -**产出：** 一个签名字符串。将其带入下一步。 - -### 7. 请求验证者访问权限 - -```bash -doublezero-solana passport request-validator-access -k -u mainnet-beta \ - --primary-validator-id \ - --backup-validator-ids ,, \ - --signature \ - --doublezero-address -``` - -等待 Sentinel 验证并创建访问通行证。可选：代理可以使用 `pubkey`（`doublezero address`）和主机公网 IP 调用 **`check_edge_access`**，直到通行证出现。 - -### 8. 连接 IBRL - -```bash -doublezero connect ibrl -``` - -等待约 1 分钟以建立 GRE。在此之前，状态可能显示为 `down` / `Unknown`。 - -```bash -doublezero status -``` - -**通过标志：** `up`，User Type 为 `IBRL`，Network 为 `mainnet-beta`，隧道通常为 `doublezero0`。 - -```bash -ip route -``` - -预期看到通过 `doublezero0` 学习到的 BGP 路由。 - ---- - -## 常见问题 - -1. **环境错误。** Testnet 软件包 / `DESIRED_DOUBLEZERO_ENV=testnet` 不会连接到 mainnet-beta。 -2. **身份不在 gossip 中。** 同一 IP 上的无效 ID 无法注册该机器。 -3. **备用节点必须共享主节点的 DoubleZero ID。** 复制 `id.json`；不要用 keygen 生成第二个身份。 -4. **使用验证者身份密钥签名**，不是 DoubleZero 密钥。 -5. **`connect ibrl` 后状态 down 约 1 分钟**是正常的，GRE 正在建立中。 - ---- - -## 另请参阅 - -- [验证者 Mainnet-Beta 连接](DZ Mainnet-beta Connection.md) -- [安装配置](setup.md) -- 下一步：[发布 shreds（Edge）](solana-shreds-publisher-runbook.md) \ No newline at end of file diff --git a/docs/solana-shreds-publisher-runbook.es.md b/docs/solana-shreds-publisher-runbook.es.md deleted file mode 100644 index 38c9a58..0000000 --- a/docs/solana-shreds-publisher-runbook.es.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -description: Runbook orientado a LLM — configurar un validador de Solana conectado para publicar leader shreds en DoubleZero Edge. Se sirve al MCP a través de GitHub raw; no se publica en el sitio de documentación. ---- - -# Publicar shreds (Edge) — runbook - -Esta página es para el MCP de DoubleZero (`get_onboarding_runbook`) a través de GitHub raw. No se -publica en el sitio de documentación. - -1. Conectar el [MCP de DoubleZero](mcp.md) (`https://data.doublezero.xyz/api/mcp`). -2. Confirmar que el validador **ya está en DoubleZero IBRL** (mainnet-beta). Si no lo está, completar primero [Conectar validador (IBRL Mainnet)](solana-ibrl-runbook.md). -3. Seguir los pasos a continuación. Guía para humanos: [Validator Multicast Connection](Validator Multicast Connection.md). - -**Cómo se ve el éxito:** el validador envía leader shreds a `233.84.178.1:7733`, la publicación multicast en `edge-solana-shreds` está activa, y [publisher-check](https://data.doublezero.xyz/dz/publisher-check) muestra publicación después de al menos un leader slot. - -Esta ruta es para **validadores**. Las firmas de trading que desean *suscribirse* deben usar [Suscribirse a shreds](solana-shreds-runbook.md). - ---- - -## Requisitos previos - -| Necesario | Notas | -|-----------|-------| -| Túnel IBRL ya activo | [Runbook de IBRL Mainnet](solana-ibrl-runbook.md) / [guía para humanos](DZ Mainnet-beta Connection.md). | -| Cliente compatible | Jito-Agave **3.1.9+**, JitoBam 3.1.9+, Frankendancer, o Harmonic **3.1.11+**. Otras versiones no publicarán. | -| Ventana de reinicio | Agregar el destino de shreds requiere un reinicio del validador. | - ---- - -## Pasos - -### 1. Apuntar el cliente al grupo de shreds de Edge - -**Jito-Agave (v3.1.9+) y Harmonic (3.1.11+)** — en el script de inicio del validador agregar: - -```text ---shred-receiver-address 233.84.178.1:7733 -``` - -Se puede enviar a Jito y a `edge-solana-shreds` al mismo tiempo. Reiniciar el validador. - -**Frankendancer** — en `config.toml`: - -```toml -[tiles.shred] -additional_shred_destinations_leader = [ "233.84.178.1:7733", ] -``` - -Reiniciar el validador. - -### 2. Publicar en el grupo multicast - -```bash -doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds -``` - -**Verificar:** `doublezero status` sigue mostrando IBRL/up, y el usuario es publisher en `edge-solana-shreds`. - -IPs de grupos activos: `doublezero multicast group list`. Todos los feeds de shreds usan UDP **`7733`**; la IP selecciona el feed. - -| Feed | Dirección | -|------|-----------| -| `edge-solana-shreds` (leader) | `233.84.178.1:7733` | -| `edge-solana-retrans-eu` | `233.84.178.12:7733` | -| `edge-solana-retrans-apac` | `233.84.178.13:7733` | -| `edge-solana-retrans-amer` | `233.84.178.14:7733` | - -### 3. Confirmar la publicación - -Abrir [publisher-check](https://data.doublezero.xyz/dz/publisher-check). No se verá confirmación hasta que el validador haya publicado leader shreds durante **al menos un slot**. - -Saludable: picos de salida alineados con los leader slots (diente de sierra). Salida constante sin patrón de slots es **retransmit** (malo). - ---- - -## Problemas comunes - -1. **Versión incorrecta del cliente.** No es 3.1.9+ / 3.1.11+ → nada útil en el cable. -2. **Flag de retransmit dejado activo.** Eliminar `--shred-retransmit-receiver-address` de Jito-Agave. Verificar la columna **No Retransmit Shreds** en publisher-check (vistas de 2 épocas vs slot reciente). -3. **Aún no es leader.** El dashboard permanece vacío hasta un leader slot. -4. **IBRL no está activo.** No comenzar aquí; completar IBRL primero. - ---- - -## Ver también - -- [Validator Multicast Connection](Validator Multicast Connection.md) -- [Validator Rewards](Validator Rewards.md) \ No newline at end of file diff --git a/docs/solana-shreds-publisher-runbook.fr.md b/docs/solana-shreds-publisher-runbook.fr.md deleted file mode 100644 index 02cd27f..0000000 --- a/docs/solana-shreds-publisher-runbook.fr.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -description: Runbook orienté LLM — configurer un validateur Solana connecté pour publier les shreds leader vers DoubleZero Edge. Servi au MCP via GitHub raw ; non publié sur le site de documentation. ---- - -# Publier des shreds (Edge) — runbook - -Cette page est destinée au MCP DoubleZero (`get_onboarding_runbook`) via GitHub raw. Elle n'est -pas publiée sur le site de documentation. - -1. Connectez le [MCP DoubleZero](mcp.md) (`https://data.doublezero.xyz/api/mcp`). -2. Confirmez que le validateur est **déjà sur DoubleZero IBRL** (mainnet-beta). Si ce n'est pas le cas, terminez d'abord [Connecter un validateur (IBRL Mainnet)](solana-ibrl-runbook.md). -3. Suivez les étapes ci-dessous. Guide utilisateur : [Validator Multicast Connection](Validator Multicast Connection.md). - -**À quoi ressemble le succès :** le validateur envoie les shreds leader vers `233.84.178.1:7733`, la publication multicast sur `edge-solana-shreds` est active, et [publisher-check](https://data.doublezero.xyz/dz/publisher-check) indique la publication après au moins un slot leader. - -Ce parcours est destiné aux **validateurs**. Les sociétés de trading qui souhaitent *s'abonner* utilisent [S'abonner aux shreds](solana-shreds-runbook.md). - ---- - -## Prérequis - -| Besoin | Notes | -|--------|--------| -| Tunnel IBRL déjà actif | [Runbook IBRL Mainnet](solana-ibrl-runbook.md) / [guide utilisateur](DZ Mainnet-beta Connection.md). | -| Client supporté | Jito-Agave **3.1.9+**, JitoBam 3.1.9+, Frankendancer, ou Harmonic **3.1.11+**. Les autres versions ne publieront pas. | -| Fenêtre de redémarrage | L'ajout de la destination shred nécessite un redémarrage du validateur. | - ---- - -## Étapes - -### 1. Pointer le client vers le groupe shred Edge - -**Jito-Agave (v3.1.9+) et Harmonic (3.1.11+)** — dans le script de démarrage du validateur, ajoutez : - -```text ---shred-receiver-address 233.84.178.1:7733 -``` - -Vous pouvez envoyer vers Jito et `edge-solana-shreds` en même temps. Redémarrez le validateur. - -**Frankendancer** — dans `config.toml` : - -```toml -[tiles.shred] -additional_shred_destinations_leader = [ "233.84.178.1:7733", ] -``` - -Redémarrez le validateur. - -### 2. Publier sur le groupe multicast - -```bash -doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds -``` - -**Vérification :** `doublezero status` indique toujours IBRL/up, et l'utilisateur est bien un publisher sur `edge-solana-shreds`. - -IP des groupes en direct : `doublezero multicast group list`. Tous les flux shred utilisent UDP **`7733`** ; l'IP sélectionne le flux. - -| Flux | Adresse | -|------|---------| -| `edge-solana-shreds` (leader) | `233.84.178.1:7733` | -| `edge-solana-retrans-eu` | `233.84.178.12:7733` | -| `edge-solana-retrans-apac` | `233.84.178.13:7733` | -| `edge-solana-retrans-amer` | `233.84.178.14:7733` | - -### 3. Confirmer la publication - -Ouvrez [publisher-check](https://data.doublezero.xyz/dz/publisher-check). Vous ne verrez pas de confirmation tant que le validateur n'aura pas publié de shreds leader pendant **au moins un slot**. - -Normal : pics sortants alignés avec les slots leader (en dents de scie). Un flux sortant constant sans motif de slot est du **retransmit** (mauvais). - ---- - -## Pièges courants - -1. **Mauvaise version du client.** Pas 3.1.9+ / 3.1.11+ → rien d'utile sur le réseau. -2. **Flag retransmit laissé actif.** Supprimez `--shred-retransmit-receiver-address` de Jito-Agave. Vérifiez la colonne **No Retransmit Shreds** sur publisher-check (vues 2-epoch vs recent-slot). -3. **Pas encore leader.** Le tableau de bord reste vide jusqu'à un slot leader. -4. **IBRL non actif.** Ne commencez pas ici ; terminez d'abord IBRL. - ---- - -## Voir aussi - -- [Validator Multicast Connection](Validator Multicast Connection.md) -- [Validator Rewards](Validator Rewards.md) \ No newline at end of file diff --git a/docs/solana-shreds-publisher-runbook.it.md b/docs/solana-shreds-publisher-runbook.it.md deleted file mode 100644 index cc1148f..0000000 --- a/docs/solana-shreds-publisher-runbook.it.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -description: Runbook orientato agli LLM — configurare un validatore Solana connesso per pubblicare leader shred su DoubleZero Edge. Servito all'MCP tramite GitHub raw; non pubblicato sul sito della documentazione. ---- - -# Pubblicare shred (Edge) — runbook - -Questa pagina è destinata al DoubleZero MCP (`get_onboarding_runbook`) tramite GitHub raw. Non è -pubblicata sul sito della documentazione. - -1. Connettere il [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). -2. Verificare che il validatore sia **già su DoubleZero IBRL** (mainnet-beta). In caso contrario, completare prima [Connetti il validatore (IBRL Mainnet)](solana-ibrl-runbook.md). -3. Seguire i passaggi sottostanti. Guida per utenti: [Validator Multicast Connection](Validator Multicast Connection.md). - -**Risultato atteso in caso di successo:** il validatore invia leader shred a `233.84.178.1:7733`, la pubblicazione multicast su `edge-solana-shreds` è attiva, e [publisher-check](https://data.doublezero.xyz/dz/publisher-check) mostra la pubblicazione dopo almeno uno slot da leader. - -Questo percorso è per i **validatori**. Le società di trading che desiderano *sottoscrivere* utilizzano [Sottoscrivere gli shred](solana-shreds-runbook.md). - ---- - -## Prerequisiti - -| Necessario | Note | -|------|--------| -| Tunnel IBRL già attivo | [Runbook IBRL Mainnet](solana-ibrl-runbook.md) / [guida per utenti](DZ Mainnet-beta Connection.md). | -| Client supportato | Jito-Agave **3.1.9+**, JitoBam 3.1.9+, Frankendancer, o Harmonic **3.1.11+**. Altre versioni non pubblicheranno. | -| Finestra di riavvio | L'aggiunta della destinazione shred richiede un riavvio del validatore. | - ---- - -## Passaggi - -### 1. Puntare il client al gruppo shred di Edge - -**Jito-Agave (v3.1.9+) e Harmonic (3.1.11+)** — nello script di avvio del validatore aggiungere: - -```text ---shred-receiver-address 233.84.178.1:7733 -``` - -È possibile inviare contemporaneamente a Jito e a `edge-solana-shreds`. Riavviare il validatore. - -**Frankendancer** — in `config.toml`: - -```toml -[tiles.shred] -additional_shred_destinations_leader = [ "233.84.178.1:7733", ] -``` - -Riavviare il validatore. - -### 2. Pubblicare sul gruppo multicast - -```bash -doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds -``` - -**Verifica:** `doublezero status` mostra ancora IBRL/up, e l'utente è un publisher su `edge-solana-shreds`. - -IP dei gruppi attivi: `doublezero multicast group list`. Tutti i feed shred utilizzano UDP **`7733`**; l'IP seleziona il feed. - -| Feed | Indirizzo | -|------|---------| -| `edge-solana-shreds` (leader) | `233.84.178.1:7733` | -| `edge-solana-retrans-eu` | `233.84.178.12:7733` | -| `edge-solana-retrans-apac` | `233.84.178.13:7733` | -| `edge-solana-retrans-amer` | `233.84.178.14:7733` | - -### 3. Confermare la pubblicazione - -Aprire [publisher-check](https://data.doublezero.xyz/dz/publisher-check). La conferma non sarà visibile finché il validatore non avrà pubblicato leader shred per **almeno uno slot**. - -Stato sano: picchi in uscita allineati con gli slot da leader (a dente di sega). Un flusso in uscita costante senza schema legato agli slot indica **retransmit** (anomalo). - ---- - -## Insidie comuni - -1. **Versione del client errata.** Non 3.1.9+ / 3.1.11+ → nessun dato utile sul filo. -2. **Flag di retransmit lasciato attivo.** Rimuovere `--shred-retransmit-receiver-address` da Jito-Agave. Controllare la colonna **No Retransmit Shreds** su publisher-check (viste 2-epoch vs slot recenti). -3. **Non ancora leader.** La dashboard resta vuota fino a uno slot da leader. -4. **IBRL non attivo.** Non iniziare da qui; completare prima IBRL. - ---- - -## Vedi anche - -- [Validator Multicast Connection](Validator Multicast Connection.md) -- [Validator Rewards](Validator Rewards.md) \ No newline at end of file diff --git a/docs/solana-shreds-publisher-runbook.ja.md b/docs/solana-shreds-publisher-runbook.ja.md deleted file mode 100644 index ec9e381..0000000 --- a/docs/solana-shreds-publisher-runbook.ja.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -description: LLM 向けランブック — 接続済みの Solana バリデーターを設定し、リーダーシュレッドを DoubleZero Edge にパブリッシュします。GitHub raw 経由で MCP に提供されます。ドキュメントサイトには公開されません。 ---- - -# シュレッドのパブリッシュ (Edge) — ランブック - -このページは GitHub raw 経由で DoubleZero MCP (`get_onboarding_runbook`) 向けに提供されています。ドキュメントサイトには公開されません。 - -1. [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`) に接続します。 -2. バリデーターが**既に DoubleZero IBRL** (mainnet-beta) に接続されていることを確認します。まだの場合は、先に [バリデーター接続 (IBRL Mainnet)](solana-ibrl-runbook.md) を完了してください。 -3. 以下の手順を実行します。ヒューマンガイド: [Validator Multicast Connection](Validator Multicast Connection.md)。 - -**成功の状態:** バリデーターがリーダーシュレッドを `233.84.178.1:7733` に送信し、`edge-solana-shreds` でのマルチキャストパブリッシュが稼働しており、少なくとも1つのリーダースロット後に [publisher-check](https://data.doublezero.xyz/dz/publisher-check) でパブリッシュが確認できること。 - -このパスは**バリデーター**向けです。シュレッドを*サブスクライブ*したいトレーディングファームは [シュレッドのサブスクライブ](solana-shreds-runbook.md) を使用してください。 - ---- - -## 前提条件 - -| 必要なもの | 備考 | -|------|--------| -| IBRL トンネルが既に稼働していること | [IBRL Mainnet ランブック](solana-ibrl-runbook.md) / [ヒューマンガイド](DZ Mainnet-beta Connection.md)。 | -| サポートされているクライアント | Jito-Agave **3.1.9+**、JitoBam 3.1.9+、Frankendancer、または Harmonic **3.1.11+**。それ以外のバージョンではパブリッシュされません。 | -| 再起動ウィンドウ | シュレッド送信先の追加にはバリデーターの再起動が必要です。 | - ---- - -## 手順 - -### 1. クライアントを Edge シュレッドグループに向ける - -**Jito-Agave (v3.1.9+) および Harmonic (3.1.11+)** — バリデーター起動スクリプトに以下を追加します: - -```text ---shred-receiver-address 233.84.178.1:7733 -``` - -Jito と `edge-solana-shreds` に同時に送信できます。バリデーターを再起動してください。 - -**Frankendancer** — `config.toml` に以下を追加します: - -```toml -[tiles.shred] -additional_shred_destinations_leader = [ "233.84.178.1:7733", ] -``` - -バリデーターを再起動してください。 - -### 2. マルチキャストグループでパブリッシュする - -```bash -doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds -``` - -**確認:** `doublezero status` が引き続き IBRL/up であること、およびユーザーが `edge-solana-shreds` のパブリッシャーになっていること。 - -ライブグループ IP: `doublezero multicast group list`。すべてのシュレッドフィードは UDP **`7733`** を使用し、IP でフィードを選択します。 - -| フィード | アドレス | -|------|---------| -| `edge-solana-shreds` (リーダー) | `233.84.178.1:7733` | -| `edge-solana-retrans-eu` | `233.84.178.12:7733` | -| `edge-solana-retrans-apac` | `233.84.178.13:7733` | -| `edge-solana-retrans-amer` | `233.84.178.14:7733` | - -### 3. パブリッシュを確認する - -[publisher-check](https://data.doublezero.xyz/dz/publisher-check) を開きます。バリデーターが**少なくとも1スロット分**のリーダーシュレッドをパブリッシュするまで、確認は表示されません。 - -正常な状態: リーダースロットに合わせたアウトバウンドのスパイク（のこぎり波形）。スロットパターンのない一定のアウトバウンドは**リトランスミット**（不正）です。 - ---- - -## 注意事項 - -1. **クライアントバージョンの誤り。** 3.1.9+ / 3.1.11+ でない場合 → ワイヤー上に有用なデータが流れません。 -2. **リトランスミットフラグが残っている。** Jito-Agave から `--shred-retransmit-receiver-address` を削除してください。publisher-check の **No Retransmit Shreds** 列（2エポック vs 最近のスロットビュー）を確認してください。 -3. **まだリーダーになっていない。** リーダースロットが来るまでダッシュボードは空のままです。 -4. **IBRL が稼働していない。** ここから始めないでください。まず IBRL を完了してください。 - ---- - -## 関連項目 - -- [Validator Multicast Connection](Validator Multicast Connection.md) -- [Validator Rewards](Validator Rewards.md) \ No newline at end of file diff --git a/docs/solana-shreds-publisher-runbook.ko.md b/docs/solana-shreds-publisher-runbook.ko.md deleted file mode 100644 index 43fdf9d..0000000 --- a/docs/solana-shreds-publisher-runbook.ko.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -description: LLM 지향 런북 — 연결된 Solana 밸리데이터가 리더 shred를 DoubleZero Edge로 퍼블리시하도록 구성합니다. GitHub raw를 통해 MCP에 제공되며, 문서 사이트에는 게시되지 않습니다. ---- - -# Shred 퍼블리시 (Edge) — 런북 - -이 페이지는 GitHub raw를 통해 DoubleZero MCP(`get_onboarding_runbook`)를 위한 것입니다. 문서 사이트에는 게시되지 않습니다. - -1. [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`)를 연결합니다. -2. 밸리데이터가 **이미 DoubleZero IBRL**(mainnet-beta)에 연결되어 있는지 확인합니다. 연결되어 있지 않다면, 먼저 [밸리데이터 연결 (IBRL Mainnet)](solana-ibrl-runbook.md)을 완료하세요. -3. 아래 단계를 따릅니다. 사람용 가이드: [Validator Multicast Connection](Validator Multicast Connection.md). - -**성공 상태:** 밸리데이터가 리더 shred를 `233.84.178.1:7733`으로 전송하고, `edge-solana-shreds`에서 멀티캐스트 퍼블리시가 작동 중이며, [publisher-check](https://data.doublezero.xyz/dz/publisher-check)에서 최소 한 번의 리더 슬롯 이후 퍼블리싱이 표시됩니다. - -이 경로는 **밸리데이터**를 위한 것입니다. *구독*하려는 트레이딩 회사는 [Shred 구독](solana-shreds-runbook.md)을 사용하세요. - ---- - -## 전제 조건 - -| 필요 사항 | 참고 | -|------|--------| -| IBRL 터널이 이미 가동 중 | [IBRL Mainnet 런북](solana-ibrl-runbook.md) / [사람용 가이드](DZ Mainnet-beta Connection.md). | -| 지원되는 클라이언트 | Jito-Agave **3.1.9+**, JitoBam 3.1.9+, Frankendancer, 또는 Harmonic **3.1.11+**. 다른 버전은 퍼블리시되지 않습니다. | -| 재시작 시간 | shred 대상 추가 시 밸리데이터 재시작이 필요합니다. | - ---- - -## 단계 - -### 1. 클라이언트를 Edge shred 그룹으로 지정 - -**Jito-Agave (v3.1.9+) 및 Harmonic (3.1.11+)** — 밸리데이터 시작 스크립트에 다음을 추가합니다: - -```text ---shred-receiver-address 233.84.178.1:7733 -``` - -Jito와 `edge-solana-shreds`에 동시에 전송할 수 있습니다. 밸리데이터를 재시작합니다. - -**Frankendancer** — `config.toml`에서: - -```toml -[tiles.shred] -additional_shred_destinations_leader = [ "233.84.178.1:7733", ] -``` - -밸리데이터를 재시작합니다. - -### 2. 멀티캐스트 그룹에서 퍼블리시 - -```bash -doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds -``` - -**확인:** `doublezero status`가 여전히 IBRL/up이고, 사용자가 `edge-solana-shreds`의 퍼블리셔인지 확인합니다. - -라이브 그룹 IP: `doublezero multicast group list`. 모든 shred 피드는 UDP **`7733`**을 사용하며, IP로 피드를 선택합니다. - -| 피드 | 주소 | -|------|---------| -| `edge-solana-shreds` (리더) | `233.84.178.1:7733` | -| `edge-solana-retrans-eu` | `233.84.178.12:7733` | -| `edge-solana-retrans-apac` | `233.84.178.13:7733` | -| `edge-solana-retrans-amer` | `233.84.178.14:7733` | - -### 3. 퍼블리싱 확인 - -[publisher-check](https://data.doublezero.xyz/dz/publisher-check)를 엽니다. 밸리데이터가 **최소 한 슬롯** 동안 리더 shred를 퍼블리시할 때까지 확인이 표시되지 않습니다. - -정상 상태: 아웃바운드 스파이크가 리더 슬롯과 일치합니다(톱니파 형태). 슬롯 패턴 없이 일정한 아웃바운드는 **재전송**(비정상)입니다. - ---- - -## 주의 사항 - -1. **잘못된 클라이언트 버전.** 3.1.9+ / 3.1.11+가 아니면 → 유효한 데이터가 전송되지 않습니다. -2. **재전송 플래그가 남아 있음.** Jito-Agave에서 `--shred-retransmit-receiver-address`를 제거하세요. publisher-check의 **No Retransmit Shreds** 열을 확인하세요(2-에포크 vs 최근 슬롯 뷰). -3. **아직 리더가 아님.** 리더 슬롯이 올 때까지 대시보드가 비어 있습니다. -4. **IBRL이 가동되지 않음.** 여기서 시작하지 마세요; 먼저 IBRL을 완료하세요. - ---- - -## 참고 자료 - -- [Validator Multicast Connection](Validator Multicast Connection.md) -- [Validator Rewards](Validator Rewards.md) \ No newline at end of file diff --git a/docs/solana-shreds-publisher-runbook.pt.md b/docs/solana-shreds-publisher-runbook.pt.md deleted file mode 100644 index c5868ea..0000000 --- a/docs/solana-shreds-publisher-runbook.pt.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -description: Runbook orientado a LLM — configure um validador Solana conectado para publicar leader shreds no DoubleZero Edge. Servido ao MCP via GitHub raw; não publicado no site de documentação. ---- - -# Publicar shreds (Edge) — runbook - -Esta página é para o DoubleZero MCP (`get_onboarding_runbook`) via GitHub raw. Ela -não é publicada no site de documentação. - -1. Conecte o [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). -2. Confirme que o validador **já está no DoubleZero IBRL** (mainnet-beta). Caso contrário, conclua primeiro [Conectar validador (IBRL Mainnet)](solana-ibrl-runbook.md). -3. Siga os passos abaixo. Guia humano: [Validator Multicast Connection](Validator Multicast Connection.md). - -**Como é o sucesso:** o validador envia leader shreds para `233.84.178.1:7733`, a publicação multicast em `edge-solana-shreds` está ativa, e o [publisher-check](https://data.doublezero.xyz/dz/publisher-check) mostra publicação após pelo menos um leader slot. - -Este caminho é para **validadores**. Empresas de trading que desejam *se inscrever* devem usar [Inscrever-se em shreds](solana-shreds-runbook.md). - ---- - -## Pré-requisitos - -| Necessário | Notas | -|------------|-------| -| Túnel IBRL já ativo | [Runbook IBRL Mainnet](solana-ibrl-runbook.md) / [guia humano](DZ Mainnet-beta Connection.md). | -| Cliente suportado | Jito-Agave **3.1.9+**, JitoBam 3.1.9+, Frankendancer, ou Harmonic **3.1.11+**. Outras versões não publicarão. | -| Janela de reinício | Adicionar o destino de shred requer um reinício do validador. | - ---- - -## Passos - -### 1. Aponte o cliente para o grupo de shred do Edge - -**Jito-Agave (v3.1.9+) e Harmonic (3.1.11+)** — no script de inicialização do validador adicione: - -```text ---shred-receiver-address 233.84.178.1:7733 -``` - -Você pode enviar para o Jito e `edge-solana-shreds` ao mesmo tempo. Reinicie o validador. - -**Frankendancer** — em `config.toml`: - -```toml -[tiles.shred] -additional_shred_destinations_leader = [ "233.84.178.1:7733", ] -``` - -Reinicie o validador. - -### 2. Publique no grupo multicast - -```bash -doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds -``` - -**Verifique:** `doublezero status` ainda IBRL/up, e o usuário é um publicador em `edge-solana-shreds`. - -IPs de grupo ao vivo: `doublezero multicast group list`. Todos os feeds de shred usam UDP **`7733`**; o IP seleciona o feed. - -| Feed | Endereço | -|------|----------| -| `edge-solana-shreds` (leader) | `233.84.178.1:7733` | -| `edge-solana-retrans-eu` | `233.84.178.12:7733` | -| `edge-solana-retrans-apac` | `233.84.178.13:7733` | -| `edge-solana-retrans-amer` | `233.84.178.14:7733` | - -### 3. Confirme a publicação - -Abra o [publisher-check](https://data.doublezero.xyz/dz/publisher-check). Você não verá confirmação até que o validador tenha publicado leader shreds por **pelo menos um slot**. - -Saudável: picos de saída alinhados com leader slots (dente de serra). Saída constante sem padrão de slot é **retransmit** (ruim). - ---- - -## Armadilhas - -1. **Versão errada do cliente.** Não é 3.1.9+ / 3.1.11+ → nada útil na rede. -2. **Flag de retransmit deixada ativa.** Remova `--shred-retransmit-receiver-address` do Jito-Agave. Verifique a coluna **No Retransmit Shreds** no publisher-check (visualizações de 2 epochs vs slot recente). -3. **Ainda não é leader.** O dashboard permanece vazio até um leader slot. -4. **IBRL não está ativo.** Não comece por aqui; conclua o IBRL primeiro. - ---- - -## Veja também - -- [Validator Multicast Connection](Validator Multicast Connection.md) -- [Validator Rewards](Validator Rewards.md) \ No newline at end of file diff --git a/docs/solana-shreds-publisher-runbook.zh.md b/docs/solana-shreds-publisher-runbook.zh.md deleted file mode 100644 index 13d2164..0000000 --- a/docs/solana-shreds-publisher-runbook.zh.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -description: 面向 LLM 的运行手册 — 配置已连接的 Solana 验证器，将 leader shreds 发布到 DoubleZero Edge。通过 GitHub raw 提供给 MCP；不在文档站点上发布。 ---- - -# 发布 shreds (Edge) — 运行手册 - -本页面通过 GitHub raw 提供给 DoubleZero MCP (`get_onboarding_runbook`)。不在文档站点上发布。 - -1. 连接 [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`)。 -2. 确认验证器**已接入 DoubleZero IBRL**（mainnet-beta）。如果尚未接入，请先完成[连接验证器 (IBRL Mainnet)](solana-ibrl-runbook.md)。 -3. 按照以下步骤操作。人工指南：[Validator Multicast Connection](Validator Multicast Connection.md)。 - -**成功的标志：** 验证器向 `233.84.178.1:7733` 发送 leader shreds，`edge-solana-shreds` 上的多播发布已启动，且 [publisher-check](https://data.doublezero.xyz/dz/publisher-check) 在至少一个 leader slot 之后显示正在发布。 - -此路径适用于**验证器**。希望*订阅*的交易公司请使用[订阅 shreds](solana-shreds-runbook.md)。 - ---- - -## 前提条件 - -| 需求 | 备注 | -|------|--------| -| IBRL 隧道已建立 | [IBRL Mainnet 运行手册](solana-ibrl-runbook.md) / [人工指南](DZ Mainnet-beta Connection.md)。 | -| 支持的客户端 | Jito-Agave **3.1.9+**、JitoBam 3.1.9+、Frankendancer 或 Harmonic **3.1.11+**。其他版本将无法发布。 | -| 重启窗口 | 添加 shred 目标地址需要重启验证器。 | - ---- - -## 步骤 - -### 1. 将客户端指向 Edge shred 组 - -**Jito-Agave (v3.1.9+) 和 Harmonic (3.1.11+)** — 在验证器启动脚本中添加： - -```text ---shred-receiver-address 233.84.178.1:7733 -``` - -您可以同时向 Jito 和 `edge-solana-shreds` 发送。重启验证器。 - -**Frankendancer** — 在 `config.toml` 中： - -```toml -[tiles.shred] -additional_shred_destinations_leader = [ "233.84.178.1:7733", ] -``` - -重启验证器。 - -### 2. 在多播组上发布 - -```bash -doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds -``` - -**验证：** `doublezero status` 仍显示 IBRL/up，且用户是 `edge-solana-shreds` 的发布者。 - -实时组 IP：`doublezero multicast group list`。所有 shred feed 使用 UDP **`7733`**；IP 地址选择对应的 feed。 - -| Feed | 地址 | -|------|---------| -| `edge-solana-shreds`（leader） | `233.84.178.1:7733` | -| `edge-solana-retrans-eu` | `233.84.178.12:7733` | -| `edge-solana-retrans-apac` | `233.84.178.13:7733` | -| `edge-solana-retrans-amer` | `233.84.178.14:7733` | - -### 3. 确认发布状态 - -打开 [publisher-check](https://data.doublezero.xyz/dz/publisher-check)。在验证器发布了**至少一个 slot** 的 leader shreds 之前，您不会看到确认信息。 - -健康状态：出站流量峰值与 leader slot 对齐（锯齿形）。稳定的出站流量且无 slot 模式则为 **retransmit**（异常）。 - ---- - -## 常见问题 - -1. **客户端版本错误。** 不是 3.1.9+ / 3.1.11+ → 线路上不会有有用的数据。 -2. **retransmit 标志未移除。** 从 Jito-Agave 中移除 `--shred-retransmit-receiver-address`。在 publisher-check 上检查 **No Retransmit Shreds** 列（2-epoch 与 recent-slot 视图）。 -3. **尚未成为 leader。** 在获得 leader slot 之前，仪表盘保持空白。 -4. **IBRL 未启动。** 不要从这里开始；请先完成 IBRL 配置。 - ---- - -## 另请参阅 - -- [Validator Multicast Connection](Validator Multicast Connection.md) -- [Validator Rewards](Validator Rewards.md) \ No newline at end of file diff --git a/docs/solana-shreds-runbook.es.md b/docs/solana-shreds-runbook.es.md deleted file mode 100644 index 4040b8b..0000000 --- a/docs/solana-shreds-runbook.es.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -description: Runbook orientado a LLM — comprar un asiento de shreds en Edge y recibir multicast de shreds de Solana en doublezero1. Servido al MCP a través de GitHub raw; no publicado en el sitio de documentación. ---- - -# Suscribirse a shreds (Edge) — runbook - -Esta página es para el MCP de DoubleZero (`get_onboarding_runbook`) a través de GitHub raw. No está publicada en el sitio de documentación. - -1. Conectar el [MCP de DoubleZero](mcp.md) (`https://data.doublezero.xyz/api/mcp`). -2. Indicarle el host Linux que **recibirá** shreds (o SSH), la wallet/keypair para `doublezero-solana`, y qué feed (leader vs retransmit). -3. Seguir los pasos a continuación en orden. Guía para humanos: [Edge Subscriber Connection](Edge Subscriber Connection.md). - -**Cómo se ve el éxito:** asiento asignado para la época actual, `doublezero status` muestra el túnel activo, shreds UDP en `doublezero1` puerto `7733` (grupo leader `233.84.178.1`). - -Al conectarse, el usuario acepta los [Términos de Uso de DoubleZero](https://doublezero.xyz/terms-protocol). Los datos son para uso interno y no pueden ser retransmitidos. - ---- - -## Prerrequisitos - -| Necesario | Notas | -|-----------|-------| -| Host Linux/amd64 | IPv4 pública, sin NAT. En AWS: deshabilitar la verificación de origen/destino del ENI. | -| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | -| Wallet | `~/.config/solana/id.json` (o `--keypair`). Necesita **SOL** (comisiones) + **USDC** (escrow del asiento). | -| Mint de USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | -| Firewall | GRE, BGP (`169.254.0.0/16` tcp/179), PIM, UDP `7733` en `doublezero1`, UDP `44880` en `doublezero0`. | - ---- - -## Pasos - -### 1. Instalar cliente + paquetes - -Seguir [setup](setup.md), luego: - -```bash -sudo apt update && sudo apt install doublezero-solana -``` - -Respaldar `~/.config/doublezero/id.json`. - -### 2. Firewall - -```bash -sudo iptables -A OUTPUT -p gre -j ACCEPT -sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT -sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT -sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT -``` - -Variantes con UFW: ver guía para humanos. - -### 3. Habilitar el reconciliador - -Necesario para que los asientos aprovisionen automáticamente el túnel. - -```bash -doublezero enable -``` - -### 4. Wallet - -```bash -solana-keygen new # si es necesario — escribe en ~/.config/solana/id.json; respaldarlo -solana address -``` - -Fondear SOL y USDC. - -### 5. Elegir dispositivo + precio - -```bash -doublezero latency -doublezero-solana shreds price -doublezero-solana shreds price --device-code -``` - -Anotar el **código de dispositivo** con menor latencia y el precio por época (base + premium). Se recomienda fondear **>1 época**. Interfaz de precios: [devices](https://data.doublezero.xyz/dz/shreds/devices). - -### 6. Comprar un asiento (bloqueante) - -En el host receptor: - -```bash -curl -4 -s ifconfig.me; echo -``` - -```bash -doublezero-solana shreds pay \ - --device-code \ - --client-ip \ - --amount -``` - -`--client-ip` debe ser la IPv4 pública de la máquina que recibirá shreds. `--amount` es USDC en decimal (ej. `100`) y debe cumplir el precio de la época. - -Si queda menos del 10% de la época, el CLI advierte. `--accept-partial-epoch` toma el remanente ahora; de lo contrario, esperar. Escrow sin fondos suficientes al momento de la liquidación → asiento perdido, túnel eliminado, **tenencia perdida**. - -Una vez asignado, el daemon levanta el túnel GRE. - -```bash -doublezero status -doublezero-solana shreds list -``` - -### 7. Confirmar shreds - -Shreds de leader: `233.84.178.1:7733` en `doublezero1`. Descubrir grupos con `doublezero multicast group list`. - -| Feed | Grupo | Dirección | -|------|-------|-----------| -| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | -| Root | `edge-solana-root` | `233.84.178.16:7733` | -| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | -| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | -| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | - -El puerto `5765` es un heartbeat del publicador — no shreds. El tráfico está encapsulado en GRE; algunos pipelines (deshredders XDP) deben eliminar el encapsulado GRE. - -```bash -sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 -``` - ---- - -## Problemas comunes - -1. **Reconciliador desactivado.** Sin `doublezero enable`, pagar no levanta el túnel. -2. **`--client-ip` ≠ IP del daemon.** La auto-detección debe coincidir con el asiento. -3. **`Multicast user already exists`.** Desconectar primero: `doublezero disconnect`, luego reintentar `shreds pay`. -4. **Monto por debajo del precio actual.** Verificar nuevamente `shreds price` y aumentar `--amount`. -5. **Asiento no asignado después del pago.** Época tardía (siguiente época), dispositivo lleno (mayor tenencia), o retiro antes de la liquidación. -6. **Mantener el escrow fondeado.** Recargar con otro `shreds pay`; no permitir que el saldo caiga por debajo del precio de la época. - ---- - -## Ver también - -- [Edge Subscriber Connection](Edge Subscriber Connection.md) -- [Soporte](support.md) -- Scoreboard / asientos: [data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) \ No newline at end of file diff --git a/docs/solana-shreds-runbook.fr.md b/docs/solana-shreds-runbook.fr.md deleted file mode 100644 index 8aacd9c..0000000 --- a/docs/solana-shreds-runbook.fr.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -description: Runbook orienté LLM — acheter un siège Edge shreds et recevoir le multicast Solana shreds sur doublezero1. Servi au MCP via GitHub raw ; non publié sur le site de documentation. ---- - -# S'abonner aux shreds (Edge) — runbook - -Cette page est destinée au DoubleZero MCP (`get_onboarding_runbook`) via GitHub raw. Elle -n'est pas publiée sur le site de documentation. - -1. Connectez le [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). -2. Indiquez-lui l'hôte Linux qui va **recevoir** les shreds (ou SSH), le wallet/keypair pour `doublezero-solana`, et quel flux (leader vs retransmit). -3. Suivez les étapes ci-dessous dans l'ordre. Guide utilisateur : [Edge Subscriber Connection](Edge Subscriber Connection.md). - -**À quoi ressemble le succès :** siège alloué pour l'époque en cours, `doublezero status` montre le tunnel actif, shreds UDP sur `doublezero1` port `7733` (groupe leader `233.84.178.1`). - -En se connectant, l'utilisateur accepte les [Conditions d'utilisation DoubleZero](https://doublezero.xyz/terms-protocol). Les données sont à usage interne et ne peuvent pas être retransmises. - ---- - -## Prérequis - -| Besoin | Notes | -|--------|--------| -| Hôte Linux/amd64 | IPv4 publique, pas de NAT. Sur AWS : désactiver la vérification source/dest de l'ENI. | -| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | -| Wallet | `~/.config/solana/id.json` (ou `--keypair`). Nécessite du **SOL** (frais) + **USDC** (escrow du siège). | -| Mint USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | -| Pare-feu | GRE, BGP (`169.254.0.0/16` tcp/179), PIM, UDP `7733` sur `doublezero1`, UDP `44880` sur `doublezero0`. | - ---- - -## Étapes - -### 1. Installer le client + les paquets - -Suivez la [configuration](setup.md), puis : - -```bash -sudo apt update && sudo apt install doublezero-solana -``` - -Sauvegardez `~/.config/doublezero/id.json`. - -### 2. Pare-feu - -```bash -sudo iptables -A OUTPUT -p gre -j ACCEPT -sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT -sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT -sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT -``` - -Variantes UFW : voir le guide utilisateur. - -### 3. Activer le réconcilieur - -Nécessaire pour que les sièges provisionnent automatiquement le tunnel. - -```bash -doublezero enable -``` - -### 4. Wallet - -```bash -solana-keygen new # si nécessaire — écrit ~/.config/solana/id.json ; sauvegardez-le -solana address -``` - -Approvisionnez en SOL et USDC. - -### 5. Choisir le dispositif + le prix - -```bash -doublezero latency -doublezero-solana shreds price -doublezero-solana shreds price --device-code -``` - -Notez le **code du dispositif** à la latence la plus faible et le prix par époque (base + premium). Préférez un financement de **>1 époque**. Interface des prix : [devices](https://data.doublezero.xyz/dz/shreds/devices). - -### 6. Acheter un siège (bloquant) - -Sur l'hôte récepteur : - -```bash -curl -4 -s ifconfig.me; echo -``` - -```bash -doublezero-solana shreds pay \ - --device-code \ - --client-ip \ - --amount -``` - -`--client-ip` doit être l'IPv4 publique de la machine qui recevra les shreds. `--amount` est en décimal USDC (par ex. `100`) et doit atteindre le prix de l'époque. - -S'il reste moins de 10 % de l'époque, le CLI émet un avertissement. `--accept-partial-epoch` prend le reste maintenant ; sinon attendez. Un escrow sous-financé au moment du règlement → siège perdu, tunnel démonté, **ancienneté perdue**. - -Une fois alloué, le daemon établit le tunnel GRE. - -```bash -doublezero status -doublezero-solana shreds list -``` - -### 7. Confirmer les shreds - -Shreds leader : `233.84.178.1:7733` sur `doublezero1`. Découvrez les groupes avec `doublezero multicast group list`. - -| Flux | Groupe | Adresse | -|------|--------|---------| -| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | -| Root | `edge-solana-root` | `233.84.178.16:7733` | -| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | -| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | -| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | - -Le port `5765` est un heartbeat de l'éditeur — pas des shreds. Le trafic est encapsulé en GRE ; certains pipelines (deshredders XDP) doivent retirer le GRE. - -```bash -sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 -``` - ---- - -## Pièges courants - -1. **Réconcilieur désactivé.** Sans `doublezero enable`, le paiement n'établit pas le tunnel. -2. **`--client-ip` ≠ IP du daemon.** La découverte automatique doit correspondre au siège. -3. **`Multicast user already exists`.** Déconnectez d'abord : `doublezero disconnect`, puis réessayez `shreds pay`. -4. **Montant inférieur au prix actuel.** Revérifiez `shreds price` et augmentez `--amount`. -5. **Siège non alloué après le paiement.** Époque tardive (époque suivante), dispositif complet (ancienneté plus élevée), ou retrait avant le règlement. -6. **Maintenez l'escrow financé.** Rechargez avec un autre `shreds pay` ; ne laissez pas le solde descendre en dessous du prix de l'époque. - ---- - -## Voir aussi - -- [Edge Subscriber Connection](Edge Subscriber Connection.md) -- [Support](support.md) -- Tableau de bord / sièges : [data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) \ No newline at end of file diff --git a/docs/solana-shreds-runbook.it.md b/docs/solana-shreds-runbook.it.md deleted file mode 100644 index e08702d..0000000 --- a/docs/solana-shreds-runbook.it.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -description: Runbook orientato agli LLM — acquistare un seat Edge per gli shred e ricevere il multicast degli shred Solana su doublezero1. Servito all'MCP tramite GitHub raw; non pubblicato sul sito della documentazione. ---- - -# Sottoscrivere gli shred (Edge) — runbook - -Questa pagina è destinata al DoubleZero MCP (`get_onboarding_runbook`) tramite GitHub raw. Non è -pubblicata sul sito della documentazione. - -1. Connettere il [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). -2. Indicare l'host Linux che **riceverà** gli shred (o SSH), il wallet/keypair per `doublezero-solana` e quale feed (leader vs retransmit). -3. Seguire i passaggi sottostanti in ordine. Guida per operatori: [Edge Subscriber Connection](Edge Subscriber Connection.md). - -**Come si presenta il successo:** seat allocato per l'epoca corrente, `doublezero status` mostra il tunnel attivo, shred UDP su `doublezero1` porta `7733` (gruppo leader `233.84.178.1`). - -Connettendosi, l'utente accetta i [Termini di Utilizzo di DoubleZero](https://doublezero.xyz/terms-protocol). I dati sono per uso interno e non possono essere ritrasmessi. - ---- - -## Prerequisiti - -| Necessario | Note | -|------|--------| -| Host Linux/amd64 | IPv4 pubblico, senza NAT. Su AWS: disabilitare il controllo source/dest dell'ENI. | -| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | -| Wallet | `~/.config/solana/id.json` (oppure `--keypair`). Necessari **SOL** (commissioni) + **USDC** (escrow del seat). | -| Mint USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | -| Firewall | GRE, BGP (`169.254.0.0/16` tcp/179), PIM, UDP `7733` su `doublezero1`, UDP `44880` su `doublezero0`. | - ---- - -## Passaggi - -### 1. Installare client e pacchetti - -Seguire il [setup](setup.md), poi: - -```bash -sudo apt update && sudo apt install doublezero-solana -``` - -Eseguire il backup di `~/.config/doublezero/id.json`. - -### 2. Firewall - -```bash -sudo iptables -A OUTPUT -p gre -j ACCEPT -sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT -sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT -sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT -``` - -Varianti UFW: consultare la guida per operatori. - -### 3. Abilitare il reconciler - -Necessario affinché i seat provisionino automaticamente il tunnel. - -```bash -doublezero enable -``` - -### 4. Wallet - -```bash -solana-keygen new # se necessario — scrive ~/.config/solana/id.json; eseguire il backup -solana address -``` - -Finanziare con SOL e USDC. - -### 5. Scegliere device e prezzo - -```bash -doublezero latency -doublezero-solana shreds price -doublezero-solana shreds price --device-code -``` - -Annotare il **device code** con latenza più bassa e il prezzo dell'epoca (base + premium). È preferibile finanziare **>1 epoca**. Interfaccia prezzi: [devices](https://data.doublezero.xyz/dz/shreds/devices). - -### 6. Acquistare un seat (bloccante) - -Sull'host ricevente: - -```bash -curl -4 -s ifconfig.me; echo -``` - -```bash -doublezero-solana shreds pay \ - --device-code \ - --client-ip \ - --amount -``` - -`--client-ip` deve essere l'IPv4 pubblico della macchina che riceverà gli shred. `--amount` è in decimali USDC (es. `100`) e deve soddisfare il prezzo dell'epoca. - -Se rimane meno del 10% dell'epoca, la CLI avvisa. `--accept-partial-epoch` prende il residuo immediatamente; altrimenti attendere. Escrow sottofinanziato al momento del settlement → seat perso, tunnel abbattuto, **tenure persa**. - -Una volta allocato, il daemon attiva il tunnel GRE. - -```bash -doublezero status -doublezero-solana shreds list -``` - -### 7. Verificare gli shred - -Shred leader: `233.84.178.1:7733` su `doublezero1`. Scoprire i gruppi con `doublezero multicast group list`. - -| Feed | Gruppo | Indirizzo | -|------|-------|---------| -| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | -| Root | `edge-solana-root` | `233.84.178.16:7733` | -| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | -| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | -| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | - -La porta `5765` è un heartbeat del publisher — non shred. Il traffico è incapsulato in GRE; alcune pipeline (deshredder XDP) devono rimuovere il GRE. - -```bash -sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 -``` - ---- - -## Problemi comuni - -1. **Reconciler disattivato.** Senza `doublezero enable`, il pagamento non attiva il tunnel. -2. **`--client-ip` ≠ IP del daemon.** L'auto-discovery deve corrispondere al seat. -3. **`Multicast user already exists`.** Disconnettersi prima: `doublezero disconnect`, poi riprovare `shreds pay`. -4. **Importo inferiore al prezzo corrente.** Ricontrollare `shreds price` e aumentare `--amount`. -5. **Seat non allocato dopo il pagamento.** Epoca tardiva (epoca successiva), device pieno (tenure più alta), o prelievo prima del settlement. -6. **Mantenere l'escrow finanziato.** Ricaricare con un altro `shreds pay`; non lasciare che il saldo scenda sotto il prezzo dell'epoca. - ---- - -## Vedi anche - -- [Edge Subscriber Connection](Edge Subscriber Connection.md) -- [Supporto](support.md) -- Scoreboard / seat: [data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) \ No newline at end of file diff --git a/docs/solana-shreds-runbook.ja.md b/docs/solana-shreds-runbook.ja.md deleted file mode 100644 index 3232bd6..0000000 --- a/docs/solana-shreds-runbook.ja.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -description: LLM向けランブック — Edge シュレッド シートを購入し、doublezero1 上で Solana シュレッド マルチキャストを受信します。GitHub raw 経由で MCP に提供されます。ドキュメントサイトには公開されません。 ---- - -# シュレッドのサブスクライブ（Edge）— ランブック - -このページは DoubleZero MCP（`get_onboarding_runbook`）向けに GitHub raw 経由で提供されています。ドキュメントサイトには公開されません。 - -1. [DoubleZero MCP](mcp.md)（`https://data.doublezero.xyz/api/mcp`）に接続します。 -2. シュレッドを**受信**する Linux ホスト（または SSH）、`doublezero-solana` 用のウォレット/キーペア、および希望するフィード（leader または retransmit）を指定します。 -3. 以下の手順を順番に実施します。ヒューマンガイド：[Edge Subscriber Connection](Edge Subscriber Connection.md)。 - -**成功した場合の状態：** 現在のエポックにシートが割り当てられ、`doublezero status` でトンネルがアップと表示され、`doublezero1` のポート `7733` で UDP シュレッドが受信される（leader グループ `233.84.178.1`）。 - -接続することにより、ユーザーは [DoubleZero Terms of Use](https://doublezero.xyz/terms-protocol) に同意したものとみなされます。データは内部利用のみを目的とし、再送信は禁止されています。 - ---- - -## 前提条件 - -| 必要なもの | 備考 | -|------|--------| -| Linux/amd64 ホスト | パブリック IPv4、NAT なし。AWS の場合：ENI の送信元/送信先チェックを無効化。 | -| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | -| ウォレット | `~/.config/solana/id.json`（または `--keypair`）。**SOL**（手数料）+ **USDC**（シート エスクロー）が必要。 | -| USDC ミント | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | -| ファイアウォール | GRE、BGP（`169.254.0.0/16` tcp/179）、PIM、`doublezero1` 上の UDP `7733`、`doublezero0` 上の UDP `44880`。 | - ---- - -## 手順 - -### 1. クライアントとパッケージのインストール - -[セットアップ](setup.md) に従い、次を実行します： - -```bash -sudo apt update && sudo apt install doublezero-solana -``` - -`~/.config/doublezero/id.json` をバックアップしてください。 - -### 2. ファイアウォール - -```bash -sudo iptables -A OUTPUT -p gre -j ACCEPT -sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT -sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT -sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT -``` - -UFW の設定方法についてはヒューマンガイドを参照してください。 - -### 3. リコンサイラーの有効化 - -シートがトンネルを自動プロビジョニングするために必要です。 - -```bash -doublezero enable -``` - -### 4. ウォレット - -```bash -solana-keygen new # 必要に応じて — ~/.config/solana/id.json に書き込まれます。バックアップしてください -solana address -``` - -SOL と USDC を入金してください。 - -### 5. デバイスと価格の選択 - -```bash -doublezero latency -doublezero-solana shreds price -doublezero-solana shreds price --device-code -``` - -最低レイテンシの**デバイスコード**とエポック価格（ベース + プレミアム）を確認します。**1 エポック以上**の資金を用意することを推奨します。価格 UI：[devices](https://data.doublezero.xyz/dz/shreds/devices)。 - -### 6. シートの購入（ブロッキング） - -受信ホスト上で： - -```bash -curl -4 -s ifconfig.me; echo -``` - -```bash -doublezero-solana shreds pay \ - --device-code \ - --client-ip \ - --amount -``` - -`--client-ip` はシュレッドを受信するマシンのパブリック IPv4 である必要があります。`--amount` は USDC の10進数値（例：`100`）で、エポック価格を満たす必要があります。 - -エポックの残りが 10% 未満の場合、CLI が警告を表示します。`--accept-partial-epoch` を使用すると残りの期間を今すぐ取得します。それ以外の場合は次のエポックまで待ちます。精算時にエスクローの資金が不足していると → シート喪失、トンネル切断、**テニュア喪失**となります。 - -割り当てが完了すると、デーモンが GRE トンネルを起動します。 - -```bash -doublezero status -doublezero-solana shreds list -``` - -### 7. シュレッドの確認 - -Leader シュレッド：`doublezero1` 上の `233.84.178.1:7733`。グループの確認には `doublezero multicast group list` を使用します。 - -| フィード | グループ | アドレス | -|------|-------|---------| -| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | -| Root | `edge-solana-root` | `233.84.178.16:7733` | -| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | -| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | -| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | - -ポート `5765` はパブリッシャーのハートビートであり、シュレッドではありません。トラフィックは GRE カプセル化されています。一部のパイプライン（XDP デシュレッダー）では GRE の除去が必要です。 - -```bash -sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 -``` - ---- - -## よくある問題 - -1. **リコンサイラーがオフ。** `doublezero enable` なしでは、支払いを行ってもトンネルは起動しません。 -2. **`--client-ip` ≠ デーモン IP。** 自動検出がシートと一致する必要があります。 -3. **`Multicast user already exists`。** まず切断してください：`doublezero disconnect`、その後 `shreds pay` を再試行します。 -4. **金額が現在の価格を下回っている。** `shreds price` を再確認し、`--amount` を増額してください。 -5. **支払い後にシートが割り当てられない。** エポック終盤（次のエポック）、デバイスが満席（テニュアが高い）、または精算前に引き出した場合。 -6. **エスクローの資金を維持する。** 追加の `shreds pay` で補充してください。残高がエポック価格を下回らないようにしてください。 - ---- - -## 関連情報 - -- [Edge Subscriber Connection](Edge Subscriber Connection.md) -- [サポート](support.md) -- スコアボード / シート：[data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) \ No newline at end of file diff --git a/docs/solana-shreds-runbook.ko.md b/docs/solana-shreds-runbook.ko.md deleted file mode 100644 index 842a1b2..0000000 --- a/docs/solana-shreds-runbook.ko.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -description: LLM 지향 런북 — Edge shreds 시트를 구매하고 doublezero1에서 Solana shred 멀티캐스트를 수신합니다. GitHub raw를 통해 MCP에 제공되며, 문서 사이트에는 게시되지 않습니다. ---- - -# shreds 구독 (Edge) — 런북 - -이 페이지는 GitHub raw를 통해 DoubleZero MCP(`get_onboarding_runbook`)를 위한 것입니다. 문서 사이트에는 게시되지 않습니다. - -1. [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`)에 연결합니다. -2. shreds를 **수신**할 Linux 호스트(또는 SSH), `doublezero-solana`용 지갑/키페어, 그리고 어떤 피드(leader vs retransmit)를 사용할지 알려줍니다. -3. 아래 단계를 순서대로 진행합니다. 사람용 가이드: [Edge Subscriber Connection](Edge Subscriber Connection.md). - -**성공 시 확인 사항:** 현재 에포크에 시트가 할당되고, `doublezero status`에서 터널이 활성 상태로 표시되며, `doublezero1` 포트 `7733`에서 UDP shreds 수신(leader 그룹 `233.84.178.1`). - -연결함으로써 사용자는 [DoubleZero 이용약관](https://doublezero.xyz/terms-protocol)에 동의합니다. 데이터는 내부 사용 목적이며 재전송할 수 없습니다. - ---- - -## 사전 요구 사항 - -| 필요 항목 | 참고 사항 | -|------|--------| -| Linux/amd64 호스트 | 공용 IPv4, NAT 없음. AWS의 경우: ENI source/dest 검사를 비활성화합니다. | -| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | -| 지갑 | `~/.config/solana/id.json` (또는 `--keypair`). **SOL**(수수료) + **USDC**(시트 에스크로)가 필요합니다. | -| USDC 민트 | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | -| 방화벽 | GRE, BGP (`169.254.0.0/16` tcp/179), PIM, `doublezero1`에서 UDP `7733`, `doublezero0`에서 UDP `44880`. | - ---- - -## 단계 - -### 1. 클라이언트 + 패키지 설치 - -[설정](setup.md)을 따른 후: - -```bash -sudo apt update && sudo apt install doublezero-solana -``` - -`~/.config/doublezero/id.json`을 백업합니다. - -### 2. 방화벽 - -```bash -sudo iptables -A OUTPUT -p gre -j ACCEPT -sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT -sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT -sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT -``` - -UFW 대안: 사람용 가이드를 참조하세요. - -### 3. 리컨실러 활성화 - -시트가 터널을 자동 프로비저닝하려면 필수입니다. - -```bash -doublezero enable -``` - -### 4. 지갑 - -```bash -solana-keygen new # 필요한 경우 — ~/.config/solana/id.json에 기록됩니다; 백업하세요 -solana address -``` - -SOL과 USDC를 충전합니다. - -### 5. 장치 + 가격 선택 - -```bash -doublezero latency -doublezero-solana shreds price -doublezero-solana shreds price --device-code -``` - -최저 지연 시간의 **장치 코드**와 에포크 가격(기본 + 프리미엄)을 기록합니다. **1 에포크 이상** 충전하는 것을 권장합니다. 가격 UI: [devices](https://data.doublezero.xyz/dz/shreds/devices). - -### 6. 시트 구매 (블로킹) - -수신 호스트에서: - -```bash -curl -4 -s ifconfig.me; echo -``` - -```bash -doublezero-solana shreds pay \ - --device-code \ - --client-ip \ - --amount -``` - -`--client-ip`는 shreds를 수신할 머신의 공용 IPv4여야 합니다. `--amount`는 USDC 소수점 값(예: `100`)이며 에포크 가격을 충족해야 합니다. - -에포크의 10% 미만이 남은 경우 CLI가 경고합니다. `--accept-partial-epoch`는 남은 기간을 즉시 사용합니다; 그렇지 않으면 기다리세요. 정산 시 에스크로 잔액 부족 → 시트 상실, 터널 해제, **테뉴어 손실**. - -할당되면 데몬이 GRE 터널을 활성화합니다. - -```bash -doublezero status -doublezero-solana shreds list -``` - -### 7. shreds 확인 - -Leader shreds: `doublezero1`의 `233.84.178.1:7733`. `doublezero multicast group list`로 그룹을 검색합니다. - -| 피드 | 그룹 | 주소 | -|------|-------|---------| -| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | -| Root | `edge-solana-root` | `233.84.178.16:7733` | -| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | -| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | -| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | - -포트 `5765`는 퍼블리셔 하트비트이며 — shreds가 아닙니다. 트래픽은 GRE 캡슐화되어 있습니다; 일부 파이프라인(XDP deshredder)은 GRE를 제거해야 합니다. - -```bash -sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 -``` - ---- - -## 주의 사항 - -1. **리컨실러 비활성화.** `doublezero enable` 없이 결제해도 터널이 활성화되지 않습니다. -2. **`--client-ip` ≠ 데몬 IP.** 자동 검색이 시트와 일치해야 합니다. -3. **`Multicast user already exists`.** 먼저 연결 해제: `doublezero disconnect`, 그런 다음 `shreds pay`를 재시도합니다. -4. **금액이 현재 가격 미만.** `shreds price`를 다시 확인하고 `--amount`를 높이세요. -5. **결제 후 시트가 할당되지 않음.** 에포크 후반(다음 에포크), 장치 만석(더 높은 테뉴어), 또는 정산 전 출금. -6. **에스크로 잔액을 유지하세요.** 추가 `shreds pay`로 충전하고, 잔액이 에포크 가격 이하로 떨어지지 않도록 하세요. - ---- - -## 참고 자료 - -- [Edge Subscriber Connection](Edge Subscriber Connection.md) -- [지원](support.md) -- 스코어보드 / 시트: [data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) \ No newline at end of file diff --git a/docs/solana-shreds-runbook.pt.md b/docs/solana-shreds-runbook.pt.md deleted file mode 100644 index 3245792..0000000 --- a/docs/solana-shreds-runbook.pt.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -description: Runbook orientado a LLM — compre um seat de Edge shreds e receba multicast de shreds Solana no doublezero1. Servido ao MCP via GitHub raw; não publicado no site de documentação. ---- - -# Subscrever shreds (Edge) — runbook - -Esta página é para o DoubleZero MCP (`get_onboarding_runbook`) via GitHub raw. Não é -publicada no site de documentação. - -1. Conecte o [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`). -2. Informe o host Linux que irá **receber** shreds (ou SSH), a wallet/keypair para `doublezero-solana`, e qual feed (leader vs retransmit). -3. Siga os passos abaixo em ordem. Guia humano: [Edge Subscriber Connection](Edge Subscriber Connection.md). - -**Como é o sucesso:** seat alocado para o epoch atual, `doublezero status` mostra o túnel ativo, shreds UDP em `doublezero1` porta `7733` (grupo leader `233.84.178.1`). - -Ao conectar, o usuário concorda com os [Termos de Uso do DoubleZero](https://doublezero.xyz/terms-protocol). Os dados são para uso interno e não podem ser retransmitidos. - ---- - -## Pré-requisitos - -| Necessário | Notas | -|------------|-------| -| Host Linux/amd64 | IPv4 público, sem NAT. Na AWS: desabilitar verificação de source/dest da ENI. | -| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | -| Wallet | `~/.config/solana/id.json` (ou `--keypair`). Precisa de **SOL** (taxas) + **USDC** (escrow do seat). | -| USDC mint | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | -| Firewall | GRE, BGP (`169.254.0.0/16` tcp/179), PIM, UDP `7733` em `doublezero1`, UDP `44880` em `doublezero0`. | - ---- - -## Passos - -### 1. Instalar cliente + pacotes - -Siga o [setup](setup.md), depois: - -```bash -sudo apt update && sudo apt install doublezero-solana -``` - -Faça backup de `~/.config/doublezero/id.json`. - -### 2. Firewall - -```bash -sudo iptables -A OUTPUT -p gre -j ACCEPT -sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT -sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT -sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT -``` - -Variantes UFW: guia humano. - -### 3. Habilitar o reconciler - -Necessário para que os seats provisionem automaticamente o túnel. - -```bash -doublezero enable -``` - -### 4. Wallet - -```bash -solana-keygen new # se necessário — grava em ~/.config/solana/id.json; faça backup -solana address -``` - -Financie com SOL e USDC. - -### 5. Escolher device + preço - -```bash -doublezero latency -doublezero-solana shreds price -doublezero-solana shreds price --device-code -``` - -Anote o **device code** de menor latência e o preço do epoch (base + premium). Prefira financiar **>1 epoch**. Interface de preços: [devices](https://data.doublezero.xyz/dz/shreds/devices). - -### 6. Comprar um seat (bloqueante) - -No host receptor: - -```bash -curl -4 -s ifconfig.me; echo -``` - -```bash -doublezero-solana shreds pay \ - --device-code \ - --client-ip \ - --amount -``` - -`--client-ip` deve ser o IPv4 público da máquina que receberá shreds. `--amount` é em USDC decimal (ex.: `100`) e deve atender o preço do epoch. - -Se restarem menos de 10% do epoch, o CLI avisa. `--accept-partial-epoch` aceita o restante agora; caso contrário, aguarde. Escrow insuficiente no settlement → seat perdido, túnel derrubado, **tenure perdido**. - -Uma vez alocado, o daemon ativa o túnel GRE. - -```bash -doublezero status -doublezero-solana shreds list -``` - -### 7. Confirmar shreds - -Shreds leader: `233.84.178.1:7733` em `doublezero1`. Descubra grupos com `doublezero multicast group list`. - -| Feed | Grupo | Endereço | -|------|-------|----------| -| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | -| Root | `edge-solana-root` | `233.84.178.16:7733` | -| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | -| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | -| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | - -A porta `5765` é um heartbeat do publisher — não são shreds. O tráfego é encapsulado em GRE; alguns pipelines (XDP deshredders) precisam remover o GRE. - -```bash -sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 -``` - ---- - -## Armadilhas - -1. **Reconciler desligado.** Sem `doublezero enable`, pagar não ativa o túnel. -2. **`--client-ip` ≠ IP do daemon.** A auto-descoberta deve corresponder ao seat. -3. **`Multicast user already exists`.** Desconecte primeiro: `doublezero disconnect`, depois tente `shreds pay` novamente. -4. **Valor abaixo do preço atual.** Verifique novamente `shreds price` e aumente `--amount`. -5. **Seat não alocado após pagamento.** Epoch tardio (próximo epoch), device cheio (tenure mais alto), ou saque antes do settlement. -6. **Mantenha o escrow financiado.** Recarregue com outro `shreds pay`; não deixe o saldo cair abaixo do preço do epoch. - ---- - -## Veja também - -- [Edge Subscriber Connection](Edge Subscriber Connection.md) -- [Suporte](support.md) -- Scoreboard / seats: [data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) \ No newline at end of file diff --git a/docs/solana-shreds-runbook.zh.md b/docs/solana-shreds-runbook.zh.md deleted file mode 100644 index 6183e75..0000000 --- a/docs/solana-shreds-runbook.zh.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -description: 面向 LLM 的运行手册 — 购买 Edge shreds 席位并在 doublezero1 上接收 Solana shred 组播。通过 GitHub raw 提供给 MCP；不在文档站点上发布。 ---- - -# 订阅 shreds (Edge) — 运行手册 - -本页面通过 GitHub raw 为 DoubleZero MCP (`get_onboarding_runbook`) 提供。不在文档站点上发布。 - -1. 连接 [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`)。 -2. 告知它将**接收** shreds 的 Linux 主机（或 SSH）、用于 `doublezero-solana` 的钱包/密钥对，以及所需的 feed 类型（leader 或 retransmit）。 -3. 按顺序完成以下步骤。人工指南：[Edge Subscriber Connection](Edge Subscriber Connection.md)。 - -**成功标志：** 当前 epoch 已分配席位，`doublezero status` 显示隧道已建立，`doublezero1` 端口 `7733` 上有 UDP shreds（leader 组 `233.84.178.1`）。 - -连接即表示用户同意 [DoubleZero 使用条款](https://doublezero.xyz/terms-protocol)。数据仅供内部使用，不得转发。 - ---- - -## 前提条件 - -| 需求 | 说明 | -|------|--------| -| Linux/amd64 主机 | 公网 IPv4，无 NAT。在 AWS 上：禁用 ENI source/dest 检查。 | -| Solana CLI + `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` | -| 钱包 | `~/.config/solana/id.json`（或 `--keypair`）。需要 **SOL**（手续费）+ **USDC**（席位托管）。 | -| USDC 铸币地址 | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | -| 防火墙 | GRE、BGP（`169.254.0.0/16` tcp/179）、PIM、`doublezero1` 上的 UDP `7733`、`doublezero0` 上的 UDP `44880`。 | - ---- - -## 步骤 - -### 1. 安装客户端和软件包 - -按照 [设置](setup.md) 操作，然后： - -```bash -sudo apt update && sudo apt install doublezero-solana -``` - -备份 `~/.config/doublezero/id.json`。 - -### 2. 防火墙 - -```bash -sudo iptables -A OUTPUT -p gre -j ACCEPT -sudo iptables -A INPUT -i doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero1 -s 169.254.0.0/16 -d 169.254.0.0/16 -p tcp --dport 179 -j ACCEPT -sudo iptables -A OUTPUT -o doublezero1 -p pim -j ACCEPT -sudo iptables -A INPUT -i doublezero1 -p udp --dport 7733 -j ACCEPT -sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT -``` - -UFW 变体：参见人工指南。 - -### 3. 启用 reconciler - -必须启用，以便席位自动配置隧道。 - -```bash -doublezero enable -``` - -### 4. 钱包 - -```bash -solana-keygen new # 如需要 — 写入 ~/.config/solana/id.json；请备份 -solana address -``` - -充值 SOL 和 USDC。 - -### 5. 选择设备和价格 - -```bash -doublezero latency -doublezero-solana shreds price -doublezero-solana shreds price --device-code -``` - -记下最低延迟的 **device code** 和 epoch 价格（基础 + 溢价）。建议充值 **超过 1 个 epoch** 的金额。定价界面：[devices](https://data.doublezero.xyz/dz/shreds/devices)。 - -### 6. 购买席位（阻塞操作） - -在接收主机上： - -```bash -curl -4 -s ifconfig.me; echo -``` - -```bash -doublezero-solana shreds pay \ - --device-code \ - --client-ip \ - --amount -``` - -`--client-ip` 必须是将接收 shreds 的机器的公网 IPv4。`--amount` 为 USDC 十进制数（例如 `100`），且必须满足 epoch 价格。 - -如果当前 epoch 剩余不足 10%，CLI 会发出警告。`--accept-partial-epoch` 会立即获取剩余时间；否则请等待。结算时托管资金不足 → 席位丢失、隧道拆除、**任期中断**。 - -分配完成后，守护进程会启动 GRE 隧道。 - -```bash -doublezero status -doublezero-solana shreds list -``` - -### 7. 确认 shreds - -Leader shreds：`doublezero1` 上的 `233.84.178.1:7733`。使用 `doublezero multicast group list` 发现组播组。 - -| Feed | 组 | 地址 | -|------|-------|---------| -| Leader | `edge-solana-shreds` | `233.84.178.1:7733` | -| Root | `edge-solana-root` | `233.84.178.16:7733` | -| Retransmit EU | `edge-solana-retrans-eu` | `233.84.178.12:7733` | -| Retransmit APAC | `edge-solana-retrans-apac` | `233.84.178.13:7733` | -| Retransmit AMER | `edge-solana-retrans-amer` | `233.84.178.14:7733` | - -端口 `5765` 是发布者心跳 — 不是 shreds。流量经过 GRE 封装；某些管道（XDP deshredder）需要剥离 GRE。 - -```bash -sudo tcpdump -ni doublezero1 host 233.84.178.1 and udp port 7733 -``` - ---- - -## 常见问题 - -1. **Reconciler 未开启。** 未执行 `doublezero enable` 时，付款不会启动隧道。 -2. **`--client-ip` ≠ 守护进程 IP。** 自动发现必须与席位匹配。 -3. **`Multicast user already exists`。** 先断开连接：`doublezero disconnect`，然后重试 `shreds pay`。 -4. **金额低于当前价格。** 重新检查 `shreds price` 并增加 `--amount`。 -5. **付款后席位未分配。** epoch 末期（下一 epoch 生效）、设备已满（需要更高任期）、或结算前已提取。 -6. **保持托管资金充足。** 通过另一次 `shreds pay` 充值；不要让余额低于 epoch 价格。 - ---- - -## 另请参阅 - -- [Edge Subscriber Connection](Edge Subscriber Connection.md) -- [支持](support.md) -- 记分板 / 席位：[data.doublezero.xyz](https://data.doublezero.xyz/dz/shreds/scoreboard) \ No newline at end of file diff --git a/scripts/translate.py b/scripts/translate.py index 406797b..502d661 100644 --- a/scripts/translate.py +++ b/scripts/translate.py @@ -44,6 +44,11 @@ def translate(content: str, lang_name: str) -> str: return message.content[0].text +def _is_runbook(filepath: str) -> bool: + name = filepath.replace("\\", "/").rsplit("/", 1)[-1] + return name == "runbooks.md" or name.endswith("-runbook.md") + + def main(): changed_files = os.environ.get("CHANGED_FILES", "").strip().splitlines() target_langs = [ @@ -53,6 +58,7 @@ def main(): ] source_files = [f.strip() for f in changed_files if f.strip() and f.endswith(".md")] + source_files = [f for f in source_files if not _is_runbook(f)] if not source_files: print("No changed source files.")