Package com.privatechain.storage

Class ChainExporter

java.lang.Object
com.privatechain.storage.ChainExporter
public final class ChainExporter extends Object
Utility class for exporting and importing a full blockchain in JSON and CSV formats.

Provides three static operations that satisfy FR-SER-02 and FR-SER-03:

  • toJson(Blockchain) — serializes all blocks to a JSON array string using the shared BlockSerializer.MAPPER instance, preserving full Jackson polymorphism for Transaction subtypes (@JsonTypeInfo).
  • fromJson(String, BlockchainStorage) — deserializes a JSON array produced by toJson and persists each block to the supplied storage backend after hash-integrity verification (NFR-SEC-03). Intended for administrative chain import and fast node bootstrap without network sync.
  • toCsv(Blockchain) — flattens the chain to one RFC-4180 CSV row per transaction across all blocks, suitable for audit exports and analytics pipelines.

This class is placed in blockchain-storage rather than blockchain-core because it depends on BlockSerializer.MAPPER — a Jackson ObjectMapper that is already a mandatory (non-optional) dependency of the storage module. Placing it here keeps blockchain-core free of mandatory Jackson transitive dependencies (design.md §7.1).

Thread safety

All methods are stateless and thread-safe. The underlying BlockSerializer.MAPPER is thread-safe once configured.

Usage


 // Export
 String json = ChainExporter.toJson(node.getChain());
 String csv  = ChainExporter.toCsv(node.getChain());

 // Import into a fresh storage backend
 InMemoryStorage fresh = new InMemoryStorage();
 ChainExporter.fromJson(json, fresh);
Since:
1.0.0
See Also:

  • Method Details

    • toJson

      public static String toJson(Blockchain chain)
      Serializes the entire blockchain to a compact JSON array string (FR-SER-02).

      Each element of the array is the canonical JSON representation of one Block, produced using the same BlockSerializer.MAPPER shared by all persistent storage implementations. The resulting string can be restored via fromJson(String, BlockchainStorage).

      Transaction polymorphism is fully preserved: each transaction object carries its concrete class name in the _type field (Jackson @JsonTypeInfo), so all subtype-specific fields survive the round-trip without registration (AC-09).

      Parameters:
      chain - the blockchain to export (non-null)
      Returns:
      compact JSON array string; never null or blank
      Throws:
      NullPointerException - if chain is null
      BlockchainException - if Jackson serialization fails

    • fromJson

      public static void fromJson(String json, BlockchainStorage storage)
      Deserializes a JSON array produced by toJson(com.privatechain.core.builder.Blockchain) and persists each block to the supplied storage backend (FR-SER-02).

      Each deserialized block is hash-verified via Block.isHashValid() before being saved to the storage. A hash mismatch causes a BlockValidationException and aborts the import immediately, leaving already-saved blocks in the storage. Callers that require transactional semantics should pass an empty storage and call BlockchainStorage.deleteAll() on failure.

      Note: This method bypasses ConsensusEngine validation intentionally. Chain import is an administrative / bootstrap operation and must only be used with trusted chain dumps. Normal block acceptance must go through Blockchain.addBlock(), which enforces consensus rules.

      Parameters:
      json - a JSON array string produced by toJson(com.privatechain.core.builder.Blockchain) (non-null, non-blank)
      storage - the backend to write the imported blocks into (non-null)
      Throws:
      NullPointerException - if json or storage is null
      IllegalArgumentException - if json is blank
      BlockValidationException - if any block fails hash-integrity verification
      BlockchainException - if JSON parsing fails

    • toCsv

      public static String toCsv(Blockchain chain)
      Exports the blockchain as a flat RFC-4180 CSV string for audit and analytics use (FR-SER-03).

      The output contains one row per transaction across all blocks. The first row is always the header. If the chain contains no transactions at all, only the header row is returned. String fields that contain a comma (,) are automatically wrapped in double-quotes per RFC-4180 §2.6.

      Columns:

      1. blockIndex — zero-based block position in the chain
      2. blockHash — full hex SHA-256 hash of the block
      3. txId — transaction UUID
      4. senderAddress — sender's blockchain address
      5. receiverAddress — receiver's blockchain address
      6. amount — token amount (BigDecimal.toPlainString())
      7. timestamp — ISO-8601 UTC timestamp of the transaction
      8. txType — simple class name of the concrete Transaction subtype
      Parameters:
      chain - the blockchain to export (non-null)
      Returns:
      RFC-4180 CSV string with a header row; never null; never empty (always has header)
      Throws:
      NullPointerException - if chain is null