Web UI and verified signing

Ship a hosted web UI for your app, raise sign requests that pop up in the Gora wallet, and get back cryptographically verified approvals.

Web UI and verified signing

Your app’s UI is a web page — Telegram-mini-app style. The Gora mobile wallet (iOS and Android) loads it in a web view, injects window.Gora, and turns your sign requests into native approval pop-ups. When the user approves, their wallet key signs the request and the Gora network verifies the signature cryptographically before anything executes. A forged or tampered approval is rejected with HTTP 400 and never stored.

your web page ── window.Gora.action(...) ──▶ native pop-up
                                               │ Decline ──▶ gora:actionCancelled
                                               │ Approve
                                               ▼
                              wallet key signs the approval document
                                               ▼
                       bridge verifies signature against signer address
                       (EVM personal_sign recovery · ed25519 Solana/Algorand)
                                               ▼
                  action executes ──▶ gora:actionComplete { approval: {…} }

Declare the UI

In gora.app.json:

{
  "ui": {
    "type": "html",
    "html_path": "ui/index.html",
    "bridge": "gora_webview_v1"
  }
}

gora deploy reads html_path from your machine and embeds the file in the manifest as ui.html (up to 1 MiB), so nothing on your laptop is needed after deploy; the bridge serves it at GET /apps/{app_id}/ui. For a larger or separately hosted page use ui.url instead. Either way, the page is pure HTML/CSS/JS — no keys, no secrets, no signing logic. The wallet owns all of that.

The window.Gora API

Every method returns a Promise. Outside the Gora app, window.Gora is undefined — feature-detect and degrade gracefully.

Method	What it does	Resolves with
Gora.context()	Wallet context	{ bridge_url, chain, available_chains, wallets: {base, solana, algorand}, owner_wallets? }
Gora.view(viewId)	Evaluate a declared view	the view response (value, plus kind-specific fields like participants_by_chain)
Gora.invoke(input)	Run your app on the Gora node	the full invoke record
Gora.action(actionId, {chain})	Raise a sign request → native pop-up	{ presented: true } immediately; outcome arrives as events
Gora.setChain(chain)	Switch the active chain	updated context

const ctx = await window.Gora.context();
const participants = await window.Gora.view("participants");
await window.Gora.action("register", { chain: "algorand" });

Events

Outcomes are delivered as DOM events on window (also mirrored as gora:event with {type, payload}):

gora:actionComplete — the user approved, the signature verified, and the action executed:

window.addEventListener("gora:actionComplete", (e) => {
  const d = e.detail;
  // d.action_id, d.chain
  // d.approval = {
  //   signing_request_id,        // audit it on the bridge
  //   signer_address,            // the wallet that approved
  //   signature,
  //   payload_base64,            // the exact signed bytes
  //   verified_by_bridge: true   // the network checked the signature
  // }
  // d.tx_hash (chain actions) or d.output (invoke_then_action results)
});

gora:actionCancelled — the user declined in the pop-up. Nothing was signed or submitted. Always handle this; a UI that ignores declines looks broken:

window.addEventListener("gora:actionCancelled", (e) => {
  showBanner(`You declined the ${e.detail.action_id} request. Nothing was signed.`);
});

gora:actionFailed — the approval may have been signed and verified, but the follow-on execution failed (no deployed contract, chain error). The detail includes message and, when available, the verified approval.

gora:ready — fired when the bridge is installed; useful if your page races the injection.

What the user actually signs

On approve, the wallet builds a canonical sorted-key JSON document and signs those exact bytes with the per-chain key:

{
  "action_id": "register",
  "app_id": "gora_raffle",
  "chain": "algorand",
  "human_summary": "Enter the raffle (free)",
  "kind": "gora_app_action_approval_v1",
  "requested_at_unix_ms": 1781193323000,
  "schema_version": 1,
  "signer_address": "72AHB…UKDE",
  "site": "https://gora-bridge.74.241.248.103.nip.io"
}

The wallet registers it (POST /mobile/signing-requests), then posts the signature (POST /mobile/signing-requests/{id}/signature). The bridge re-verifies before storing:

• Base / EVM — EIP-191 personal_sign; the recovered address must equal signer_address.
• Solana — ed25519 over the payload; signer_address is the base58 public key; signature base58.
• Algorand — ed25519 over the payload; signer_address is the standard address (checksum validated); signature base64.

Anyone can audit the result (on the live testnet, BRIDGE is https://gora-bridge.74.241.248.103.nip.io — see Connect to the testnet):

curl $BRIDGE/mobile/signing-requests/{id}/status
# → { "status": "signed",
#     "signed_transaction": { "signature_verified": true,
#                             "verified_signer_address": "72AHB…" } }

A signature that doesn’t verify — wrong key, wrong signer, edited payload — never reaches signed status. There is no structurally-trusted path.

Declared actions drive the pop-up

The pop-up’s content and the post-approval execution come from your manifest’s interface.actions. A free registration on Algorand:

{
  "id": "register",
  "kind": "chain_transaction",
  "label": "Enter the raffle (free)",
  "description": "Opt into the raffle app on Algorand. No GORA required.",
  "network_fee": { "enabled": false },
  "transactions": {
    "algorand": { "type": "algorand_app_call", "contract": "algorand", "on_complete": "opt_in" }
  }
}

An invoke_then_action (run the app, then settle on chain with the output):

{
  "id": "run_round",
  "kind": "invoke_then_action",
  "input": { "round_view": "next_round", "participants_view": "participants" },
  "settle_action": "settle_winners"
}

The settle template maps app output into transaction arguments with $. paths ("$.round", "$.winner_1.address"). Use named output fields — the path resolver does not support array subscripts like $.winners[0].

Checklist for a good app page

• Feature-detect window.Gora; show a “open this in the Gora app” message otherwise.
• Handle all three outcome events; re-enable your buttons in each.
• Show the verification result — users trust a visible ”✓ signature verified by the Gora network” with the signer address.
• Poll your views (10–15 s) instead of assuming actions changed state.
• Never put keys, mnemonics, or RPC tokens in the page. It’s a UI surface.

The GORA Raffle is a complete working example — gora-raffle (examples distribution)/ui/index.html is ~250 lines and exercises every event above. Operational details (hosting, systemd, demo script): docs/web-ui-signing-runbook.md in the repo.