# Gora Docs for AI Agents

Gora lets developers build local JS/TS/Python/WASM apps, deploy them to Gora Devnet, and connect their results to Base, Solana, Algorand, mobile approval, or chain contracts.

Use this file as the decision guide before asking the user for missing chain metadata.

## Canonical model

- `gora deploy` deploys the Gora app package to a Gora node.
- `gora contract deploy` deploys, records, or resolves chain contract metadata.
- Gora app deployment and chain contract deployment are separate.
- Gora app code returns JSON results, intents, callbacks, or signing requests.
- Gora app code must not hold private keys or sign transactions directly.
- Mobile app UI is HTML-only. Apps publish UI with `gora.app.json` `ui.html_path`, `ui.html`, or `ui.url`; iOS loads it in a WebView.
- App-specific chain reads and transaction/action shapes belong in `gora.app.json` `interface`; HTML calls them through `window.Gora` / bridge APIs. Do not add app-specific native mobile screens for participants, rounds, or action builders.
- Chain execution happens through a gateway, app contract, smart wallet, mobile signature, or submitter.
- A Devnet VM can run Gora, Base, Solana, Algorand, ngrok, and the contract registry.
- A local developer can point the CLI at the Gora ngrok URL and does not need VM-only chain files.

## Key docs

- `index.mdx`: high-level start page.
- `concepts/how-gora-apps-work.mdx`: mental model.
- `concepts/validators-and-consensus.mdx`: how validators run, who can launch one (Solana, Base, or Algorand stake entry), how consensus rounds produce attestations.
- `concepts/randomness-and-vrf.mdx`: verifiable randomness for off-chain apps (via `req.vrf`) and smart contracts (via the chain gateway callback).
- `concepts/external-calls.mdx`: `gora.fetch` host function, proposer-fetch transcript vs quorum-fetch modes, policy allowlist, sensitive-header redaction.
- `app/create-offchain-wasm-app.mdx`: app creation and templates.
- `app/add-smart-contract.mdx`: contract metadata and chain linking.
- `app/build-attested-on-chain-app.mdx`: pattern for apps that hold value on-chain (operator records, winner claims).
- `app/set-policy-and-payments.mdx`: policy and execution modes.
- `examples.mdx`: list of runnable reference examples.
- `examples/raffle-app.mdx`: rebuild and deploy the cross-chain raffle app.
- `launch/devnet-js-ts-quickstart.mdx`: VM-to-local golden path.
- `launch/canonical-flows.mdx`: the three MVP app flows and self-serve QA command.
- `launch/devnet-seeded-wallets.mdx`: dev-only keys and wallets.
- `launch/deploy-to-gora.mdx`: deploy reference.
- `launch/test-with-mobile.mdx`: mobile approval/signing.
- `launch/troubleshooting.mdx`: symptom-based fixes.

## Golden path for local developers

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

gora config set node.url https://gora-dev.ngrok.app

gora contract doctor --chain algorand --node https://gora-dev.ngrok.app
gora contract build --chain algorand
gora contract deploy --chain algorand --node https://gora-dev.ngrok.app
gora contract link --chain algorand

gora build
gora validate
gora deploy

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

Use `base` or `solana` in place of `algorand` when appropriate.

## Devnet operator path

On the VM:

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

This starts Gora, local chains, contract metadata, the dev bridge, and ngrok tunnels. The default bridge URLs are:

```text
VM-local bridge: http://127.0.0.1:8787
Mobile URL:      https://gora-bridge-dev.ngrok.app
```

Check:

```bash
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
```

Use `tmux` if the process should stay running after disconnect.

## P08.8 self-serve QA

After rebuilding the CLI and starting Devnet:

```bash
node ops/p08_8_self_serve_qa.mjs --node https://gora-dev.ngrok.app --bridge https://gora-bridge-dev.ngrok.app
```

For template-only checks:

```bash
node ops/p08_8_self_serve_qa.mjs --offline
```

The script creates the `offchain-callback`, `mobile-coin-flip`, and `agent-mobile-signing` templates, validates them, checks node/bridge health, and simulates bridge mobile signing with a mock submission plan.

## Templates

Supported `gora init --template` values:

- `offchain-callback`
- `mobile-coin-flip`
- `agent-mobile-signing`

A template can still be combined with `--chain`, `--language`, `--contract`, and `--wallet` overrides.
Mobile signing templates must include `mobile_signing_request.signing_payload.bytes_base64` and `submission_plan`.

## Examples

When the user asks how to rebuild a concrete app, start with:

- `examples/raffle-app.mdx`

The raffle app demonstrates an off-chain Gora drawer plus app-owned treasuries on Base, Solana, and Algorand. Contract receipts should be read from `.gora/contracts/<chain>/latest.json`; `raffle.json` is kept only as a legacy copy for the reference script.
The Devnet launcher defaults to `GORA_DEV_EXAMPLE_APP=raffle-app`; use `GORA_DEV_EXAMPLE_APP` or `GORA_DEV_EXAMPLE_APP_DIR` for another example app.

Generic clients should inspect:

```bash
curl https://gora-bridge-dev.ngrok.app/apps/raffle_app/ui
curl https://gora-bridge-dev.ngrok.app/apps/raffle_app/views/participants
curl https://gora-bridge-dev.ngrok.app/apps/raffle_app/views/next_round
```

## Contract metadata discovery

Before asking a user for an app id, program id, address, RPC URL, or VM filesystem path, query Gora Devnet:

```bash
curl https://DEVNET-ENDPOINT/v1/contracts
curl https://DEVNET-ENDPOINT/v1/contracts/algorand
curl https://DEVNET-ENDPOINT/v1/contracts/base
curl https://DEVNET-ENDPOINT/v1/contracts/solana
```

Prefer CLI resolution:

```bash
gora contract deploy --chain <chain> --node https://DEVNET-ENDPOINT
```

This records returned metadata into `.gora/contracts/<chain>/latest.json`.

## Algorand datadir rule

`--datadir` is the local Algorand `Node/` directory containing `algod.net` and `algod.token`.

Only use:

```bash
gora contract deploy --chain algorand --rpc <rpc_url> --datadir <Node_DIR>
```

when the CLI is running on the same machine as that Algorand localnet.

For normal local development, use:

```bash
gora contract deploy --chain algorand --node https://DEVNET-ENDPOINT
gora contract link --chain algorand
```

If metadata says `needs_deployment`, ask the Devnet operator to deploy the gateway or publish `ALGORAND_APP_ID`, then refresh the registry.

## Expected Algorand metadata

```json
{
  "ok": true,
  "chain": "algorand",
  "contract": {
    "chain": "algorand",
    "kind": "algorand_application",
    "name": "GoraAlgorandGateway",
    "role": "app_contract",
    "status": "deployed",
    "app_id": "1001",
    "address": "1001",
    "deployment_tx": "TX_ID",
    "network": "devnet-local",
    "chain_id": "31337",
    "rpc_url": "https://algorand-dev.ngrok.app",
    "auth": {
      "type": "algod_token",
      "header": "X-Algo-API-Token",
      "token_env": "ALGORAND_ALGOD_TOKEN",
      "token_included": false
    }
  }
}
```

If `token_included` is false, do not ask for the VM datadir. Read the token from the named environment variable if present, or ask the operator for a secure dev-only token.

## Secrets rule

Never put these in app source, manifest, policy, fixtures, package metadata, stdout, or committed files:

- private keys
- seed phrases
- deployer keys
- API tokens
- RPC secrets
- Algod tokens

Devnet seeded keys are only for local development and mobile signing tests.

## Runtime contract

For JS/TS/Python apps:

```text
stdin: JSON request envelope
stdout: JSON result only
stderr: logs
exit 0: success
exit nonzero: failure
```

If logs are printed to stdout, Gora may fail to parse the result.

## Mobile signing

If an app needs user-paid execution, return a `mobile_signing_request`. The node can fill request metadata and publish it to a bridge or signing sink.

With `gora devnet up`, the signing sink is configured automatically to the VM-local dev bridge. Mobile clients on another computer should read from `https://gora-bridge-dev.ngrok.app`.

Common submission modes:

- `mock`
- `evm_raw`
- `solana_raw`
- `algorand_raw`

A successful `gora invoke` does not guarantee a chain transaction. It means the app ran and returned a result. A gateway, wallet, mobile flow, or submitter must still execute chain state changes.

## Solana and Algorand testing tokens

Solana Devnet does not currently have a fixed documented seeded wallet. Generate a dev-only keypair and fund it from the local validator faucet:

```bash
solana-keygen new --no-bip39-passphrase --outfile target/devnet-chains/solana-dev-wallet.json --force
SOLANA_ADDR="$(solana address --keypair target/devnet-chains/solana-dev-wallet.json)"
solana airdrop 100 "$SOLANA_ADDR" --url http://127.0.0.1:8899
solana balance "$SOLANA_ADDR" --url http://127.0.0.1:8899
```

From a local computer, try `--url https://solana-dev.ngrok.app`; if the faucet call fails, ask the Devnet operator for a dev-only funded JSON keypair.

Algorand Devnet creates funded `Wallet1`, `Wallet2`, and `Wallet3` accounts in the active VM localnet. They are regenerated when localnet resets. List them on the VM:

```bash
chains/algorand/.tooling/bin/goal account list \
  -d target/devnet-chains/algorand-localnet/Node
```

Typical starting balances are `4000000000000000`, `4000000000000000`, and `2000000000000000` microAlgos. Export a dev-only mobile mnemonic with:

```bash
chains/algorand/.tooling/bin/goal account export \
  -a <ADDRESS> \
  -d target/devnet-chains/algorand-localnet/Node
```

## Troubleshooting decisions

- Health fails locally on VM: run `gora devnet status` and check the Gora process.
- Health works locally but ngrok fails: check ngrok auth/domain/port.
- `gora validate` missing artifact: run `gora build` and verify manifest path.
- Algorand asks for `--datadir` locally: use `--node` contract metadata resolution instead.
- `contract.status` is `needs_deployment`: operator must deploy or publish contract/app id in registry.
- Invoke succeeds but no chain tx appears: connect mobile signing, gateway fulfillment, or a chain submitter.