@twin.org/synchronised-storage-service 0.0.1-next.3 → 0.0.1-next.4

package/dist/types/entities/syncSnapshotEntry.d.ts

@@ -1,5 +1,4 @@
-import type { ISynchronisedEntity } from "@twin.org/synchronised-storage-models";
-import type { ISyncChange } from "../models/ISyncChange";
+import type { ISyncChange, ISynchronisedEntity } from "@twin.org/synchronised-storage-models";
 /**
  * Class representing an entry for the sync snapshot.
  */

package/dist/types/helpers/blobStorageHelper.d.ts

@@ -0,0 +1,33 @@
+import type { IBlobStorageConnector } from "@twin.org/blob-storage-models";
+import type { ILoggingConnector } from "@twin.org/logging-models";
+import { type IVaultConnector } from "@twin.org/vault-models";
+/**
+ * Class for performing blob storage operations.
+ */
+export declare class BlobStorageHelper {
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of BlobStorageHelper.
+     * @param logging The logging connector to use for logging.
+     * @param vaultConnector The vault connector to use for for the encryption key.
+     * @param blobStorageConnector The blob storage component to use.
+     * @param blobStorageEncryptionKeyId The id of the vault key to use for encrypting/decrypting blobs.
+     * @param isTrustedNode Is this a trusted node.
+     */
+    constructor(logging: ILoggingConnector | undefined, vaultConnector: IVaultConnector, blobStorageConnector: IBlobStorageConnector, blobStorageEncryptionKeyId: string, isTrustedNode: boolean);
+    /**
+     * Load a blob from storage.
+     * @param blobId The id of the blob to apply.
+     * @returns The blob.
+     */
+    load<T>(blobId: string): Promise<T | undefined>;
+    /**
+     * Save a blob.
+     * @param blob The blob to save.
+     * @returns The id of the blob.
+     */
+    saveBlob<T>(blob: T): Promise<string>;
+}

package/dist/types/helpers/changeSetHelper.d.ts

@@ -1,10 +1,9 @@
-import { type IBlobStorageComponent } from "@twin.org/blob-storage-models";
 import type { IEventBusComponent } from "@twin.org/event-bus-models";
 import { type IIdentityConnector } from "@twin.org/identity-models";
 import type { ILoggingConnector } from "@twin.org/logging-models";
 import { type IProof } from "@twin.org/standards-w3c-did";
-import { type ISynchronisedEntity } from "@twin.org/synchronised-storage-models";
-import type { ISyncChangeSet } from "../models/ISyncChangeSet";
+import { type ISyncChangeSet, type ISynchronisedEntity } from "@twin.org/synchronised-storage-models";
+import type { BlobStorageHelper } from "./blobStorageHelper";
 /**
  * Class for performing change set operations.
  */
@@ -17,11 +16,16 @@ export declare class ChangeSetHelper<T extends ISynchronisedEntity = ISynchronis
      * Create a new instance of ChangeSetHelper.
      * @param logging The logging connector to use for logging.
      * @param eventBusComponent The event bus component to use for events.
-     * @param blobStorageComponent The blob storage component to use for remote sync states.
      * @param identityConnector The identity connector to use for signing/verifying changesets.
+     * @param blobStorageHelper The blob storage component to use for remote sync states.
      * @param decentralisedStorageMethodId The id of the identity method to use when signing/verifying changesets.
      */
-    constructor(logging: ILoggingConnector | undefined, eventBusComponent: IEventBusComponent, blobStorageComponent: IBlobStorageComponent, identityConnector: IIdentityConnector, decentralisedStorageMethodId: string);
+    constructor(logging: ILoggingConnector | undefined, eventBusComponent: IEventBusComponent, identityConnector: IIdentityConnector, blobStorageHelper: BlobStorageHelper, decentralisedStorageMethodId: string);
+    /**
+     * Set the node identity to use for signing changesets.
+     * @param nodeIdentity The identity of the node that is performing the update.
+     */
+    setNodeIdentity(nodeIdentity: string): void;
     /**
      * Get and verify a changeset.
      * @param changeSetStorageId The id of the sync changeset to apply.
@@ -43,10 +47,9 @@ export declare class ChangeSetHelper<T extends ISynchronisedEntity = ISynchronis
     /**
      * Store the changeset.
      * @param syncChangeSet The sync change set to store.
-     * @param nodeIdentity The node identity to use for the changeset.
      * @returns The id of the change set.
      */
-    storeChangeSet(syncChangeSet: ISyncChangeSet, nodeIdentity: string): Promise<string>;
+    storeChangeSet(syncChangeSet: ISyncChangeSet): Promise<string>;
     /**
      * Verify the proof of a sync changeset.
      * @param syncChangeset The sync changeset to verify.
@@ -59,4 +62,13 @@ export declare class ChangeSetHelper<T extends ISynchronisedEntity = ISynchronis
      * @returns The proof.
      */
     createChangeSetProof(syncChangeset: ISyncChangeSet): Promise<IProof>;
+    /**
+     * Copy a change set.
+     * @param syncChangeSet The sync changeset to copy.
+     * @returns The id of the updated change set.
+     */
+    copyChangeset(syncChangeSet: ISyncChangeSet<T>): Promise<{
+        syncChangeSet: ISyncChangeSet<T>;
+        changeSetStorageId: string;
+    } | undefined>;
 }

package/dist/types/helpers/localSyncStateHelper.d.ts

@@ -15,10 +15,10 @@ export declare class LocalSyncStateHelper<T extends ISynchronisedEntity = ISynch
     /**
      * Create a new instance of LocalSyncStateHelper.
      * @param logging The logging connector to use for logging.
-     * @param localSyncSnapshotEntryEntityStorage The storage connector for the local sync snapshot entries.
+     * @param snapshotEntryEntityStorage The storage connector for the sync snapshot entries.
      * @param changeSetHelper The change set helper to use for applying changesets.
      */
-    constructor(logging: ILoggingConnector | undefined, localSyncSnapshotEntryEntityStorage: IEntityStorageConnector<SyncSnapshotEntry<T>>, changeSetHelper: ChangeSetHelper<T>);
+    constructor(logging: ILoggingConnector | undefined, snapshotEntryEntityStorage: IEntityStorageConnector<SyncSnapshotEntry<T>>, changeSetHelper: ChangeSetHelper<T>);
     /**
      * Add a new change to the local snapshot.
      * @param storageKey The storage key of the snapshot to add the change for.
@@ -28,43 +28,28 @@ export declare class LocalSyncStateHelper<T extends ISynchronisedEntity = ISynch
      */
     addLocalChange(storageKey: string, operation: SyncChangeOperation, id: string): Promise<void>;
     /**
-     * Get the current local snapshot.
+     * Get the current local snapshot which contains just the changes for this node.
      * @param storageKey The storage key of the snapshot to get.
      * @returns The local snapshot entry.
      */
     getLocalChangeSnapshot(storageKey: string): Promise<SyncSnapshotEntry<T>>;
     /**
-     * Set the current local snapshot.
+     * Set the current local snapshot with changes for this node.
      * @param localChangeSnapshot The local change snapshot to set.
      * @returns Nothing.
      */
     setLocalChangeSnapshot(localChangeSnapshot: SyncSnapshotEntry<T>): Promise<void>;
     /**
-     * Get the current local snapshot.
+     * Get the current local snapshot with the changes for this node.
      * @param localChangeSnapshot The local change snapshot to remove.
      * @returns Nothing.
      */
     removeLocalChangeSnapshot(localChangeSnapshot: SyncSnapshotEntry<T>): Promise<void>;
     /**
-     * Sync local data using a remote sync state.
+     * Apply a sync state to the local node.
      * @param storageKey The storage key of the snapshot to sync with.
-     * @param remoteSyncState The sync state to sync with.
+     * @param syncState The sync state to sync with.
      * @returns Nothing.
      */
-    syncFromRemote(storageKey: string, remoteSyncState: ISyncState): Promise<void>;
-    /**
-     * Process the modified snapshots and store them in the local storage.
-     * @param modifiedSnapshots The modified snapshots to process.
-     * @returns Nothing.
-     */
-    processModifiedSnapshots(modifiedSnapshots: {
-        localSnapshot: SyncSnapshotEntry<T>;
-        remoteSnapshot: SyncSnapshotEntry<T>;
-    }[]): Promise<void>;
-    /**
-     * Process the new snapshots and store them in the local storage.
-     * @param newSnapshots The new snapshots to process.
-     * @returns Nothing.
-     */
-    private processNewSnapshots;
+    applySyncState(storageKey: string, syncState: ISyncState): Promise<void>;
 }

package/dist/types/helpers/remoteSyncStateHelper.d.ts

@@ -1,10 +1,9 @@
-import { type IBlobStorageComponent } from "@twin.org/blob-storage-models";
 import type { IEventBusComponent } from "@twin.org/event-bus-models";
 import type { ILoggingConnector } from "@twin.org/logging-models";
-import { type ISynchronisedEntity } from "@twin.org/synchronised-storage-models";
+import { type ISyncChange, type ISyncChangeSet, type ISynchronisedEntity } from "@twin.org/synchronised-storage-models";
 import type { IVerifiableStorageConnector } from "@twin.org/verifiable-storage-models";
+import type { BlobStorageHelper } from "./blobStorageHelper";
 import type { ChangeSetHelper } from "./changeSetHelper";
-import type { ISyncChange } from "../models/ISyncChange";
 import type { ISyncPointerStore } from "../models/ISyncPointerStore";
 import type { ISyncState } from "../models/ISyncState";
 /**
@@ -19,32 +18,37 @@ export declare class RemoteSyncStateHelper<T extends ISynchronisedEntity = ISync
      * Create a new instance of DecentralisedEntityStorageConnector.
      * @param logging The logging connector to use for logging.
      * @param eventBusComponent The event bus component to use for events.
-     * @param blobStorageComponent The blob storage component to use for remote sync states.
      * @param verifiableSyncPointerStorageConnector The verifiable storage connector to use for storing sync pointers.
+     * @param blobStorageHelper The blob storage helper to use for remote sync states.
      * @param changeSetHelper The change set helper to use for managing changesets.
-     * @param synchronisedStorageKey The synchronised storage key to use for verified storage operations.
+     * @param isTrustedNode Whether the node is trusted or not.
      */
-    constructor(logging: ILoggingConnector | undefined, eventBusComponent: IEventBusComponent, blobStorageComponent: IBlobStorageComponent, verifiableSyncPointerStorageConnector: IVerifiableStorageConnector, changeSetHelper: ChangeSetHelper<T>, synchronisedStorageKey: string);
+    constructor(logging: ILoggingConnector | undefined, eventBusComponent: IEventBusComponent, verifiableSyncPointerStorageConnector: IVerifiableStorageConnector, blobStorageHelper: BlobStorageHelper, changeSetHelper: ChangeSetHelper<T>, isTrustedNode: boolean);
     /**
      * Set the node identity to use for signing changesets.
      * @param nodeIdentity The identity of the node that is performing the update.
      */
     setNodeIdentity(nodeIdentity: string): void;
     /**
-     * Create and store a change set.
+     * Set the synchronised storage key.
+     * @param synchronisedStorageKey The synchronised storage key to use.
+     */
+    setSynchronisedStorageKey(synchronisedStorageKey: string): void;
+    /**
+     * Build a changeset.
      * @param storageKey The storage key of the change set.
      * @param changes The changes to apply.
      * @param completeCallback The callback to call when the changeset is created and stored.
      * @returns The storage id of the change set if created.
      */
-    createAndStoreChangeSet(storageKey: string, changes: ISyncChange<T>[], completeCallback: (id?: string) => Promise<void>): Promise<void>;
+    buildChangeSet(storageKey: string, changes: ISyncChange<T>[], completeCallback: (syncChangeSet?: ISyncChangeSet<T>, id?: string) => Promise<void>): Promise<void>;
     /**
      * Finalise the full details for the sync change set.
      * @param storageKey The storage key of the change set.
      * @param completeCallback The callback to call when the changeset is populated.
      * @returns Nothing.
      */
-    finaliseFullChanges(storageKey: string, completeCallback: (id?: string) => Promise<void>): Promise<void>;
+    finaliseFullChanges(storageKey: string, completeCallback: (syncChangeSet?: ISyncChangeSet<T>, id?: string) => Promise<void>): Promise<void>;
     /**
      * Add a new changeset into the sync state.
      * @param storageKey The storage key of the change set to add.
@@ -58,7 +62,7 @@ export declare class RemoteSyncStateHelper<T extends ISynchronisedEntity = ISync
      * @param batchSize The batch size to use for consolidation.
      * @returns Nothing.
      */
-    consolidateFromLocal(storageKey: string, batchSize: number): Promise<void>;
+    consolidationStart(storageKey: string, batchSize: number): Promise<void>;
     /**
      * Get the sync pointer store.
      * @returns The sync pointer store.
@@ -83,7 +87,7 @@ export declare class RemoteSyncStateHelper<T extends ISynchronisedEntity = ISync
      */
     getRemoteSyncState(syncPointerId: string): Promise<ISyncState | undefined>;
     /**
-     * Handle the batch response.
+     * Handle the batch response which is triggered from a consolidation request.
      * @param response The batch response to handle.
      */
     private handleBatchResponse;

package/dist/types/helpers/versions.d.ts

@@ -0,0 +1,3 @@
+export declare const SYNC_STATE_VERSION: string;
+export declare const SYNC_POINTER_STORE_VERSION: string;
+export declare const SYNC_SNAPSHOT_VERSION: string;

package/dist/types/index.d.ts

@@ -1,6 +1,4 @@
 export * from "./entities/syncSnapshotEntry";
-export * from "./models/ISyncChange";
-export * from "./models/ISyncChangeSet";
 export * from "./models/ISynchronisedStorageServiceConfig";
 export * from "./models/ISynchronisedStorageServiceConstructorOptions";
 export * from "./models/ISyncPointerStore";

package/dist/types/models/ISyncPointerStore.d.ts

@@ -2,6 +2,10 @@
  * The object definition for the sync pointer store.
  */
 export interface ISyncPointerStore {
+    /**
+     * The version of the sync pointer store.
+     */
+    version: string;
     /**
      * The mapping from storage keys to sync pointers.
      */

package/dist/types/models/ISyncSnapshot.d.ts

@@ -2,6 +2,10 @@
  * The object definition for a sync snapshot.
  */
 export interface ISyncSnapshot {
+    /**
+     * The version of the sync state.
+     */
+    version: string;
     /**
      * The id of the snapshot.
      */
@@ -13,7 +17,7 @@ export interface ISyncSnapshot {
     /**
      * The date the snapshot was last modified.
      */
-    dateModified?: string;
+    dateModified: string;
     /**
      * The ids of the storage for the change sets in the snapshot.
      */

package/dist/types/models/ISyncState.d.ts

@@ -3,6 +3,10 @@ import type { ISyncSnapshot } from "./ISyncSnapshot";
  * The object definition for a sync state.
  */
 export interface ISyncState {
+    /**
+     * The version of the sync state.
+     */
+    version: string;
     /**
      * The snapshots.
      */

package/dist/types/models/ISynchronisedStorageServiceConfig.d.ts

@@ -3,12 +3,7 @@
  */
 export interface ISynchronisedStorageServiceConfig {
     /**
-     * The key to use for the remote synchronised storage, the initial item will have been
-     * generated by a trusted node.
-     */
-    synchronisedStorageKey: string;
-    /**
-     * The id of the identity method to use when signing/verifying changesets.
+     * The id of the identity method to use when signing/verifying requests and changesets.
      * @default synchronised-storage-assertion
      */
     synchronisedStorageMethodId?: string;
@@ -32,4 +27,15 @@ export interface ISynchronisedStorageServiceConfig {
      * @default 1000
      */
     consolidationBatchSize?: number;
+    /**
+     * The encryption key id from the vault to use for blob storage, only required for trusted nodes, untrusted nodes will request the key.
+     * @default synchronised-storage-blob-encryption-key
+     */
+    blobStorageEncryptionKeyId?: string;
+    /**
+     * The verifiable storage key to use, already expected to be created.
+     * if the key is not found in the keys.json it is considered to be a custom verifiable storage id.
+     * @default local
+     */
+    verifiableStorageKeyId: "mainnet" | "testnet" | "devnet" | string;
 }

package/dist/types/models/ISynchronisedStorageServiceConstructorOptions.d.ts

@@ -11,16 +11,20 @@ export interface ISynchronisedStorageServiceConstructorOptions {
      * The event bus component type.
      */
     eventBusComponentType?: string;
+    /**
+     * The vault connector type.
+     */
+    vaultConnectorType?: string;
     /**
      * The entity storage connector type to use for sync snapshots.
      * @default sync-snapshot-entry
      */
     syncSnapshotStorageConnectorType?: string;
     /**
-     * The blob storage component used for remote sync state.
+     * The blob storage connector used for remote sync state.
      * @default blob-storage
      */
-    blobStorageComponentType?: string;
+    blobStorageConnectorType?: string;
     /**
      * The verifiable storage connector type to use for decentralised state.
      * @default verifiable-storage

package/dist/types/synchronisedStorageRoutes.d.ts

@@ -1,5 +1,5 @@
 import type { IHttpRequestContext, INoContentResponse, IRestRoute, ITag } from "@twin.org/api-models";
-import type { ISyncChangeSetRequest } from "@twin.org/synchronised-storage-models";
+import type { ISyncChangeSetRequest, ISyncDecryptionKeyRequest, ISyncDecryptionKeyResponse } from "@twin.org/synchronised-storage-models";
 /**
  * The tag to associate with the routes.
  */
@@ -19,3 +19,11 @@ export declare function generateRestRoutesSynchronisedStorage(baseRouteName: str
  * @returns The response object with additional http response properties.
  */
 export declare function synchronisedStorageSyncChangeSetRequest(httpRequestContext: IHttpRequestContext, componentName: string, request: ISyncChangeSetRequest): Promise<INoContentResponse>;
+/**
+ * Request the decryption key.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function synchronisedStorageGetDecryptionKeyRequest(httpRequestContext: IHttpRequestContext, componentName: string, request: ISyncDecryptionKeyRequest): Promise<ISyncDecryptionKeyResponse>;

package/dist/types/synchronisedStorageService.d.ts

@@ -1,4 +1,5 @@
-import { type ISynchronisedEntity, type ISynchronisedStorageComponent } from "@twin.org/synchronised-storage-models";
+import { type IProof } from "@twin.org/standards-w3c-did";
+import { type ISyncChangeSet, type ISynchronisedEntity, type ISynchronisedStorageComponent } from "@twin.org/synchronised-storage-models";
 import type { ISynchronisedStorageServiceConstructorOptions } from "./models/ISynchronisedStorageServiceConstructorOptions";
 /**
  * Class for performing synchronised storage operations.
@@ -34,9 +35,17 @@ export declare class SynchronisedStorageService<T extends ISynchronisedEntity =
         [id: string]: unknown;
     }): Promise<void>;
     /**
-     * Synchronise a complete set of changes, assumes this is a trusted node.
-     * @param changeSetStorageId The id of the change set to synchronise in blob storage.
+     * Get the decryption key for the synchronised storage.
+     * This is used to decrypt the data stored in the synchronised storage.
+     * @param nodeIdentity The identity of the node requesting the decryption key.
+     * @param proof The proof of the request so we know the request is from the specified node.
+     * @returns The decryption key.
+     */
+    getDecryptionKey(nodeIdentity: string, proof: IProof): Promise<string>;
+    /**
+     * Synchronise a set of changes from an untrusted node, assumes this is a trusted node.
+     * @param syncChangeSet The change set to synchronise.
      * @returns Nothing.
      */
-    syncChangeSet(changeSetStorageId: string): Promise<void>;
+    syncChangeSet(syncChangeSet: ISyncChangeSet<T>): Promise<void>;
 }

package/docs/architecture.md

@@ -0,0 +1,125 @@
+# Synchronised Storage Service Architecture
+
+## Overview
+
+The Synchronised Storage Service implements a distributed, eventually-consistent data replication system built on a decentralised architecture. The system provides conflict-free, cryptographically-verifiable synchronisation of entity storage mutations across a network of heterogeneous nodes through a combination of trusted node coordination and decentralised storage protocols.
+
+## Core Architecture
+
+### System Components
+
+#### 1. Entity Storage Layer
+
+- **Purpose**: Persistent data layer storing application entities
+- **Interface**: CRUD operations with change event emission via event bus
+- **Implementation**: Pluggable storage connectors (Memory, File System, Database)
+- **Change Detection**: Mutation observers capture CREATE, UPDATE, DELETE operations
+- **Event Emission**: Publishes change notifications to event bus for downstream processing
+
+#### 2. Change Capture Subsystem
+
+- **Event Bus Integration**: Subscribes to entity storage change events via decoupled event bus architecture
+- **Change Sets**: Immutable collections of related entity mutations aggregated from event notifications
+- **Serialisation**: Compressed binary format with cryptographic signatures
+- **Metadata**: Timestamps, node identity, operation vectors
+- **Batching**: Configurable aggregation windows for performance optimisation
+
+#### 3. Cryptographic Verification Layer
+
+- **Digital Signatures**: DID Proofs on change set payloads
+- **Identity Management**: DID-based node authentication
+- **Proof Chains**: Verifiable computation proofs for data integrity
+- **Encryption**: RSA-2048 encryption for sensitive payload data with SPKI keys available to regular nodes, and PKCS and SPKI on the trusted nodes
+
+#### 5. Event Bus Architecture
+
+- **Decoupled Communication**: Asynchronous message passing between entity storage and change capture systems
+- **Topic-Based Routing**: Structured message topics for different operation types (create, update, delete)
+- **Pluggable Connectors**: Support for various event bus implementations (Local, Redis, AMQP, Kafka)
+- **Message Serialisation**: JSON-based message payloads with type-safe schemas
+
+#### 6. Network Topology
+
+```text
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Regular Node  │    │   Regular Node  │    │   Regular Node  │
+│                 │    │                 │    │                 │
+└────────┬────────┘    └────────┬────────┘    └────────┬────────┘
+         │                      │                      │
+         └──────────────────────┼──────────────────────┘
+                                │
+              ┌─────────────────┴─────────────────┐
+              │                                   │
+   ┌──────────▼──────────┐              ┌────────▼────────────┐
+   │   Trusted Node A    │              │   Trusted Node B    │
+   │ • Change Validation │              │ • Change Validation │
+   │ • Load Distribution │              │ • Load Distribution │
+   │ • State Consensus   │◄────────────►│ • State Consensus   │
+   └──────────┬──────────┘              └─────────┬───────────┘
+              │                                   │
+              └─────────────────┬─────────────────┘
+                                │
+                    ┌───────────▼────────────┐
+                    │  Verifiable Storage    │
+                    │   • On-chain Pointers  │
+                    │   • State Root Hashes  │
+                    │   • Access Control     │
+                    └───────────┬────────────┘
+                                │
+                    ┌───────────▼────────────┐
+                    │ Decentralised Storage  │
+                    │   • IPFS/Content Hash  │
+                    │   • Immutable Blobs    │
+                    │   • Distributed Refs   │
+                    └────────────────────────┘
+```
+
+## Node Types & Responsibilities
+
+### Regular Nodes
+
+- **Local Change Monitoring**: Capture entity storage mutations via event bus
+- **Change Set Generation**: Aggregate mutations into signed, compressed payloads
+- **Trusted Node Communication**: Submit change sets for global replication
+- **Sync State Polling**: Periodically query verifiable storage for remote updates
+- **Conflict Resolution**: Apply three-way merge algorithms for concurrent modifications
+- **Resource Constraints**: Minimal storage and computational requirements
+
+### Trusted Nodes
+
+- **Multi-Node Architecture**: Multiple trusted nodes operate in parallel to distribute processing load and provide high availability
+- **Change Validation**: Verify cryptographic signatures and node permissions across the cluster
+- **Change Set Consolidation**: Periodic compaction of historical change logs distributed across trusted node instances
+- **Decentralised Storage Interface**: Upload/download operations to IPFS-like systems with load balancing
+- **Verifiable Storage Updates**: Atomic updates to on-chain state pointers with consensus agreement
+- **Load Distribution**: Automatic distribution of regular node connections and change processing across available trusted nodes
+
+## Data Flow Architecture
+
+### 1. Local Change Detection
+
+```typescript
+EntityStorage → ChangeCapture → LocalSnapshot → EventBus
+```
+
+### 2. Change Set Propagation
+
+```typescript
+LocalNode → [Sign] → ChangeSet → TrustedNode → [Validation] → GlobalState
+```
+
+### 3. Global State Persistence
+
+```typescript
+TrustedNode → [Sign & Compression] → DecentralisedStorage → [StateRoot] → VerifiableStorage
+```
+
+### 4. Remote Synchronisation
+
+```typescript
+AnyNode → [Poll] → VerifiableStorage → [Fetch] → DecentralisedStorage → [Merge] → LocalState
+```
+
+## Data Structures
+
+- ChangeSet - contains a set of changes that a regular node will send to a trusted node - will contain a proof generated by the identity of the regular node

package/docs/changelog.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.0.1-next.4](https://github.com/twinfoundation/synchronised-storage/compare/synchronised-storage-service-v0.0.1-next.3...synchronised-storage-service-v0.0.1-next.4) (2025-08-08)
+
+
+### Features
+
+* add payload versioning ([3bbbce0](https://github.com/twinfoundation/synchronised-storage/commit/3bbbce0bdf24bbe67c1a265704538d505d7feb91))
+* blob storage connector instead of component ([#7](https://github.com/twinfoundation/synchronised-storage/issues/7)) ([ea27241](https://github.com/twinfoundation/synchronised-storage/commit/ea27241cf0810b52ab7a6be7346809d127b7109a))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/synchronised-storage-models bumped from 0.0.1-next.3 to 0.0.1-next.4
+
 ## [0.0.1-next.3](https://github.com/twinfoundation/synchronised-storage/compare/synchronised-storage-service-v0.0.1-next.2...synchronised-storage-service-v0.0.1-next.3) (2025-07-25)