API Reference

Score registry (on-chain)

interface IScoreRegistry {
  function latest(bytes32 orderId) external view returns (
    uint16 scoreBps,
    uint64 timestamp,
    bytes32 dataRoot,
    address oracle
  );

  function lastPublishedAt(bytes32 orderId) external view returns (uint64);
  function state() external view returns (uint8); // Active | Degraded | Paused
}

HTTP: fetch score bundle

GET /v1/scores/:orderId
Authorization: Bearer <api-key>

{
  "orderId": "0x…",
  "scoreBps": 8720,
  "timestamp": 1730000000,
  "dataRoot": "0x…",
  "signature": "0x…",
  "oracle": "0x…",
  "evidenceUri": "ipfs://…"
}

HTTP: evidence proof

GET /v1/scores/:orderId/proof?leaf=<hash>

Returns the Merkle proof for a leaf committed in dataRoot.

Agency evaluate (view)

function evaluate(
  address agent,
  address target,
  bytes4 selector,
  uint256 value,
  bytes calldata data
) external view returns (bool allowed, string memory reason);

SPOOL oracle callback

function onScore(
  bytes32 orderId,
  uint16 scoreBps,
  uint64 timestamp,
  bytes32 dataRoot,
  bytes calldata signature
) external;

Callback verifies freshness and signer before mutating order state. Failed verification must not update scores or unlock advances.

Status codes