Reference · Contract API

Contract API reference

On-chain reference, not a live REST API

No API server is deployed for Novak yet. Every endpoint below documents the intended surface against the real, already-implemented on-chain function signatures (EventRegistry, EventComposer, EventBus) so a future indexer/API layer has an exact contract to build against. Today, reads happen via the SDK or direct contract calls — the curl examples below are illustrative of the intended REST shape, not something you can call right now.

GET/events

List primitive events, optionally filtered by status.

Param	Type	Description
status	EventStatus \| string	Open, ObservationsSubmitted, ProposedOutcome, Disputed, Finalized, Voided, Expired.
limit	number	Page size, default 25.
cursor	string	Opaque pagination cursor.

JSON Response Schema

200 OK Response

{
  "events": [
    {
      "id": "0x1a2b...9f1a2b",
      "sourceId": "example.rate-decision",
      "status": "Finalized",
      "quorumThreshold": 2,
      "observationDeadline": 1798761600
    }
  ],
  "nextCursor": null
}

Invocation Example

curl "https://api.novak.xyz/events?status=Finalized&limit=25"

GET/events/:id

Single primitive event: its spec and, once finalized, its outcome.

Param	Type	Description
id*	bytes32 (hex)	Event ID.

JSON Response Schema

200 OK Response

{
  "id": "0x1a2b...9f1a2b",
  "spec": {
    "specVersion": 1,
    "sourceId": "example.rate-decision",
    "openTimestamp": 1798000000,
    "observationDeadline": 1798086400,
    "disputeWindowSeconds": 3600,
    "quorumThreshold": 2
  },
  "status": "Finalized",
  "outcome": {
    "exists": true,
    "outcomeData": "0x...(abi.encode(bool))",
    "finalizedAt": 1798090001
  }
}

Invocation Example

curl "https://api.novak.xyz/events/0x1a2b...9f1a2b"

GET/events/:id/status

Lightweight status poll — just the enum, for tight polling loops.

Param	Type	Description
id*	bytes32 (hex)	Event or composite ID.

JSON Response Schema

200 OK Response

{ "status": "ObservationsSubmitted" }

Invocation Example

curl "https://api.novak.xyz/events/0x1a2b...9f1a2b/status"

POST/events

Create a new primitive event — permissionless (anyone may create an event; only authorized resolvers can later observe it).

Param	Type	Description
sourceId*	string	Which resolver adapter class can serve this event.
specVersion*	number	Outcome payload schema version (1 = abi.encode(bool)).
observationDeadline*	unix timestamp	Last time a resolver may submit an observation.
disputeWindowSeconds*	number	Challenge window after a proposed outcome.
quorumThreshold*	number	Matching authorized-resolver observations required.
spec*	hex	Opaque, versioned event definition.

JSON Response Schema

200 OK Response

{ "id": "0x1a2b...9f1a2b", "txHash": "0xabc...123" }

Invocation Example

curl -X POST "https://api.novak.xyz/events" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":"example.rate-decision","specVersion":1,"observationDeadline":1798086400,"disputeWindowSeconds":3600,"quorumThreshold":2,"spec":"0x..."}'

GET/composite-events/:id

Composite event detail, including its full child event tree.

Param	Type	Description
id*	bytes32 (hex)	Composite event ID.

JSON Response Schema

200 OK Response

{
  "id": "0x4d5e...3c4d5e",
  "op": "Within",
  "window": 172800,
  "status": "True",
  "depth": 1,
  "operands": [
    { "id": "0x1a2b...9f1a2b", "kind": "primitive", "status": "Finalized" },
    { "id": "0x2b3c...b3c4d", "kind": "primitive", "status": "Finalized" }
  ]
}

Invocation Example

curl "https://api.novak.xyz/composite-events/0x4d5e...3c4d5e"

POST/compose

Build a new composite event from existing primitive or composite IDs.

Param	Type	Description
op*	"And"\|"Or"\|"Not"\|"Before"\|"Within"	Operator.
operands*	bytes32[]	Existing event/composite IDs. Must already exist.
window	number (seconds)	Only meaningful for Before/Within.

JSON Response Schema

200 OK Response

{ "id": "0x4d5e...3c4d5e", "txHash": "0xdef...456" }

Invocation Example

curl -X POST "https://api.novak.xyz/compose" \
  -H "Content-Type: application/json" \
  -d '{"op":"Within","operands":["0x1a2b...9f1a2b","0x2b3c...b3c4d"],"window":172800}'

POST/observationsResolver-only — not a general dev endpoint

A resolver submits an observation (outcome + evidence hash) for an event it watches. Requires the caller to be an authorized resolver (EventRegistry.setResolverAuthorization).

Param	Type	Description
eventId*	bytes32 (hex)	Event being observed.
outcomeData*	hex	abi.encode(bool) for specVersion 1.
evidenceHash*	bytes32 (hex)	Commitment to the resolver's raw evidence.

JSON Response Schema

200 OK Response

{ "accepted": true, "quorumReached": false }

Invocation Example

# Resolver-signed request — never a general developer credential.
curl -X POST "https://api.novak.xyz/observations" \
  -H "Authorization: Bearer <resolver-signing-key>" \
  -d '{"eventId":"0x1a2b...9f1a2b","outcomeData":"0x...","evidenceHash":"0x..."}'