vgrid export

Export canonical financial truth data as deterministic CSV seeds and a JSON manifest. Designed for dbt workflows — the output can be seeded directly into a warehouse for verification against transformed data.

vgrid export truth --transactions <file.csv> [options]
vgrid export truth --daily-totals <file.csv> [options]

Option	Description
`--transactions`	Input truth_transactions.csv (full transaction detail)
`--daily-totals`	Input truth_daily_totals.csv (skip transaction aggregation)
`--out`	Output directory (default: `seeds/`)
`-q, --quiet`	Suppress stderr output

Provide either --transactions or --daily-totals, not both.

Examples

# From transaction-level data → seeds/
vgrid export truth --transactions stripe_truth.csv

# Custom output directory
vgrid export truth --transactions data/truth.csv --out dbt_seeds/

# From pre-aggregated daily totals (skip aggregation)
vgrid export truth --daily-totals daily_totals.csv --out seeds/

Output files

When using --transactions:

File	Description
`seeds/truth_transactions.csv`	Deterministic, sorted canonical transactions
`seeds/truth_daily_totals.csv`	Aggregated daily totals by (date, currency, source_account)
`seeds/truth_manifest.json`	Hashes, metadata, schema version

When using --daily-totals:

File	Description
`seeds/truth_daily_totals.csv`	Re-written deterministically
`seeds/truth_manifest.json`	Hashes and metadata

Transaction CSV format

The input truth_transactions.csv must have these columns:

source,source_account,source_id,occurred_at,posted_at,currency,direction,amount_gross,fee_amount,amount_net,counterparty,description,raw_hash

Column	Type	Description
`source`	string	Data source (e.g. `stripe`, `mercury`)
`source_account`	string	Account identifier
`source_id`	string	Transaction ID from source
`occurred_at`	date	Transaction date (`YYYY-MM-DD`)
`posted_at`	date or empty	Settlement date
`currency`	string	ISO 4217 code (e.g. `USD`)
`direction`	enum	`credit` or `debit`
`amount_gross`	decimal	Gross amount in micro-units (6 decimal places)
`fee_amount`	decimal	Fee amount in micro-units
`amount_net`	decimal	Net amount in micro-units
`counterparty`	string or empty	Other party
`description`	string or empty	Transaction description
`raw_hash`	string	Source row fingerprint

Daily totals format

The truth_daily_totals.csv format (both input and output):

date,currency,source_account,total_gross,total_fee,total_net,transaction_count

All amounts are in micro-units (1e-6 of currency unit). $100.00 = 100.000000.

Aggregation rules:

Gross/Net: credits are positive, debits are negative (signed sum)
Fee: always non-negative (absolute sum)
Sorted by: date, currency, source_account
Single-account enforcement: all transactions must share the same source_account

Manifest

{
  "schema_version": "1.0",
  "transactions_hash": "abc123...",
  "daily_totals_hash": "def456...",
  "source_account": "acct_demo_001",
  "date_range": { "min": "2026-01-15", "max": "2026-01-18" },
  "transaction_count": 10,
  "daily_totals_rows": 4,
  "mapping_profile_hash": null
}

Hashes use BLAKE3. The manifest provides a tamper-evident summary of the exported data.

Deterministic output

The same input data in any order produces byte-identical output CSVs. This is critical for:

Hash stability across runs
Reproducible dbt seeds
Proof chain integrity

Transactions are sorted by (occurred_at, source_id). Daily totals are sorted by (date, currency, source_account). Amounts are always formatted to exactly 6 decimal places.

dbt integration

The output is designed as dbt seed input:

# 1. Export truth seeds
vgrid export truth --transactions stripe_truth.csv --out seeds/

# 2. Seed into warehouse
dbt seed

# 3. Build warehouse model (produces warehouse_daily_totals)
dbt run

# 4. Verify truth vs warehouse
vgrid verify totals seeds/truth_daily_totals.csv warehouse_daily_totals.csv \
  --sign --proof proof.json