{"openapi":"3.0.3","info":{"title":"ArcFlow Sentinel API","version":"0.3.0","description":"Lifecycle, invariants and evidence for CCTP V2 USDC transfers between Arc and Base. Amounts are decimal strings in 6-decimal atomic units. Errors are RFC 7807 problems."},"paths":{"/api/traces":{"post":{"summary":"Trace a source transaction (idempotent)","description":"201 when new traces were created, 200 with the existing traces otherwise. requireAppConfirmation needs an API key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTrace"}}}},"responses":{"200":{"description":"Existing traces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Traces"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Traces"}}}},"400":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"summary":"Look up traces by source transaction","parameters":[{"name":"sourceTxHash","in":"query","required":true,"schema":{"type":"string"}},{"name":"sourceChain","in":"query","required":true,"schema":{"type":"string","enum":["base","arc"]}}],"responses":{"200":{"description":"Traces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Traces"}}}},"400":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/traces/{id}":{"get":{"summary":"Get a trace","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Trace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trace"}}}},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/traces/{id}/events":{"get":{"summary":"Raw and decoded observations","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Events"}}}},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/traces/{id}/invariants":{"get":{"summary":"Invariant results","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Invariants","content":{"application/json":{"schema":{"type":"object","properties":{"invariants":{"type":"array","items":{"$ref":"#/components/schemas/Invariant"}}}}}}},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/traces/{id}/evidence":{"get":{"summary":"Signed evidence bundle (deterministic; ?download=1 serves it as a file)","description":"RFC 8785 canonical payload, its SHA-256 and keccak256 (the value anchored on Arc), and an Ed25519 signature. Verify with `verify-evidence` against /.well-known/sentinel-key.json.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"download","in":"query","required":false,"schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Evidence bundle"},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/traces/{id}/anchor":{"post":{"summary":"Anchor the trace's current evidence hash on Arc (queued; the worker signs)","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Queued"},"401":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/.well-known/sentinel-key.json":{"get":{"summary":"Public key that signs this deployment's evidence","responses":{"200":{"description":"Key"},"503":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/traces/{id}/confirm":{"post":{"summary":"Application confirmation (MINT_CONFIRMED → APPLICATION_CONFIRMED)","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Confirm"}}}},"responses":{"200":{"description":"Trace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trace"}}}},"400":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/webhooks/test":{"post":{"summary":"Send a signed test event to every endpoint","security":[{"bearerAuth":[]}],"responses":{"202":{"description":"Queued"},"401":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/health/live":{"get":{"summary":"Liveness","responses":{"200":{"description":"OK"}}}},"/api/health/ready":{"get":{"summary":"Readiness (database)","responses":{"200":{"description":"OK"},"503":{"description":"Unavailable"}}}},"/api/health/routes":{"get":{"summary":"Chain heads and Iris reachability (cached 15s)","responses":{"200":{"description":"OK"},"503":{"description":"Degraded"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"CreateTrace":{"type":"object","properties":{"sourceTxHash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$","description":"Hash of the transaction that burned USDC (DepositForBurn)."},"sourceChain":{"type":"string","enum":["base","arc"],"description":"Chain the burn happened on."},"requireAppConfirmation":{"description":"Needs an API key. The trace then waits at Minted until your app calls /confirm.","type":"boolean"}},"required":["sourceTxHash","sourceChain"],"additionalProperties":false},"Confirm":{"type":"object","properties":{"reference":{"description":"Your own id for the credit (order, ledger entry). Up to 200 characters.","type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"Trace":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"route":{"type":"object","properties":{"sourceChain":{"type":"string","enum":["base","arc"]},"sourceDomain":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"destinationChain":{"type":"string","enum":["base","arc"]},"destinationDomain":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["sourceChain","sourceDomain","destinationChain","destinationDomain"],"additionalProperties":false},"sourceTxHash":{"type":"string","description":"0x-prefixed hex"},"sourceLogIndex":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sourceBlockNumber":{"type":"string","description":"decimal block number"},"sourceBlockTime":{"nullable":true,"type":"string","description":"ISO-8601 timestamp"},"nonce":{"nullable":true,"type":"string","description":"0x-prefixed hex"},"sender":{"type":"string","description":"0x-prefixed hex"},"recipient":{"type":"string","description":"0x-prefixed hex"},"amountAtomic":{"type":"string","description":"USDC amount in 6-decimal atomic units (decimal string)"},"status":{"type":"string","enum":["SOURCE_OBSERVED","FINALITY_WAIT","ATTESTATION_PENDING","ATTESTED","DESTINATION_SUBMITTED","MINT_CONFIRMED","APPLICATION_CONFIRMED","FAILED_OR_STUCK"]},"progress":{"type":"string","enum":["SOURCE_OBSERVED","FINALITY_WAIT","ATTESTATION_PENDING","ATTESTED","DESTINATION_SUBMITTED","MINT_CONFIRMED","APPLICATION_CONFIRMED","FAILED_OR_STUCK"]},"reason":{"nullable":true,"type":"string","enum":["STUCK","FAILED"]},"statusReason":{"nullable":true,"type":"string"},"destinationTxHash":{"nullable":true,"type":"string","description":"0x-prefixed hex"},"stageDeadlineAt":{"nullable":true,"type":"string","description":"ISO-8601 timestamp"},"requireAppConfirmation":{"type":"boolean"},"applicationConfirmedAt":{"nullable":true,"type":"string","description":"ISO-8601 timestamp"},"applicationReference":{"nullable":true,"type":"string"},"isDemo":{"type":"boolean","description":"seeded from historical fixtures for demonstration"},"explorer":{"type":"object","properties":{"source":{"type":"string","format":"uri"},"destination":{"nullable":true,"type":"string","format":"uri"}},"required":["source","destination"],"additionalProperties":false},"firstSeenAt":{"type":"string","description":"ISO-8601 timestamp"},"updatedAt":{"type":"string","description":"ISO-8601 timestamp"}},"required":["id","route","sourceTxHash","sourceLogIndex","sourceBlockNumber","sourceBlockTime","nonce","sender","recipient","amountAtomic","status","progress","reason","statusReason","destinationTxHash","stageDeadlineAt","requireAppConfirmation","applicationConfirmedAt","applicationReference","isDemo","explorer","firstSeenAt","updatedAt"],"additionalProperties":false},"Traces":{"type":"object","properties":{"traces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"route":{"type":"object","properties":{"sourceChain":{"type":"string","enum":["base","arc"]},"sourceDomain":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"destinationChain":{"type":"string","enum":["base","arc"]},"destinationDomain":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["sourceChain","sourceDomain","destinationChain","destinationDomain"],"additionalProperties":false},"sourceTxHash":{"type":"string","description":"0x-prefixed hex"},"sourceLogIndex":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sourceBlockNumber":{"type":"string","description":"decimal block number"},"sourceBlockTime":{"nullable":true,"type":"string","description":"ISO-8601 timestamp"},"nonce":{"nullable":true,"type":"string","description":"0x-prefixed hex"},"sender":{"type":"string","description":"0x-prefixed hex"},"recipient":{"type":"string","description":"0x-prefixed hex"},"amountAtomic":{"type":"string","description":"USDC amount in 6-decimal atomic units (decimal string)"},"status":{"type":"string","enum":["SOURCE_OBSERVED","FINALITY_WAIT","ATTESTATION_PENDING","ATTESTED","DESTINATION_SUBMITTED","MINT_CONFIRMED","APPLICATION_CONFIRMED","FAILED_OR_STUCK"]},"progress":{"type":"string","enum":["SOURCE_OBSERVED","FINALITY_WAIT","ATTESTATION_PENDING","ATTESTED","DESTINATION_SUBMITTED","MINT_CONFIRMED","APPLICATION_CONFIRMED","FAILED_OR_STUCK"]},"reason":{"nullable":true,"type":"string","enum":["STUCK","FAILED"]},"statusReason":{"nullable":true,"type":"string"},"destinationTxHash":{"nullable":true,"type":"string","description":"0x-prefixed hex"},"stageDeadlineAt":{"nullable":true,"type":"string","description":"ISO-8601 timestamp"},"requireAppConfirmation":{"type":"boolean"},"applicationConfirmedAt":{"nullable":true,"type":"string","description":"ISO-8601 timestamp"},"applicationReference":{"nullable":true,"type":"string"},"isDemo":{"type":"boolean","description":"seeded from historical fixtures for demonstration"},"explorer":{"type":"object","properties":{"source":{"type":"string","format":"uri"},"destination":{"nullable":true,"type":"string","format":"uri"}},"required":["source","destination"],"additionalProperties":false},"firstSeenAt":{"type":"string","description":"ISO-8601 timestamp"},"updatedAt":{"type":"string","description":"ISO-8601 timestamp"}},"required":["id","route","sourceTxHash","sourceLogIndex","sourceBlockNumber","sourceBlockTime","nonce","sender","recipient","amountAtomic","status","progress","reason","statusReason","destinationTxHash","stageDeadlineAt","requireAppConfirmation","applicationConfirmedAt","applicationReference","isDemo","explorer","firstSeenAt","updatedAt"],"additionalProperties":false}}},"required":["traces"],"additionalProperties":false},"Events":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"chainId":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"domain":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"blockNumber":{"type":"string"},"blockHash":{"type":"string","description":"0x-prefixed hex"},"txHash":{"type":"string","description":"0x-prefixed hex"},"logIndex":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"eventType":{"type":"string","enum":["burn","message_sent","message_received","mint"]},"removed":{"type":"boolean","description":"dropped by a chain reorganization; kept as evidence"},"observedAt":{"type":"string","description":"ISO-8601 timestamp"},"decoded":{"type":"object","additionalProperties":{}}},"required":["chainId","domain","blockNumber","blockHash","txHash","logIndex","eventType","removed","observedAt","decoded"],"additionalProperties":false}},"attestations":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"nonce":{"nullable":true,"type":"string","description":"0x-prefixed hex"},"delayReason":{"nullable":true,"type":"string"},"responseHash":{"type":"string","description":"SHA-256 of the raw Iris response"},"observedAt":{"type":"string","description":"ISO-8601 timestamp"}},"required":["status","nonce","delayReason","responseHash","observedAt"],"additionalProperties":false}}},"required":["events","attestations"],"additionalProperties":false},"Invariant":{"type":"object","properties":{"ruleId":{"type":"string"},"result":{"type":"string","enum":["PASS","FAIL","UNKNOWN"]},"explanation":{"type":"string"},"evidenceRefs":{"type":"array","items":{"type":"string"}},"evaluatedAt":{"type":"string","description":"ISO-8601 timestamp"}},"required":["ruleId","result","explanation","evidenceRefs","evaluatedAt"],"additionalProperties":false},"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"detail":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["path","message"],"additionalProperties":false}}},"required":["type","title","status"],"additionalProperties":false}}},"x-webhooks":{"headers":["x-sentinel-event-id","x-sentinel-event-type","x-sentinel-sequence","x-sentinel-timestamp","x-sentinel-retry","x-sentinel-signature"],"signature":"v1=hex(HMAC-SHA256(secret, `${timestamp}.${rawBody}`)); reject timestamps older than 5 minutes; ignore events whose sequence is not greater than the last one processed for the trace"}}