The .fiqh DSL

A .fiqh file declares one instrument (or a bundle of legs). The compiler reads it into an AST, then the semantic engine checks it against the active rule-base. Everything below is opt-in: a base instrument with no optional sections still compiles to a complete contract.

Run it as you read

Every snippet here is real syntax. Paste any of it into the Playground and watch the engine respond. For the normative EBNF + AST, see Grammar & AST.

The skeleton

instrument <Name> : <class> {        // name, then the instrument class it must satisfy
  meta    { ... }                    // provenance, currency, citations
  parties { name : role flag*; }     // who, and in what capacity
  capital { party : N bps; ... }     // the ownership split
  returns { ... }                    // how value flows (rent, buyout, profit …)
  risk    { loss: ...; capital_guarantee: ...; }

  // optional sections, each enforced at its own layer:
  oracle      { mode: consensus; committee: N; quorum: K; gharar_bound_bps: B; }
  zakat       { rate_bps: 250; nisab: ...; haul: hijri_year; beneficiary: ...; }
  contingency { ... }
  dispute     { remedy: arbiter_ruling; }

  invariant <name> { <expr> }        // a machine-checkable assertion about the shape
  rescission { khiyar_al_shart { ... } iqalah { ... } }
  lifecycle  { fund; payRent; buyShare(bps); settle; }
}

meta & parties

meta carries provenance — the standard a spec claims consistency with, the currency unit, scriptural references (all flagged [scholar-verify]). parties binds a name to a role, with optional flags:

parties {
  bank    : financier;
  client  : acquirer;
  valuer  : oracle independent;     // role `oracle`, flag `independent` — the gharar trust boundary
  arbiter : adjudicator;
  maslahah: beneficiary;
}

capital

Shares in basis points, with an optional require constraint the engine carries:

capital {
  bank   : 8000 bps;
  client : 2000 bps;
  require bank + client == 10000 bps;
}

returns & risk

returns holds named sub-blocks — rent, buyout, profit — whose keys are checked structurally (e.g. rent must price the living share or the usufruct, never the principal). risk declares how loss is borne and whether capital is guaranteed:

returns {
  rent   { basis: bank.share; rate: 1 per_bps_period; }
  buyout { price: oracle.fairValue * bps; transfers: bank.share -> client.share; }
}
risk {
  loss: proportional_to_ownership;   // RISK-1
  capital_guarantee: none;           // RIBA-1 — `bank` here would refuse to compile
}

invariants

The heart of a spec: named, machine-checkable assertions over the structure. Expressions are reasoned about, never evaluated (see Grammar → Expressions).

invariant ownership_conserved  { bank.share + client.share == 10000 }
invariant loss_follows_capital { loss == proportional_to_ownership }
invariant price_attested       { buyout.price == oracle.fairValue }
invariant role_separation      { valuer != bank }

Optional sections at a glance

• oracle — mode: consensus; committee: N; quorum: K; gharar_bound_bps: B; — replaces the lone valuer with a committee; fairValue() reverts when agreement falls below quorum (gharar made a computed quantity). See Codegen.
• zakat — routes 2.5% (rubʿ al-ʿushr) of the eligible base to a beneficiary once niṣāb and a lunar ḥawl are met. See Charge.
• contingency — jāʾiḥah abates obligations (no riba); farāʾiḍ dissolves a deceased partner’s stake by exact inheritance arithmetic. See Contingency.
• dispute — remedy: arbiter_ruling; exposes an adjudicated release/refund path.

Instruments (classes)

The class after the colon selects the rule-base:

Class	Instrument
musharakah_mutanaqisah	diminishing partnership (home finance)
mudarabah	profit-sharing trust financing
ijarah_imbt	lease ending in ownership
commercial_escrow	regime-neutral escrow / judiciary engine (meta { regime: common_law; })

Composite contracts (bundle)

A bundle groups legs the engine reasons about as one asset-flow graph — see Grammar → bundle and Composition. Bundle checking runs via the CLI (deducible check).