Suno Valuation Engine¶

This is the financial model behind the valuations Suno publishes for its solar projects: the net present value of each project and the net asset value (NAV) of each pWatt, the token that represents one thousandth of an installed kWp.

The model is published as source. It is the same code that computes the numbers Suno reports — not a description of it, not a reimplementation for illustration. Anyone holding a valuation's inputs can run it and get the published figure back, without asking Suno for anything and without trusting anything Suno says on this site.

The package is pure calculation: no database, no network calls, no configuration, and no third-party dependencies at all. It installs on the Python standard library alone, so nothing installed alongside it can change a result.

What has been measured¶

On 2026-09-18 every valuation Suno had published was re-run through this package, from its stored inputs:


Valuations published	59
Reproduced exactly (bit-for-bit equality on both NPV and NAV)	56
Refused as not reproducible	3

"Exactly" is meant literally: the comparison is float equality, not a tolerance. The engine returned the same bits that were published.

The three exceptions belong to one project and were published in July 2026, under snapshot schemas 3 and 5, before this package existed. They are refused by name rather than approximated. Reconstructing them would mean running today's model over inputs that lack wht_rate, opex_real_escalation and ppa_base_year, and reading each macro year's sofr field as if it were usd_inflation, which it is not. The result would be reproducible and wrong. All three are superseded by newer versions of the same project, which do reproduce.

The loader accepts snapshot schemas 14 and 15. Anything else is refused by number. See Reproduce a valuation for what that means for an audit report.

What reproduction proves, and what it does not¶

Reproducing a valuation proves exactly one thing: the published code turns those inputs into that output. It is a check on the arithmetic and on the honesty of the published model — nothing more.

It says nothing about whether the inputs themselves are true. That is the verifier's own work, and it is a different job:

Input	Cross-check it against
Historical generation (`hist_prod_monthly`)	the plant's revenue meter readings
PPA price curve (`ppa`)	the signed power purchase agreement
Macro series (`macro`: FX, CPI, PPI, US rates)	the official published index or the central bank's series
Installed capacity (`kwp`), commissioning date	the as-built documentation and the interconnection record
O&M history (`hist_opex_monthly`)	the maintenance invoices
pWatt supply backing the NAV per token	the token contract on chain

A valuation that reproduces exactly and is built on an overstated generation figure is still wrong. This package narrows the question an auditor has to answer from "is this number right?" to "are these inputs right?", which is a question that can be settled with documents.

Install¶

pip install "suno-valuation-engine @ git+https://gitlab.com/suno-finance/suno-valuation-engine.git@<commit-sha>"

Pin the commit SHA the valuation names, not a tag. A tag is a movable label; the SHA is the content. Every published valuation records the engine version and the commit that produced it, and that commit is what should be installed to check it.

Python 3.12 or newer. The command above installs nothing else.

Reproduce a valuation in three steps¶

# 1. Get the snapshot: the complete set of inputs the valuation consumed,
#    as a JSON document.
#    (Any copy works — the engine neither knows nor cares where it came from.)

# 2. Run the model over it.
suno-valuation run snapshot.json

# 3. Check it against the number that was published.
suno-valuation verify snapshot.json --expect-nav 1.0841352254

verify exits 0 when the numbers match, 1 when they do not, and 2 when the snapshot cannot be evaluated at all. The full walkthrough, including what each exit code should become in an audit report, is in Reproduce a valuation.

Where to go next¶

Methodology — the model phase by phase, in financial language. Written to be read without opening the source.
Reproduce a valuation — the auditor's walkthrough.
Divergences from the Excel — the ten places where this engine deliberately departs from the reference spreadsheet, each with its measured effect on NPV and NAV.
API reference — the public names, for reading the source or driving the engine from Python.

Reporting something wrong¶

A report about a published number — a valuation you believe is incorrect — is the most valuable kind of report this project can receive, and it is welcome whether or not you can point at the line of code responsible. Open an issue at https://gitlab.com/suno-finance/suno-valuation-engine/-/issues using the Calculation defect template, and include the snapshot (or a minimal set of inputs that reproduces the problem), what you expected, what you observed, and the engine version and commit the result was computed with.

Anything that should stay private until it is fixed goes through SECURITY.md instead.