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

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

@@ -7,6 +7,10 @@ export declare class SyncSnapshotEntry<T extends ISynchronisedEntity = ISynchron
      * The id for the snapshot.
      */
     id: string;
+    /**
+     * The version for the snapshot.
+     */
+    version: string;
     /**
      * The storage key for the snapshot i.e. which entity is being synchronized.
      */
@@ -18,11 +22,19 @@ export declare class SyncSnapshotEntry<T extends ISynchronisedEntity = ISynchron
     /**
      * The date the snapshot was last modified.
      */
-    dateModified?: string;
+    dateModified: string;
+    /**
+     * The flag to determine if this is the snapshot is the local one containing changes for this node.
+     */
+    isLocal: boolean;
+    /**
+     * The flag to determine if this is a consolidated snapshot.
+     */
+    isConsolidated: boolean;
     /**
-     * The flag to determine if this is the current local snapshot containing changes for this node.
+     * The epoch for the changeset.
      */
-    isLocalSnapshot?: boolean;
+    epoch: number;
     /**
      * The ids of the storage for the change sets in the snapshot, if this is not a local snapshot.
      */

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

@@ -23,11 +23,17 @@ export declare class BlobStorageHelper {
      * @param blobId The id of the blob to apply.
      * @returns The blob.
      */
-    load<T>(blobId: string): Promise<T | undefined>;
+    loadBlob<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>;
+    /**
+     * Remove a blob from storage.
+     * @param blobId The id of the blob to remove.
+     * @returns Nothing.
+     */
+    removeBlob(blobId: string): Promise<void>;
 }

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

@@ -2,7 +2,7 @@ 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 ISyncChangeSet, type ISynchronisedEntity } from "@twin.org/synchronised-storage-models";
+import { type ISyncChangeSet, type ISynchronisedEntity, type SyncNodeIdentityMode } from "@twin.org/synchronised-storage-models";
 import type { BlobStorageHelper } from "./blobStorageHelper";
 /**
  * Class for performing change set operations.
@@ -71,4 +71,11 @@ export declare class ChangeSetHelper<T extends ISynchronisedEntity = ISynchronis
         syncChangeSet: ISyncChangeSet<T>;
         changeSetStorageId: string;
     } | undefined>;
+    /**
+     * Reset the storage for a given storage key.
+     * @param storageKey The key of the storage to reset.
+     * @param resetMode The reset mode, this will use the nodeIdentity in the entities to determine which are local/remote.
+     * @returns Nothing.
+     */
+    reset(storageKey: string, resetMode: SyncNodeIdentityMode): Promise<void>;
 }

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

@@ -1,6 +1,6 @@
 import type { IEntityStorageConnector } from "@twin.org/entity-storage-models";
 import type { ILoggingConnector } from "@twin.org/logging-models";
-import type { ISynchronisedEntity, SyncChangeOperation } from "@twin.org/synchronised-storage-models";
+import { type ISynchronisedEntity, type SyncChangeOperation } from "@twin.org/synchronised-storage-models";
 import type { ChangeSetHelper } from "./changeSetHelper";
 import type { SyncSnapshotEntry } from "../entities/syncSnapshotEntry";
 import type { ISyncState } from "../models/ISyncState";
@@ -28,11 +28,12 @@ export declare class LocalSyncStateHelper<T extends ISynchronisedEntity = ISynch
      */
     addLocalChange(storageKey: string, operation: SyncChangeOperation, id: string): Promise<void>;
     /**
-     * Get the current local snapshot which contains just the changes for this node.
+     * Get the snapshot which contains just the changes for this node.
      * @param storageKey The storage key of the snapshot to get.
+     * @param isLocal Whether to get the local snapshot or not.
      * @returns The local snapshot entry.
      */
-    getLocalChangeSnapshot(storageKey: string): Promise<SyncSnapshotEntry<T>>;
+    getSnapshots(storageKey: string, isLocal: boolean): Promise<SyncSnapshotEntry<T>[]>;
     /**
      * Set the current local snapshot with changes for this node.
      * @param localChangeSnapshot The local change snapshot to set.

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

@@ -22,8 +22,9 @@ export declare class RemoteSyncStateHelper<T extends ISynchronisedEntity = ISync
      * @param blobStorageHelper The blob storage helper to use for remote sync states.
      * @param changeSetHelper The change set helper to use for managing changesets.
      * @param isTrustedNode Whether the node is trusted or not.
+     * @param maxConsolidations The maximum number of consolidations to keep in storage.
      */
-    constructor(logging: ILoggingConnector | undefined, eventBusComponent: IEventBusComponent, verifiableSyncPointerStorageConnector: IVerifiableStorageConnector, blobStorageHelper: BlobStorageHelper, changeSetHelper: ChangeSetHelper<T>, isTrustedNode: boolean);
+    constructor(logging: ILoggingConnector | undefined, eventBusComponent: IEventBusComponent, verifiableSyncPointerStorageConnector: IVerifiableStorageConnector, blobStorageHelper: BlobStorageHelper, changeSetHelper: ChangeSetHelper<T>, isTrustedNode: boolean, maxConsolidations: number);
     /**
      * Set the node identity to use for signing changesets.
      * @param nodeIdentity The identity of the node that is performing the update.
@@ -85,7 +86,7 @@ export declare class RemoteSyncStateHelper<T extends ISynchronisedEntity = ISync
      * @param syncPointerId The id of the sync pointer to retrieve the state for.
      * @returns The remote sync state.
      */
-    getRemoteSyncState(syncPointerId: string): Promise<ISyncState | undefined>;
+    getSyncState(syncPointerId: string): Promise<ISyncState | undefined>;
     /**
      * Handle the batch response which is triggered from a consolidation request.
      * @param response The batch response to handle.

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

@@ -18,6 +18,14 @@ export interface ISyncSnapshot {
      * The date the snapshot was last modified.
      */
     dateModified: string;
+    /**
+     * Is this a consolidated snapshot?
+     */
+    isConsolidated: boolean;
+    /**
+     * The epoch of the snapshot.
+     */
+    epoch: number;
     /**
      * The ids of the storage for the change sets in the snapshot.
      */

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

@@ -7,6 +7,10 @@ export interface ISyncState {
      * The version of the sync state.
      */
     version: string;
+    /**
+     * The storage type contained in the sync state.
+     */
+    storageKey: string;
     /**
      * The snapshots.
      */

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

@@ -27,6 +27,11 @@ export interface ISynchronisedStorageServiceConfig {
      * @default 1000
      */
     consolidationBatchSize?: number;
+    /**
+     * The maximum number of consolidations to keep in storage.
+     * @default 5
+     */
+    maxConsolidations?: 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

package/docs/architecture.md

@@ -122,4 +122,7 @@ AnyNode → [Poll] → VerifiableStorage → [Fetch] → DecentralisedStorage
 
 ## 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
+- Sync Pointer Store - stored in verifiable storage, for each storage type contains a storage id of the location for sync states
+- Sync State - stored in decentralised storage, contains all of the snapshots for a specific storage key
+- Sync Snapshot - contains a list of all the decentralised storage ids for the change sets which make up the snapshot
+- Change Set - contains a set of changes to be made to the entity storage

package/docs/changelog.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.0.1-next.6](https://github.com/twinfoundation/synchronised-storage/compare/synchronised-storage-service-v0.0.1-next.5...synchronised-storage-service-v0.0.1-next.6) (2025-08-11)
+
+
+### Features
+
+* improve consolidation logic ([698232f](https://github.com/twinfoundation/synchronised-storage/commit/698232f57640f87642ecd323cb1e4670eda33343))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/synchronised-storage-models bumped from 0.0.1-next.5 to 0.0.1-next.6
+
+## [0.0.1-next.5](https://github.com/twinfoundation/synchronised-storage/compare/synchronised-storage-service-v0.0.1-next.4...synchronised-storage-service-v0.0.1-next.5) (2025-08-11)
+
+
+### Features
+
+* additional node identity checks ([76257c4](https://github.com/twinfoundation/synchronised-storage/commit/76257c4173303d484391f71f581fd0e214204029))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/synchronised-storage-models bumped from 0.0.1-next.4 to 0.0.1-next.5
+
 ## [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)
 
 

package/docs/open-api/spec.json

@@ -41,6 +41,7 @@
 									"value": {
 										"id": "0909090909090909090909090909090909090909090909090909090909090909",
 										"dateCreated": "2025-05-29T01:00:00.000Z",
+										"dateModified": "2025-05-29T01:00:00.000Z",
 										"nodeIdentity": "did:entity-storage:0xd2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2",
 										"changes": [
 											{
@@ -340,6 +341,7 @@
 					"id",
 					"dateCreated",
 					"storageKey",
+					"dateModified",
 					"changes",
 					"nodeIdentity"
 				],

package/docs/reference/classes/SyncSnapshotEntry.md

@@ -28,6 +28,14 @@ The id for the snapshot.
 
 ***
 
+### version
+
+> **version**: `string`
+
+The version for the snapshot.
+
+***
+
 ### storageKey
 
 > **storageKey**: `string`
@@ -44,19 +52,35 @@ The date the snapshot was created.
 
 ***
 
-### dateModified?
+### dateModified
 
-> `optional` **dateModified**: `string`
+> **dateModified**: `string`
 
 The date the snapshot was last modified.
 
 ***
 
-### isLocalSnapshot?
+### isLocal
+
+> **isLocal**: `boolean`
+
+The flag to determine if this is the snapshot is the local one containing changes for this node.
+
+***
+
+### isConsolidated
+
+> **isConsolidated**: `boolean`
+
+The flag to determine if this is a consolidated snapshot.
+
+***
+
+### epoch
 
-> `optional` **isLocalSnapshot**: `boolean`
+> **epoch**: `number`
 
-The flag to determine if this is the current local snapshot containing changes for this node.
+The epoch for the changeset.
 
 ***
 

package/docs/reference/interfaces/ISyncSnapshot.md

@@ -36,6 +36,22 @@ The date the snapshot was last modified.
 
 ***
 
+### isConsolidated
+
+> **isConsolidated**: `boolean`
+
+Is this a consolidated snapshot?
+
+***
+
+### epoch
+
+> **epoch**: `number`
+
+The epoch of the snapshot.
+
+***
+
 ### changeSetStorageIds
 
 > **changeSetStorageIds**: `string`[]

package/docs/reference/interfaces/ISyncState.md

@@ -12,6 +12,14 @@ The version of the sync state.
 
 ***
 
+### storageKey
+
+> **storageKey**: `string`
+
+The storage type contained in the sync state.
+
+***
+
 ### snapshots
 
 > **snapshots**: [`ISyncSnapshot`](ISyncSnapshot.md)[]

package/docs/reference/interfaces/ISynchronisedStorageServiceConfig.md

@@ -74,6 +74,20 @@ The number of entities to process in a single consolidation batch.
 
 ***
 
+### maxConsolidations?
+
+> `optional` **maxConsolidations**: `number`
+
+The maximum number of consolidations to keep in storage.
+
+#### Default
+
+```ts
+5
+```
+
+***
+
 ### blobStorageEncryptionKeyId?
 
 > `optional` **blobStorageEncryptionKeyId**: `string`

package/locales/en.json

@@ -10,14 +10,18 @@
 			"createdChangeSetProof": "Created change proof for change set with id \"{id}\", proof value is \"{proofValue}\"",
 			"getChangeSet": "Retrieving change set with id \"{changeSetStorageId}\"",
 			"getChangeSetEmpty": "No change set found with id \"{changeSetStorageId}\"",
-			"copyChangeSet": "Copying change set with id \"{changeSetStorageId}\""
+			"copyChangeSet": "Copying change set with id \"{changeSetStorageId}\"",
+			"storageReset": "Resetting storage for storage key \"{storageKey}\""
 		},
 		"localSyncStateHelper": {
-			"getLocalChangeSnapshot": "Retrieving local change snapshot for storage key \"{storageKey}\"",
-			"localChangeSnapshotExists": "Found existing local change snapshot for storage key \"{storageKey}\"",
-			"localChangeSnapshotDoesNotExist": "No local change snapshot found for storage key \"{storageKey}\", creating new one",
+			"getSnapshots": "Retrieving snapshot for storage key \"{storageKey}\"",
+			"getSnapshotsExists": "Found existing snapshot for storage key \"{storageKey}\"",
+			"getSnapshotsDoesNotExist": "No local change snapshot found for storage key \"{storageKey}\", creating new one",
 			"applySyncState": "Syncing from remote state with \"{snapshotCount}\" snapshots",
 			"applySnapshot": "Processing sync snapshot with id \"{snapshotId}\" created on \"{dateCreated}\"",
+			"applySnapshotNoExisting": "There are no existing snapshots, find a consolidated snapshot for storage key \"{storageKey}\"",
+			"applySnapshotFoundConsolidated": "Found consolidated snapshot with id \"{snapshotId}\" for storage key \"{storageKey}\"",
+			"applySnapshotNoConsolidated": "No consolidated snapshot found, cannot apply sync state for storage key \"{storageKey}\"",
 			"processModifiedSnapshot": "Processing modified sync snapshot with id \"{snapshotId}\", remote modified on \"{remoteModified}\", local modified on \"{localModified}\"",
 			"processNewSnapshot": "Processing new sync snapshot with id \"{snapshotId}\", created on \"{dateCreated}\"",
 			"removeLocalChangeSnapshot": "Removing local change snapshot with id \"{snapshotId}\"",
@@ -29,10 +33,10 @@
 			"verifiableSyncPointerStoreNotFound": "No verifiable sync pointer store found for key \"{key}\"",
 			"verifiableSyncPointerStoreRetrieved": "Retrieved verifiable sync pointer for key \"{key}\"",
 			"verifiableSyncPointerStoreStoring": "Storing verifiable sync pointer store for key \"{key}\"",
-			"remoteSyncStateStoring": "Storing remote sync state entry with \"{snapshotCount}\" snapshots",
-			"remoteSyncStateRetrieving": "Retrieving remote sync state entry for syncPointerId \"{syncPointerId}\"",
-			"remoteSyncStateRetrieved": "Retrieving remote sync state entry for syncPointerId \"{syncPointerId}\" with \"{snapshotCount}\" snapshots",
-			"remoteSyncStateNotFound": "No remote sync state entry found for syncPointerId \"{syncPointerId}\"",
+			"syncStateStoring": "Storing sync state entry with \"{snapshotCount}\" snapshots",
+			"syncStateRetrieving": "Retrieving sync state entry for syncPointerId \"{syncPointerId}\"",
+			"syncStateRetrieved": "Retrieving sync state entry for syncPointerId \"{syncPointerId}\" with \"{snapshotCount}\" snapshots",
+			"syncStateNotFound": "No sync state entry found for syncPointerId \"{syncPointerId}\"",
 			"consolidationStarting": "Starting consolidation of remote sync state",
 			"consolidationCompleted": "Consolidation of remote sync state completed",
 			"addChangeSetToSyncState": "Adding change set with id \"{changeSetStorageId}\" to remote sync state for storage key \"{storageKey}\"",
@@ -58,7 +62,10 @@
 			"loadedBlob": "Loaded blob with id \"{blobId}\"",
 			"loadBlobEmpty": "No blob found with id \"{blobId}\"",
 			"saveBlob": "Saving blob",
-			"savedBlob": "Saved blob with id \"{blobId}\""
+			"savedBlob": "Saved blob with id \"{blobId}\"",
+			"removeBlob": "Removing blob with id \"{blobId}\"",
+			"removedBlob": "Removed blob with id \"{blobId}\"",
+			"removeBlobEmpty": "No blob found to remove with id \"{blobId}\""
 		}
 	},
 	"error": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/synchronised-storage-service",
-	"version": "0.0.1-next.4",
+	"version": "0.0.1-next.6",
 	"description": "Synchronised storage contract implementation and REST endpoint definitions",
 	"repository": {
 		"type": "git",
@@ -26,7 +26,7 @@
 		"@twin.org/logging-models": "next",
 		"@twin.org/nameof": "next",
 		"@twin.org/standards-w3c-did": "next",
-		"@twin.org/synchronised-storage-models": "0.0.1-next.4",
+		"@twin.org/synchronised-storage-models": "0.0.1-next.6",
 		"@twin.org/verifiable-storage-models": "next",
 		"@twin.org/web": "next"
 	},