Skip to main content

Pricing Snapshots & Integrity

To ensure quotations remain audit-safe, Kloyst uses an immutable snapshot system. A snapshot captures all rates, regions, fees, and rules used to calculate a quotation at the moment of estimation.

🔒 Immutable Snapshots​

Quotations are locked to a specific PricingSnapshot to guarantee that cost estimates do not change when underlying pricing tables are updated:

       Campaign Estimation
                │
                ▼
  [ pricing-rates  -  pricing-regions ]  <-- Freeze rates, regions,
  [ platform-fees  -  pricing-tiers   ]      and discount configurations
                │
                ▼
    Compile to JSON Payload
                │
                ▼
  Compute Deterministic Checksum  <-- SHA256 Signature
                │
                ▼
     PricingSnapshot Saved
                │
                ▼
  Quotation Linked via snapshotId  <-- Immutable link

🛠️ Schema Configuration​

model PricingSnapshot {
  id                      String   @id @default(uuid()) @db.Uuid
  estimationEngineVersion String   @default("1.0.0") @db.VarChar(20)
  rates                   Json     // Mapped array of PricingRates
  regions                 Json     // Mapped array of PricingRegions
  feeRules                Json     // Mapped array of PlatformFeeRules
  tiers                   Json     // Mapped array of PricingTiers
  assumptions             Json     // Exchange rates, engine configs
  checksum                String   @db.VarChar(64)
  createdAt               DateTime @default(now())

  quotations Quotation[]
}

🛡️ SHA256 Integrity Verification​

To prevent unauthorized tampering with JSON fields in the database, the snapshot includes a SHA256 cryptographic signature.

Signature Generation Algorithm​

import * as crypto from 'crypto';

const payload = {
  estimationEngineVersion: '1.0.0',
  rates,
  regions,
  feeRules,
  tiers,
  assumptions,
};

// Sort JSON keys alphabetically for deterministic output
const sorted = JSON.stringify(payload, Object.keys(payload).sort());

// Compute SHA256 signature
const checksum = crypto.createHash('sha256').update(sorted).digest('hex');

🔍 Reproducibility Auditing​

If a vendor queries an older quotation:

  • The engine loads the quotation's associated snapshotId.
  • The engine reconstructs the calculation using only the frozen rates and rules from the snapshot.
  • Re-running calculations from the snapshot guarantees cost reproducibility and ensures audit compliance.