{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "$id": "https://umbra-inference.app/receipt.schema.json",
 "title": "Umbra signed receipt",
 "description": "Returned with every paid answer: in the X-Umbra-Receipt header (base64 JSON) and in the body as `umbra` (final event on streams). Verify: signature.value is Ed25519 over the canonical JSON of `receipt` (keys sorted recursively, no whitespace, JavaScript number formatting) with signature.public_key; look the key up in https://umbra-inference.app/keys.json.",
 "type": "object",
 "required": [
  "receipt",
  "signature"
 ],
 "properties": {
  "receipt": {
   "type": "object",
   "required": [
    "id",
    "issued_at",
    "issuer",
    "model",
    "scheme",
    "network",
    "asset",
    "facilitation",
    "prompt_sha256",
    "tokens",
    "cost",
    "retained",
    "tier",
    "attestation",
    "stop_reason"
   ],
   "properties": {
    "id": {
     "type": "string",
     "pattern": "^rcpt_[0-9a-f]{20}$"
    },
    "issued_at": {
     "type": "string",
     "format": "date-time"
    },
    "issuer": {
     "const": "umbra-gateway"
    },
    "model": {
     "type": "string",
     "description": "model id returned by the runtime"
    },
    "scheme": {
     "enum": [
      "exact",
      "upto"
     ]
    },
    "network": {
     "type": "string",
     "description": "CAIP-2, e.g. eip155:4663"
    },
    "asset": {
     "enum": [
      "USDG",
      "USDC",
      "UMBRA"
     ]
    },
    "facilitation": {
     "enum": [
      "gateway",
      "PayAI"
     ],
     "description": "who verified and settled the payment"
    },
    "prompt_sha256": {
     "type": "string",
     "pattern": "^[0-9a-f]{64}$",
     "description": "sha256 of JSON {system, messages[, tools, tool_choice]} as sent"
    },
    "tokens": {
     "type": "object",
     "required": [
      "input",
      "output"
     ],
     "properties": {
      "input": {
       "type": "integer",
       "minimum": 0
      },
      "output": {
       "type": "integer",
       "minimum": 0
      }
     }
    },
    "cost": {
     "type": "object",
     "required": [
      "settled",
      "settled_atomic",
      "usage",
      "usage_atomic",
      "currency",
      "fee_bps",
      "holder"
     ],
     "properties": {
      "settled": {
       "type": "string",
       "description": "USD (or USD-equivalent for UMBRA), 6 decimals"
      },
      "settled_atomic": {
       "type": "string",
       "description": "amount moved on chain, atomic units of `currency`"
      },
      "usage": {
       "type": "string"
      },
      "usage_atomic": {
       "type": "string"
      },
      "authorized_atomic": {
       "type": [
        "string",
        "null"
       ],
       "description": "the ceiling the payer signed"
      },
      "currency": {
       "enum": [
        "USDG",
        "USDC",
        "UMBRA"
       ]
      },
      "fee_bps": {
       "type": "integer",
       "description": "protocol fee applied: 400, 200 (holder tier1) or 0 (tier2)"
      },
      "holder": {
       "type": "object",
       "properties": {
        "tier": {
         "enum": [
          "none",
          "tier1",
          "tier2"
         ]
        },
        "balance_umbra": {
         "type": [
          "number",
          "null"
         ]
        },
        "standard_fee_bps": {
         "type": "integer"
        }
       }
      },
      "flow": {
       "enum": [
        "upfront"
       ],
       "description": "present when the ceiling was settled before the answer"
      },
      "refunded": {
       "type": "string"
      },
      "refunded_atomic": {
       "type": "string"
      },
      "refund_tx": {
       "type": [
        "string",
        "null"
       ]
      },
      "unit": {
       "type": "string"
      },
      "umbra_usd": {
       "type": [
        "number",
        "null"
       ]
      },
      "fee_burn": {
       "type": "object",
       "properties": {
        "share_bps": {
         "type": "integer"
        },
        "umbra": {
         "type": "string"
        },
        "how": {
         "type": "string"
        }
       }
      },
      "settlement_tx": {
       "type": "string",
       "description": "the settlement transaction, present on the upfront flow (streams, long answers): the settlement happened before the receipt was signed. On the authorization flow the receipt is signed first and the transaction rides in the PAYMENT-RESPONSE header."
      },
      "settlement_network": {
       "type": "string",
       "description": "CAIP-2 network of settlement_tx"
      }
     }
    },
    "retained": {
     "type": "object",
     "required": [
      "prompt_bytes",
      "response_bytes"
     ],
     "properties": {
      "prompt_bytes": {
       "const": 0
      },
      "response_bytes": {
       "const": 0
      }
     }
    },
    "tier": {
     "enum": [
      "sealed",
      "standard"
     ]
    },
    "attestation": {
     "type": "object",
     "required": [
      "gateway",
      "model_runtime"
     ],
     "properties": {
      "tee": {
       "type": [
        "string",
        "null"
       ],
       "description": "legacy field, always null; see gateway.tee"
      },
      "gateway": {
       "type": "object",
       "properties": {
        "tee": {
         "enum": [
          "tdx",
          null
         ]
        },
        "app_id": {
         "type": "string"
        },
        "compose_hash": {
         "type": "string",
         "pattern": "^[0-9a-f]{64}$"
        },
        "instance_id": {
         "type": "string"
        },
        "report_data": {
         "type": "string",
         "pattern": "^[0-9a-f]{64}$",
         "description": "sha256('umbra-receipt-key:' + signature.public_key); also 0x01||compose_hash is the quote's mr_config_id"
        },
        "attestation_url": {
         "type": "string"
        }
       }
      },
      "model_runtime": {
       "type": "object",
       "properties": {
        "tee": {
         "enum": [
          "tdx+gpu",
          null
         ]
        },
        "provider": {
         "type": "string"
        },
        "upstream_receipt_id": {
         "type": [
          "string",
          "null"
         ]
        },
        "attestation_url": {
         "type": [
          "string",
          "null"
         ]
        },
        "workload_keyset_digest": {
         "type": [
          "string",
          "null"
         ]
        },
        "source": {
         "type": [
          "object",
          "null"
         ],
         "properties": {
          "repo_url": {
           "type": "string"
          },
          "commit": {
           "type": "string"
          }
         }
        },
        "note": {
         "type": "string"
        }
       }
      }
     }
    },
    "stop_reason": {
     "enum": [
      "end_turn",
      "max_tokens",
      "tool_use",
      "stop_sequence"
     ]
    }
   }
  },
  "signature": {
   "type": "object",
   "required": [
    "alg",
    "public_key",
    "value"
   ],
   "properties": {
    "alg": {
     "const": "ed25519"
    },
    "public_key": {
     "type": "string",
     "pattern": "^[0-9a-f]{64}$"
    },
    "value": {
     "type": "string",
     "contentEncoding": "base64"
    }
   }
  }
 }
}