-
- Current Treasury Balance
-
-
- {formatCurrency(snapshot.totalUsd)}
-
-
{syncCopy}
- {justUpdated ? (
-
- Updated just now
+
+
+
+
+
+
+ Current Treasury Balance
+
+
+ {formatCurrency(snapshot.totalUsd)}
- ) : null}
+
{syncCopy}
+ {justUpdated ? (
+
+ Updated just now
+
+ ) : null}
+
+
-
-
-
-
-
- Accounts
- -
- {snapshot.accounts.length}
-
-
-
-
- Assets
- -
- {snapshot.assets.length}
-
-
-
-
- Source
- - Gnosis accounts
-
-
-
-
-
-
-
-
-
+
+
+
- Accounts
+ -
+ {snapshot.accounts.length}
+
+
+
+
- Assets
+ -
+ {snapshot.assets.length}
+
-
Account
-
Included accounts
+
- Source
+
- {sourceLabel}
+ {sourceChainNames.length > 1 ? (
+
-
+ {sourceChainNames.join(", ")}
+
+ ) : null}
+
+
+
+
+ Balance by chain
+
+
+ {chainSummaries.map((chain) => (
+
+
+ {chain.chainName}
+
+
+ {formatCurrency(String(chain.totalUsd))}
+
+
+ ))}
-
- {snapshot.accounts.length} accounts
-
-
- {snapshot.accounts.map((account) => (
-
-
-
- {account.name}
-
-
- {formatCurrency(account.totalUsd)}
-
+
+
+
+
+
+
+
+
Account
+
Included accounts
- {account.address ? (
-
-
- {formatAddress(account.address)}
-
-
-
- ) : (
-
- Address not configured
-
- )}
- ))}
+
+ {snapshot.accounts.length} accounts
+
+
+
+
+ {snapshot.accounts.map((account) => (
+
+
+
+ {account.name}
+
+
+ {formatCurrency(account.totalUsd)}
+
+
+ {account.address ? (
+
+
+ {formatAddress(account.address)}
+
+
+
+ ) : (
+
+ Address not configured
+
+ )}
+
+ ))}
+
-
-
+
+
@@ -316,15 +372,16 @@ export function TreasuryDashboard({
isRefreshing ? "opacity-75" : "opacity-100"
}`}
>
-
+
Asset
+ Chain
Balance
USD Value
{snapshot.assets.map((asset) => (
{asset.symbol}
@@ -332,6 +389,9 @@ export function TreasuryDashboard({
{asset.name}
+
+ {asset.chainIds.map(getChainName).join(", ")}
+
{formatNumber(asset.balance)} {asset.symbol}
@@ -385,14 +445,21 @@ export function TreasuryDashboard({
? formatTimestamp(quarter.publishedAt)
: "date unavailable"}
-
+
+
+ View Report
+
+
+
+ Export
+
+
))}
diff --git a/src/db/schema.ts b/src/db/schema.ts
index 6ceb07d..bf28b5a 100644
--- a/src/db/schema.ts
+++ b/src/db/schema.ts
@@ -103,6 +103,11 @@ export const quarterBalanceBoundaryEnum = pgEnum("quarter_balance_boundary", [
"closing",
]);
+export const quarterBalanceValidationStatusEnum = pgEnum(
+ "quarter_balance_validation_status",
+ ["not_ready", "needs_review", "validated", "acknowledged"],
+);
+
export const auditActionEnum = pgEnum("audit_action", [
"create",
"update",
@@ -385,6 +390,38 @@ export const quarterBalanceSnapshots = pgTable(
],
);
+export const quarterBalanceValidations = pgTable(
+ "quarter_balance_validations",
+ {
+ id: uuid("id").defaultRandom().primaryKey(),
+ quarterId: uuid("quarter_id")
+ .notNull()
+ .references(() => quarters.id, { onDelete: "cascade" }),
+ status: quarterBalanceValidationStatusEnum("status").notNull(),
+ checkedCount: integer("checked_count").default(0).notNull(),
+ varianceCount: integer("variance_count").default(0).notNull(),
+ excludedCount: integer("excluded_count").default(0).notNull(),
+ totalVarianceUsd: numeric("total_variance_usd", {
+ precision: 18,
+ scale: 2,
+ })
+ .default("0")
+ .notNull(),
+ details: jsonb("details").notNull(),
+ acknowledgementNoteEncrypted: jsonb("acknowledgement_note_encrypted"),
+ acknowledgedByWalletAddress: text("acknowledged_by_wallet_address"),
+ acknowledgedAt: timestamp("acknowledged_at", { withTimezone: true }),
+ sourceSyncRunId: text("source_sync_run_id"),
+ ...timestamps,
+ },
+ (table) => [
+ uniqueIndex("quarter_balance_validations_quarter_id_unique").on(
+ table.quarterId,
+ ),
+ index("quarter_balance_validations_status_idx").on(table.status),
+ ],
+);
+
export const treasuryTransactions = pgTable(
"treasury_transactions",
{
diff --git a/src/lib/quarter-balance-validation.ts b/src/lib/quarter-balance-validation.ts
new file mode 100644
index 0000000..879c2ad
--- /dev/null
+++ b/src/lib/quarter-balance-validation.ts
@@ -0,0 +1,708 @@
+import "server-only";
+
+import { and, eq, inArray, sql } from "drizzle-orm";
+
+import { getDb } from "@/db";
+import {
+ ledgerEntries,
+ quarterBalanceSnapshots,
+ quarterBalanceValidations,
+ treasuryAccounts,
+ treasuryTransactionTransfers,
+} from "@/db/schema";
+import {
+ decryptField,
+ encryptField,
+ type EncryptedField,
+} from "@/lib/encryption";
+import type { QuarterClassificationSummary, QuarterSummary } from "@/lib/quarters";
+import { isQuarterSyncFresh, type QuarterSyncStatus } from "@/lib/quarter-sync";
+
+export type QuarterBalanceValidationStatus =
+ | "not_ready"
+ | "needs_review"
+ | "validated"
+ | "acknowledged";
+
+export type QuarterBalanceValidationVariance = {
+ accountAddress: string;
+ accountName: string;
+ actualClosing: string;
+ assetSymbol: string;
+ chainId: number;
+ difference: string;
+ expectedClosing: string;
+ movement: string;
+ opening: string;
+ usdPrice: string;
+ varianceUsd: string;
+};
+
+export type QuarterBalanceValidationExcludedRow = {
+ assetAmount: string;
+ assetSymbol: string;
+ category: string;
+ id: string;
+ reason: string;
+ source: string;
+};
+
+export type QuarterBalanceValidationDetails = {
+ excludedRows: QuarterBalanceValidationExcludedRow[];
+ variances: QuarterBalanceValidationVariance[];
+};
+
+export type QuarterBalanceValidation = {
+ acknowledgedAt: string | null;
+ acknowledgedByWalletAddress: string | null;
+ acknowledgementNote: string | null;
+ checkedCount: number;
+ details: QuarterBalanceValidationDetails;
+ excludedCount: number;
+ id: string;
+ quarterId: string;
+ sourceSyncRunId: string | null;
+ status: QuarterBalanceValidationStatus;
+ totalVarianceUsd: string;
+ updatedAt: string;
+ varianceCount: number;
+};
+
+export type QuarterBalanceValidationReadiness = {
+ reason: string | null;
+ ready: boolean;
+};
+
+type QuarterValidationInput = Pick<
+ QuarterSummary,
+ "endsOn" | "id" | "startsOn"
+>;
+
+type BalanceRow = typeof quarterBalanceSnapshots.$inferSelect;
+type ManualLedgerEntry = typeof ledgerEntries.$inferSelect;
+
+const ZERO = BigInt(0);
+const ONE = BigInt(1);
+const NEGATIVE_ONE = BigInt(-1);
+const DECIMAL_SCALE = BigInt(10) ** BigInt(18);
+const TOKEN_TOLERANCE = BigInt(10) ** BigInt(12); // 0.000001 at 18-decimal precision.
+
+function parseFixedDecimal(value: string | null | undefined) {
+ if (!value?.trim()) {
+ return ZERO;
+ }
+
+ const trimmed = value.trim();
+ const sign = trimmed.startsWith("-") ? NEGATIVE_ONE : ONE;
+ const unsigned = trimmed.replace(/^[+-]/, "");
+ const [whole = "0", fraction = ""] = unsigned.split(".");
+
+ if (!/^\d*$/.test(whole) || !/^\d*$/.test(fraction)) {
+ return ZERO;
+ }
+
+ const wholeValue = BigInt(whole || "0") * DECIMAL_SCALE;
+ const fractionValue = BigInt(
+ fraction.padEnd(18, "0").slice(0, 18) || "0",
+ );
+
+ return sign * (wholeValue + fractionValue);
+}
+
+function absFixed(value: bigint) {
+ return value < ZERO ? -value : value;
+}
+
+function formatFixedDecimal(value: bigint, fractionDigits = 18) {
+ const sign = value < ZERO ? "-" : "";
+ const absolute = absFixed(value);
+ const whole = absolute / DECIMAL_SCALE;
+ const fraction = absolute % DECIMAL_SCALE;
+ const fractionText = fraction
+ .toString()
+ .padStart(18, "0")
+ .slice(0, fractionDigits)
+ .replace(/0+$/, "");
+
+ return `${sign}${whole.toString()}${fractionText ? `.${fractionText}` : ""}`;
+}
+
+function multiplyFixed(left: bigint, right: bigint) {
+ return (left * right) / DECIMAL_SCALE;
+}
+
+function formatUsd(value: bigint) {
+ const sign = value < ZERO ? "-" : "";
+ const cents =
+ (absFixed(value) * BigInt(100) + DECIMAL_SCALE / BigInt(2)) /
+ DECIMAL_SCALE;
+ const dollars = cents / BigInt(100);
+ const pennies = cents % BigInt(100);
+
+ return `${sign}${dollars.toString()}.${pennies.toString().padStart(2, "0")}`;
+}
+
+function getKey({
+ accountAddress,
+ assetSymbol,
+ chainId,
+}: {
+ accountAddress: string;
+ assetSymbol: string;
+ chainId: number;
+}) {
+ return `${chainId}:${accountAddress.toLowerCase()}:${assetSymbol.toUpperCase()}`;
+}
+
+function getMetadataObject(value: unknown) {
+ return value && typeof value === "object"
+ ? (value as Record
)
+ : {};
+}
+
+function getMetadataString(
+ metadata: Record,
+ key: string,
+): string | null {
+ const value = metadata[key];
+
+ return typeof value === "string" && value ? value : null;
+}
+
+function mapValidation(
+ validation: typeof quarterBalanceValidations.$inferSelect,
+): QuarterBalanceValidation {
+ return {
+ acknowledgedAt: validation.acknowledgedAt?.toISOString() ?? null,
+ acknowledgedByWalletAddress: validation.acknowledgedByWalletAddress,
+ acknowledgementNote: validation.acknowledgementNoteEncrypted
+ ? decryptField(validation.acknowledgementNoteEncrypted as EncryptedField)
+ : null,
+ checkedCount: validation.checkedCount,
+ details: validation.details as QuarterBalanceValidationDetails,
+ excludedCount: validation.excludedCount,
+ id: validation.id,
+ quarterId: validation.quarterId,
+ sourceSyncRunId: validation.sourceSyncRunId,
+ status: validation.status,
+ totalVarianceUsd: validation.totalVarianceUsd,
+ updatedAt: validation.updatedAt.toISOString(),
+ varianceCount: validation.varianceCount,
+ };
+}
+
+export async function getQuarterBalanceValidation(quarterId: string) {
+ const [validation] = await getDb()
+ .select()
+ .from(quarterBalanceValidations)
+ .where(eq(quarterBalanceValidations.quarterId, quarterId))
+ .limit(1);
+
+ return validation ? mapValidation(validation) : null;
+}
+
+export async function getQuarterBalanceValidationMap(quarterIds: string[]) {
+ if (quarterIds.length === 0) {
+ return new Map();
+ }
+
+ const rows = await getDb()
+ .select()
+ .from(quarterBalanceValidations)
+ .where(inArray(quarterBalanceValidations.quarterId, quarterIds));
+
+ return new Map(rows.map((row) => [row.quarterId, mapValidation(row)]));
+}
+
+export function isQuarterBalanceValidationSatisfied(
+ validation: QuarterBalanceValidation | null,
+) {
+ return (
+ validation?.status === "validated" || validation?.status === "acknowledged"
+ );
+}
+
+export function getQuarterValidationReadiness({
+ classificationSummary,
+ quarter,
+ syncStatus,
+}: {
+ classificationSummary: QuarterClassificationSummary;
+ quarter: Pick;
+ syncStatus: QuarterSyncStatus | null;
+}): QuarterBalanceValidationReadiness {
+ if (!isQuarterSyncFresh({ quarter, syncStatus })) {
+ return {
+ ready: false,
+ reason: "Sync quarter activity and balances before validating",
+ };
+ }
+
+ if (syncStatus?.balancesStatus !== "success") {
+ return {
+ ready: false,
+ reason: "Quarter balances must sync successfully before validating",
+ };
+ }
+
+ if (classificationSummary.unclassifiedTransfers > 0) {
+ return {
+ ready: false,
+ reason: "Classify every transaction before validating balances",
+ };
+ }
+
+ return { ready: true, reason: null };
+}
+
+export async function deleteQuarterBalanceValidation(quarterId: string) {
+ await getDb()
+ .delete(quarterBalanceValidations)
+ .where(eq(quarterBalanceValidations.quarterId, quarterId));
+}
+
+function getManualMovementAccountAddress({
+ entry,
+ trackedAccounts,
+}: {
+ entry: ManualLedgerEntry;
+ trackedAccounts: Set;
+}) {
+ if (!entry.chainId) {
+ return null;
+ }
+
+ const metadata = getMetadataObject(entry.sourceMetadata);
+ const candidates =
+ entry.category === "raid_revenue" || entry.category === "raid_spoils"
+ ? [
+ getMetadataString(metadata, "receivingAddress"),
+ getMetadataString(metadata, "toAddress"),
+ ]
+ : [
+ getMetadataString(metadata, "paidAddress"),
+ getMetadataString(metadata, "fromAddress"),
+ getMetadataString(metadata, "senderAddress"),
+ ];
+
+ for (const candidate of candidates) {
+ if (!candidate) {
+ continue;
+ }
+
+ if (trackedAccounts.has(`${entry.chainId}:${candidate.toLowerCase()}`)) {
+ return candidate;
+ }
+ }
+
+ return null;
+}
+
+function getManualMovementSign(category: string) {
+ if (category === "raid_revenue" || category === "raid_spoils") {
+ return 1;
+ }
+
+ if (
+ category === "provider_expense" ||
+ category === "ragequit" ||
+ category === "rip_expense" ||
+ category === "subcontractor_payout"
+ ) {
+ return -1;
+ }
+
+ return null;
+}
+
+function getTransferMovementSign({
+ accountAddress,
+ fromAddress,
+ toAddress,
+}: {
+ accountAddress: string;
+ fromAddress: string;
+ toAddress: string;
+}) {
+ const account = accountAddress.toLowerCase();
+ const from = fromAddress.toLowerCase();
+ const to = toAddress.toLowerCase();
+
+ if (from === account && to === account) {
+ return 0;
+ }
+
+ if (to === account) {
+ return 1;
+ }
+
+ if (from === account) {
+ return -1;
+ }
+
+ return null;
+}
+
+export async function runQuarterBalanceValidation({
+ classificationSummary,
+ quarter,
+ syncStatus,
+}: {
+ classificationSummary: QuarterClassificationSummary;
+ quarter: QuarterValidationInput;
+ syncStatus: QuarterSyncStatus | null;
+}) {
+ const readiness = getQuarterValidationReadiness({
+ classificationSummary,
+ quarter,
+ syncStatus,
+ });
+
+ if (!readiness.ready) {
+ throw new Error(readiness.reason ?? "Quarter is not ready for validation");
+ }
+
+ const db = getDb();
+ const [balanceRows, transferRows, manualRows] = await Promise.all([
+ db
+ .select()
+ .from(quarterBalanceSnapshots)
+ .where(eq(quarterBalanceSnapshots.quarterId, quarter.id)),
+ db
+ .select({
+ ledgerEntry: ledgerEntries,
+ transfer: treasuryTransactionTransfers,
+ })
+ .from(treasuryTransactionTransfers)
+ .innerJoin(
+ ledgerEntries,
+ eq(
+ ledgerEntries.treasuryTransactionTransferId,
+ treasuryTransactionTransfers.id,
+ ),
+ )
+ .where(eq(ledgerEntries.quarterId, quarter.id)),
+ db
+ .select()
+ .from(ledgerEntries)
+ .where(
+ and(
+ eq(ledgerEntries.quarterId, quarter.id),
+ sql`${ledgerEntries.treasuryTransactionTransferId} is null`,
+ ),
+ ),
+ ]);
+ const openingByKey = new Map();
+ const closingByKey = new Map();
+ const movements = new Map();
+ const trackedAccounts = new Set();
+ const accountNames = new Map();
+ const treasuryAccountIds = [
+ ...new Set(
+ balanceRows
+ .map((row) => row.treasuryAccountId)
+ .filter((id): id is string => Boolean(id)),
+ ),
+ ];
+ const treasuryAccountNameRows =
+ treasuryAccountIds.length > 0
+ ? await db
+ .select({
+ id: treasuryAccounts.id,
+ nameEncrypted: treasuryAccounts.nameEncrypted,
+ })
+ .from(treasuryAccounts)
+ .where(inArray(treasuryAccounts.id, treasuryAccountIds))
+ : [];
+ const treasuryAccountNames = new Map(
+ treasuryAccountNameRows.map((account) => [
+ account.id,
+ decryptField(account.nameEncrypted as EncryptedField),
+ ]),
+ );
+ const excludedRows: QuarterBalanceValidationExcludedRow[] = [];
+
+ for (const row of balanceRows) {
+ const accountKey = `${row.chainId}:${row.accountAddress.toLowerCase()}`;
+ const key = getKey({
+ accountAddress: row.accountAddress,
+ assetSymbol: row.symbol,
+ chainId: row.chainId,
+ });
+
+ trackedAccounts.add(accountKey);
+ accountNames.set(
+ accountKey,
+ row.treasuryAccountId
+ ? (treasuryAccountNames.get(row.treasuryAccountId) ?? "Tracked Account")
+ : "Treasury",
+ );
+
+ if (row.boundary === "opening") {
+ openingByKey.set(key, row);
+ } else {
+ closingByKey.set(key, row);
+ }
+ }
+
+ const balanceKeys = new Set([...openingByKey.keys(), ...closingByKey.keys()]);
+
+ if (balanceKeys.size === 0) {
+ throw new Error("Quarter balances must sync before validation can run");
+ }
+
+ for (const { ledgerEntry, transfer } of transferRows) {
+ if (ledgerEntry.category === "uncategorized") {
+ excludedRows.push({
+ assetAmount: transfer.amount,
+ assetSymbol: transfer.assetSymbol,
+ category: ledgerEntry.category,
+ id: ledgerEntry.id,
+ reason: "Transaction is not classified",
+ source: ledgerEntry.source,
+ });
+ continue;
+ }
+
+ const sign = getTransferMovementSign({
+ accountAddress: transfer.accountAddress,
+ fromAddress: transfer.fromAddress,
+ toAddress: transfer.toAddress,
+ });
+
+ if (sign === null) {
+ excludedRows.push({
+ assetAmount: transfer.amount,
+ assetSymbol: transfer.assetSymbol,
+ category: ledgerEntry.category,
+ id: ledgerEntry.id,
+ reason: "Transfer does not match the tracked account side",
+ source: ledgerEntry.source,
+ });
+ continue;
+ }
+
+ const key = getKey({
+ accountAddress: transfer.accountAddress,
+ assetSymbol: transfer.assetSymbol,
+ chainId: transfer.chainId,
+ });
+
+ movements.set(
+ key,
+ (movements.get(key) ?? ZERO) +
+ BigInt(sign) * parseFixedDecimal(transfer.amount),
+ );
+ balanceKeys.add(key);
+ }
+
+ for (const entry of manualRows) {
+ if (entry.category === "uncategorized") {
+ excludedRows.push({
+ assetAmount: entry.assetAmount,
+ assetSymbol: entry.assetSymbol,
+ category: entry.category,
+ id: entry.id,
+ reason: "Ledger entry is not classified",
+ source: entry.source,
+ });
+ continue;
+ }
+
+ const sign = getManualMovementSign(entry.category);
+
+ if (sign === null || !entry.chainId) {
+ excludedRows.push({
+ assetAmount: entry.assetAmount,
+ assetSymbol: entry.assetSymbol,
+ category: entry.category,
+ id: entry.id,
+ reason: "Ledger entry does not have enough account data",
+ source: entry.source,
+ });
+ continue;
+ }
+
+ const accountAddress = getManualMovementAccountAddress({
+ entry,
+ trackedAccounts,
+ });
+
+ if (!accountAddress) {
+ excludedRows.push({
+ assetAmount: entry.assetAmount,
+ assetSymbol: entry.assetSymbol,
+ category: entry.category,
+ id: entry.id,
+ reason: "Ledger entry account is not included in quarter balances",
+ source: entry.source,
+ });
+ continue;
+ }
+
+ const key = getKey({
+ accountAddress,
+ assetSymbol: entry.assetSymbol,
+ chainId: entry.chainId,
+ });
+
+ movements.set(
+ key,
+ (movements.get(key) ?? ZERO) +
+ BigInt(sign) * parseFixedDecimal(entry.assetAmount),
+ );
+ balanceKeys.add(key);
+ }
+
+ const variances: QuarterBalanceValidationVariance[] = [];
+
+ for (const key of balanceKeys) {
+ const [chainIdText, accountAddress, assetSymbol] = key.split(":");
+ const opening = openingByKey.get(key);
+ const closing = closingByKey.get(key);
+ const openingAmount = parseFixedDecimal(opening?.balance);
+ const actualClosing = parseFixedDecimal(closing?.balance);
+ const movement = movements.get(key) ?? ZERO;
+ const expectedClosing = openingAmount + movement;
+ const difference = actualClosing - expectedClosing;
+
+ if (absFixed(difference) <= TOKEN_TOLERANCE) {
+ continue;
+ }
+
+ const chainId = Number(chainIdText);
+ const usdPrice = parseFixedDecimal(closing?.usdPrice ?? opening?.usdPrice);
+ const varianceUsd = multiplyFixed(absFixed(difference), usdPrice);
+ const accountKey = `${chainId}:${accountAddress.toLowerCase()}`;
+
+ variances.push({
+ accountAddress,
+ accountName: accountNames.get(accountKey) ?? "Unknown Account",
+ actualClosing: formatFixedDecimal(actualClosing),
+ assetSymbol,
+ chainId,
+ difference: formatFixedDecimal(difference),
+ expectedClosing: formatFixedDecimal(expectedClosing),
+ movement: formatFixedDecimal(movement),
+ opening: formatFixedDecimal(openingAmount),
+ usdPrice: formatUsd(usdPrice),
+ varianceUsd: formatUsd(varianceUsd),
+ });
+ }
+
+ variances.sort(
+ (left, right) => {
+ const difference =
+ parseFixedDecimal(right.varianceUsd) -
+ parseFixedDecimal(left.varianceUsd);
+
+ if (difference > ZERO) {
+ return 1;
+ }
+
+ if (difference < ZERO) {
+ return -1;
+ }
+
+ return 0;
+ },
+ );
+
+ const status: QuarterBalanceValidationStatus =
+ variances.length === 0 && excludedRows.length === 0
+ ? "validated"
+ : "needs_review";
+ const totalVarianceUsd = variances.reduce(
+ (total, variance) => total + parseFixedDecimal(variance.varianceUsd),
+ ZERO,
+ );
+
+ const [validation] = await db
+ .insert(quarterBalanceValidations)
+ .values({
+ checkedCount: balanceKeys.size,
+ details: {
+ excludedRows,
+ variances,
+ } satisfies QuarterBalanceValidationDetails,
+ excludedCount: excludedRows.length,
+ quarterId: quarter.id,
+ sourceSyncRunId: syncStatus?.runId ?? null,
+ status,
+ totalVarianceUsd: formatUsd(totalVarianceUsd),
+ varianceCount: variances.length,
+ })
+ .onConflictDoUpdate({
+ set: {
+ acknowledgedAt: null,
+ acknowledgedByWalletAddress: null,
+ acknowledgementNoteEncrypted: null,
+ checkedCount: balanceKeys.size,
+ details: {
+ excludedRows,
+ variances,
+ } satisfies QuarterBalanceValidationDetails,
+ excludedCount: excludedRows.length,
+ sourceSyncRunId: syncStatus?.runId ?? null,
+ status,
+ totalVarianceUsd: formatUsd(totalVarianceUsd),
+ updatedAt: sql`now()`,
+ varianceCount: variances.length,
+ },
+ target: quarterBalanceValidations.quarterId,
+ })
+ .returning();
+
+ return mapValidation(validation);
+}
+
+export async function acknowledgeQuarterBalanceValidation({
+ note,
+ quarterId,
+ walletAddress,
+}: {
+ note: string;
+ quarterId: string;
+ walletAddress: string;
+}) {
+ const existing = await getQuarterBalanceValidation(quarterId);
+
+ if (!existing) {
+ throw new Error("Run balance validation before acknowledging variance");
+ }
+
+ if (existing.status === "validated") {
+ throw new Error("This quarter has no variance to acknowledge");
+ }
+
+ if (existing.status !== "needs_review") {
+ throw new Error("Re-run validation before acknowledging variance");
+ }
+
+ if (!note.trim()) {
+ throw new Error("Variance note is required");
+ }
+
+ const [validation] = await getDb()
+ .update(quarterBalanceValidations)
+ .set({
+ acknowledgedAt: new Date(),
+ acknowledgedByWalletAddress: walletAddress,
+ acknowledgementNoteEncrypted: encryptField(note.trim()),
+ status: "acknowledged",
+ updatedAt: sql`now()`,
+ })
+ .where(
+ and(
+ eq(quarterBalanceValidations.quarterId, quarterId),
+ eq(quarterBalanceValidations.status, "needs_review"),
+ ),
+ )
+ .returning();
+
+ if (!validation) {
+ throw new Error("Validation status changed. Re-run validation and try again.");
+ }
+
+ return mapValidation(validation);
+}
diff --git a/src/lib/quarter-export-readiness.ts b/src/lib/quarter-export-readiness.ts
index 659945f..a26c5ca 100644
--- a/src/lib/quarter-export-readiness.ts
+++ b/src/lib/quarter-export-readiness.ts
@@ -1,15 +1,17 @@
import type { QuarterReportingPeriod } from "@/lib/quarters";
import { isQuarterSyncFresh } from "@/lib/quarter-sync";
+import { isQuarterBalanceValidationSatisfied } from "@/lib/quarter-balance-validation";
export function isQuarterExportReady(
quarter: Pick<
QuarterReportingPeriod,
- "classificationSummary" | "endsOn" | "syncStatus"
+ "balanceValidation" | "classificationSummary" | "endsOn" | "syncStatus"
>,
) {
return (
isQuarterSyncFresh({ quarter, syncStatus: quarter.syncStatus }) &&
quarter.syncStatus?.balancesStatus === "success" &&
- quarter.classificationSummary.unclassifiedTransfers === 0
+ quarter.classificationSummary.unclassifiedTransfers === 0 &&
+ isQuarterBalanceValidationSatisfied(quarter.balanceValidation)
);
}
diff --git a/src/lib/quarter-report.ts b/src/lib/quarter-report.ts
new file mode 100644
index 0000000..22ce758
--- /dev/null
+++ b/src/lib/quarter-report.ts
@@ -0,0 +1,160 @@
+import "server-only";
+
+import type { QuarterSummary } from "@/lib/quarters";
+import {
+ listQuarterBalanceRows,
+ summarizeQuarterBalanceRows,
+ type QuarterAccountBalanceSummary,
+} from "@/lib/quarter-balances";
+import {
+ buildQuarterLedgerRows,
+ type QuarterExportLedgerRow,
+} from "@/lib/quarter-xlsx-export";
+
+export type QuarterReportMetric = {
+ label: string;
+ value: number;
+};
+
+export type QuarterReportLinkedRow = {
+ label: string;
+ totalUsd: number;
+ entries: number;
+};
+
+export type QuarterReportData = {
+ balances: QuarterAccountBalanceSummary[];
+ ledgerRows: QuarterExportLedgerRow[];
+ metrics: {
+ expenses: number;
+ net: number;
+ revenue: number;
+ spoilsReceived: number;
+ subcontractorPayouts: number;
+ };
+ providerExpenses: QuarterReportLinkedRow[];
+ ripExpenses: QuarterReportLinkedRow[];
+ topRaids: QuarterReportLinkedRow[];
+};
+
+function toNumber(value: string | null | undefined) {
+ if (!value) {
+ return 0;
+ }
+
+ const number = Number(value);
+
+ return Number.isFinite(number) ? number : 0;
+}
+
+function sumRows(
+ rows: QuarterExportLedgerRow[],
+ categories: NonNullable[],
+) {
+ return rows.reduce((total, row) => {
+ if (!row.category || !categories.includes(row.category)) {
+ return total;
+ }
+
+ return total + toNumber(row.usdAmount);
+ }, 0);
+}
+
+function sumRaidLinkedSubcontractorPayouts(rows: QuarterExportLedgerRow[]) {
+ return rows.reduce((total, row) => {
+ if (row.category !== "subcontractor_payout" || !row.raid) {
+ return total;
+ }
+
+ return total + toNumber(row.usdAmount);
+ }, 0);
+}
+
+function summarizeLinkedRows({
+ category,
+ fallbackLabel,
+ getLabel,
+ rows,
+}: {
+ category: NonNullable;
+ fallbackLabel: string;
+ getLabel: (row: QuarterExportLedgerRow) => string;
+ rows: QuarterExportLedgerRow[];
+}) {
+ const summaries = new Map();
+
+ for (const row of rows) {
+ if (row.category !== category) {
+ continue;
+ }
+
+ const label = getLabel(row) || fallbackLabel;
+ const summary =
+ summaries.get(label) ??
+ ({
+ entries: 0,
+ label,
+ totalUsd: 0,
+ } satisfies QuarterReportLinkedRow);
+
+ summary.entries += 1;
+ summary.totalUsd += toNumber(row.usdAmount);
+ summaries.set(label, summary);
+ }
+
+ return Array.from(summaries.values()).sort((left, right) => {
+ if (left.totalUsd !== right.totalUsd) {
+ return right.totalUsd - left.totalUsd;
+ }
+
+ return left.label.localeCompare(right.label);
+ });
+}
+
+export async function getQuarterReportData(
+ quarter: QuarterSummary,
+): Promise {
+ const [ledgerRows, balanceRows] = await Promise.all([
+ buildQuarterLedgerRows({ quarter }),
+ listQuarterBalanceRows(quarter.id),
+ ]);
+ const revenue = sumRows(ledgerRows, ["raid_revenue", "member_dues"]);
+ const expenses = sumRows(ledgerRows, [
+ "provider_expense",
+ "ragequit",
+ "rip_expense",
+ "subcontractor_payout",
+ ]);
+ const spoilsReceived = sumRows(ledgerRows, ["raid_spoils"]);
+ const subcontractorPayouts = sumRaidLinkedSubcontractorPayouts(ledgerRows);
+
+ return {
+ balances: summarizeQuarterBalanceRows(balanceRows),
+ ledgerRows,
+ metrics: {
+ expenses,
+ net: revenue - expenses,
+ revenue,
+ spoilsReceived,
+ subcontractorPayouts,
+ },
+ providerExpenses: summarizeLinkedRows({
+ category: "provider_expense",
+ fallbackLabel: "Unlinked Provider",
+ getLabel: (row) => row.counterparty,
+ rows: ledgerRows,
+ }),
+ ripExpenses: summarizeLinkedRows({
+ category: "rip_expense",
+ fallbackLabel: "Unlinked RIP",
+ getLabel: (row) => row.rip,
+ rows: ledgerRows,
+ }),
+ topRaids: summarizeLinkedRows({
+ category: "raid_revenue",
+ fallbackLabel: "Unlinked Raid",
+ getLabel: (row) => row.raid,
+ rows: ledgerRows,
+ }),
+ };
+}
diff --git a/src/lib/quarter-sync.ts b/src/lib/quarter-sync.ts
index e1a3940..e3d7cc5 100644
--- a/src/lib/quarter-sync.ts
+++ b/src/lib/quarter-sync.ts
@@ -46,7 +46,7 @@ export type QuarterSyncStatus = {
};
export type QuarterWorkflowStep = {
- key: "sync" | "classify" | "ready" | "publish";
+ key: "sync" | "classify" | "validate" | "ready" | "publish";
label: string;
status: "complete" | "current" | "blocked" | "pending" | "failed";
detail: string;
@@ -156,6 +156,7 @@ export function buildQuarterWorkflowSteps({
classificationSummary,
quarter,
syncStatus,
+ validation,
}: {
classificationSummary: {
classifiedTransfers: number;
@@ -164,6 +165,10 @@ export function buildQuarterWorkflowSteps({
};
quarter: QuarterLike;
syncStatus: QuarterSyncStatus | null;
+ validation?: {
+ status: "not_ready" | "needs_review" | "validated" | "acknowledged";
+ varianceCount: number;
+ } | null;
}): QuarterWorkflowStep[] {
const syncFresh = isQuarterSyncFresh({ quarter, syncStatus });
const syncFailed =
@@ -227,6 +232,34 @@ export function buildQuarterWorkflowSteps({
status: syncFresh ? "current" : "blocked",
};
+ const validationComplete =
+ validation?.status === "validated" || validation?.status === "acknowledged";
+ const validateStep: QuarterWorkflowStep = validationComplete
+ ? {
+ detail:
+ validation.status === "acknowledged"
+ ? `${validation.varianceCount} variance${validation.varianceCount === 1 ? "" : "s"} acknowledged`
+ : "Balances reconciled",
+ key: "validate",
+ label: "Validate balances",
+ status: "complete",
+ }
+ : validation?.status === "needs_review"
+ ? {
+ detail: "Acknowledge variance or resolve ledger differences",
+ key: "validate",
+ label: "Validate balances",
+ status: "current",
+ }
+ : {
+ detail: classificationComplete
+ ? "Ready to validate"
+ : "Finish classification first",
+ key: "validate",
+ label: "Validate balances",
+ status: classificationComplete ? "current" : "blocked",
+ };
+
const readyComplete =
quarter.status === "ready_for_review" || quarter.status === "published";
const readyStep: QuarterWorkflowStep = readyComplete
@@ -237,10 +270,10 @@ export function buildQuarterWorkflowSteps({
status: "complete",
}
: {
- detail: classificationComplete ? "Ready to mark" : "Finish review first",
+ detail: validationComplete ? "Ready to mark" : "Validate balances first",
key: "ready",
label: "Mark ready",
- status: classificationComplete ? "current" : "blocked",
+ status: validationComplete ? "current" : "blocked",
};
const publishStep: QuarterWorkflowStep =
@@ -251,7 +284,7 @@ export function buildQuarterWorkflowSteps({
label: "Publish",
status: "complete",
}
- : quarter.status === "ready_for_review" && classificationComplete
+ : quarter.status === "ready_for_review" && validationComplete
? {
detail: "Ready to publish",
key: "publish",
@@ -268,7 +301,7 @@ export function buildQuarterWorkflowSteps({
status: "blocked",
};
- return [syncStep, classifyStep, readyStep, publishStep];
+ return [syncStep, classifyStep, validateStep, readyStep, publishStep];
}
export async function startOrResumeQuarterSync(quarterId: string) {
diff --git a/src/lib/quarter-xlsx-export.ts b/src/lib/quarter-xlsx-export.ts
index 95871d4..8254a0b 100644
--- a/src/lib/quarter-xlsx-export.ts
+++ b/src/lib/quarter-xlsx-export.ts
@@ -14,7 +14,7 @@ import {
type LedgerCategory,
} from "@/lib/transaction-classification";
-type ExportLedgerRow = {
+export type QuarterExportLedgerRow = {
account: string;
assetAmount: string;
assetSymbol: string;
@@ -102,7 +102,7 @@ function addRowsSheet(
return worksheet;
}
-function sumUsd(rows: ExportLedgerRow[], categories: LedgerCategory[]) {
+function sumUsd(rows: QuarterExportLedgerRow[], categories: LedgerCategory[]) {
return rows.reduce((total, row) => {
if (!row.category || !categories.includes(row.category)) {
return total;
@@ -112,7 +112,7 @@ function sumUsd(rows: ExportLedgerRow[], categories: LedgerCategory[]) {
}, 0);
}
-function getQuarterRaidRows(ledgerRows: ExportLedgerRow[]) {
+function getQuarterRaidRows(ledgerRows: QuarterExportLedgerRow[]) {
const rows = new Map();
for (const ledgerRow of ledgerRows) {
@@ -158,7 +158,7 @@ function getQuarterRaidRows(ledgerRows: ExportLedgerRow[]) {
});
}
-function buildLedgerRows({ quarter }: { quarter: QuarterSummary }) {
+export function buildQuarterLedgerRows({ quarter }: { quarter: QuarterSummary }) {
return Promise.all([
listClassificationOptions(),
listTreasuryTransferClassifications({ quarter, status: "all" }),
@@ -171,7 +171,7 @@ function buildLedgerRows({ quarter }: { quarter: QuarterSummary }) {
options.raids.map((raid) => [raid.id, `${raid.name} (${raid.clientName})`]),
);
const ripsById = new Map(options.rips.map((rip) => [rip.id, rip.title]));
- const rows: ExportLedgerRow[] = [
+ const rows: QuarterExportLedgerRow[] = [
...transfers.map((transfer) => ({
account: transfer.accountName,
assetAmount: transfer.assetAmount,
@@ -231,7 +231,7 @@ export async function buildQuarterXlsxExport(quarter: QuarterSummary) {
const [ledgerRows, membershipReport, proposalActivity, balanceRows] =
await Promise.all([
- buildLedgerRows({ quarter }),
+ buildQuarterLedgerRows({ quarter }),
getMembershipActivityReport({ visibility: "admin" }),
listProposalActivity({ visibility: "admin" }),
listQuarterBalanceRows(quarter.id),
diff --git a/src/lib/quarters.ts b/src/lib/quarters.ts
index 07a7700..c85f4fd 100644
--- a/src/lib/quarters.ts
+++ b/src/lib/quarters.ts
@@ -16,6 +16,10 @@ import {
type QuarterSyncStatus,
type QuarterWorkflowStep,
} from "@/lib/quarter-sync";
+import {
+ getQuarterBalanceValidationMap,
+ type QuarterBalanceValidation,
+} from "@/lib/quarter-balance-validation";
export type QuarterStatus = (typeof quarterStatusEnum.enumValues)[number];
@@ -52,6 +56,7 @@ export type QuarterReportingPeriod = QuarterSummary & {
classificationSummary: QuarterClassificationSummary;
history: QuarterHistoryEvent[];
syncStatus: QuarterSyncStatus | null;
+ balanceValidation: QuarterBalanceValidation | null;
workflowSteps: QuarterWorkflowStep[];
};
@@ -250,9 +255,13 @@ export async function listQuarterReportingPeriods(): Promise<
const syncStatusByQuarter = await getQuarterSyncStatusMap(
quarterRows.map((quarter) => quarter.id),
);
+ const validationByQuarter = await getQuarterBalanceValidationMap(
+ quarterRows.map((quarter) => quarter.id),
+ );
return quarterRows.map((quarter, index) => ({
...quarter,
+ balanceValidation: validationByQuarter.get(quarter.id) ?? null,
classificationSummary: summaries[index],
history: historyByQuarter.get(quarter.id) ?? [],
syncStatus: syncStatusByQuarter.get(quarter.id) ?? null,
@@ -260,6 +269,7 @@ export async function listQuarterReportingPeriods(): Promise<
classificationSummary: summaries[index],
quarter,
syncStatus: syncStatusByQuarter.get(quarter.id) ?? null,
+ validation: validationByQuarter.get(quarter.id) ?? null,
}),
}));
}
diff --git a/src/lib/treasury/balances.ts b/src/lib/treasury/balances.ts
index 97d2941..b358686 100644
--- a/src/lib/treasury/balances.ts
+++ b/src/lib/treasury/balances.ts
@@ -182,10 +182,12 @@ async function getTrackedAccountSources(): Promise<
function createEmptyAssetBalance(
asset: TrackedTreasuryAsset,
+ chainId: number,
): TreasuryAssetBalance {
return {
symbol: asset.symbol,
name: asset.name,
+ chainIds: [chainId],
rawAmount: "0",
balance: "0.00",
usdValue: "0.00",
@@ -213,7 +215,9 @@ function createEmptyAccountBalance(
address: account.address,
chainId: account.chainId,
totalUsd: "0.00",
- assets: trackedAssets.map(createEmptyAssetBalance),
+ assets: trackedAssets.map((asset) =>
+ createEmptyAssetBalance(asset, account.chainId),
+ ),
};
}
@@ -354,10 +358,14 @@ function aggregateAssets(
? matchingAssets.find((matchingAsset) => toNumber(matchingAsset.usdPrice))
?.usdPrice
: formatPrice(usdValue / toNumber(balance));
+ const chainIds = [
+ ...new Set(matchingAssets.flatMap((matchingAsset) => matchingAsset.chainIds)),
+ ].sort((left, right) => left - right);
return {
symbol: asset.symbol,
name: asset.name,
+ chainIds,
rawAmount: rawTotal.toString(),
balance,
usdValue: formatUsd(usdValue),
@@ -369,10 +377,14 @@ function aggregateAssets(
return sortAssetsByUsdValue(aggregatedAssets);
}
-function mapCachedAsset(asset: typeof treasuryBalanceAssets.$inferSelect) {
+function mapCachedAsset(
+ asset: typeof treasuryBalanceAssets.$inferSelect,
+ chainId: number,
+) {
return {
symbol: asset.symbol as TreasuryAssetSymbol,
name: asset.name,
+ chainIds: [chainId],
rawAmount: asset.rawAmount,
balance: asset.balance,
usdValue: asset.usdValue,
@@ -422,10 +434,12 @@ async function getLatestCachedAccountSnapshot(
.from(treasuryBalanceAssets)
.where(eq(treasuryBalanceAssets.snapshotId, snapshot.id));
const assetMap = new Map(
- assets.map((asset) => [asset.symbol, mapCachedAsset(asset)]),
+ assets.map((asset) => [asset.symbol, mapCachedAsset(asset, account.chainId)]),
);
const orderedAssets = getTrackedAssetsForAccount(account).map(
- (asset) => assetMap.get(asset.symbol) ?? createEmptyAssetBalance(asset),
+ (asset) =>
+ assetMap.get(asset.symbol) ??
+ createEmptyAssetBalance(asset, account.chainId),
);
const isFailed = snapshot.status === "failed";
const isStale = isFailed || isSyncedAtStale(snapshot.syncedAt);
@@ -492,11 +506,13 @@ async function getCoinGeckoUsdPrices(coinIds: string[]) {
async function fetchLiveAssetBalances({
address,
+ chainId,
client,
trackedAssets,
pricePromise,
}: {
address: Address;
+ chainId: number;
client: ReturnType;
trackedAssets: TrackedTreasuryAsset[];
pricePromise: Promise>;
@@ -550,6 +566,7 @@ async function fetchLiveAssetBalances({
return {
symbol: asset.symbol,
name: asset.name,
+ chainIds: [chainId],
rawAmount: rawAmount.toString(),
balance,
usdValue: formatUsd(usdValue),
@@ -576,6 +593,7 @@ async function syncAccountBalanceSnapshot({
const trackedAssets = getTrackedAssetsForAccount(account);
const { assets, priceError } = await fetchLiveAssetBalances({
address: account.address,
+ chainId: account.chainId,
client,
trackedAssets,
pricePromise,
diff --git a/src/lib/treasury/types.ts b/src/lib/treasury/types.ts
index 700f890..2e0341e 100644
--- a/src/lib/treasury/types.ts
+++ b/src/lib/treasury/types.ts
@@ -17,6 +17,7 @@ export type TreasurySnapshotStatus =
export type TreasuryAssetBalance = {
symbol: TreasuryAssetSymbol;
name: string;
+ chainIds: number[];
rawAmount: string;
balance: string;
usdValue: string;