@brightchain/brightchain-lib 0.30.1 → 0.31.0

package/src/lib/db/headRegistryGossipTransport.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * HeadRegistryGossipTransport — Gossip-aware decorator for IHeadRegistry.
+ *
+ * Wraps any IHeadRegistry and wires it to an IGossipService so that:
+ *   1. Outbound: after every successful setHead(), the update is announced
+ *      to peers via gossip.
+ *   2. Inbound: incoming 'head_update' gossip announcements are merged into
+ *      the wrapped registry using last-writer-wins semantics.
+ *   3. Anti-entropy: an optional periodic timer re-announces all known head
+ *      pointers so that nodes that missed earlier announcements can converge.
+ *
+ * Usage:
+ *   const transport = new HeadRegistryGossipTransport(inner, gossipService);
+ *   transport.start(30_000); // optional anti-entropy every 30 s
+ *   // … use transport as an IHeadRegistry …
+ *   await transport.stop();
+ *
+ * @see Requirements 2.1, 7.1, 7.2
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeadRegistryGossipTransport = void 0;
+class HeadRegistryGossipTransport {
+    inner;
+    gossip;
+    announcementHandler;
+    antiEntropyTimer;
+    constructor(inner, gossip) {
+        this.inner = inner;
+        this.gossip = gossip;
+        // Build the inbound handler once so we can unregister the exact same
+        // reference in stop().
+        this.announcementHandler = (ann) => {
+            if (ann.type !== 'head_update' || !ann.headUpdate)
+                return;
+            const { dbName, collectionName } = ann.headUpdate;
+            const blockId = String(ann.blockId);
+            const timestamp = ann.timestamp; // already a Date
+            // Best-effort inbound merge — do not let gossip errors surface.
+            this.inner
+                .mergeHeadUpdate(dbName, collectionName, blockId, timestamp)
+                .catch(() => {
+                // Intentionally swallowed: gossip failures must not crash the service.
+            });
+        };
+        this.gossip.onAnnouncement(this.announcementHandler);
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────────
+    /**
+     * Start the optional anti-entropy timer.
+     * When `antiEntropyIntervalMs` is provided and > 0, the transport will
+     * periodically re-announce all known head pointers so that peers that
+     * joined late (or missed earlier announcements) can converge.
+     *
+     * @param antiEntropyIntervalMs - Interval in milliseconds between anti-entropy
+     *   passes.  Pass 0 or omit to disable.
+     */
+    start(antiEntropyIntervalMs) {
+        if (antiEntropyIntervalMs && antiEntropyIntervalMs > 0) {
+            this.antiEntropyTimer = setInterval(() => {
+                void this.pushSnapshot();
+            }, antiEntropyIntervalMs);
+        }
+    }
+    /**
+     * Stop the anti-entropy timer and unregister the inbound handler.
+     * Should be called when the transport is no longer needed.
+     */
+    async stop() {
+        if (this.antiEntropyTimer !== undefined) {
+            clearInterval(this.antiEntropyTimer);
+            this.antiEntropyTimer = undefined;
+        }
+        this.gossip.offAnnouncement(this.announcementHandler);
+    }
+    /**
+     * Re-announce every known head pointer via gossip.
+     * Used by the anti-entropy timer and can also be called manually to
+     * trigger an immediate convergence pass.
+     */
+    async pushSnapshot() {
+        const snapshot = this.inner.exportSnapshot();
+        for (const [key, record] of snapshot) {
+            const colon = key.indexOf(':');
+            const dbName = colon === -1 ? key : key.slice(0, colon);
+            const collectionName = colon === -1 ? '' : key.slice(colon + 1);
+            try {
+                await this.gossip.announceHeadUpdate(dbName, collectionName, record.blockId);
+            }
+            catch {
+                // Best-effort: individual failures must not abort the whole pass.
+            }
+        }
+    }
+    // ── IHeadRegistry – mutations with outbound gossip ───────────────────────
+    /**
+     * Set the head pointer locally and announce the update to peers.
+     * Gossip announcement is best-effort: a failure does not roll back the
+     * local write.
+     */
+    async setHead(dbName, collectionName, blockId, writeProof) {
+        await this.inner.setHead(dbName, collectionName, blockId, writeProof);
+        // Best-effort outbound announcement.
+        try {
+            await this.gossip.announceHeadUpdate(dbName, collectionName, blockId);
+        }
+        catch {
+            // Intentionally swallowed: gossip failures must not break local writes.
+        }
+    }
+    // ── IHeadRegistry – pure delegations ─────────────────────────────────────
+    getHead(dbName, collectionName) {
+        return this.inner.getHead(dbName, collectionName);
+    }
+    async removeHead(dbName, collectionName, writeProof) {
+        return this.inner.removeHead(dbName, collectionName, writeProof);
+    }
+    async clear() {
+        return this.inner.clear();
+    }
+    async load() {
+        return this.inner.load();
+    }
+    getAllHeads() {
+        return this.inner.getAllHeads();
+    }
+    getHeadTimestamp(dbName, collectionName) {
+        return this.inner.getHeadTimestamp(dbName, collectionName);
+    }
+    async mergeHeadUpdate(dbName, collectionName, blockId, timestamp, writeProof) {
+        return this.inner.mergeHeadUpdate(dbName, collectionName, blockId, timestamp, writeProof);
+    }
+    async deferHeadUpdate(dbName, collectionName, blockId, timestamp) {
+        return this.inner.deferHeadUpdate(dbName, collectionName, blockId, timestamp);
+    }
+    async applyDeferredUpdates(blockId) {
+        return this.inner.applyDeferredUpdates(blockId);
+    }
+    getDeferredUpdates() {
+        return this.inner.getDeferredUpdates();
+    }
+    exportSnapshot() {
+        return this.inner.exportSnapshot();
+    }
+    async mergeSnapshot(snapshot) {
+        return this.inner.mergeSnapshot(snapshot);
+    }
+    onHeadChange(dbName, collectionName, callback) {
+        return this.inner.onHeadChange(dbName, collectionName, callback);
+    }
+}
+exports.HeadRegistryGossipTransport = HeadRegistryGossipTransport;
+//# sourceMappingURL=headRegistryGossipTransport.js.map

package/src/lib/db/headRegistryGossipTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headRegistryGossipTransport.js","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/headRegistryGossipTransport.ts"],"names":[],"mappings":"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"}

package/src/lib/db/inMemoryHeadRegistry.d.ts

@@ -8,10 +8,12 @@
  * Use `createIsolated()` for test scenarios that need an independent registry.
  */
 import type { DeferredHeadUpdate, IHeadRegistry } from '../interfaces/storage/headRegistry';
+import type { HeadRecord } from '../interfaces/storage/headRegistryDriver';
 export declare class InMemoryHeadRegistry implements IHeadRegistry {
     private readonly heads;
     private readonly timestamps;
     private readonly deferred;
+    private readonly changeListeners;
     private makeKey;
     getHead(dbName: string, collectionName: string): string | undefined;
     setHead(dbName: string, collectionName: string, blockId: string): Promise<void>;
@@ -21,9 +23,16 @@ export declare class InMemoryHeadRegistry implements IHeadRegistry {
     getAllHeads(): Map<string, string>;
     getHeadTimestamp(dbName: string, collectionName: string): Date | undefined;
     mergeHeadUpdate(dbName: string, collectionName: string, blockId: string, timestamp: Date): Promise<boolean>;
+    private notifyHeadChange;
+    onHeadChange(dbName: string, collectionName: string, callback: (blockId: string) => void): () => void;
     deferHeadUpdate(dbName: string, collectionName: string, blockId: string, timestamp: Date): Promise<void>;
     applyDeferredUpdates(blockId: string): Promise<number>;
     getDeferredUpdates(): DeferredHeadUpdate[];
+    exportSnapshot(): ReadonlyMap<string, HeadRecord>;
+    mergeSnapshot(snapshot: Iterable<readonly [string, HeadRecord]>): Promise<{
+        merged: number;
+        skipped: number;
+    }>;
     /**
      * Factory method that creates an independent InMemoryHeadRegistry instance.
      * Useful for tests that need isolated state.

package/src/lib/db/inMemoryHeadRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inMemoryHeadRegistry.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/inMemoryHeadRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EACV,kBAAkB,EAClB,aAAa,EACd,MAAM,oCAAoC,CAAC;AAE5C,qBAAa,oBAAqB,YAAW,aAAa;IACxD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IAErD,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7D,OAAO,CACX,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAMV,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAIlC,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIpE,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,IAAI,GACd,OAAO,CAAC,OAAO,CAAC;IAeb,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,IAAI,GACd,OAAO,CAAC,IAAI,CAAC;IAIV,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuB5D,kBAAkB,IAAI,kBAAkB,EAAE;IAI1C;;;OAGG;IACH,MAAM,CAAC,cAAc,IAAI,oBAAoB;CAG9C"}
+{"version":3,"file":"inMemoryHeadRegistry.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/inMemoryHeadRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EACV,kBAAkB,EAClB,aAAa,EACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E,qBAAa,oBAAqB,YAAW,aAAa;IACxD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAG5B;IAEJ,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7D,OAAO,CACX,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAMV,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAIlC,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIpE,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,IAAI,GACd,OAAO,CAAC,OAAO,CAAC;IAgBnB,OAAO,CAAC,gBAAgB;IASxB,YAAY,CACV,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAClC,MAAM,IAAI;IAYP,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,IAAI,GACd,OAAO,CAAC,IAAI,CAAC;IAIV,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuB5D,kBAAkB,IAAI,kBAAkB,EAAE;IAI1C,cAAc,IAAI,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC;IAY3C,aAAa,CACjB,QAAQ,EAAE,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAChD,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAsB/C;;;OAGG;IACH,MAAM,CAAC,cAAc,IAAI,oBAAoB;CAG9C"}

package/src/lib/db/inMemoryHeadRegistry.js

@@ -5,6 +5,7 @@ class InMemoryHeadRegistry {
     heads = new Map();
     timestamps = new Map();
     deferred = [];
+    changeListeners = new Map();
     makeKey(dbName, collectionName) {
         return `${dbName}:${collectionName}`;
     }
@@ -42,11 +43,30 @@ class InMemoryHeadRegistry {
         if (!localTimestamp || timestamp.getTime() > localTimestamp.getTime()) {
             this.heads.set(key, blockId);
             this.timestamps.set(key, timestamp);
+            this.notifyHeadChange(key, blockId);
             return true;
         }
         // Local is same age or newer — reject
         return false;
     }
+    notifyHeadChange(key, blockId) {
+        const listeners = this.changeListeners.get(key);
+        if (listeners) {
+            for (const cb of listeners) {
+                cb(blockId);
+            }
+        }
+    }
+    onHeadChange(dbName, collectionName, callback) {
+        const key = this.makeKey(dbName, collectionName);
+        if (!this.changeListeners.has(key)) {
+            this.changeListeners.set(key, new Set());
+        }
+        this.changeListeners.get(key).add(callback);
+        return () => {
+            this.changeListeners.get(key)?.delete(callback);
+        };
+    }
     async deferHeadUpdate(dbName, collectionName, blockId, timestamp) {
         this.deferred.push({ dbName, collectionName, blockId, timestamp });
     }
@@ -69,6 +89,34 @@ class InMemoryHeadRegistry {
     getDeferredUpdates() {
         return [...this.deferred];
     }
+    exportSnapshot() {
+        const result = new Map();
+        for (const [key, blockId] of this.heads) {
+            const ts = this.timestamps.get(key);
+            result.set(key, {
+                blockId,
+                timestamp: ts ? ts.toISOString() : new Date(0).toISOString(),
+            });
+        }
+        return result;
+    }
+    async mergeSnapshot(snapshot) {
+        let merged = 0;
+        let skipped = 0;
+        for (const [key, record] of snapshot) {
+            const colon = key.indexOf(':');
+            const dbName = colon === -1 ? key : key.slice(0, colon);
+            const collectionName = colon === -1 ? '' : key.slice(colon + 1);
+            const applied = await this.mergeHeadUpdate(dbName, collectionName, record.blockId, new Date(record.timestamp));
+            if (applied) {
+                merged++;
+            }
+            else {
+                skipped++;
+            }
+        }
+        return { merged, skipped };
+    }
     /**
      * Factory method that creates an independent InMemoryHeadRegistry instance.
      * Useful for tests that need isolated state.

package/src/lib/db/inMemoryHeadRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"inMemoryHeadRegistry.js","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/inMemoryHeadRegistry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"inMemoryHeadRegistry.js","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/inMemoryHeadRegistry.ts"],"names":[],"mappings":";;;AAeA,MAAa,oBAAoB;IACd,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAClC,UAAU,GAAG,IAAI,GAAG,EAAgB,CAAC;IACrC,QAAQ,GAAyB,EAAE,CAAC;IACpC,eAAe,GAAG,IAAI,GAAG,EAGvC,CAAC;IAEI,OAAO,CAAC,MAAc,EAAE,cAAsB;QACpD,OAAO,GAAG,MAAM,IAAI,cAAc,EAAE,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,MAAc,EAAE,cAAsB;QAC5C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,OAAO,CACX,MAAc,EACd,cAAsB,EACtB,OAAe;QAEf,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;QACjD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC7B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,MAAc,EAAE,cAAsB;QACrD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;QACjD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,IAAI;QACR,qCAAqC;IACvC,CAAC;IAED,WAAW;QACT,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,gBAAgB,CAAC,MAAc,EAAE,cAAsB;QACrD,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IACnE,CAAC;IAED,KAAK,CAAC,eAAe,CACnB,MAAc,EACd,cAAsB,EACtB,OAAe,EACf,SAAe;QAEf,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;QACjD,MAAM,cAAc,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEhD,4EAA4E;QAC5E,IAAI,CAAC,cAAc,IAAI,SAAS,CAAC,OAAO,EAAE,GAAG,cAAc,CAAC,OAAO,EAAE,EAAE,CAAC;YACtE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC7B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YACpC,IAAI,CAAC,gBAAgB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YACpC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,sCAAsC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IAEO,gBAAgB,CAAC,GAAW,EAAE,OAAe;QACnD,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChD,IAAI,SAAS,EAAE,CAAC;YACd,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;gBAC3B,EAAE,CAAC,OAAO,CAAC,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAED,YAAY,CACV,MAAc,EACd,cAAsB,EACtB,QAAmC;QAEnC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;QAC3C,CAAC;QAED,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7C,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClD,CAAC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,eAAe,CACnB,MAAc,EACd,cAAsB,EACtB,OAAe,EACf,SAAe;QAEf,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,KAAK,CAAC,oBAAoB,CAAC,OAAe;QACxC,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,MAAM,SAAS,GAAyB,EAAE,CAAC;QAE3C,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnC,IAAI,MAAM,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;gBAC/B,MAAM,IAAI,CAAC,eAAe,CACxB,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,cAAc,EACrB,MAAM,CAAC,OAAO,EACd,MAAM,CAAC,SAAS,CACjB,CAAC;gBACF,OAAO,EAAE,CAAC;YACZ,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC;QACjC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,kBAAkB;QAChB,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED,cAAc;QACZ,MAAM,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAC;QAC7C,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACxC,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE;gBACd,OAAO;gBACP,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE;aAC7D,CAAC,CAAC;QACL,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,aAAa,CACjB,QAAiD;QAEjD,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACrC,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC/B,MAAM,MAAM,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YACxD,MAAM,cAAc,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YAChE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,eAAe,CACxC,MAAM,EACN,cAAc,EACd,MAAM,CAAC,OAAO,EACd,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAC3B,CAAC;YACF,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,EAAE,CAAC;YACX,CAAC;iBAAM,CAAC;gBACN,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,cAAc;QACnB,OAAO,IAAI,oBAAoB,EAAE,CAAC;IACpC,CAAC;CACF;AAhLD,oDAgLC"}

package/src/lib/db/inMemoryHeadRegistryDriver.d.ts

@@ -0,0 +1,13 @@
+import type { HeadRecord, IHeadRegistryDriver } from '../interfaces/storage/headRegistryDriver';
+/**
+ * InMemoryHeadRegistryDriver — Map-backed driver, no I/O.
+ * Used for tests and as a fallback when no persistent store is available.
+ */
+export declare class InMemoryHeadRegistryDriver implements IHeadRegistryDriver {
+    private readonly store;
+    readRecord(key: string): Promise<HeadRecord | null>;
+    writeRecord(key: string, record: HeadRecord): Promise<void>;
+    deleteRecord(key: string): Promise<void>;
+    listKeys(): Promise<string[]>;
+}
+//# sourceMappingURL=inMemoryHeadRegistryDriver.d.ts.map

package/src/lib/db/inMemoryHeadRegistryDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemoryHeadRegistryDriver.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/inMemoryHeadRegistryDriver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,mBAAmB,EACpB,MAAM,0CAA0C,CAAC;AAElD;;;GAGG;AACH,qBAAa,0BAA2B,YAAW,mBAAmB;IACpE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IAEjD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAInD,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,QAAQ,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAGpC"}

package/src/lib/db/inMemoryHeadRegistryDriver.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryHeadRegistryDriver = void 0;
+/**
+ * InMemoryHeadRegistryDriver — Map-backed driver, no I/O.
+ * Used for tests and as a fallback when no persistent store is available.
+ */
+class InMemoryHeadRegistryDriver {
+    store = new Map();
+    async readRecord(key) {
+        return this.store.get(key) ?? null;
+    }
+    async writeRecord(key, record) {
+        this.store.set(key, record);
+    }
+    async deleteRecord(key) {
+        this.store.delete(key);
+    }
+    async listKeys() {
+        return Array.from(this.store.keys());
+    }
+}
+exports.InMemoryHeadRegistryDriver = InMemoryHeadRegistryDriver;
+//# sourceMappingURL=inMemoryHeadRegistryDriver.js.map

package/src/lib/db/inMemoryHeadRegistryDriver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemoryHeadRegistryDriver.js","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/inMemoryHeadRegistryDriver.ts"],"names":[],"mappings":";;;AAKA;;;GAGG;AACH,MAAa,0BAA0B;IACpB,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAEvD,KAAK,CAAC,UAAU,CAAC,GAAW;QAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,GAAW,EAAE,MAAkB;QAC/C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,GAAW;QAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;CACF;AAlBD,gEAkBC"}

package/src/lib/db/index.d.ts

@@ -2,10 +2,13 @@ export * from './aggregation';
 export * from './brightdb';
 export * from './collection';
 export * from './cursor';
+export * from './driverBackedHeadRegistry';
 export * from './errors';
+export * from './headRegistryGossipTransport';
 export * from './indexing';
 export * from './inMemoryDatabase';
 export * from './inMemoryHeadRegistry';
+export * from './inMemoryHeadRegistryDriver';
 export * from './queryEngine';
 export * from './schemaValidation';
 export * from './transaction';

package/src/lib/db/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/index.ts"],"names":[],"mappings":"AACA,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/index.ts"],"names":[],"mappings":"AACA,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,4BAA4B,CAAC;AAC3C,cAAc,UAAU,CAAC;AACzB,cAAc,+BAA+B,CAAC;AAC9C,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}

package/src/lib/db/index.js

@@ -6,10 +6,13 @@ tslib_1.__exportStar(require("./aggregation"), exports);
 tslib_1.__exportStar(require("./brightdb"), exports);
 tslib_1.__exportStar(require("./collection"), exports);
 tslib_1.__exportStar(require("./cursor"), exports);
+tslib_1.__exportStar(require("./driverBackedHeadRegistry"), exports);
 tslib_1.__exportStar(require("./errors"), exports);
+tslib_1.__exportStar(require("./headRegistryGossipTransport"), exports);
 tslib_1.__exportStar(require("./indexing"), exports);
 tslib_1.__exportStar(require("./inMemoryDatabase"), exports);
 tslib_1.__exportStar(require("./inMemoryHeadRegistry"), exports);
+tslib_1.__exportStar(require("./inMemoryHeadRegistryDriver"), exports);
 tslib_1.__exportStar(require("./queryEngine"), exports);
 tslib_1.__exportStar(require("./schemaValidation"), exports);
 tslib_1.__exportStar(require("./transaction"), exports);

package/src/lib/db/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/index.ts"],"names":[],"mappings":";;;AAAA,qFAAqF;AACrF,wDAA8B;AAC9B,qDAA2B;AAC3B,uDAA6B;AAC7B,mDAAyB;AACzB,mDAAyB;AACzB,qDAA2B;AAC3B,6DAAmC;AACnC,iEAAuC;AACvC,wDAA8B;AAC9B,6DAAmC;AACnC,wDAA8B;AAC9B,kDAAwB;AACxB,yDAA+B;AAC/B,0DAAgC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/db/index.ts"],"names":[],"mappings":";;;AAAA,qFAAqF;AACrF,wDAA8B;AAC9B,qDAA2B;AAC3B,uDAA6B;AAC7B,mDAAyB;AACzB,qEAA2C;AAC3C,mDAAyB;AACzB,wEAA8C;AAC9C,qDAA2B;AAC3B,6DAAmC;AACnC,iEAAuC;AACvC,uEAA6C;AAC7C,wDAA8B;AAC9B,6DAAmC;AACnC,wDAA8B;AAC9B,kDAAwB;AACxB,yDAA+B;AAC/B,0DAAgC"}

package/src/lib/energyAccount.d.ts

@@ -1,71 +1,24 @@
-import { IEnergyAccount, IEnergyAccountDto } from './interfaces/energyAccount';
+import { AssetAccount } from './asset/assetAccount';
 import { Checksum } from './types/checksum';
 /**
- * Energy account for tracking member's Joule balance
- * Follows existing Member/Document patterns
+ * Energy account for tracking a member's microjoule balance.
+ *
+ * Extends {@link AssetAccount} with `assetId = 'joule'` and provides the
+ * legacy `netEnergy` alias and `createWithTrialCredits` factory retained for
+ * backward compatibility.
  */
-export declare class EnergyAccount implements IEnergyAccount {
-    readonly memberId: Checksum;
-    readonly createdAt: Date;
-    balance: number;
-    earned: number;
-    spent: number;
-    reserved: number;
-    reputation: number;
-    lastUpdated: Date;
-    constructor(memberId: Checksum, createdAt?: Date, balance?: number, earned?: number, spent?: number, reserved?: number, reputation?: number, // New users start at neutral reputation
-    lastUpdated?: Date);
-    /**
-     * Create new account with trial credits
-     */
+export declare class EnergyAccount extends AssetAccount {
+    constructor(memberId: Checksum, createdAt?: Date, balance?: bigint, earned?: bigint, spent?: bigint, reserved?: bigint, reputation?: number, lastUpdated?: Date);
+    /** Create a new account pre-loaded with trial credits. */
     static createWithTrialCredits(memberId: Checksum): EnergyAccount;
     /**
-     * Get available balance (balance - reserved)
-     */
-    get availableBalance(): number;
-    /**
-     * Get net energy (earned - spent)
-     */
-    get netEnergy(): number;
-    /**
-     * Check if account can afford operation
-     */
-    canAfford(amount: number): boolean;
-    /**
-     * Reserve energy for operation
-     */
-    reserve(amount: number): void;
-    /**
-     * Release reserved energy
-     */
-    release(amount: number): void;
-    /**
-     * Charge energy (deduct from balance)
-     */
-    charge(amount: number): void;
-    /**
-     * Credit energy (add to balance)
-     */
-    credit(amount: number): void;
-    /**
-     * Update reputation score
-     */
-    updateReputation(newReputation: number): void;
-    /**
-     * Convert to DTO for serialization
-     */
-    toDto(): IEnergyAccountDto;
-    /**
-     * Create from DTO
-     */
-    static fromDto(dto: IEnergyAccountDto): EnergyAccount;
-    /**
-     * Convert to JSON
-     */
-    toJson(): string;
-    /**
-     * Create from JSON
+     * Net energy = earned − spent.
+     * @deprecated Use {@link netAsset}.
      */
+    get netEnergy(): bigint;
+    /** Override to return a typed {@link EnergyAccount} instance. */
+    static fromDto(dto: Record<string, unknown>): EnergyAccount;
+    /** Override to return a typed {@link EnergyAccount} instance. */
     static fromJson(json: string): EnergyAccount;
 }
 //# sourceMappingURL=energyAccount.d.ts.map

package/src/lib/energyAccount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"energyAccount.d.ts","sourceRoot":"","sources":["../../../../brightchain-lib/src/lib/energyAccount.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C;;;GAGG;AACH,qBAAa,aAAc,YAAW,cAAc;aAShC,QAAQ,EAAE,QAAQ;aAClB,SAAS,EAAE,IAAI;IAT1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,IAAI,CAAC;gBAGP,QAAQ,EAAE,QAAQ,EAClB,SAAS,GAAE,IAAiB,EAC5C,OAAO,GAAE,MAA6B,EACtC,MAAM,GAAE,MAAU,EAClB,KAAK,GAAE,MAAU,EACjB,QAAQ,GAAE,MAAU,EACpB,UAAU,GAAE,MAAY,EAAE,wCAAwC;IAClE,WAAW,CAAC,EAAE,IAAI;IAUpB;;OAEG;IACH,MAAM,CAAC,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa;IAIhE;;OAEG;IACH,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIlC;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAc7B;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK7B;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAe5B;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAM5B;;OAEG;IACH,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI;IAK7C;;OAEG;IACH,KAAK,IAAI,iBAAiB;IAa1B;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,iBAAiB,GAAG,aAAa;IAarD;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;CAG7C"}
+{"version":3,"file":"energyAccount.d.ts","sourceRoot":"","sources":["../../../../brightchain-lib/src/lib/energyAccount.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAMpD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAM5C;;;;;;GAMG;AACH,qBAAa,aAAc,SAAQ,YAAY;gBAE3C,QAAQ,EAAE,QAAQ,EAClB,SAAS,GAAE,IAAiB,EAC5B,OAAO,GAAE,MAAkC,EAC3C,MAAM,GAAE,MAAW,EACnB,KAAK,GAAE,MAAW,EAClB,QAAQ,GAAE,MAAW,EACrB,UAAU,GAAE,MAAY,EACxB,WAAW,CAAC,EAAE,IAAI;IAepB,0DAA0D;IAC1D,MAAM,CAAC,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa;IAIhE;;;OAGG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,iEAAiE;WACjD,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAcpE,iEAAiE;WACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;CAGtD"}

package/src/lib/energyAccount.js

@@ -1,137 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EnergyAccount = void 0;
+const assetAccount_1 = require("./asset/assetAccount");
+const jouleConstants_1 = require("./asset/jouleConstants");
 const energyConsts_1 = require("./energyConsts");
-const enumerations_1 = require("./enumerations");
-const translatableBrightChainError_1 = require("./errors/translatableBrightChainError");
-const checksum_1 = require("./types/checksum");
+/** Trial credits in microjoules (1 000 Joules × 1 000 000 microjoules/Joule). */
+const TRIAL_CREDITS_MICROJOULES = BigInt(energyConsts_1.ENERGY.TRIAL_CREDITS) * jouleConstants_1.JOULE_MICROUNITS_PER_UNIT;
 /**
- * Energy account for tracking member's Joule balance
- * Follows existing Member/Document patterns
+ * Energy account for tracking a member's microjoule balance.
+ *
+ * Extends {@link AssetAccount} with `assetId = 'joule'` and provides the
+ * legacy `netEnergy` alias and `createWithTrialCredits` factory retained for
+ * backward compatibility.
  */
-class EnergyAccount {
-    memberId;
-    createdAt;
-    balance;
-    earned;
-    spent;
-    reserved;
-    reputation;
-    lastUpdated;
-    constructor(memberId, createdAt = new Date(), balance = energyConsts_1.ENERGY.TRIAL_CREDITS, earned = 0, spent = 0, reserved = 0, reputation = 0.5, // New users start at neutral reputation
-    lastUpdated) {
-        this.memberId = memberId;
-        this.createdAt = createdAt;
-        this.balance = balance;
-        this.earned = earned;
-        this.spent = spent;
-        this.reserved = reserved;
-        this.reputation = reputation;
-        this.lastUpdated = lastUpdated ?? createdAt;
+class EnergyAccount extends assetAccount_1.AssetAccount {
+    constructor(memberId, createdAt = new Date(), balance = TRIAL_CREDITS_MICROJOULES, earned = 0n, spent = 0n, reserved = 0n, reputation = 0.5, lastUpdated) {
+        super(memberId, jouleConstants_1.JOULE_ASSET_ID, createdAt, balance, earned, spent, reserved, reputation, lastUpdated);
     }
-    /**
-     * Create new account with trial credits
-     */
+    /** Create a new account pre-loaded with trial credits. */
     static createWithTrialCredits(memberId) {
         return new EnergyAccount(memberId);
     }
     /**
-     * Get available balance (balance - reserved)
-     */
-    get availableBalance() {
-        return Math.max(0, this.balance - this.reserved);
-    }
-    /**
-     * Get net energy (earned - spent)
+     * Net energy = earned − spent.
+     * @deprecated Use {@link netAsset}.
      */
     get netEnergy() {
-        return this.earned - this.spent;
-    }
-    /**
-     * Check if account can afford operation
-     */
-    canAfford(amount) {
-        return this.availableBalance >= amount;
-    }
-    /**
-     * Reserve energy for operation
-     */
-    reserve(amount) {
-        if (!this.canAfford(amount)) {
-            throw new translatableBrightChainError_1.TranslatableBrightChainError(enumerations_1.BrightChainStrings.EnergyAccount_InsufficientBalanceTemplate, {
-                AMOUNT: amount,
-                AVAILABLE: this.availableBalance,
-            });
-        }
-        this.reserved += amount;
-        this.lastUpdated = new Date();
-    }
-    /**
-     * Release reserved energy
-     */
-    release(amount) {
-        this.reserved = Math.max(0, this.reserved - amount);
-        this.lastUpdated = new Date();
-    }
-    /**
-     * Charge energy (deduct from balance)
-     */
-    charge(amount) {
-        if (amount > this.balance) {
-            throw new translatableBrightChainError_1.TranslatableBrightChainError(enumerations_1.BrightChainStrings.EnergyAccount_InsufficientBalanceTemplate, {
-                AMOUNT: amount,
-                AVAILABLE: this.balance,
-            });
-        }
-        this.balance -= amount;
-        this.spent += amount;
-        this.lastUpdated = new Date();
+        return this.netAsset;
     }
-    /**
-     * Credit energy (add to balance)
-     */
-    credit(amount) {
-        this.balance += amount;
-        this.earned += amount;
-        this.lastUpdated = new Date();
-    }
-    /**
-     * Update reputation score
-     */
-    updateReputation(newReputation) {
-        this.reputation = Math.max(0, Math.min(1, newReputation));
-        this.lastUpdated = new Date();
-    }
-    /**
-     * Convert to DTO for serialization
-     */
-    toDto() {
-        return {
-            memberId: this.memberId.toHex(),
-            balance: this.balance,
-            earned: this.earned,
-            spent: this.spent,
-            reserved: this.reserved,
-            reputation: this.reputation,
-            createdAt: this.createdAt.toISOString(),
-            lastUpdated: this.lastUpdated.toISOString(),
-        };
-    }
-    /**
-     * Create from DTO
-     */
+    /** Override to return a typed {@link EnergyAccount} instance. */
     static fromDto(dto) {
-        return new EnergyAccount(checksum_1.Checksum.fromHex(dto.memberId), new Date(dto.createdAt), dto.balance, dto.earned, dto.spent, dto.reserved, dto.reputation, new Date(dto.lastUpdated));
-    }
-    /**
-     * Convert to JSON
-     */
-    toJson() {
-        return JSON.stringify(this.toDto());
+        const base = assetAccount_1.AssetAccount.fromDto(dto);
+        return new EnergyAccount(base.memberId, base.createdAt, base.balance, base.earned, base.spent, base.reserved, base.reputation, base.lastUpdated);
     }
-    /**
-     * Create from JSON
-     */
+    /** Override to return a typed {@link EnergyAccount} instance. */
     static fromJson(json) {
         return EnergyAccount.fromDto(JSON.parse(json));
     }