Devnet quickstart

Run Gora Devnet on a VM, develop locally, deploy through a public tunnel, invoke, and inspect results.

Devnet quickstart

This page is for running your own local devnet / validator infrastructure. To build against the live Gora testnet you don’t need any of this — see Connect to the testnet. URLs like https://YOUR-NODE-URL below are placeholders for your own tunnel or reverse proxy (ngrok, Caddy, or any HTTPS tunnel works).

This is the clearest VM-to-local flow for DevNet.

For the CLI-only BTC/USD oracle callback path, start with Serve smart contracts: oracle callbacks. That path does not use the mobile app.

1. A VM runs Gora Devnet, local chains, and a public tunnel (ngrok, Caddy, or any HTTPS tunnel).
2. Your local computer runs the Gora CLI and app code.
3. The local CLI points at the Gora public tunnel URL.
4. Contract metadata comes from Gora Devnet, not from VM-only files.

Devnet Testing

Use this role split when testing the distributable validator binary with real DevNet operators, funded GORA, and developer-owned callback apps.

Validator operators

Each validator receives one release or tester archive from the launch packet. They should verify the checksum, extract it on their VM, and run setup with their own wallet and public validator URL:

sha256sum -c <archive>.sha256
tar -xzf <archive>
cd <extracted-package>

cp config/devnet.validator-profile.example.json config/devnet.validator-profile.json
# For Solana or Algorand, start from the matching profile file:
# config/devnet.validator-profile.solana.example.json
# config/devnet.validator-profile.algorand.example.json

Edit config/devnet.validator-profile.json so it has the real DevNet RPC URL, bootstrap peers, staking contract/program/app, and GORA token identifier for the chain where this validator will stake.

bin/gora validator profile validate \
  --profile config/devnet.validator-profile.json

bin/gora validator setup \
  --data-dir validator \
  --profile config/devnet.validator-profile.json \
  --owner <validator-wallet-address> \
  --public-url https://validator.example.com

The validator sends validator/funding-request.json to the admin. That file contains the staking owner address, required GORA amount, native fee token requirement, chain target, and any preconditions. Solana validators may need an associated token account for the GORA SPL mint. Algorand validators must opt into the GORA ASA before the admin can fund the wallet.

After the wallet is funded and the registration transaction is signed, the validator finalizes and starts:

bin/gora validator finalize \
  --data-dir validator \
  --delegation-signature <wallet-signature>

bin/gora validator check-config --data-dir validator
bin/gora validator check-stake --data-dir validator
bin/gora validator run --data-dir validator

The validator returns the ready receipt, check-stake output, and any requested remote-smoke logs to the admin for final evidence collection.

Smart contract and off-chain app developers

Developers deploy their chain callback contract/program/app first, then deploy the Gora off-chain app that fetches or transforms data and emits the callback intent.

For a starter callback app:

gora init callback-demo --template offchain-callback --chain base --yes
cd callback-demo

gora config set node.url https://YOUR-NODE-URL
gora contract build --chain base
gora contract deploy --chain base --node https://YOUR-NODE-URL
gora contract link --chain base

gora build
gora validate
gora package
gora deploy
gora invoke --app callback_demo --input fixtures/request.json

Use --chain solana or --chain algorand for those callback targets. The generated app returns chain_callback.operation.target and chain_callback.operation.params objects, plus an operation_schema, so submitters can route the callback without relying on positional arguments.

For the BTC/USD oracle callback path, follow Serve smart contracts: oracle callbacks. In live DevNet testing, fixtures must use command-mode submitters so Base, Solana, and Algorand callbacks land as real transactions.

Admin and GORA funding

The admin owns the launch packet and funding checklist. Start from:

target/devnet-launch-packet
target/devnet-launch-packet/testers/tester-send-manifest.csv
target/devnet-launch-packet/funding/devnet-fleet-funding-plan.csv
target/devnet-launch-packet/funding/devnet-fleet-funding-list.csv

For each validator:

1. Confirm the archive checksum in tester-send-manifest.csv.
2. Confirm the validator public URL is externally reachable.
3. Confirm the staking owner and chain target in the funding CSV.
4. Send the required GORA amount to that staking owner on the correct chain.
5. Send enough native fee token for registration and staking.
6. For Solana, create or fund the GORA SPL associated token account if needed.
7. For Algorand, wait for the validator to opt into the GORA ASA before sending GORA.

After funding, collect final evidence:

node ops/capture-final-devnet-launch-evidence.mjs \
  --packet target/devnet-launch-packet \
  --inventory target/devnet-initial-testers/inventory.json \
  --node "$GORA_NODE_URL" \
  --bridge "$GORA_BRIDGE_URL" \
  --out-dir target/final-devnet-launch

Then run the final gate:

node ops/devnet-readiness-audit.mjs \
  --out target/devnet-readiness-audit.final.json \
  --launch-evidence target/final-devnet-launch/devnet-launch-evidence.json \
  --launch-packet-out target/devnet-launch-packet \
  --release-dir target/gora-release-devnet \
  --handoff-dir target/devnet-handoff-linux \
  --handoff-dir target/devnet-handoff-darwin \
  --chains base,solana,algorand \
  --require-final

The final audit should report ready_for_devnet: true, manual_gates_cleared: true, and no remaining manual gates before moving from DevNet testing to testnet.

A. Start Devnet on the VM

On the VM where the Gora repo, local chains, and your tunnel live:

gora devnet up --chains base,solana,algorand --mobile-signing true

This starts:

• Gora dev HTTP API
• Dev Bridge for mobile approval/signing
• Base/Ganache local RPC
• Solana local validator
• Algorand localnet
• public tunnels (ngrok by default; Caddy or any HTTPS tunnel works)
• contract metadata registry

The command stays running. Use tmux if you want to detach:

tmux new -s gora-devnet
gora devnet up --chains base,solana,algorand --mobile-signing true

Check status from another VM shell:

gora devnet status
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8787/health
curl http://127.0.0.1:8080/v1/contracts

Typical public endpoints:

Gora API:   https://YOUR-NODE-URL
Dev Bridge: https://YOUR-BRIDGE-URL
Base RPC:   https://YOUR-BASE-RPC-URL
Solana RPC: https://YOUR-SOLANA-RPC-URL
Algorand:   https://YOUR-ALGORAND-RPC-URL

Gora posts mobile signing requests to the bridge over the VM-local URL http://127.0.0.1:8787. Mobile apps on another machine read the same requests through https://YOUR-BRIDGE-URL.

Stop processes started by the helper:

gora devnet down

B. Configure your local app

For the no-mobile price oracle, use the schedule commands in Serve smart contracts: oracle callbacks.

On your local computer, create an app:

gora init my-agent --template agent-mobile-signing --chain algorand --yes
cd my-agent

Set the Gora Devnet URL:

gora config set node.url https://YOUR-NODE-URL

If Devnet requires a token:

gora config set api.token YOUR_TOKEN

Check health:

curl https://YOUR-NODE-URL/health

C. Resolve chain contract metadata

For apps that target Base, Solana, or Algorand, link chain metadata before deploying the Gora app package.

First run doctor:

gora contract doctor --chain algorand --node https://YOUR-NODE-URL

Then resolve and link:

gora contract build --chain algorand
gora contract deploy --chain algorand --node https://YOUR-NODE-URL
gora contract link --chain algorand

For Base:

gora contract build --chain base
gora contract deploy --chain base --node https://YOUR-NODE-URL
gora contract link --chain base

For Solana:

gora contract build --chain solana
gora contract deploy --chain solana --node https://YOUR-NODE-URL
gora contract link --chain solana

The --node form calls GET /v1/contracts/{chain} and records the deployed address, program id, or Algorand app id in .gora/contracts/<chain>/latest.json.

For Algorand, this is the important distinction:

• local developers use --node https://YOUR-NODE-URL
• VM operators may use --datadir /path/to/Node

Do not use --datadir from a local computer unless that computer is running the Algorand localnet.

D. Build, validate, package, deploy

gora build
gora validate
gora package
gora deploy

gora deploy uploads:

• app artifact
• manifest
• policy
• package metadata
• linked contract metadata

It writes a deployment receipt to:

.gora/deployments/dev.json

E. Invoke

Use the generated fixture:

gora invoke --app my_agent --input fixtures/request.json

The response includes a request_id.

If your app result includes a chain field, Devnet may attach contract_metadata to the invoke or result response. Use that metadata for app ids, program ids, addresses, RPC URLs, and auth hints.

F. Inspect

gora inspect request <request-id>
gora inspect result <request-id>
gora inspect attestation <request-id>
gora inspect app my_agent
gora status --app my_agent --bridge https://YOUR-BRIDGE-URL

Inspect receipts are saved under:

.gora/inspect/

What success means

A successful invoke means:

1. Devnet found your deployed app.
2. Devnet ran the declared artifact.
3. Your app returned valid JSON.
4. Gora recorded the result and attestation data.

It does not necessarily mean a chain transaction was submitted. Chain execution requires a gateway, wallet, mobile signing flow, or submitter.

For mobile signing flows, use:

gora inspect signing <signing-request-id> --bridge https://YOUR-BRIDGE-URL
gora inspect submission <signing-request-id> --bridge https://YOUR-BRIDGE-URL

One-screen local flow

gora init my-agent --template agent-mobile-signing --chain algorand --yes
cd my-agent

gora config set node.url https://YOUR-NODE-URL

gora contract doctor --chain algorand --node https://YOUR-NODE-URL
gora contract build --chain algorand
gora contract deploy --chain algorand --node https://YOUR-NODE-URL
gora contract link --chain algorand

gora build
gora validate
gora deploy

gora invoke --app my_agent --input fixtures/request.json

Next: Deploy to Gora.