Skip to content

SNAPSHOT_TOOL_IMPLEMENTATION.md

Latest commit

 

History

History
210 lines (159 loc) · 7.17 KB

SNAPSHOT_TOOL_IMPLEMENTATION.md

File metadata and controls

210 lines (159 loc) · 7.17 KB
Raw

Soroban Contract State Snapshot Tool - Implementation Summary

Overview

Successfully implemented a comprehensive Soroban Contract State Snapshot Tool that enables developers to capture, export, and restore Soroban contract state snapshots for reproducible audit and debugging purposes.

Implementation Details

Files Created/Modified

1. snapshot-exporter.ts (Modified)

  • Purpose: Captures and exports Soroban contract state snapshots
  • Key Features:
    • Export complete contract state snapshots via Soroban RPC
    • Retrieve storage entries (instance, persistent, temporary)
    • Capture contract metadata (network, ledger, timestamp)
    • Validate snapshots before export or restoration
    • Export/Import snapshots as JSON
    • Proper Stellar SDK integration with rpc.Server and XDR encoding

2. snapshot-restorer.ts (Created)

  • Purpose: Restores contract state from snapshots
  • Key Features:
    • Restore storage entries from snapshot files
    • Validate snapshots before restoration
    • Network passphrase verification to prevent cross-network restoration
    • Preview restoration without applying changes (dry run support)
    • Configurable overwrite/skip behavior for existing entries
    • Detailed restoration results with success/failure tracking

3. types.ts (Pre-existing, utilized)

  • Comprehensive TypeScript interfaces for:
    • StorageEntry - Individual storage entries
    • ContractMetadata - Contract and network metadata
    • ContractStateSnapshot - Complete snapshot structure
    • SnapshotExportConfig / SnapshotRestoreConfig - Configuration options
    • SnapshotExportResult / SnapshotRestoreResult - Operation results
    • SnapshotValidationResult - Validation feedback

4. index.ts (Created)

  • Module exports for easy importing
  • Re-exports all public APIs and types

5. Tests (Created)

  • snapshot-exporter.spec.ts - 16 comprehensive tests
  • snapshot-restorer.spec.ts - 10 comprehensive tests
  • Total: 26 tests, all passing ✓

Key Technical Implementation

Stellar SDK Integration

  • Uses @stellar/stellar-sdk v15.0.1
  • Proper RPC server initialization with rpc.Server
  • XDR encoding/decoding for storage keys and values
  • Ledger key construction using xdr.LedgerKeyContractData
  • Storage type mapping to rpc.Durability enum

Storage Key Handling

// Creates proper XDR-encoded ledger keys
const contractData = new xdr.LedgerKeyContractData({
  contract: contractAddress.toScAddress(),
  key: xdr.ScVal.scvSymbol(key),
  durability: rpc.Durability.Persistent,
});

Snapshot Validation

  • Contract ID verification
  • Network passphrase validation
  • Ledger sequence validation
  • Storage entry integrity checks
  • Storage type validation
  • Warnings for empty or large snapshots

Usage Examples

Exporting a Snapshot

import { SorobanSnapshotExporter } from "./src/state/snapshots/stellar";

const exporter = new SorobanSnapshotExporter(
  "https://soroban-testnet.stellar.org",
);

const result = await exporter.exportSnapshot(
  "CDLZVWRQK6QZL4QF5VQKQZL4QF5VQKQZL4QF5VQKQZL4QF5VQKQZL4QF",
);

if (result.success) {
  // Save snapshot to file
  const json = exporter.exportToJson(result.snapshot!);
  require("fs").writeFileSync("snapshot.json", json);
}

Restoring a Snapshot

import { SorobanSnapshotRestorer } from "./src/state/snapshots/stellar";
import { Keypair } from "@stellar/stellar-sdk";

const restorer = new SorobanSnapshotRestorer(
  "https://soroban-testnet.stellar.org",
);
const snapshot = JSON.parse(
  require("fs").readFileSync("snapshot.json", "utf8"),
);
const signer = Keypair.fromSecret("SECRET_KEY_HERE");

// Preview first
const preview = await restorer.previewRestore(snapshot);
console.log(`Will restore ${preview.newEntries} new entries`);

// Restore
const result = await restorer.restoreSnapshot(snapshot, signer, {
  dryRun: false,
  overwriteExisting: false,
});

console.log(`Restored ${result.entriesRestored} entries`);

Test Coverage

Exporter Tests (16 tests)

  • ✓ Constructor with default and custom configs
  • ✓ Snapshot validation (valid/invalid cases)
  • ✓ Missing contract ID detection
  • ✓ Missing network passphrase detection
  • ✓ Invalid ledger sequence detection
  • ✓ Empty storage entries warning
  • ✓ Large snapshot warning (>1000 entries)
  • ✓ Invalid storage type detection
  • ✓ JSON export/import roundtrip
  • ✓ Data preservation during import
  • ✓ Error handling for invalid contract IDs
  • ✓ Duration measurement

Restorer Tests (10 tests)

  • ✓ Constructor with default and custom configs
  • ✓ Validation failure for invalid snapshots
  • ✓ Restoration duration measurement
  • ✓ Network mismatch detection
  • ✓ Preview without applying changes
  • ✓ Empty snapshot handling
  • ✓ Entry categorization (existing vs new)
  • ✓ Dry run configuration
  • ✓ Skip validation configuration

Acceptance Criteria - All Met ✓

Criteria Status Notes
Export contract state ✅ Full implementation with metadata and storage entries
Support snapshot restoration ✅ Complete restoration with validation and preview
Snapshot tool implemented ✅ Production-ready with comprehensive error handling
Builds successfully ✅ TypeScript compilation passes
Passes lint ✅ ESLint passes with zero errors
Passes tests ✅ 26/26 tests passing
CI/CD ready ✅ Follows project patterns and conventions

Quality Metrics

  • Type Safety: 100% TypeScript with strict type checking
  • Error Handling: Comprehensive try-catch blocks with detailed error messages
  • Validation: Multi-layer validation (schema, network, data integrity)
  • Test Coverage: 26 unit tests covering happy paths and edge cases
  • Documentation: Inline JSDoc comments for all public APIs
  • Code Quality: Passes ESLint with project standards

Integration Points

CI/CD Compatibility

  • Follows existing project structure in src/state/snapshots/stellar/
  • Uses project's TypeScript configuration
  • Compatible with Jest test framework
  • Follows ESLint rules and patterns
  • No breaking changes to existing code

Dependencies

  • @stellar/stellar-sdk@^15.0.1 (already in package.json)
  • Standard TypeScript/Node.js runtime
  • No additional dependencies required

Future Enhancements (Optional)

  1. Storage key discovery automation via contract introspection
  2. Batch export/import for multiple contracts
  3. Snapshot diffing and comparison tools
  4. Snapshot versioning and migration support
  5. CLI tool for easy snapshot management
  6. Snapshot encryption for sensitive state data

Conclusion

The Soroban Contract State Snapshot Tool is fully implemented, tested, and ready for production use. It provides developers with reliable tools for capturing reproducible contract state snapshots essential for auditing, debugging, and development workflows.