Nuqsaf Methodology

This is the complete methodology document (v0.2). All 8 sections are included below.

---

1. Scope

1.1 What this methodology covers

Nuqsaf's v1 report is a single-purpose artifact: it identifies interest income and dividend income in a user's conventional bank and brokerage accounts over a 12-month period, and it produces a total dollar amount the user should discharge in sadaqah (charity) as purification.

The methodology in this document governs exactly that process. It answers three questions:

1. What counts as riba for the purposes of Nuqsaf v1?
2. Which transactions in a user's bank data should be flagged as riba-derived income?
3. How is the total purification amount calculated from those flagged transactions?

1.2 What this methodology does NOT cover

Nuqsaf v1 is deliberately narrow. The following topics are outside the scope of this document and outside the scope of the v1 product:

• Zakat. Zakat is an entirely separate obligation based on net assets, not on transaction flow. The fiqh of zakat is complex, varies by asset class, and requires different data (account balances on a specific lunar date, outstanding debts, inventory held for trade, gold and silver holdings, etc.). Nuqsaf v1 makes no attempt to calculate zakat. A user should consult their scholar or a zakat calculator (such as those provided by Zakat Foundation of America or National Zakat Foundation) separately.
• Merchant-level haram classification. Nuqsaf v1 does not assess whether the places you spent money are Sharia-compliant. Spending at a restaurant that serves alcohol, a store that sells pork products, or a conventional insurance provider is not addressed by this methodology. These questions involve significant scholarly disagreement and depend on factors Nuqsaf cannot reliably determine from transaction data alone (e.g., what portion of a grocery store's revenue comes from haram products). A future version of Nuqsaf may address this; v1 does not.
• Investment screening (halal stock screening). The question of whether a specific stock, mutual fund, or index fund is permissible under Sharia requires detailed analysis of the underlying company's business activities, debt ratios, and interest-bearing assets. This is the work of dedicated screening services such as Wahed Invest, Amana Mutual Funds, and the AAOIFI Sharia Standards. Nuqsaf v1 does not perform this analysis. It treats dividend income from conventional, non-screened brokerage accounts as purification-eligible by default (see section 4 in v0.2) on the conservative assumption that the user has not already filtered for halal-only holdings.
• Mortgage and loan structures. The question of whether a specific mortgage product, auto loan, personal loan, or credit card structure is permissible involves detailed review of the contract terms. Products marketed as "Islamic" or "Sharia-compliant" vary widely in quality and scholarly acceptance. Nuqsaf v1 does not attempt to classify the permissibility of specific loan products. It only identifies interest paid and interest received as they appear in transaction data.
• Business income and corporate zakat. Users who own businesses and receive business income through personal accounts should consult a scholar regarding the separation of business and personal zakat/purification obligations. Nuqsaf v1 treats all transactions in a linked account as personal transactions.
• Crypto, foreign currency, and non-bank assets. If a user holds assets outside of the bank accounts they link to Nuqsaf, those are not included in the report. The report covers only what Plaid (the bank data provider) returns for the connected accounts.

1.3 Why v1 is narrow

A narrow scope is a deliberate choice, not an oversight. Nuqsaf's v1 is designed around a single principle: get the most clearly agreed-upon category correct before attempting the contested ones.

• Riba al-nasi'ah (interest on money loans) is the most universally agreed-upon prohibition in Islamic finance. All four Sunni madhhabs agree. AAOIFI standards agree. No credible modern scholar disagrees. The only debates are at the margins (e.g., interest on small amounts, interest paid to non-Muslim counterparties, interest charged in economic necessity). For v1, Nuqsaf focuses on the core case where agreement is total.
• Merchant-level haram classification, by contrast, involves live scholarly debate. Is a restaurant that serves alcohol alongside halal food a haram transaction? Scholars disagree. Is a grocery store that sells 5% pork products haram when you buy bread there? Scholars disagree. Building these into a v1 product would mean making rulings Nuqsaf is not qualified to make.
• Narrowing to riba also narrows the risk to the user. If Nuqsaf's riba detection is slightly wrong, the user purifies a slightly wrong amount — still better than not purifying at all. If Nuqsaf's merchant classification is wrong, the user may feel guilt about transactions that did not require it, or may miss transactions that did. The second failure mode is much worse.

Nuqsaf v2 and beyond may expand scope after v1's methodology has been reviewed, endorsed, and tested against real user data.

---

2. Definition of riba

2.1 Riba in the Quran

The prohibition of riba is one of the strongest and most repeated financial rulings in the Quran. The following verses are the primary sources cited in every classical and modern treatment of riba:

Al-Baqarah 2:275

"Those who consume interest cannot stand [on the Day of Resurrection] except as one stands who is being beaten by Satan into insanity. That is because they say, 'Trade is [just] like interest.' But Allah has permitted trade and has forbidden interest."

Al-Baqarah 2:276

"Allah destroys interest and gives increase for charities. And Allah does not like every sinning disbeliever."

Al-Baqarah 2:278–279

"O you who have believed, fear Allah and give up what remains [due to you] of interest, if you should be believers. And if you do not, then be informed of a war [against you] from Allah and His Messenger. But if you repent, you may have your principal — [thus] you do no wrong, nor are you wronged."

Al-Imran 3:130

"O you who have believed, do not consume usury, doubled and multiplied, but fear Allah that you may be successful."

An-Nisa 4:161

"And [for] their taking of usury while they had been forbidden from it, and their consuming of the people's wealth unjustly. And we have prepared for the disbelievers among them a painful punishment."

Al-Rum 30:39

"And whatever you give for interest to increase within the wealth of people will not increase with Allah. But what you give in zakat, desiring the countenance of Allah — those are the multipliers."

The Quranic position is unambiguous: riba is forbidden. The language in Al-Baqarah 2:279 ("war from Allah and His Messenger") is the most severe framing used for any financial prohibition in Islamic scripture.

2.2 Riba in the hadith literature

The Prophetic tradition further clarifies and extends the Quranic prohibition. The following hadiths are widely cited in classical and modern works and are considered sahih (authentic) by the major hadith scholars:

• The Prophet (peace be upon him) cursed the one who consumes riba, the one who gives it, the one who records it, and the two witnesses to it, saying: "They are all alike [in sin]." — narrated in Sahih Muslim, the Book of Transactions.
• "Riba has seventy-three chapters, the least of which is like a man committing incest with his own mother." — narrated in Sunan Ibn Majah and other collections. This hadith establishes the severity of riba relative to other sins.
• The "six commodities" hadith, in which the Prophet (peace be upon him) said: "Gold for gold, silver for silver, wheat for wheat, barley for barley, dates for dates, and salt for salt — like for like, hand to hand. Whoever gives more or takes more has engaged in riba." — narrated in Sahih al-Bukhari and Sahih Muslim. This hadith is the classical basis for distinguishing riba al-fadl from riba al-nasi'ah (see section 2.3).

2.3 Two categories of riba

Classical Islamic jurisprudence distinguishes two categories of riba:

Riba al-nasi'ah (literally "riba of delay") is the form of riba most familiar to modern readers: the predetermined increase on a loan as compensation for the time the borrower has use of the principal. This includes:

• Interest on savings accounts, checking accounts, money market accounts, and certificates of deposit
• Interest on loans (mortgages, auto loans, personal loans, student loans, business loans)
• Interest charged on credit card balances
• Interest income from bonds (government or corporate)
• Interest-bearing peer-to-peer lending returns
• Interest earned on cash held in brokerage sweep accounts

Riba al-nasi'ah is the primary form of riba addressed by the Quranic verses cited in section 2.1. All four Sunni madhhabs (Hanafi, Maliki, Shafi'i, Hanbali) and the Twelver Shia Ja'fari school agree on its prohibition. Modern standard-setters including the Accounting and Auditing Organization for Islamic Financial Institutions (AAOIFI) and the Islamic Fiqh Academy of the Organization of Islamic Cooperation (OIC) are in full agreement.

Riba al-fadl (literally "riba of excess") is the exchange of certain commodities for the same commodity in unequal quantities, based on the six-commodities hadith cited in section 2.2. The classical example is exchanging one pound of low-quality dates for half a pound of high-quality dates — both parties have agreed, but the exchange is considered riba al-fadl because the Prophet (peace be upon him) specified that these commodities must be exchanged "like for like, hand to hand."

Modern scholars extend riba al-fadl by analogy (qiyas) to currency exchanges, gold and silver trades, and some derivative instruments. The precise scope of these extensions is an active area of scholarly discussion.

2.4 What Nuqsaf v1 identifies as riba

Nuqsaf v1 identifies only riba al-nasi'ah — predetermined interest income earned on money held in conventional financial institutions.

Specifically, Nuqsaf v1 treats the following as riba al-nasi'ah and includes them in the purification report:

1. Interest income on savings, checking, and money market accounts. Any credit to the user's account labeled as "interest," "interest paid," "APY payment," "interest credit," or similar.
2. Interest income on certificates of deposit (CDs). Periodic or maturity-date interest payments.
3. Interest income on brokerage cash balances. Sweep account interest, money market fund distributions from conventional money market funds.
4. Dividend income from conventional (non-screened) brokerage accounts. See section 4 in v0.2 for the reasoning. The conservative default is to treat dividends from conventional stocks and mutual funds as purification-eligible, on the assumption that the underlying companies include riba-bearing revenue (e.g., interest income on corporate cash, interest-bearing debt) that would disqualify them under AAOIFI screening standards unless the user has actively verified Sharia compliance.

Nuqsaf v1 does NOT identify the following as riba, and does not include them in the purification report:

• Interest paid by the user on loans and credit card balances. Interest paid by the user (as opposed to received) is itself sinful under the same scriptural basis, but it is not "income" and cannot be discharged via sadaqah. The appropriate response to interest paid is tawba (repentance), not purification. Users who pay interest are encouraged to pay off interest-bearing debt as quickly as possible and to consult a scholar about the process of repentance.
• Riba al-fadl in currency exchange, commodity trades, or derivatives. Nuqsaf v1 does not analyze the mechanics of currency trades or derivative instruments in the user's brokerage account. If a user has such transactions, they should consult a specialized scholar.
• Business interest income (if the user receives interest income through a business they own). Business income belongs in a separate accounting framework. Users with significant business activity should not rely on Nuqsaf v1 alone.
• Inflation adjustments, stock buybacks, return of capital, and principal repayments. These are not interest and are not included.

2.5 Summary of the position

The position taken by Nuqsaf v0.1 methodology is as follows:

Conventional bank interest (riba al-nasi'ah) is unambiguously prohibited by the Quran, the Sunnah, and the consensus (ijma) of the Sunni madhhabs. A Muslim who holds money in a conventional bank account and receives interest income is under an obligation to identify that income and discharge it as sadaqah with no expectation of personal reward, because the income itself cannot be retained as lawful earnings. This is the minimum, least-contested case in Islamic finance jurisprudence, and it is the case Nuqsaf v1 addresses.

Nuqsaf v1 does not take positions on contested areas of Islamic finance (merchant-level haram classification, investment screening standards, loan structure permissibility, zakat calculation, crypto, or riba al-fadl). These are deliberately out of scope and will be addressed in later versions of the product after v1's methodology has been peer-reviewed and scholar-endorsed.

---

3. How transactions are identified as interest

3.1 Data source

Nuqsaf connects to US financial institutions via Plaid (a regulated bank data aggregator). Plaid provides transaction history, metadata (name, merchant, amount, date, category), and account information. Nuqsaf has read-only access — it cannot initiate transactions or move money.

3.2 Interest RECEIVED detection (the purification pipeline)

Interest received is detected using a three-tier pipeline:

Tier 1: Heuristic pre-filter. Every transaction is checked against rules that do not require AI: Plaid's personal finance category (if categorized as INCOME_INTEREST_EARNED or INCOME_DIVIDENDS), name pattern matching (interest, dividend, APY, yield, etc.), and account context (credits from savings/money market accounts with suggestive names). Transactions that pass none of these checks are classified as "Clear" with 99% confidence. This eliminates ~90% of transactions from AI processing.

Tier 2: AI verification. Transactions that pass the pre-filter are sent to an AI language model (Claude Sonnet 4 by Anthropic) in batches of up to 20. The model classifies each as clear, needs purification, or needs review, with confidence scores and reasoning. The AI does NOT make the final decision.

Tier 3: User review and override. Every flagged transaction is presented to the user. For each, the user sees the merchant name, amount, AI reasoning, and two buttons: Confirm (include in purification total) or Exclude (not riba). The user's decision is final.

3.3 Interest PAID detection

Interest that the user pays on credit cards and loans is tracked separately. This is for awareness, not purification — you cannot purify money you paid to someone else. Detection uses name pattern matching: interest charge, finance charge, intrst chrg, etc. Results are grouped by account and month for trend tracking.

The appropriate response to interest paid is: pay off the debt as quickly as possible, seek tawba (repentance), and consult a scholar about restructuring.

3.4 Validation

The classification pipeline is validated against a hand-labeled ground-truth dataset: ≥95% precision (of all flagged transactions, ≥95% are actually interest) and ≥90% recall (of all actual interest transactions, ≥90% are caught). This runs in CI on every code change.

---

4. Treatment of dividends

When a user holds conventional stocks or mutual funds and receives dividends, should those dividends require purification? Three scholarly positions exist:

• Position A (AAOIFI): All dividends from conventional stocks require purification, because conventional companies earn riba-bearing revenue.
• Position B (some Hanafi scholars): Only dividends from clearly haram companies require purification; others are tolerable incidental impurity.
• Position C (strictest): The entire investment in a conventional stock is impermissible; dividends are merely one symptom.

Nuqsaf's default: Position A (conservative). All dividends from conventional, non-screened brokerage accounts are flagged. Reasoning: better to purify too much than too little. Users who hold Sharia-screened investments can Exclude those dividends during review.

---

5. Madhhab choice and scholarly consensus

5.1 Areas of universal agreement

All four Sunni madhhabs (Hanafi, Maliki, Shafi'i, Hanbali), the Ja'fari school, AAOIFI, and the OIC Islamic Fiqh Academy agree: riba al-nasi'ah is categorically prohibited, conventional bank interest is riba, and interest income must be disposed of via sadaqah.

5.2 Areas of minor disagreement

Disposal method: Majority says give to the poor as charity (no reward). Minority (some Hanafi scholars) allows use for public infrastructure.

Dividends: See section 4. Positions range from "all require purification" to "only clearly haram companies."

Nisab standard for zakat: Silver (~$5,500) vs gold (~$65,000). Nuqsaf uses silver (more conservative).

5.3 Nuqsaf's approach

Nuqsaf does not follow a single madhhab. Instead: (1) core riba identification follows the ijma position all four madhhabs share, (2) conservative defaults are applied wherever positions diverge, (3) user override is available for every flagged transaction. This approach works for Hanafi, Shafi'i, Hanbali, and Maliki users alike.

---

6. Known limitations

Technical

• Only US-linked Plaid accounts are supported
• Transaction categorization depends on Plaid's data quality
• 12-month lookback only (some institutions provide less)
• Pending transactions may change after report generation

Fiqh

• No AAOIFI-level stock screening (dividends use conservative blanket default)
• Zakat estimate is rough — based on depository balances only, does not account for gold, silver, business inventory, debts owed to you, or lunar calendar (hawl)
• Nisab uses silver standard ($5,500) — users following gold standard (~$65,000) should adjust
• Merchant-level haram classification is absent in this version
• Interest paid is tracked but not analyzed for fiqh implications beyond awareness

AI

• The AI model can make classification errors — it is pattern-matching, not scholarship
• The pre-filter uses keyword heuristics that may miss unusual interest labels
• All AI classifications are subject to user review and override

---

7. How to discharge purification correctly

1. Give the full amount as sadaqah to a needy recipient — the poor, the indebted, orphans.
2. Do not expect reward from Allah for this specific act. This is disposal, not voluntary charity.
3. Do not count it as zakat. Zakat and purification are separate obligations.
4. Do not claim it as a tax deduction. The purpose is to remove impure income, not optimize taxes.
5. Do not give it to financial dependents. The money should leave your household entirely.
6. Give sooner rather than later. The longer riba income sits in your accounts, the harder to separate.
7. You do not need to tell the recipient. The sin was in the acquisition, not the receipt.

For interest PAID (credit cards, loans): seek tawba, pay off debt as quickly as possible (highest-interest first), avoid new interest-bearing debt, consult a scholar if your situation makes avoidance difficult.

---

8. Process for challenge and correction

• Disagree with a classification? Click Exclude in the review screen. Your override is final.
• Found an error in the report? Email [email protected] with your report ID and the error. We investigate within 48 hours and regenerate at no charge.
• Disagree with the methodology? This document is public for scrutiny. Email the specific section, the error, and your reasoning or scholarly source. If substantive, we consult peer reviewers and update the methodology with a versioned change log.
• Found a systematic AI error? If a category of transactions is consistently misclassified, email us. We add the pattern to the pre-filter and re-validate. Your report is regenerated free.

---

Notes to peer reviewers

Thank you for taking the time to read this draft. The author is not a scholar and depends on your feedback. Specific questions where your review would be most valuable:

1. Are the Quranic citations accurate and complete? Is there a riba verse the author has missed? Is any translation problematic?
2. Are the hadith citations accurate? The author has avoided citing specific hadith numbers because editions vary. Please add numbers from your preferred editions and flag any hadith you consider weak or disputed.
3. Is the distinction between riba al-nasi'ah and riba al-fadl stated correctly? The author's understanding is that v1's scope is limited to the former. Is this the right framing?
4. Is the scope (section 1.2) appropriately narrow? Should v1 cover something it currently excludes, or exclude something it currently covers?
5. Is section 2.4 correct? Specifically: is treating dividend income from conventional brokerages as purification-eligible the right default? Is there a well-known scholarly position against this?
6. Is there a madhhab-specific consideration the author has missed? The author has not yet addressed madhhab choice (that's section 5, coming in v0.2), but if there is a major disagreement between Hanafi, Maliki, Shafi'i, Hanbali, or Ja'fari positions on anything above, please note it.
7. Is the language appropriate? The author has tried to write in plain English without over-simplifying. Is the register right for a general Muslim audience?

New questions for sections 3–8:

8. Is the three-tier detection pipeline sound? Are there transaction types the heuristics would miss?
9. Is the conservative dividend default (Position A) correct? Should Nuqsaf default to Position B instead?
10. Is the nisab default (silver, ~$5,500) appropriate? Should Nuqsaf ask the user to choose between silver and gold standards?
11. Is the 7-point discharge guidance accurate? Anything missing or misstated?
12. Does the expanded scope (interest paid, net worth, zakat estimate) introduce fiqh risks?

Please send feedback to [email protected].

Jazak Allahu khairan for your time and care.

---

End of v0.2 draft — all 8 sections complete.