zainod 0.6.0

Crate containing the Zaino Indexer binary.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# zainod

`zainod` is the Zaino indexer daemon — an indexer for the Zcash blockchain,
written in Rust.

It sits between a Zcash full validator (Zebra or Zcashd) and client
applications, serving:

- the [lightclient protocol API](https://github.com/zcash/lightwallet-protocol), the interface today
  served by [lightwalletd](https://github.com/zcash/lightwalletd), and
- a **JSON-RPC API** covering the subset of Zcash RPCs needed by wallets and
  block explorers.

This crate ships the `zainod` binary. The library half of the crate,
`zainodlib`, exposes the `run` entrypoint and configuration types for embedding
the daemon in other Rust programs.

For project background and architecture, see the
[Zaino repository](https://github.com/zingolabs/zaino).

## CLI

```text
zainod generate-config [--output FILE]   # write a default config file
zainod start [--config FILE]             # start the indexer
```

When `--config`/`--output` is omitted, the path defaults to
`$XDG_CONFIG_HOME/zaino/zainod.toml` (falling back to
`$HOME/.config/zaino/zainod.toml`).

Configuration is layered, highest priority first:

1. environment variables (prefix `ZAINO_`),
2. the TOML config file,
3. built-in defaults.

Sensitive fields (passwords, secrets, tokens, cookies, private keys) cannot be
set via environment variables and must come from the config file.

## Launching

`zainod` needs a running validator to connect to. The examples below assume one
is reachable at the address in your config.

### From crates.io

```sh
cargo install zainod
zainod generate-config            # writes the default config, then edit it
zainod start                      # uses the default config path
# or point at an explicit file:
zainod start --config ./zainod.toml
```

### From source

```sh
git clone https://github.com/zingolabs/zaino.git
cd zaino
cargo run --release -p zainod -- start --config ./zainod.toml
```

### With Podman (rootless)

The daemon is published as a container image with `zainod start` as the default
command. It runs as a non-root user (UID 1000) and refuses to start as root,
which makes it a natural fit for rootless Podman.

Run it directly, mounting a config file and a data volume:

```sh
podman run --rm \
  -p 8137:8137 \
  -p 8237:8237 \
  -v ./zainod.toml:/app/config/zainod.toml:ro,Z \
  -v zaino-data:/app/data \
  zainod:latest
```

`--userns=keep-id` maps the container's UID 1000 to your host user, so files in
the mounted data volume stay owned by you:

```sh
podman run --rm --userns=keep-id \
  -p 8137:8137 \
  -v ./zainod.toml:/app/config/zainod.toml:ro,Z \
  -v zaino-data:/app/data \
  zainod:latest
```

A typical deployment runs `zainod` alongside Zebra with `podman compose`:

```yaml
services:
  zaino:
    image: zainod:latest
    ports:
      - "8137:8137"   # gRPC
      - "8237:8237"   # JSON-RPC (if enabled)
    volumes:
      - ./config:/app/config:ro,Z
      - zaino-data:/app/data
    depends_on:
      - zebra

volumes:
  zaino-data:
```

```sh
podman compose up
```

See [`docs/docker.md`](https://github.com/zingolabs/zaino/blob/dev/docs/docker.md)
for the full container guide.

## License

Apache-2.0.