@brightchain/brightchain-api-lib 0.12.0 → 0.13.0

package/src/lib/controllers/api/scbl.d.ts

@@ -0,0 +1,80 @@
+import { RetrieveSCBLResponse, StoreSCBLResponse } from '@brightchain/brightchain-lib';
+import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
+import { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { Request } from 'express';
+import { IBrightChainApplication } from '../../interfaces';
+import { DefaultBackendIdType } from '../../shared-types';
+import { BaseController } from '../base';
+/**
+ * Handler keys for the SCBL controller
+ */
+interface SCBLHandlers {
+    storeSCBL: string;
+    retrieveSCBL: string;
+}
+/**
+ * Controller for Super CBL (Hierarchical Constituent Block List) operations.
+ *
+ * Super CBLs enable storage of files larger than a single CBL can reference
+ * through recursive sub-CBL structures. This controller provides endpoints
+ * for storing and retrieving large files using the Super CBL hierarchy.
+ *
+ * ## Endpoints
+ *
+ * ### POST /api/scbl/store
+ * Store a large file as a Super CBL hierarchy.
+ *
+ * **Request Body:**
+ * - `data` (string, required): Base64 encoded file data
+ * - `durabilityLevel` (string, optional): 'ephemeral', 'standard', 'enhanced', 'maximum'
+ * - `isEncrypted` (boolean, optional): Flag indicating data is already encrypted
+ *
+ * **Response:** magnetUrl and metadata (hierarchyDepth, subCblCount)
+ *
+ * ### GET /api/scbl/retrieve
+ * Retrieve and reconstruct a file from its Super CBL hierarchy.
+ *
+ * **Query Parameters:**
+ * - `magnetUrl` (string, required): Full magnet URL from store response
+ *
+ * **Response:** Reconstructed file data (base64 encoded)
+ *
+ * @requirements 2.1, 2.2, 2.3, 2.4, 2.5
+ */
+export declare class SCBLController<TID extends PlatformID = DefaultBackendIdType> extends BaseController<TID, any, SCBLHandlers, CoreLanguageCode> {
+    private readonly blockStore;
+    private readonly cblService;
+    private readonly checksumService;
+    constructor(application: IBrightChainApplication<TID>);
+    /**
+     * Initialize route definitions
+     */
+    protected initRouteDefinitions(): void;
+    /**
+     * Calculate the maximum data size that can fit in a single CBL
+     * based on the block size and CBL header overhead.
+     */
+    private getCblThreshold;
+    /**
+     * Store a large file as a Super CBL hierarchy.
+     * POST /api/scbl/store
+     *
+     * @requirements 2.1, 2.3, 2.5
+     */
+    storeSCBL(_req: Request): Promise<{
+        statusCode: number;
+        response: StoreSCBLResponse;
+    }>;
+    /**
+     * Retrieve and reconstruct a file from its Super CBL hierarchy.
+     * GET /api/scbl/retrieve
+     *
+     * @requirements 2.2, 2.4
+     */
+    retrieveSCBL(req: Request): Promise<{
+        statusCode: number;
+        response: RetrieveSCBLResponse;
+    }>;
+}
+export {};
+//# sourceMappingURL=scbl.d.ts.map

package/src/lib/controllers/api/scbl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scbl.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/controllers/api/scbl.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,oBAAoB,EAGpB,iBAAiB,EAClB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAmB,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAE7D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,OAAO,EACL,uBAAuB,EAExB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAiBzC;;GAEG;AACH,UAAU,YAAY;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,cAAc,CACzB,GAAG,SAAS,UAAU,GAAG,oBAAoB,CAC7C,SAAQ,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,YAAY,EAAE,gBAAgB,CAAC;IAChE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAC7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;gBAEtC,WAAW,EAAE,uBAAuB,CAAC,GAAG,CAAC;IAwBrD;;OAEG;IACH,SAAS,CAAC,oBAAoB,IAAI,IAAI;IA+CtC;;;OAGG;IACH,OAAO,CAAC,eAAe;IAYvB;;;;;OAKG;IACU,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;QAC7C,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,iBAAiB,CAAC;KAC7B,CAAC;IA4HF;;;;;OAKG;IACU,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;QAC/C,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,oBAAoB,CAAC;KAChC,CAAC;CAsIH"}

package/src/lib/controllers/api/scbl.js

@@ -0,0 +1,325 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCBLController = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+const i18n_lib_1 = require("@digitaldefiance/i18n-lib");
+const express_validator_1 = require("express-validator");
+const stores_1 = require("../../stores");
+const base_1 = require("../base");
+/**
+ * Type guard for StoreSCBLRequest
+ */
+function isStoreSCBLRequest(body) {
+    return (typeof body['data'] === 'string' &&
+        (body['durabilityLevel'] === undefined ||
+            typeof body['durabilityLevel'] === 'string') &&
+        (body['isEncrypted'] === undefined ||
+            typeof body['isEncrypted'] === 'boolean'));
+}
+/**
+ * Controller for Super CBL (Hierarchical Constituent Block List) operations.
+ *
+ * Super CBLs enable storage of files larger than a single CBL can reference
+ * through recursive sub-CBL structures. This controller provides endpoints
+ * for storing and retrieving large files using the Super CBL hierarchy.
+ *
+ * ## Endpoints
+ *
+ * ### POST /api/scbl/store
+ * Store a large file as a Super CBL hierarchy.
+ *
+ * **Request Body:**
+ * - `data` (string, required): Base64 encoded file data
+ * - `durabilityLevel` (string, optional): 'ephemeral', 'standard', 'enhanced', 'maximum'
+ * - `isEncrypted` (boolean, optional): Flag indicating data is already encrypted
+ *
+ * **Response:** magnetUrl and metadata (hierarchyDepth, subCblCount)
+ *
+ * ### GET /api/scbl/retrieve
+ * Retrieve and reconstruct a file from its Super CBL hierarchy.
+ *
+ * **Query Parameters:**
+ * - `magnetUrl` (string, required): Full magnet URL from store response
+ *
+ * **Response:** Reconstructed file data (base64 encoded)
+ *
+ * @requirements 2.1, 2.2, 2.3, 2.4, 2.5
+ */
+class SCBLController extends base_1.BaseController {
+    constructor(application) {
+        super(application);
+        // Initialize block store from application environment
+        const storePath = this.application.environment.blockStorePath ?? 'tmp/blockstore';
+        const blockSize = (this.application.environment.blockStoreBlockSize
+            ? this.application.environment.blockStoreBlockSize
+            : brightchain_lib_1.BlockSize.Medium);
+        this.blockStore = new stores_1.DiskBlockAsyncStore({ storePath, blockSize });
+        this.checksumService = new brightchain_lib_1.ChecksumService();
+        // Initialize CBL service using ServiceProvider
+        const serviceProvider = brightchain_lib_1.ServiceProvider.getInstance();
+        this.cblService = new brightchain_lib_1.CBLService(this.checksumService, serviceProvider.eciesService, serviceProvider.idProvider);
+    }
+    /**
+     * Initialize route definitions
+     */
+    initRouteDefinitions() {
+        // Bind handler methods to this instance
+        this.handlers = {
+            storeSCBL: this.storeSCBL.bind(this),
+            retrieveSCBL: this.retrieveSCBL.bind(this),
+        };
+        this.routeDefinitions = [
+            {
+                method: 'post',
+                path: '/store',
+                handlerKey: 'storeSCBL',
+                useAuthentication: false,
+                validation: [
+                    (0, express_validator_1.body)('data')
+                        .isString()
+                        .notEmpty()
+                        .withMessage('data is required and must be a non-empty string'),
+                    (0, express_validator_1.body)('durabilityLevel')
+                        .optional()
+                        .isIn(['ephemeral', 'standard', 'enhanced', 'maximum'])
+                        .withMessage('durabilityLevel must be one of: ephemeral, standard, enhanced, maximum'),
+                    (0, express_validator_1.body)('isEncrypted')
+                        .optional()
+                        .isBoolean()
+                        .withMessage('isEncrypted must be a boolean'),
+                ],
+            },
+            {
+                method: 'get',
+                path: '/retrieve',
+                handlerKey: 'retrieveSCBL',
+                useAuthentication: false,
+                validation: [
+                    (0, express_validator_1.query)('magnetUrl')
+                        .isString()
+                        .notEmpty()
+                        .withMessage('magnetUrl is required and must be a non-empty string'),
+                ],
+            },
+        ];
+    }
+    /**
+     * Calculate the maximum data size that can fit in a single CBL
+     * based on the block size and CBL header overhead.
+     */
+    getCblThreshold() {
+        // A CBL can reference multiple blocks, but the CBL itself must fit in a block
+        // The threshold is approximately the block size minus header overhead
+        // For simplicity, we use a conservative estimate
+        const blockSize = this.blockStore.blockSize;
+        // CBL header is approximately 200 bytes, each address is 64 bytes
+        // A single CBL can reference (blockSize - 200) / 64 blocks
+        // Each block can hold blockSize bytes of data
+        const maxAddresses = Math.floor((blockSize - 200) / 64);
+        return maxAddresses * blockSize;
+    }
+    /**
+     * Store a large file as a Super CBL hierarchy.
+     * POST /api/scbl/store
+     *
+     * @requirements 2.1, 2.3, 2.5
+     */
+    async storeSCBL(_req) {
+        const body = this.validatedBody;
+        if (!isStoreSCBLRequest(body)) {
+            throw new i18n_lib_1.HandleableError(new Error('Invalid request body format'), {
+                statusCode: 400,
+            });
+        }
+        try {
+            // Decode file data from base64
+            const fileData = Buffer.from(body.data, 'base64');
+            const totalSize = fileData.length;
+            // Get durability level
+            const durabilityLevel = body.durabilityLevel
+                ? brightchain_lib_1.DurabilityMap[body.durabilityLevel]
+                : brightchain_lib_1.DurabilityLevel.Standard;
+            // Calculate CBL threshold to determine if we need Super CBL
+            const cblThreshold = this.getCblThreshold();
+            // If data fits in a single CBL, store it directly
+            if (totalSize <= cblThreshold) {
+                // Store as a regular CBL with whitening
+                const result = await this.blockStore.storeCBLWithWhitening(new Uint8Array(fileData), {
+                    durabilityLevel,
+                    isEncrypted: body.isEncrypted,
+                });
+                return {
+                    statusCode: 200,
+                    response: {
+                        success: true,
+                        message: 'File stored successfully as CBL',
+                        magnetUrl: result.magnetUrl,
+                        metadata: {
+                            hierarchyDepth: 0, // No hierarchy, just a single CBL
+                            subCblCount: 0,
+                            totalSize,
+                            rootBlockIds: [result.blockId1, result.blockId2],
+                        },
+                    },
+                };
+            }
+            // For larger files, we need to create a Super CBL hierarchy
+            // Split data into chunks that fit in individual CBLs
+            const chunkSize = cblThreshold;
+            const chunks = [];
+            for (let i = 0; i < totalSize; i += chunkSize) {
+                chunks.push(fileData.subarray(i, Math.min(i + chunkSize, totalSize)));
+            }
+            // Store each chunk as a CBL and collect their magnet URLs
+            const subCblResults = [];
+            for (const chunk of chunks) {
+                const result = await this.blockStore.storeCBLWithWhitening(new Uint8Array(chunk), {
+                    durabilityLevel, // Propagate durability level to sub-CBLs (Requirement 2.5)
+                    isEncrypted: body.isEncrypted,
+                });
+                subCblResults.push(result);
+            }
+            // Create the Super CBL header data containing references to sub-CBLs
+            // For now, we store the sub-CBL references as a JSON structure
+            // and whitened like a regular CBL
+            const superCblData = {
+                type: 'super-cbl',
+                version: 1,
+                subCblCount: subCblResults.length,
+                hierarchyDepth: 1,
+                totalSize,
+                isEncrypted: body.isEncrypted ?? false,
+                subCbls: subCblResults.map((r) => ({
+                    magnetUrl: r.magnetUrl,
+                    blockId1: r.blockId1,
+                    blockId2: r.blockId2,
+                })),
+            };
+            const superCblBytes = new TextEncoder().encode(JSON.stringify(superCblData));
+            // Store the Super CBL manifest with the same durability level
+            const rootResult = await this.blockStore.storeCBLWithWhitening(superCblBytes, {
+                durabilityLevel, // Propagate durability level (Requirement 2.5)
+                isEncrypted: false, // The manifest itself is not encrypted
+            });
+            return {
+                statusCode: 200,
+                response: {
+                    success: true,
+                    message: 'File stored successfully as Super CBL',
+                    magnetUrl: rootResult.magnetUrl,
+                    metadata: {
+                        hierarchyDepth: 1,
+                        subCblCount: subCblResults.length,
+                        totalSize,
+                        rootBlockIds: [rootResult.blockId1, rootResult.blockId2],
+                    },
+                },
+            };
+        }
+        catch (error) {
+            if (error instanceof brightchain_lib_1.StoreError) {
+                throw new i18n_lib_1.HandleableError(error, {
+                    statusCode: error.message.includes('too large') ? 413 : 500,
+                });
+            }
+            throw error;
+        }
+    }
+    /**
+     * Retrieve and reconstruct a file from its Super CBL hierarchy.
+     * GET /api/scbl/retrieve
+     *
+     * @requirements 2.2, 2.4
+     */
+    async retrieveSCBL(req) {
+        const { magnetUrl } = req.query;
+        if (!magnetUrl) {
+            throw new i18n_lib_1.HandleableError(new Error('magnetUrl query parameter is required'), { statusCode: 400 });
+        }
+        try {
+            // Parse the magnet URL to get block IDs
+            const components = this.blockStore.parseCBLMagnetUrl(magnetUrl);
+            // Retrieve the root CBL data
+            const rootData = await this.blockStore.retrieveCBL(components.blockId1, components.blockId2, components.block1ParityIds, components.block2ParityIds);
+            // Try to parse as Super CBL manifest
+            let superCblManifest = null;
+            try {
+                const decoded = new TextDecoder().decode(rootData);
+                const parsed = JSON.parse(decoded);
+                if (parsed.type === 'super-cbl') {
+                    superCblManifest = parsed;
+                }
+            }
+            catch {
+                // Not a Super CBL manifest, treat as regular CBL data
+            }
+            // If it's a regular CBL (not a Super CBL), return the data directly
+            if (!superCblManifest) {
+                return {
+                    statusCode: 200,
+                    response: {
+                        success: true,
+                        message: 'File retrieved successfully',
+                        data: Buffer.from(rootData).toString('base64'),
+                        isEncrypted: components.isEncrypted,
+                    },
+                };
+            }
+            // Recursively reconstruct file from sub-CBLs
+            const chunks = [];
+            for (let i = 0; i < superCblManifest.subCbls.length; i++) {
+                const subCbl = superCblManifest.subCbls[i];
+                try {
+                    // Parse sub-CBL magnet URL
+                    const subComponents = this.blockStore.parseCBLMagnetUrl(subCbl.magnetUrl);
+                    // Retrieve sub-CBL data
+                    const chunkData = await this.blockStore.retrieveCBL(subComponents.blockId1, subComponents.blockId2, subComponents.block1ParityIds, subComponents.block2ParityIds);
+                    chunks.push(chunkData);
+                }
+                catch (error) {
+                    // Handle missing sub-CBL (Requirement 2.4)
+                    if (error instanceof brightchain_lib_1.StoreError &&
+                        error.message.includes('not found')) {
+                        throw new i18n_lib_1.HandleableError(new Error(`Sub-CBL ${i + 1} of ${superCblManifest.subCblCount} not found: ${subCbl.magnetUrl}`), { statusCode: 404 });
+                    }
+                    throw error;
+                }
+            }
+            // Concatenate all chunks to reconstruct the original file
+            const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+            const reconstructedData = new Uint8Array(totalLength);
+            let offset = 0;
+            for (const chunk of chunks) {
+                reconstructedData.set(chunk, offset);
+                offset += chunk.length;
+            }
+            return {
+                statusCode: 200,
+                response: {
+                    success: true,
+                    message: 'File retrieved successfully from Super CBL',
+                    data: Buffer.from(reconstructedData).toString('base64'),
+                    isEncrypted: superCblManifest.isEncrypted,
+                },
+            };
+        }
+        catch (error) {
+            if (error instanceof i18n_lib_1.HandleableError) {
+                throw error;
+            }
+            if (error instanceof brightchain_lib_1.StoreError) {
+                throw new i18n_lib_1.HandleableError(error, {
+                    statusCode: error.message.includes('not found') ? 404 : 500,
+                });
+            }
+            if (error instanceof Error &&
+                error.message.includes('Invalid magnet URL')) {
+                throw new i18n_lib_1.HandleableError(error, { statusCode: 400 });
+            }
+            throw error;
+        }
+    }
+}
+exports.SCBLController = SCBLController;
+//# sourceMappingURL=scbl.js.map

package/src/lib/controllers/api/scbl.js.map

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

package/src/lib/controllers/api/sync.d.ts

@@ -0,0 +1,140 @@
+import { IAvailabilityService, IBlockLocationsResponse, IReconcileResponse, IReconciliationService, IReplicateBlockResponse, ISyncRequestResponse } from '@brightchain/brightchain-lib';
+import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
+import { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { ApiErrorResponse, ApiRequestHandler, TypedHandlers } from '@digitaldefiance/node-express-suite';
+import { IBrightChainApplication } from '../../interfaces/application';
+import { EventNotificationSystem } from '../../services/eventNotificationSystem';
+import { DefaultBackendIdType } from '../../shared-types';
+import { BaseController } from '../base';
+type SyncApiResponse = IReplicateBlockResponse | IBlockLocationsResponse | ISyncRequestResponse | IReconcileResponse | ApiErrorResponse;
+interface SyncHandlers extends TypedHandlers {
+    replicateBlock: ApiRequestHandler<IReplicateBlockResponse | ApiErrorResponse>;
+    getBlockLocations: ApiRequestHandler<IBlockLocationsResponse | ApiErrorResponse>;
+    syncRequest: ApiRequestHandler<ISyncRequestResponse | ApiErrorResponse>;
+    reconcile: ApiRequestHandler<IReconcileResponse | ApiErrorResponse>;
+}
+/**
+ * Controller for block replication and synchronization operations.
+ *
+ * Provides REST API endpoints for replicating blocks to other nodes,
+ * querying block locations, checking block availability, and triggering
+ * reconciliation with peers.
+ *
+ * ## Endpoints
+ *
+ * ### POST /api/blocks/:blockId/replicate
+ * Replicate a block to specified target nodes.
+ *
+ * **Parameters:**
+ * - `blockId` (string, required): Block ID to replicate
+ *
+ * **Request Body:**
+ * - `targetNodeIds` (string[], required): Array of node IDs to replicate to
+ *
+ * **Response:**
+ * - `blockId` (string): The block ID that was replicated
+ * - `replicationResults` (array): Results for each target node
+ *
+ * ### GET /api/blocks/:blockId/locations
+ * Get all known locations for a block.
+ *
+ * **Parameters:**
+ * - `blockId` (string, required): Block ID to query
+ *
+ * **Response:**
+ * - `blockId` (string): The block ID queried
+ * - `locations` (array): Array of location records
+ *
+ * ### POST /api/sync/request
+ * Check which blocks are available locally and which need to be fetched.
+ *
+ * **Request Body:**
+ * - `blockIds` (string[], required): Array of block IDs to check
+ *
+ * **Response:**
+ * - `available` (string[]): Block IDs available locally
+ * - `missing` (string[]): Block IDs that need to be fetched
+ * - `unknown` (string[]): Block IDs with unknown status
+ *
+ * ### POST /api/sync/reconcile
+ * Initiate reconciliation with connected peers.
+ *
+ * **Response:**
+ * - `result` (object): Reconciliation result with statistics
+ *
+ * @requirements 4.1, 4.2, 4.3, 4.4
+ */
+export declare class SyncController<TID extends PlatformID = DefaultBackendIdType> extends BaseController<TID, SyncApiResponse, SyncHandlers, CoreLanguageCode> {
+    private availabilityService;
+    private reconciliationService;
+    private eventSystem;
+    constructor(application: IBrightChainApplication<TID>);
+    /**
+     * Set the AvailabilityService instance.
+     * This allows for dependency injection and testing.
+     */
+    setAvailabilityService(service: IAvailabilityService): void;
+    /**
+     * Set the ReconciliationService instance.
+     * This allows for dependency injection and testing.
+     */
+    setReconciliationService(service: IReconciliationService): void;
+    /**
+     * Set the EventNotificationSystem instance.
+     * This allows for dependency injection and testing.
+     * @requirements 4.5
+     */
+    setEventSystem(eventSystem: EventNotificationSystem): void;
+    /**
+     * Get the AvailabilityService instance.
+     * Throws if the service has not been set.
+     */
+    private getAvailabilityService;
+    /**
+     * Get the ReconciliationService instance.
+     * Throws if the service has not been set.
+     */
+    private getReconciliationService;
+    protected initRouteDefinitions(): void;
+    /**
+     * Convert ILocationRecord to response format
+     */
+    private locationToInfo;
+    /**
+     * POST /api/sync/blocks/:blockId/replicate
+     * Replicate a block to specified target nodes.
+     *
+     * @param req - Request containing block ID and target node IDs
+     * @returns Replication results for each target node
+     * @requirements 4.1, 4.5
+     */
+    private handleReplicateBlock;
+    /**
+     * GET /api/sync/blocks/:blockId/locations
+     * Get all known locations for a block.
+     *
+     * @param req - Request containing the block ID parameter
+     * @returns Array of location records
+     * @requirements 4.2
+     */
+    private handleGetBlockLocations;
+    /**
+     * POST /api/sync/request
+     * Check which blocks are available locally and which need to be fetched.
+     *
+     * @param req - Request containing array of block IDs to check
+     * @returns Partitioned lists of available, missing, and unknown blocks
+     * @requirements 4.3
+     */
+    private handleSyncRequest;
+    /**
+     * POST /api/sync/reconcile
+     * Initiate reconciliation with connected peers.
+     *
+     * @returns Reconciliation result with statistics
+     * @requirements 4.4
+     */
+    private handleReconcile;
+}
+export {};
+//# sourceMappingURL=sync.d.ts.map

package/src/lib/controllers/api/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/controllers/api/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EAEpB,uBAAuB,EAEvB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EAEvB,oBAAoB,EACrB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC7D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EAEd,MAAM,qCAAqC,CAAC;AAM7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAM1D,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC,KAAK,eAAe,GAChB,uBAAuB,GACvB,uBAAuB,GACvB,oBAAoB,GACpB,kBAAkB,GAClB,gBAAgB,CAAC;AAErB,UAAU,YAAa,SAAQ,aAAa;IAC1C,cAAc,EAAE,iBAAiB,CAAC,uBAAuB,GAAG,gBAAgB,CAAC,CAAC;IAC9E,iBAAiB,EAAE,iBAAiB,CAClC,uBAAuB,GAAG,gBAAgB,CAC3C,CAAC;IACF,WAAW,EAAE,iBAAiB,CAAC,oBAAoB,GAAG,gBAAgB,CAAC,CAAC;IACxE,SAAS,EAAE,iBAAiB,CAAC,kBAAkB,GAAG,gBAAgB,CAAC,CAAC;CACrE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,qBAAa,cAAc,CACzB,GAAG,SAAS,UAAU,GAAG,oBAAoB,CAC7C,SAAQ,cAAc,CAAC,GAAG,EAAE,eAAe,EAAE,YAAY,EAAE,gBAAgB,CAAC;IAC5E,OAAO,CAAC,mBAAmB,CAAqC;IAChE,OAAO,CAAC,qBAAqB,CAAuC;IACpE,OAAO,CAAC,WAAW,CAAwC;gBAE/C,WAAW,EAAE,uBAAuB,CAAC,GAAG,CAAC;IAIrD;;;OAGG;IACI,sBAAsB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAIlE;;;OAGG;IACI,wBAAwB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI;IAItE;;;;OAIG;IACI,cAAc,CAAC,WAAW,EAAE,uBAAuB,GAAG,IAAI;IAIjE;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAO9B;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAOhC,SAAS,CAAC,oBAAoB,IAAI,IAAI;IAgCtC;;OAEG;IACH,OAAO,CAAC,cAAc;IAStB;;;;;;;OAOG;YACW,oBAAoB;IAiGlC;;;;;;;OAOG;YACW,uBAAuB;IA2BrC;;;;;;;OAOG;YACW,iBAAiB;IA8D/B;;;;;;OAMG;YACW,eAAe;CA8B9B"}