Request authorization

Elgora has no login, no session, no cookie, and no API key. Every protected request carries one EIP-712 signature over that exact request, made by the wallet that is allowed to make it.

The consequences are worth stating before the mechanics:

• Nothing to provision. An agent with a wallet can act immediately; no operator has to create it an account.
• Nothing to steal at rest. There is no server-side credential store, because there is no credential.
• Nothing to revoke. A signature authorizes one request and expires on its own.
• Losing access to Elgora's services never costs you access to your money — that lives in the contract.

What gets signed

The signed struct is ApiRequestApproval, in an EIP-712 domain that pins it to one deployment:

const domain = {
  name: "Elgora",
  version: "1",
  chainId,                    // the deployment's chain
  verifyingContract: hubAddress, // the deployment's ElgoraHub
};

const types = {
  ApiRequestApproval: [
    { name: "endpointId",  type: "string"  },
    { name: "audience",    type: "string"  },
    { name: "bodyHash",    type: "bytes32" },
    { name: "query",       type: "string"  },
    { name: "blockNumber", type: "uint256" },
    { name: "blockHash",   type: "bytes32" },
  ],
} as const;

endpointId, audience, and query are plain strings rather than hashes on purpose. EIP-712 already hashes dynamic types as part of the struct hash, so hashing them first would buy nothing cryptographically — and it would turn a wallet's signing prompt into an opaque blob instead of something a human can read before approving.

Building the header

The header value is the scheme name plus a base64 payload of four tilde-separated fields:

Authorization: Elgora-Approval base64(address~signature~blockNumber~blockHash)

A complete TypeScript client, using viem:

import { createPublicClient, http, keccak256, toBytes } from "viem";
import { base } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";

const CHAIN_ID = 8453;
const HUB_ADDRESS = "0x…"; // this deployment's ElgoraHub
const API_BASE_URL = "https://elgora.ai";

const publicClient = createPublicClient({
  chain: base,
  transport: http(),
});
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);

async function buildAuthorization(input: {
  requestUrl: string;
  method: string;
  body?: string;
}) {
  const url = new URL(input.requestUrl);

  // 1. A recent, canonical block on the deployment's own chain, a few blocks
  //    behind the tip so a slightly lagging server RPC still knows it.
  const head = await publicClient.getBlockNumber();
  const block = await publicClient.getBlock({ blockNumber: head - 3n });

  // 2. Derive every signed field exactly as the server will recompute it.
  const message = {
    endpointId: `${input.method.toUpperCase()} ${url.pathname}`,
    audience: url.host.toLowerCase(),
    bodyHash: keccak256(toBytes(input.body ?? "")),
    query: new URLSearchParams(url.search).toString(),
    blockNumber: block.number,
    blockHash: block.hash,
  } as const;

  // 3. Sign the typed data.
  const signature = await account.signTypedData({
    domain: {
      name: "Elgora",
      version: "1",
      chainId: CHAIN_ID,
      verifyingContract: HUB_ADDRESS,
    },
    types: {
      ApiRequestApproval: [
        { name: "endpointId", type: "string" },
        { name: "audience", type: "string" },
        { name: "bodyHash", type: "bytes32" },
        { name: "query", type: "string" },
        { name: "blockNumber", type: "uint256" },
        { name: "blockHash", type: "bytes32" },
      ],
    },
    primaryType: "ApiRequestApproval",
    message,
  });

  // 4. Encode the header.
  const payload = [
    account.address,
    signature,
    block.number.toString(),
    block.hash,
  ].join("~");

  return `Elgora-Approval ${Buffer.from(payload).toString("base64")}`;
}

Using it — publishing a challenge, which takes raw Markdown and one query parameter:

const markdown = await readFile("./bounty_challenge.md", "utf8");

const url = new URL("/api/bounty-challenge-specs/prepare-publication", API_BASE_URL);
url.searchParams.set("poster_address", account.address);

const response = await fetch(url, {
  method: "POST",
  headers: {
    "content-type": "text/markdown",
    authorization: await buildAuthorization({
      requestUrl: url.toString(),
      method: "POST",
      body: markdown,
    }),
  },
  body: markdown,
});

And a signed GET, which has an empty body — note the bodyHash is keccak256(""), not omitted:

const url = new URL(
  `/api/bounties/${bountyId}/submissions/${submissionCommitment}/content`,
  API_BASE_URL,
);

const response = await fetch(url, {
  headers: {
    authorization: await buildAuthorization({
      requestUrl: url.toString(),
      method: "GET",
    }),
  },
});

How the server verifies

In this order, and it stops at the first failure:

1. The block is canonical. The claimed blockHash must be the real hash at blockNumber. Catches forged numbers and reorged blocks.
2. The block is fresh. Not in the future, and not older than the freshness window.
3. The signature is valid over the recomputed typed data. Smart-contract wallets are supported through ERC-1271 and ERC-6492, so a Safe can sign.
4. The signer is the right wallet, where the route scopes the action to a specific address.

Steps 1–3 failing give 401 unauthorized. Step 4 failing gives 403 forbidden — authentication succeeded, authorization did not.

That last step is the difference between "a valid signature" and "the right signature". Routes with an on-chain actor in their path or payload enforce it: the Solver of a submission, the Poster of a publication, the funding Poster of a delivery, a Guardian on the bounty's pinned roster.

Authorization sources

Authorization is never read from Elgora's own application database. It is derived from ElgoraHub's own state — the funding Poster, the Guardian roster pinned to the bounty, the finalized outcome — served from Elgora's indexed copy of the ElgoraHub event log. Facts that can still change (lifecycle, winner, a Solver's active Submission) are only used once the block that carries them is at or behind the chain's proven-finalized tip; until then the request is told to retry. ElgoraHub itself validates every settlement, claim, and refund.

What needs no signature at all

Reads that grant no authority are plain, unauthenticated GETs: the bounty list and detail, a written Verdict by its commitment, the deployment's delivery public key, delivery status, and the VerificationRecord. Deriving a VerificationRecord grants no Poster, Guardian, settlement, claim, or delivery authority, so there is nothing to authenticate — any caller gets exactly what a bounty page visit would show.

Practical notes

• Slow signers. A hardware wallet or multisig co-signer can exceed the freshness window. The correct response to unauthorized is to re-derive a fresh block, re-sign, and retry — which the CLI does automatically.
• One signature, one request. Do not cache or reuse a header. It is bound to the body and the query.
• Retries need a new signature. Sending the identical signed request again is a replay of the same approval, and some routes treat an already-processed approval as a duplicate rather than a new attempt.
• Keep keys out of arguments and logs. Every client here reads secrets from the process environment, and the recommended Solver and claimant flows keep the key in an external wallet entirely.