Asset Integrity Rail (KYA)

Asset Integrity Rail (KYA)

“IOF verifies the asset before the finance happens.”

The Asset Integrity Rail (KYA) verifies an asset’s identity, encumbrance state, and Shariah permissibility before any contract is executed. Every asset fingerprint is reproducible, every Shariah recommendation cites the AAOIFI paragraph it came from, and every evidence pack is signed and audience-scoped.

When to use it

• A bank wants to underwrite a Murabaha contract and needs to prove the underlying asset has not already been pledged elsewhere.
• A Shariah board wants a structured pre-screen of a Sukuk-Ijarah pool with AAOIFI SS-17 / SS-26 citations.
• A regulator demands an audit-pack proving the fingerprint, ownership chain, and permissibility evaluation at a specific point in time.
• A takaful operator needs to confirm the underlying risk pool is free of gharar / maysir before a claim is paid.

Pipeline

raw AssetObject  →  canonicalise  →  fingerprint  →  shariah-evaluate
                                                       ↓
                                  evidence-pack  ←  compose-proof
                                         ↓
                                      outbox  →  IOF control plane

All five engines are pure / deterministic — same inputs always produce the same outputs.

Engines

Engine	Purpose	Spec
canonicalisation-engine	Sorted-keys, whitespace-normalised JSON canonical form	§13.1
fingerprint-service	SHA-256 + Merkle tree over canonical form + document leaves	§13.2
encumbrance-engine	State-machine validation (financing-lock lifecycle)	§13.3
shariah-asset-engine	AAOIFI SS-8 / SS-9 / SS-17 / SS-26 evaluator	§13.4
proof-service	V1 hash + Merkle envelope composer	§13.5
evidence-pack-engine	Auditor / regulator / Shariah-board pack composer	§13.6

Wired endpoints (Phase 2)

Method	Path	Engine
POST	/v1/asset-objects/:id/canonicalise	canonicalisation-engine
POST	/v1/asset-objects/:id/fingerprint	fingerprint-service
GET	/v1/asset-objects/:id/evidence-pack	evidence-pack-engine
POST	/v1/encumbrances/apply	encumbrance-engine
POST	/v1/shariah/asset-reviews	shariah-asset-engine
POST	/v1/shariah/asset-reviews/proof	proof-service

22 additional endpoints land in Phase 3+ (compliance-node BYOC, verification flow, webhook endpoints).

BYOC — Compliance Node

For tier-1 banks who cannot let raw asset data leave their network, IOF ships a BYOC compliance node as a Docker image. It runs INSIDE the customer’s network and exposes the same engine pipeline. Only signed proof envelopes and audience-scoped evidence packs cross the boundary.

Reference: services/compliance-node/.

Shariah governance

The shariah-asset-engine never auto-approves. Every output is a recommendation for the Shariah board, with decision_owner: "shariah_board_member_required". Hard EFFECT_DENY is enforced for any approve action against an asset flagged asset_permissibility = "non_permissible".

AAOIFI standards explicitly cited in rules_fired[]:

• SS-8 §3 Murabaha — financier must own the asset before sale (risk transfer)
• SS-8 §5 Murabaha — cost and markup disclosure
• SS-9 §3 Ijarah — lessor retains ownership-risk for the lease term
• SS-9 §6 Ijarah — late-payment penalties go to charity (no riba al-jahiliyya)
• SS-17 §4 Sukuk — underlying asset must be Shariah-permissible
• SS-17 §5 Sukuk — uniqueness of underlying asset (no double-pledging)
• SS-26 §3 Investment Sukuk — sectoral screening of pool composition
• SS-26 §4 Takaful — risk pool must be free of gharar and maysir

Authentication

All endpoints require authentication via Bearer token or API key, plus an X-IOF-Tenant header. Cerbos policy asset_object.yaml enforces ABAC on every action.

Rate limiting

Standard rate limits apply. See Rate Limiting for details.

See also

• API Explorer — interactive endpoint documentation
• .ralph/asset-integrity-rail-PROMPT.md — full PRD/ARD/ERD spec
• config/cerbos/policies/asset_object.yaml — ABAC policy
• config/cerbos/policies/shariah_asset.yaml — Shariah SPDP