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 optional 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 and 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, sale …)
  risk    { loss: ...; capital_guarantee: ...; }

  // optional sections, each enforced at its own layer:
  pool        { name : N bps; ... }  // a multilateral participant set (sukuk, takaful, mudarabah pool)
  oracle      { mode: consensus; committee: N; quorum: K; gharar_bound_bps: B; }
  zakat       { kind: tijarah; 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, the 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 whose keys are checked structurally. Which blocks are expected depends on the class: a sale for murabaha, a profit for mudarabah, a rent and a buyout for a diminishing partnership, an exchange for ṣarf. The engine checks that, for example, rent prices the living share or the usufruct rather than 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; writing `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

• pool declares a multilateral participant set, shares summing to 10000 bps, distributed pro-rata. It is what ṣukūk, takāful, and the muḍāraba pool use. See The multilateral pool.
• oracle with 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 the genus-appropriate rate of the eligible base to a beneficiary once niṣāb and the right ḥawl are met. The rate follows the kind (2.5% for trade goods, gold, currency, salary; 10% for rain-fed crops, 5% for irrigated), and an eight-aṣnāf disbursement policy may be attached. See Charge.
• contingency lets a jāʾiḥah abate obligations (no riba) and farāʾiḍ dissolve a deceased partner’s stake by exact inheritance arithmetic. See Contingency.
• dispute with remedy: arbiter_ruling; exposes an adjudicated release/refund path.

Instruments (classes)

The class after the colon selects the rule-base. There are roughly twenty-seven, across the sale, partnership, lease-and-service, security-and-credit, capital-markets, social, and common-law families. The instrument catalogue documents each one with its codes and a real example. A few of the foundational classes:

Class	Instrument
musharakah_mutanaqisah	diminishing partnership (home finance)
murabahah	cost-plus trust sale
mudarabah	profit-sharing trust financing
ijarah_imbt	lease ending in ownership
sukuk	investment certificates (uses a pool)
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 (deduce check).