Step-by-step guide to staking $GITLAWB, registering your node on-chain, and earning protocol fees as a PoS operator.
- A wallet with at least 10,000 $GITLAWB (minimum stake) plus a small amount of ETH on Base for gas
- Docker or Rust 1.91+ (for running the node process)
- PostgreSQL 16+ — the node uses
pg_input_is_valid, which exists only on PostgreSQL 16 and later. The bundleddocker-compose.ymlpinspostgres:16-alpine; if you supply your ownDATABASE_URL, the server must be 16+. - A public HTTP URL (your-host.com) — can be a VPS, Fly.io app, or anything reachable. A Fly.io config is provided at
infra/fly/fly.toml(deploy from the repo root withfly deploy -c infra/fly/fly.toml)
curl -fsSL https://twigpine.com/install.sh | sh
# or build from source:
cargo install --path crates/twigpine-cliEvery node is identified by an Ed25519 DID keypair:
twigpine identity new
twigpine identity show
# → did:key:z6Mk...This is your node DID — it's distinct from your Ethereum wallet.
This stakes $GITLAWB and links your node DID to your operator wallet:
export TWIGPINE_OPERATOR_PRIVATE_KEY=0xYOUR_KEY
export TWIGPINE_TOKEN=0x5F980Dcfc4c0fa3911554cf5ab288ed0eb13DBa3
export TWIGPINE_CONTRACT_NODE_STAKING=0xNODE_STAKING_ADDR
export TWIGPINE_CHAIN_RPC_URL=https://mainnet.base.org
twigpine node register \
--stake 10000 \
--http-url https://my-node.example.comWhat this does:
- Checks your $GITLAWB balance
- Calls
token.approve(NodeStaking, 10000e18)if needed - Calls
NodeStaking.registerNode(didHash, httpUrl, 10000e18) - Transfers 10,000 $GITLAWB into escrow
docker run -d \
--name twigpine-node \
-p 7545:7545 \
-p 7546:7546/udp \
-v gitlawb-data:/data \
-e DATABASE_URL=postgresql://user:pass@host/gitlawb \
-e TWIGPINE_PUBLIC_URL=https://my-node.example.com \
-e TWIGPINE_OPERATOR_PRIVATE_KEY=$TWIGPINE_OPERATOR_PRIVATE_KEY \
-e TWIGPINE_CONTRACT_NODE_STAKING=$TWIGPINE_CONTRACT_NODE_STAKING \
-e TWIGPINE_CHAIN_RPC_URL=$TWIGPINE_CHAIN_RPC_URL \
-e TWIGPINE_OPERATOR_STRICT_MODE=true \
ghcr.io/twigpine/node:latestSee docker-compose.yml — bundles node + Postgres.
cargo run -p twigpine-node --releaseRequired env for on-chain PoS mode:
TWIGPINE_CONTRACT_NODE_STAKING— contract addressTWIGPINE_OPERATOR_PRIVATE_KEY— key that posts heartbeatsTWIGPINE_CHAIN_RPC_URL— Base RPC URL (default Sepolia)
Optional:
TWIGPINE_OPERATOR_STRICT_MODE=true— refuse to start if not registered or not currently activeTWIGPINE_HEARTBEAT_INTERVAL_HOURS=20— how often to post heartbeats (must be < 24)TWIGPINE_RECONCILIATION_SWEEP=true— enable the hourly durability sweep that re-pins/backstops missing objects (defaulttrue; disabled when no IPFS/Pinata backend is configured). Public pin repair runs against any configured backend. Encrypted recovery repair requires local IPFS (TWIGPINE_IPFS_API); Pinata-only nodes reconcile public pins only. Set=falseto disable.
twigpine node onchain-statusExpected output:
On-chain status for did:key:z6Mk...
Operator wallet: 0x...
Staked: 10000 $GITLAWB
HTTP URL: https://my-node.example.com
Last heartbeat: 1760000000 (unix)
Active flag: true
Currently active: true
Pending rewards: 0 $GITLAWB
Check your node logs — you should see operator heartbeat loop starting and a heartbeat tx within a few seconds of startup.
The node's heartbeat loop runs every 20 hours. As long as you stay active:
- Every Sunday, the
FeeDistributordistributes accumulated fees. - 75% of the weekly pot is split across all active nodes (pro-rata by stake).
- Your share accrues as
pendingRewardson-chain — claim anytime without unstaking.
twigpine node claim7-day cooldown, two steps:
# Step 1: request unstake (starts 7-day timer)
twigpine node unstake-request
# ... wait 7 days ...
# Step 2: complete — returns stake + any pending rewards
twigpine node unstakeDuring the cooldown your node still earns rewards if it keeps heartbeating.
On the git-receive-pack POST — the push itself — the node requires the
authenticated pusher to be the repo owner, or to present a UCAN whose proof chain
roots at the owner and carries git/push for this repository (see Delegating
push to a CI agent below). Anyone else is rejected with HTTP 403 before any ref
update is applied, on every branch. The owner is matched in both the full
did:key:z6Mk… form and its bare z6Mk… suffix.
This is on by default, and the default is the point. The node authenticates every
git-receive-pack push with a valid RFC 9421 did:key signature, but did:key
is self-certifying: any party can generate a key, derive its DID and sign.
Authentication is not authorization, so without this gate every signed caller can
push to every repository — private ones included — on any branch that is not
explicitly protected.
A git push crosses two independent gates, and this section is about the second:
- Read visibility, enforced twice on a push: on the
info/refsadvertisement that precedes every fetch and every push, and again on thegit-receive-packPOST itself, because a client can skip the advertisement entirely. The owner always passes. A visibility rule that matches/is an allow-list: only the DIDs in its reader list pass, on a public repository as much as on a private one. With no matching rule the repository's own flag decides: public admits everyone, private denies every non-reader with the same 404 a missing repository gets. A UCAN plays no part here — a delegation grants no read access. - Push authorization, on the
git-receive-packPOST: the owner, or an owner-rooted, bounded, repository-scoped push delegation.
Both must pass. With no / rule on a public repository the first is open to
everyone, so a delegation alone is enough; with a / rule, or on a private
repository, the delegate must also be a reader — see Private repositories and
/ rules below.
TWIGPINE_ENFORCE_OWNER_PUSH=falseBoth the environment variable and --enforce-owner-push false disable it; the
bare --enforce-owner-push flag still means true.
Do this only for a rolling upgrade whose pushers are not yet the repo owner, and treat it as temporary: while it is off, your node accepts a push to any repository from anyone who can generate a keypair.
- When
true— a push whose authenticated DID is not the repo owner is rejected (HTTP 403) before any ref update is applied, unless it carries a valid delegation (the next bullet). The owner is matched in both the fulldid:key:z6Mk…form and its barez6Mk…suffix. - A delegated key can still push. A non-owner clears this gate by presenting a
UCAN whose proof chain roots at the repo owner and which carries
git/pushfor this repository. See Delegating push to a CI agent below.
The owner issues a capability, the agent stores it, and the git helper presents it automatically on every push:
Before anything below, set TWIGPINE_KEY to an absolute path to the
identity PEM (twigpine identity new prints it). twigpine ucan import and
git-remote-twigpine both resolve the delegation store from that key's parent
directory, so do not pass import --dir pointing anywhere else: an import that
succeeds elsewhere leaves the push unsigned. The README and .env.example
cover the layout.
# Owner, once per agent per repo:
twigpine ucan delegate --to did:key:z6MkAgent… \
--cap gitlawb://repos/<owner-did>/<repo> --can git/push --expiry 168
# Agent:
twigpine ucan import <token-or-path>
git push origin main # git-remote-twigpine attaches it as X-Ucan--expiry is measured in hours: 168 is 7 days, 720 is 30.
<repo> is the repository's canonical name: the record name without a .git
suffix. A trailing .git in the capability (or pasted from the remote URL) is
stripped the same way the git remote strips it, at most once, so
gitlawb://repos/<owner-did>/myrepo.git delegates to myrepo.
What the node requires, and why:
| Requirement | Reason |
|---|---|
| The chain's root issuer is the repo owner | A did:key is self-certifying, so anyone can mint a chain. The owner is the only anchor the node holds independently of the token. |
| Every link names this repository | A delegation's scope is fixed when it is issued. The node walks the whole proof chain, so a * resource authorizes nothing — not in the leaf and not in any proof behind it. Refusing only the leaf would not have been enough: attenuation permits narrowing a * parent to a concrete child, so one wildcard grant could otherwise reach every repository the owner has or later creates. twigpine ucan delegate therefore refuses to issue a push-class * at all. |
| Every link carries an expiry | There is no revocation path yet. An unbounded delegation could never be withdrawn once leaked, so the node refuses one outright. twigpine ucan delegate defaults to 30 days. |
No nb constraints |
Constraints are reserved but not yet interpreted, so a capability carrying them authorizes nothing rather than silently granting more than the owner intended. |
| The token is addressed to the pusher | The node requires the proof's audience to equal the invocation's issuer, and twigpine ucan import refuses a token addressed to another identity rather than storing one that can only fail. |
Private repositories and / rules. A delegation clears the push gate
only. The info/refs advertisement that git push fetches first is read-gated,
and a UCAN grants no read access, so on a private repository the delegate must
also be a reader — and the same holds on a public repository that has a /
rule, because a matching rule is an allow-list that replaces the public flag:
# Owner: check the existing rules first — a `/` rule you already set has a mode
# you want to keep, and `set` replaces its reader list wholesale.
twigpine visibility list --repo <repo>
# Then grant read to the agent AND every existing reader on `/`. The mode
# (`a`/`b`) must match what `list` showed; only reach for `b` when no `/`
# rule exists yet.
twigpine visibility set / --repo <repo> --mode <a|b> --readers did:key:z6MkReader1,did:key:z6MkAgent…Without it the agent's push fails with a 404 — the same answer a stranger gets,
because a private repository is not confirmed to exist for a non-reader. A
normal git push sees it at the info/refs advertisement; a client that skips
the advertisement sees the identical denial on the git-receive-pack POST
itself. Either way the delegation is valid and would clear the push gate: the
read gate is what refused it. On a public repository with no / rule this
step is unnecessary. The two gates are
independent in the other direction as well: a reader with no delegation is still
refused on the push.
One repository per token. twigpine ucan delegate issues one capability per token,
and twigpine ucan import stores one repository per token. A hand-built token that
names several repositories is refused at import rather than applied to some of
them; ask the owner for one delegation per repository.
A delegation does not override branch protection. A protected branch is your explicit marker that even routine writes should stop, so a delegate is still refused there and only the owner may push. That is deliberate: if a delegation overrode it, issuing any capability would weaken every protection you had set.
Withdrawal is by expiry only. There is no revocation today. If a delegated
token leaks, it remains valid until its exp, and the only faster remedy is
rotating the owner DID the repository is keyed on. Choose --expiry accordingly —
short lifetimes reissued often are safer than one long-lived grant.
| Concern | Recommendation |
|---|---|
| Heartbeat gas | ~$0.03/month on Base L2 — negligible |
| Missed heartbeats | After 3 days without one, you're excluded from rewards until you beat again |
| Operator key | Dedicated wallet, small ETH balance, not your main treasury |
| Monitoring | Watch lastHeartbeat on-chain; alert if > 22h since last beat |
| Public URL | Must resolve and serve /health for liveness and DB-aware /ready for peer readiness |
| Rolling upgrade (advisory-lock algorithm) | The SHA-256 advisory-lock key swap (replacing DefaultHasher) re-keys every repo in the first release that carries it. During a shared-Postgres rolling upgrade, old nodes compute a different i64 key than new nodes for the same repo, so PostgreSQL treats them as independent locks and cross-machine write-exclusion is lost. Drain in-flight writes or cut over through a single node before bringing new-binary nodes online. |
"insufficient $GITLAWB balance" — fund the operator wallet with at least 10,000 $GITLAWB.
Node refuses to start with "strict-mode operator check failed" — either twigpine node register first, or set TWIGPINE_OPERATOR_STRICT_MODE=false. Unsetting it is not enough if the setting is also present under its old name, GITLAWB_OPERATOR_STRICT_MODE.
Node refuses to start with "TWIGPINE_DB_LOCK_POOL_MAX_CONNECTIONS (20) must be at least max_concurrent_git_pushes (32) plus 8 for non-push mutations that share the lock pool": raise TWIGPINE_DB_LOCK_POOL_MAX_CONNECTIONS to at least the push cap plus 8 (40 with the default cap of 32, which is also the shipped default), or lower TWIGPINE_MAX_CONCURRENT_GIT_PUSHES. The check is deliberate: each concurrent push pins one connection from the lock pool for its whole receive-pack, so a lock pool that does not clear the push cap lets a burst of slow pushes starve every other mutation that needs a lock.
Node refuses to start with "TWIGPINE_DB_MAX_CONNECTIONS (4) must be at least 8 for non-git database paths": raise TWIGPINE_DB_MAX_CONNECTIONS to 8 or more (48 is the shipped default). This is the main pool, which serves everything other than held write locks; pushes no longer count against it.
Rewards are 0 after a week — run twigpine node onchain-status. If currentlyActive: false, check your heartbeat loop (node logs for operator heartbeat sent).
Want to rotate operator wallet — requires unstake → re-register with new wallet. No in-place rotation in v1.
See ECONOMICS.md for the full reward math.