HUB
Sign inSign up

rinzlerfr/aioznode

By rinzlerfr

•Updated 4 days ago

Unattended AIOZ DePIN node: self-updating, health-checked, rewards withdrawn

Image
0

628

rinzlerfr/aioznode repository overview

⁠AIOZ DePIN node in Docker

Tests pre-commit Release Docker Pulls Docker Image Size License

An AIOZ DePIN node that runs itself: it updates, proves that it works, restarts when it does not, and withdraws its rewards.

A Docker image for an AIOZ DePIN⁠ node, on any Docker host. Each start installs the latest upstream CLI; the health check proves that the node answers and reads its rewards; an optional second container withdraws the rewards to your wallet.

The repository is also a worked example of a small infrastructure project: every rule it follows is written down, and most of them are checked by a test.

The diagram of the containers⁠, on GitHub.

⁠Quick start

The commands run against any Docker context, local or remote (docker context use, DOCKER_HOST=ssh://user@host). The node data lives in a named volume: no folder of the host has to be known.

docker volume create aioznode-data
docker run -d --name aioznode --restart=always -p 1317:1317 \
  -v aioznode-data:/nodedata rinzlerfr/aioznode
docker logs -f aioznode    # until: Wallet successfully configured

Warning At its first start the node creates a new wallet, and the volume holds the only copy of its key. Back the key up to a safe place, out of any clone: docker cp writes it on the machine that runs the command, not on a remote Docker host.

docker cp aioznode:/nodedata/privkey.json privkey.json
chmod 600 privkey.json

The node and the reward withdrawal together, from a clone of this repository:

WITHDRAW_ADDRESS_HEX=0xYourAddress docker compose up -d

Running the image⁠ covers the rest: an existing wallet, a host folder instead of the volume, the compose commands, and the migration of a compose deployment that keeps its wallet in ./nodedata.

⁠Configuration

  • WITHDRAW_ADDRESS_HEX (required in withdraw mode): the 0x address that receives the rewards.
  • WITHDRAW_MIN_VALUE (10^18, 1 AIOZ): the balance, in attoaioz, above which the rewards are withdrawn.
  • CHECK_FREQ (60): seconds between two withdraw checks.
  • RUN_TIMEOUT (86400): seconds before the node stops, so that the container restarts and updates.
  • GITHUB_TOKEN (unset): authenticates the release lookup.

Every setting, the watchdog timings included: environment variables⁠.

⁠Engineering practices

  • Self-updating, safely. Each start checks the latest upstream release against its SHA256SUMS, and keeps the installed CLI when the update fails (ADR 0001⁠).
  • A health check that proves the function. The node must answer and the wallet must read its rewards; after repeated failures a watchdog stops the node, so that the container restarts (ADR 0002⁠).
  • One image, two modes: the node, or the reward withdrawal with the node data read-only (ADR 0003⁠).
  • Upstream bugs handled, not hidden. The node works around a broken upstream start, and a daily workflow reports what changes upstream (ADR 0005⁠, upstream watch⁠).
  • Tested shell. bats suites run in Docker, against fakes asserted on the PATH and real captures of the GitHub API and the CLI. Fitness tests turn the repository rules into tests, this page included.
  • Hardened delivery. Workflows read-only by default, actions pinned to a commit and checked by zizmor, trivy scans; outdated hooks and actions block the commit; latest only moves to the highest release (CI and release⁠).
  • Operated, not only built. A host script reports when the node stops earning delivery rewards, and when it earns them again (delivery watch⁠).
  • AI harness, model and tool agnostic. One file, AGENTS.md⁠, instructs every coding agent; tests keep the tool-specific files from drifting (AI harness⁠).

⁠Documentation

⁠Contributing

Issues and pull requests are welcome: see CONTRIBUTING.md⁠. Report a vulnerability privately, as SECURITY.md⁠ describes, never in a public issue.

⁠Support

If you find this project useful, please consider donating:

  • AIOZ: 0x4D11B64d9bb0652a92FCaD019d7Fc79f14821571
  • AIOZ (bech32): aioz1f5gmvnvmkpjj4yhu45qe6l78nu2gy9t3mklmct

⁠License

MIT⁠

Tag summary

Content type

Image

Digest

sha256:905f7f787…

Size

210 MB

Last updated

4 days ago

docker pull rinzlerfr/aioznode