spherenet-admin 0.3.0

Command-line tool for SphereNet governance and network administration
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
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

# SphereNet Admin CLI

Command-line tool for SphereNet governance and network administration.

```bash
cargo install spherenet-admin
spherenet-admin --help
```

Global flags (all commands): `--url <URL>` (defaults to testnet `https://api.test.sphere.net`) and `--output text|json`. In both modes stdout carries only the result and diagnostics go to stderr, so `… --output json | jq` always sees clean JSON.

Every governance/program/transfer command runs **single-sig** (`--authority <keypair>`, executes immediately) or **multisig** (`--multisig <create-key> --multisig-authority <member>`, creates a Squads proposal). A multisig is always referenced by its **create-key** (a pubkey), which the CLI resolves + validates to the vault that holds funds and signs.

---

## Public commands

Everything a validator, deployer, or user runs on their own — no governance authority required.

### Join the network (`vw request` / `pw request`)

Onboarding is **two-step**: you *request*, an authority *approves* async. The requester co-signs to prove control of the key.

```bash
# Validator: request a validator-whitelist entry (the vote account co-signs)
spherenet-admin vw request ./vote-account.json --start-epoch 100 --end-epoch 200 --authority ./payer.json

# Deployer: request program-deploy access (the deploy authority co-signs)
spherenet-admin pw request ./deploy-authority.json --authority ./payer.json
```

The `--authority` here is just the fee-payer; the requesting key (vote account / deploy authority) is the co-signer that proves control. Once an admin approves, you're active.

### Vote (`vote`)

```bash
spherenet-admin vote create --vote-account ./vote.json --identity ./identity.json \
  --authorized-voter <PK> --authorized-withdrawer <PK> --commission 100 \
  --from ./funder.json --payer ./payer.json          # add --no-bls for legacy V1 (pre-SIMD-0464)
```
- `vote show <VOTE_ACCOUNT>` · `vote withdraw --vote-account <PK> --destination <PK> (--all) --withdraw-authority ./w.json`

Defaults to a V2 account with a BLS key derived from `--identity`; keep `--authorized-withdrawer` distinct from the identity.

### Stake (`stake`)

```bash
spherenet-admin stake create --stake-account ./stake.json --amount 10000 \
  --stake-authority <PK> --withdraw-authority <PK> --from ./funder.json --payer ./payer.json
spherenet-admin stake delegate --stake-account <PK> --vote-account <PK> --stake-authority ./staker.json --payer ./payer.json
```
- `stake show <PK>` · `stake deactivate …` · `stake withdraw … (--amount <SPHR> | --all)`

Delegation is gated on the validator whitelist and fails fast if the vote account isn't approved.

### Programs (`program`)

The upgrade authority must be `pw`-approved first (see *Join the network*).

```bash
spherenet-admin program deploy --program-so ./p.so --program-keypair ./p-keypair.json \
  --upgrade-authority ./auth.json --payer ~/.config/solana/id.json [--max-data-len 500000]
```
- `program upgrade --program-id <ID> --program-so ./p.so …` (single-sig or multisig)
- `program extend --program-id <ID> --bytes <N>` — grow capacity (permissionless; payer covers the added rent)
- `program set-upgrade-authority --program-id <ID> [--new-authority <PK> | --new-multisig <CK> | --final]`

### Multisig (`multisig`)

```bash
spherenet-admin multisig create --members <PK>,<PK>,<PK> --threshold 2 --create-key ./ck.json --payer ./payer.json --memo "Treasury"
spherenet-admin multisig show    --multisig <CREATE_KEY>
spherenet-admin multisig approve --multisig <CREATE_KEY> --transaction-index <N> --member ./member.json
spherenet-admin multisig execute --multisig <CREATE_KEY> --transaction-index <N> --member ./member.json
```

### Utilities

```bash
spherenet-admin transfer --amount 1.5 --to <PK> --from ./keypair.json     # or --to-multisig <CREATE_KEY>
spherenet-admin airdrop  --pubkey <PK> --amount 5.0                        # testnet faucet
spherenet-admin balance  <PK>
spherenet-admin epoch
spherenet-admin server --port 8080                                        # read-only JSON HTTP API (GET /mp /vw /pw /epoch /balance/{pk} …)
```

---

## Admin commands

Governance-authority actions. Three whitelists/policies govern the network:

- **Validator Whitelist (`vw`)** — which validators may join consensus.
- **Program Whitelist (`pw`)** — which authorities may deploy/upgrade programs.
- **Monetary Policy (`mp`)** — inflation rate, per-signature fee, fee burn, and per-epoch VAT.

Each is a single config account with a transferable authority; `vw`/`pw` entries move through a **request → approve/reject** lifecycle.

### Validator Whitelist (`vw`)

```bash
spherenet-admin vw approve <VOTE_ACCOUNT> --start-epoch 100 --end-epoch 200 --authority ./authority.json
spherenet-admin vw reject  <VOTE_ACCOUNT> --authority ./authority.json
```
- `vw show` — authority + entries (each `Pending` or `Approved`)
- `vw remove <VOTE_ACCOUNT>` · `vw update-start-epoch <VA> --epoch <N>` · `vw update-end-epoch <VA> --epoch <N>`
- `vw propose-authority [--new-authority <PK> | --new-multisig <CK>]` · `vw accept-authority` · `vw cancel-authority`

### Program Whitelist (`pw`)

```bash
spherenet-admin pw approve <DEPLOYER_PUBKEY> --authority ./authority.json
spherenet-admin pw reject  <DEPLOYER_PUBKEY> --authority ./authority.json
```
- `pw show` · `pw remove <DEPLOYER>`
- `pw propose-authority [--new-authority | --new-multisig]` · `pw accept-authority` · `pw cancel-authority`

### Monetary Policy (`mp`)

```bash
spherenet-admin mp update-inflation-rate <BIPS> --authority ./authority.json    # 0–2000 = 0–20%
```
- `mp show`
- `mp update-lamports-per-signature <LAMPORTS>` · `mp update-burn-percent <PERCENT>` · `mp update-vat-lamports-per-epoch <LAMPORTS>`
- `mp propose-authority [--new-authority | --new-multisig]` · `mp accept-authority` · `mp cancel-authority`

The `mp` config account is created at genesis, not by this CLI.

---

## Built-in addresses

Testnet RPC: `https://api.test.sphere.net`

| program | address |
|---|---|
| Stake | `Stake11111111111111111111111111111111111111` |
| Vote | `Vote111111111111111111111111111111111111111` |
| Validator Whitelist | `VwL1111111111111111111111111111111111111111` |
| Program Whitelist | `PwL1111111111111111111111111111111111111111` |
| Monetary Policy | `MpM1111111111111111111111111111111111111111` |
| Squads v4 | `Sqds111111111111111111111111111111111111111` |
| ZK Loader | `ZkLoader11111111111111111111111111111111111` |
| SPL Token | `TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA` |
| Token-2022 | `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` |
| Associated Token Account | `ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL` |