@open-captable-protocol/canton 0.2.192 → 0.2.193

package/dist/functions/OpenCapTable/capTable/getCapTableState.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Query Canton for the current state of a CapTable contract.
+ *
+ * Provides a snapshot of all OCF entities currently on-chain for an issuer,
+ * enabling stateless replication by comparing against database state.
+ *
+ * @module getCapTableState
+ */
+import type { LedgerJsonApiClient } from '@fairmint/canton-node-sdk';
+import type { OcfEntityType } from './batchTypes';
+/**
+ * Mapping from CapTable contract field names (snake_case) to OcfEntityType (camelCase).
+ *
+ * Each field in the CapTable DAML contract is a Map from OCF ID (Text) to ContractId.
+ * This mapping allows extraction of entity inventories from the contract payload.
+ *
+ * Note: planSecurity* types (7 total) are intentionally omitted from this mapping.
+ * They are aliases for equityCompensation* types and are stored under equity_compensation_*
+ * fields in Canton. The SDK normalizes planSecurity → equityCompensation during upload.
+ */
+export declare const FIELD_TO_ENTITY_TYPE: Record<string, OcfEntityType>;
+/**
+ * Current state of a CapTable on Canton, with all OCF IDs grouped by entity type.
+ */
+export interface CapTableState {
+    /** Contract ID of the CapTable contract. */
+    capTableContractId: string;
+    /** Contract ID of the Issuer contract (referenced by the CapTable). */
+    issuerContractId: string;
+    /**
+     * Map of entity type to OCF IDs currently on-chain.
+     * Each entry contains all OCF object IDs of that type in the CapTable.
+     */
+    entities: Map<OcfEntityType, Set<string>>;
+    /**
+     * Map of entity type to (OCF ID → Contract ID) for fetching individual contracts.
+     * Useful for deep verification where contract data needs to be compared.
+     */
+    contractIds: Map<OcfEntityType, Map<string, string>>;
+}
+/**
+ * Query Canton for the current state of a CapTable.
+ *
+ * Uses getActiveContracts filtered by party to efficiently retrieve only
+ * the CapTable contract for the specified issuer.
+ *
+ * Note: In the standard deployment model, each issuer party has exactly one
+ * active CapTable contract. If multiple CapTable contracts exist for the same
+ * party (which would indicate a configuration issue), this function returns
+ * the first one found. The system design ensures this is a 1:1 relationship.
+ *
+ * @param client - LedgerJsonApiClient instance
+ * @param issuerPartyId - Party ID of the issuer
+ * @returns CapTableState with all OCF IDs on-chain, or null if no CapTable exists
+ *
+ * @example
+ * ```typescript
+ * const state = await getCapTableState(client, 'issuer::party123');
+ * if (state) {
+ *   const stakeholderIds = state.entities.get('stakeholder') ?? new Set();
+ *   console.log(`${stakeholderIds.size} stakeholders on-chain`);
+ * }
+ * ```
+ */
+export declare function getCapTableState(client: LedgerJsonApiClient, issuerPartyId: string): Promise<CapTableState | null>;
+//# sourceMappingURL=getCapTableState.d.ts.map

package/dist/functions/OpenCapTable/capTable/getCapTableState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getCapTableState.d.ts","sourceRoot":"","sources":["../../../../src/functions/OpenCapTable/capTable/getCapTableState.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAGrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAiE9D,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,kBAAkB,EAAE,MAAM,CAAC;IAE3B,uEAAuE;IACvE,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,QAAQ,EAAE,GAAG,CAAC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAE1C;;;OAGG;IACH,WAAW,EAAE,GAAG,CAAC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,mBAAmB,EAC3B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAuD/B"}

package/dist/functions/OpenCapTable/capTable/getCapTableState.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Query Canton for the current state of a CapTable contract.
+ *
+ * Provides a snapshot of all OCF entities currently on-chain for an issuer,
+ * enabling stateless replication by comparing against database state.
+ *
+ * @module getCapTableState
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIELD_TO_ENTITY_TYPE = void 0;
+exports.getCapTableState = getCapTableState;
+const open_captable_protocol_daml_js_1 = require("@fairmint/open-captable-protocol-daml-js");
+/**
+ * Mapping from CapTable contract field names (snake_case) to OcfEntityType (camelCase).
+ *
+ * Each field in the CapTable DAML contract is a Map from OCF ID (Text) to ContractId.
+ * This mapping allows extraction of entity inventories from the contract payload.
+ *
+ * Note: planSecurity* types (7 total) are intentionally omitted from this mapping.
+ * They are aliases for equityCompensation* types and are stored under equity_compensation_*
+ * fields in Canton. The SDK normalizes planSecurity → equityCompensation during upload.
+ */
+exports.FIELD_TO_ENTITY_TYPE = {
+    // Core Objects (7 types)
+    stakeholders: 'stakeholder',
+    stock_classes: 'stockClass',
+    stock_plans: 'stockPlan',
+    vesting_terms: 'vestingTerms',
+    stock_legend_templates: 'stockLegendTemplate',
+    documents: 'document',
+    valuations: 'valuation',
+    // Stock Class Adjustments (4 types)
+    stock_class_authorized_shares_adjustments: 'stockClassAuthorizedSharesAdjustment',
+    stock_class_conversion_ratio_adjustments: 'stockClassConversionRatioAdjustment',
+    stock_class_splits: 'stockClassSplit',
+    issuer_authorized_shares_adjustments: 'issuerAuthorizedSharesAdjustment',
+    // Stock Transactions (9 types)
+    stock_issuances: 'stockIssuance',
+    stock_cancellations: 'stockCancellation',
+    stock_transfers: 'stockTransfer',
+    stock_acceptances: 'stockAcceptance',
+    stock_conversions: 'stockConversion',
+    stock_repurchases: 'stockRepurchase',
+    stock_reissuances: 'stockReissuance',
+    stock_retractions: 'stockRetraction',
+    stock_consolidations: 'stockConsolidation',
+    // Equity Compensation (8 types)
+    equity_compensation_issuances: 'equityCompensationIssuance',
+    equity_compensation_cancellations: 'equityCompensationCancellation',
+    equity_compensation_transfers: 'equityCompensationTransfer',
+    equity_compensation_acceptances: 'equityCompensationAcceptance',
+    equity_compensation_exercises: 'equityCompensationExercise',
+    equity_compensation_releases: 'equityCompensationRelease',
+    equity_compensation_repricings: 'equityCompensationRepricing',
+    equity_compensation_retractions: 'equityCompensationRetraction',
+    // Convertibles (6 types)
+    convertible_issuances: 'convertibleIssuance',
+    convertible_cancellations: 'convertibleCancellation',
+    convertible_transfers: 'convertibleTransfer',
+    convertible_acceptances: 'convertibleAcceptance',
+    convertible_conversions: 'convertibleConversion',
+    convertible_retractions: 'convertibleRetraction',
+    // Warrants (6 types)
+    warrant_issuances: 'warrantIssuance',
+    warrant_cancellations: 'warrantCancellation',
+    warrant_transfers: 'warrantTransfer',
+    warrant_acceptances: 'warrantAcceptance',
+    warrant_exercises: 'warrantExercise',
+    warrant_retractions: 'warrantRetraction',
+    // Stock Plan Events (2 types)
+    stock_plan_pool_adjustments: 'stockPlanPoolAdjustment',
+    stock_plan_return_to_pools: 'stockPlanReturnToPool',
+    // Vesting Events (3 types)
+    vesting_accelerations: 'vestingAcceleration',
+    vesting_events: 'vestingEvent',
+    vesting_starts: 'vestingStart',
+    // Stakeholder Events (2 types)
+    stakeholder_relationship_change_events: 'stakeholderRelationshipChangeEvent',
+    stakeholder_status_change_events: 'stakeholderStatusChangeEvent',
+};
+/**
+ * Query Canton for the current state of a CapTable.
+ *
+ * Uses getActiveContracts filtered by party to efficiently retrieve only
+ * the CapTable contract for the specified issuer.
+ *
+ * Note: In the standard deployment model, each issuer party has exactly one
+ * active CapTable contract. If multiple CapTable contracts exist for the same
+ * party (which would indicate a configuration issue), this function returns
+ * the first one found. The system design ensures this is a 1:1 relationship.
+ *
+ * @param client - LedgerJsonApiClient instance
+ * @param issuerPartyId - Party ID of the issuer
+ * @returns CapTableState with all OCF IDs on-chain, or null if no CapTable exists
+ *
+ * @example
+ * ```typescript
+ * const state = await getCapTableState(client, 'issuer::party123');
+ * if (state) {
+ *   const stakeholderIds = state.entities.get('stakeholder') ?? new Set();
+ *   console.log(`${stakeholderIds.size} stakeholders on-chain`);
+ * }
+ * ```
+ */
+async function getCapTableState(client, issuerPartyId) {
+    // Query for CapTable contract by party
+    // Use the DAML-JS package's templateId for compatibility with deployed packages.
+    const contracts = await client.getActiveContracts({
+        parties: [issuerPartyId],
+        templateIds: [open_captable_protocol_daml_js_1.Fairmint.OpenCapTable.CapTable.CapTable.templateId],
+    });
+    if (contracts.length === 0) {
+        return null;
+    }
+    // Extract payload from the first matching contract
+    const capTableContract = contracts[0];
+    const contractData = capTableContract;
+    const contractId = contractData.contractId ?? contractData.contract_id ?? '';
+    const payload = contractData.payload ?? contractData.contract?.payload ?? {};
+    // Build entity maps from payload fields
+    const entities = new Map();
+    const contractIds = new Map();
+    for (const [field, entityType] of Object.entries(exports.FIELD_TO_ENTITY_TYPE)) {
+        const fieldData = payload[field];
+        if (fieldData && typeof fieldData === 'object') {
+            // DAML Map is serialized as an object with OCF IDs as keys
+            const ocfIdToContractId = fieldData;
+            const ocfIds = new Set(Object.keys(ocfIdToContractId));
+            if (ocfIds.size > 0) {
+                entities.set(entityType, ocfIds);
+                contractIds.set(entityType, new Map(Object.entries(ocfIdToContractId)));
+            }
+        }
+    }
+    // Extract issuer contract ID from payload
+    const issuerContractId = typeof payload.issuer === 'string' ? payload.issuer : '';
+    return {
+        capTableContractId: contractId,
+        issuerContractId,
+        entities,
+        contractIds,
+    };
+}
+//# sourceMappingURL=getCapTableState.js.map

package/dist/functions/OpenCapTable/capTable/getCapTableState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getCapTableState.js","sourceRoot":"","sources":["../../../../src/functions/OpenCapTable/capTable/getCapTableState.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAmIH,4CA0DC;AA1LD,6FAAoE;AAIpE;;;;;;;;;GASG;AACU,QAAA,oBAAoB,GAAkC;IACjE,yBAAyB;IACzB,YAAY,EAAE,aAAa;IAC3B,aAAa,EAAE,YAAY;IAC3B,WAAW,EAAE,WAAW;IACxB,aAAa,EAAE,cAAc;IAC7B,sBAAsB,EAAE,qBAAqB;IAC7C,SAAS,EAAE,UAAU;IACrB,UAAU,EAAE,WAAW;IAEvB,oCAAoC;IACpC,yCAAyC,EAAE,sCAAsC;IACjF,wCAAwC,EAAE,qCAAqC;IAC/E,kBAAkB,EAAE,iBAAiB;IACrC,oCAAoC,EAAE,kCAAkC;IAExE,+BAA+B;IAC/B,eAAe,EAAE,eAAe;IAChC,mBAAmB,EAAE,mBAAmB;IACxC,eAAe,EAAE,eAAe;IAChC,iBAAiB,EAAE,iBAAiB;IACpC,iBAAiB,EAAE,iBAAiB;IACpC,iBAAiB,EAAE,iBAAiB;IACpC,iBAAiB,EAAE,iBAAiB;IACpC,iBAAiB,EAAE,iBAAiB;IACpC,oBAAoB,EAAE,oBAAoB;IAE1C,gCAAgC;IAChC,6BAA6B,EAAE,4BAA4B;IAC3D,iCAAiC,EAAE,gCAAgC;IACnE,6BAA6B,EAAE,4BAA4B;IAC3D,+BAA+B,EAAE,8BAA8B;IAC/D,6BAA6B,EAAE,4BAA4B;IAC3D,4BAA4B,EAAE,2BAA2B;IACzD,8BAA8B,EAAE,6BAA6B;IAC7D,+BAA+B,EAAE,8BAA8B;IAE/D,yBAAyB;IACzB,qBAAqB,EAAE,qBAAqB;IAC5C,yBAAyB,EAAE,yBAAyB;IACpD,qBAAqB,EAAE,qBAAqB;IAC5C,uBAAuB,EAAE,uBAAuB;IAChD,uBAAuB,EAAE,uBAAuB;IAChD,uBAAuB,EAAE,uBAAuB;IAEhD,qBAAqB;IACrB,iBAAiB,EAAE,iBAAiB;IACpC,qBAAqB,EAAE,qBAAqB;IAC5C,iBAAiB,EAAE,iBAAiB;IACpC,mBAAmB,EAAE,mBAAmB;IACxC,iBAAiB,EAAE,iBAAiB;IACpC,mBAAmB,EAAE,mBAAmB;IAExC,8BAA8B;IAC9B,2BAA2B,EAAE,yBAAyB;IACtD,0BAA0B,EAAE,uBAAuB;IAEnD,2BAA2B;IAC3B,qBAAqB,EAAE,qBAAqB;IAC5C,cAAc,EAAE,cAAc;IAC9B,cAAc,EAAE,cAAc;IAE9B,+BAA+B;IAC/B,sCAAsC,EAAE,oCAAoC;IAC5E,gCAAgC,EAAE,8BAA8B;CACjE,CAAC;AAyBF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACI,KAAK,UAAU,gBAAgB,CACpC,MAA2B,EAC3B,aAAqB;IAErB,uCAAuC;IACvC,iFAAiF;IACjF,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC;QAChD,OAAO,EAAE,CAAC,aAAa,CAAC;QACxB,WAAW,EAAE,CAAC,yCAAQ,CAAC,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC;KAClE,CAAC,CAAC;IAEH,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,mDAAmD;IACnD,MAAM,gBAAgB,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAUtC,MAAM,YAAY,GAAG,gBAA8C,CAAC;IACpE,MAAM,UAAU,GAAG,YAAY,CAAC,UAAU,IAAI,YAAY,CAAC,WAAW,IAAI,EAAE,CAAC;IAC7E,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,IAAI,YAAY,CAAC,QAAQ,EAAE,OAAO,IAAI,EAAE,CAAC;IAE7E,wCAAwC;IACxC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA8B,CAAC;IACvD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAsC,CAAC;IAElE,KAAK,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,4BAAoB,CAAC,EAAE,CAAC;QACvE,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;QAEjC,IAAI,SAAS,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;YAC/C,2DAA2D;YAC3D,MAAM,iBAAiB,GAAG,SAAmC,CAAC;YAC9D,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC;YAEvD,IAAI,MAAM,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;gBACpB,QAAQ,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;gBACjC,WAAW,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;YAC1E,CAAC;QACH,CAAC;IACH,CAAC;IAED,0CAA0C;IAC1C,MAAM,gBAAgB,GAAG,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAElF,OAAO;QACL,kBAAkB,EAAE,UAAU;QAC9B,gBAAgB;QAChB,QAAQ;QACR,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/functions/OpenCapTable/capTable/index.d.ts

@@ -4,4 +4,5 @@ export * from './batchTypes';
 export { CapTableBatch, buildUpdateCapTableCommand, type CapTableBatchParams } from './CapTableBatch';
 export { convertToDaml } from './ocfToDaml';
 export { ENTITY_DATA_FIELD_MAP, convertToOcf, extractCreateArgument, extractEntityData, getEntityAsOcf, type GetEntityAsOcfResult, type SupportedOcfReadType, } from './damlToOcf';
+export { FIELD_TO_ENTITY_TYPE, getCapTableState, type CapTableState } from './getCapTableState';
 //# sourceMappingURL=index.d.ts.map

package/dist/functions/OpenCapTable/capTable/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/functions/OpenCapTable/capTable/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,SAAS,CAAC;AAGxB,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,0BAA0B,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtG,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EACL,qBAAqB,EACrB,YAAY,EACZ,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/functions/OpenCapTable/capTable/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,SAAS,CAAC;AAGxB,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,0BAA0B,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtG,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EACL,qBAAqB,EACrB,YAAY,EACZ,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/functions/OpenCapTable/capTable/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getEntityAsOcf = exports.extractEntityData = exports.extractCreateArgument = exports.convertToOcf = exports.ENTITY_DATA_FIELD_MAP = exports.convertToDaml = exports.buildUpdateCapTableCommand = exports.CapTableBatch = void 0;
+exports.getCapTableState = exports.FIELD_TO_ENTITY_TYPE = exports.getEntityAsOcf = exports.extractEntityData = exports.extractCreateArgument = exports.convertToOcf = exports.ENTITY_DATA_FIELD_MAP = exports.convertToDaml = exports.buildUpdateCapTableCommand = exports.CapTableBatch = void 0;
 __exportStar(require("./buildCapTableCommand"), exports);
 __exportStar(require("./types"), exports);
 // Batch API exports
@@ -31,4 +31,8 @@ Object.defineProperty(exports, "convertToOcf", { enumerable: true, get: function
 Object.defineProperty(exports, "extractCreateArgument", { enumerable: true, get: function () { return damlToOcf_1.extractCreateArgument; } });
 Object.defineProperty(exports, "extractEntityData", { enumerable: true, get: function () { return damlToOcf_1.extractEntityData; } });
 Object.defineProperty(exports, "getEntityAsOcf", { enumerable: true, get: function () { return damlToOcf_1.getEntityAsOcf; } });
+// CapTable state reader (for replication)
+var getCapTableState_1 = require("./getCapTableState");
+Object.defineProperty(exports, "FIELD_TO_ENTITY_TYPE", { enumerable: true, get: function () { return getCapTableState_1.FIELD_TO_ENTITY_TYPE; } });
+Object.defineProperty(exports, "getCapTableState", { enumerable: true, get: function () { return getCapTableState_1.getCapTableState; } });
 //# sourceMappingURL=index.js.map

package/dist/functions/OpenCapTable/capTable/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/functions/OpenCapTable/capTable/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,0CAAwB;AAExB,oBAAoB;AACpB,+CAA6B;AAC7B,iDAAsG;AAA7F,8GAAA,aAAa,OAAA;AAAE,2HAAA,0BAA0B,OAAA;AAClD,yCAA4C;AAAnC,0GAAA,aAAa,OAAA;AAEtB,2CAA2C;AAC3C,yCAQqB;AAPnB,kHAAA,qBAAqB,OAAA;AACrB,yGAAA,YAAY,OAAA;AACZ,kHAAA,qBAAqB,OAAA;AACrB,8GAAA,iBAAiB,OAAA;AACjB,2GAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/functions/OpenCapTable/capTable/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,0CAAwB;AAExB,oBAAoB;AACpB,+CAA6B;AAC7B,iDAAsG;AAA7F,8GAAA,aAAa,OAAA;AAAE,2HAAA,0BAA0B,OAAA;AAClD,yCAA4C;AAAnC,0GAAA,aAAa,OAAA;AAEtB,2CAA2C;AAC3C,yCAQqB;AAPnB,kHAAA,qBAAqB,OAAA;AACrB,yGAAA,YAAY,OAAA;AACZ,kHAAA,qBAAqB,OAAA;AACrB,8GAAA,iBAAiB,OAAA;AACjB,2GAAA,cAAc,OAAA;AAKhB,0CAA0C;AAC1C,uDAAgG;AAAvF,wHAAA,oBAAoB,OAAA;AAAE,oHAAA,gBAAgB,OAAA"}

package/dist/utils/index.d.ts

@@ -5,6 +5,7 @@ export * from './ocfComparison';
 export * from './ocfHelpers';
 export * from './ocfMetadata';
 export * from './planSecurityAliases';
+export * from './replicationHelpers';
 export * from './transactionHelpers';
 export * from './typeConversions';
 export * from './typeGuards';

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}

package/dist/utils/index.js

@@ -21,6 +21,7 @@ __exportStar(require("./ocfComparison"), exports);
 __exportStar(require("./ocfHelpers"), exports);
 __exportStar(require("./ocfMetadata"), exports);
 __exportStar(require("./planSecurityAliases"), exports);
+__exportStar(require("./replicationHelpers"), exports);
 __exportStar(require("./transactionHelpers"), exports);
 __exportStar(require("./typeConversions"), exports);
 __exportStar(require("./typeGuards"), exports);

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iEAA+C;AAC/C,qDAAmC;AACnC,oDAAkC;AAClC,kDAAgC;AAChC,+CAA6B;AAC7B,gDAA8B;AAC9B,wDAAsC;AACtC,uDAAqC;AACrC,oDAAkC;AAClC,+CAA6B;AAC7B,+CAA6B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iEAA+C;AAC/C,qDAAmC;AACnC,oDAAkC;AAClC,kDAAgC;AAChC,+CAA6B;AAC7B,gDAA8B;AAC9B,wDAAsC;AACtC,uDAAqC;AACrC,uDAAqC;AACrC,oDAAkC;AAClC,+CAA6B;AAC7B,+CAA6B"}

package/dist/utils/replicationHelpers.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Replication helpers for cap table synchronization.
+ *
+ * Provides utilities for:
+ * - Mapping database types to SDK entity types
+ * - Computing replication diffs between DB and Canton state
+ * - Human-readable labels for display
+ *
+ * @module replicationHelpers
+ */
+import type { OcfEntityType } from '../functions/OpenCapTable/capTable/batchTypes';
+import type { CapTableState } from '../functions/OpenCapTable/capTable/getCapTableState';
+/**
+ * Map database type/subtype to OcfEntityType.
+ *
+ * The database schema uses:
+ * - Direct types: STAKEHOLDER, STOCK_CLASS, STOCK_PLAN stored in `type` column
+ * - Object subtypes: type='OBJECT', actual type in `subtype` column
+ * - Transaction subtypes: type='TRANSACTION', actual type in `subtype` column (TX_ prefix)
+ *
+ * @param dbType - The database OCF type (STAKEHOLDER, OBJECT, TRANSACTION, etc.)
+ * @param dbSubtype - The database subtype for OBJECT and TRANSACTION types
+ * @returns The corresponding OcfEntityType, or null if not supported
+ *
+ * @example
+ * ```typescript
+ * mapDbTypeToEntityType('STAKEHOLDER', null); // 'stakeholder'
+ * mapDbTypeToEntityType('OBJECT', 'DOCUMENT'); // 'document'
+ * mapDbTypeToEntityType('TRANSACTION', 'TX_STOCK_ISSUANCE'); // 'stockIssuance'
+ * ```
+ */
+export declare function mapDbTypeToEntityType(dbType: string, dbSubtype: string | null): OcfEntityType | null;
+/**
+ * Get a human-readable label for an entity type with count.
+ *
+ * @param type - The OcfEntityType
+ * @param count - The count (determines singular vs plural)
+ * @returns Human-readable string like "3 Stock Classes" or "1 Stakeholder"
+ *
+ * @example
+ * ```typescript
+ * getEntityTypeLabel('stockClass', 1); // "1 Stock Class"
+ * getEntityTypeLabel('stockClass', 3); // "3 Stock Classes"
+ * getEntityTypeLabel('stakeholder', 0); // "0 Stakeholders"
+ * ```
+ */
+export declare function getEntityTypeLabel(type: OcfEntityType, count: number): string;
+/**
+ * A single item to be synced from DB to Canton.
+ */
+export interface ReplicationItem {
+    /** OCF object ID */
+    ocfId: string;
+    /** Entity type (SDK format) */
+    entityType: OcfEntityType;
+    /** Operation to perform */
+    operation: 'create' | 'edit' | 'delete';
+    /** OCF data for create/edit operations */
+    data?: unknown;
+}
+/**
+ * Result of comparing DB state (desired) to Canton state (actual).
+ */
+export interface ReplicationDiff {
+    /** Items in DB but not in Canton - need to be created */
+    creates: ReplicationItem[];
+    /** Items in both - may need to be edited */
+    edits: ReplicationItem[];
+    /** Items in Canton but not in DB - may need to be deleted */
+    deletes: ReplicationItem[];
+    /** Total number of operations */
+    total: number;
+}
+/**
+ * Options for computing the replication diff.
+ */
+export interface ComputeReplicationDiffOptions {
+    /**
+     * Whether to include delete operations for items in Canton but not in DB.
+     * Default: false (safer - doesn't delete data)
+     */
+    syncDeletes?: boolean;
+    /**
+     * Whether to always include edit operations for items that exist in both.
+     * When true: All existing items are marked as edits (ensures sync)
+     * When false: Only new items are marked as creates (existence check only)
+     * Default: false
+     */
+    alwaysEdit?: boolean;
+}
+/**
+ * Compute what needs to be synced from DB to Canton.
+ *
+ * Compares a list of DB items (desired state) against Canton state (actual state)
+ * and returns operations needed to synchronize them.
+ *
+ * @param dbItems - OCF items from database (desired state)
+ * @param cantonState - Current Canton state from getCapTableState()
+ * @param options - Sync options
+ * @returns Replication diff with creates, edits, and deletes
+ *
+ * @example
+ * ```typescript
+ * const dbItems = [
+ *   { ocfId: 'stakeholder-1', entityType: 'stakeholder', data: {...} },
+ *   { ocfId: 'stock-class-1', entityType: 'stockClass', data: {...} },
+ * ];
+ * const cantonState = await getCapTableState(client, issuerPartyId);
+ * const diff = computeReplicationDiff(dbItems, cantonState, { syncDeletes: true });
+ * // diff.creates = items in DB but not Canton
+ * // diff.deletes = items in Canton but not DB
+ * ```
+ */
+export declare function computeReplicationDiff(dbItems: Array<{
+    ocfId: string;
+    entityType: OcfEntityType;
+    data: unknown;
+}>, cantonState: CapTableState, options?: ComputeReplicationDiffOptions): ReplicationDiff;
+//# sourceMappingURL=replicationHelpers.d.ts.map

package/dist/utils/replicationHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replicationHelpers.d.ts","sourceRoot":"","sources":["../../src/utils/replicationHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+CAA+C,CAAC;AACnF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAC;AAqGzF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,aAAa,GAAG,IAAI,CAiBpG;AA2FD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI7E;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,UAAU,EAAE,aAAa,CAAC;IAC1B,2BAA2B;IAC3B,SAAS,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;IACxC,0CAA0C;IAC1C,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,4CAA4C;IAC5C,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,6DAA6D;IAC7D,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,EAC3E,WAAW,EAAE,aAAa,EAC1B,OAAO,GAAE,6BAAkC,GAC1C,eAAe,CAiFjB"}

package/dist/utils/replicationHelpers.js

@@ -0,0 +1,330 @@
+"use strict";
+/**
+ * Replication helpers for cap table synchronization.
+ *
+ * Provides utilities for:
+ * - Mapping database types to SDK entity types
+ * - Computing replication diffs between DB and Canton state
+ * - Human-readable labels for display
+ *
+ * @module replicationHelpers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapDbTypeToEntityType = mapDbTypeToEntityType;
+exports.getEntityTypeLabel = getEntityTypeLabel;
+exports.computeReplicationDiff = computeReplicationDiff;
+const planSecurityAliases_1 = require("./planSecurityAliases");
+// ============================================================================
+// DB Type Mapping
+// ============================================================================
+/**
+ * Direct database type to OcfEntityType mappings.
+ * These types are stored directly in the `type` column.
+ */
+const DIRECT_TYPE_MAP = {
+    STAKEHOLDER: 'stakeholder',
+    STOCK_CLASS: 'stockClass',
+    STOCK_PLAN: 'stockPlan',
+};
+/**
+ * OBJECT subtype to OcfEntityType mappings.
+ * These are stored with type='OBJECT' and the actual type in subtype.
+ */
+const OBJECT_SUBTYPE_MAP = {
+    DOCUMENT: 'document',
+    VESTING_TERMS: 'vestingTerms',
+    STOCK_LEGEND_TEMPLATE: 'stockLegendTemplate',
+    VALUATION: 'valuation',
+};
+/**
+ * TRANSACTION subtype to OcfEntityType mappings.
+ * These are stored with type='TRANSACTION' and the actual type in subtype.
+ * DB uses TX_ prefix with UPPER_SNAKE_CASE, SDK uses camelCase.
+ */
+const TRANSACTION_SUBTYPE_MAP = {
+    // Stock Transactions (9 types)
+    TX_STOCK_ISSUANCE: 'stockIssuance',
+    TX_STOCK_CANCELLATION: 'stockCancellation',
+    TX_STOCK_TRANSFER: 'stockTransfer',
+    TX_STOCK_ACCEPTANCE: 'stockAcceptance',
+    TX_STOCK_CONVERSION: 'stockConversion',
+    TX_STOCK_REPURCHASE: 'stockRepurchase',
+    TX_STOCK_REISSUANCE: 'stockReissuance',
+    TX_STOCK_RETRACTION: 'stockRetraction',
+    TX_STOCK_CONSOLIDATION: 'stockConsolidation',
+    // Equity Compensation (8 types)
+    TX_EQUITY_COMPENSATION_ISSUANCE: 'equityCompensationIssuance',
+    TX_EQUITY_COMPENSATION_CANCELLATION: 'equityCompensationCancellation',
+    TX_EQUITY_COMPENSATION_TRANSFER: 'equityCompensationTransfer',
+    TX_EQUITY_COMPENSATION_ACCEPTANCE: 'equityCompensationAcceptance',
+    TX_EQUITY_COMPENSATION_EXERCISE: 'equityCompensationExercise',
+    TX_EQUITY_COMPENSATION_RELEASE: 'equityCompensationRelease',
+    TX_EQUITY_COMPENSATION_REPRICING: 'equityCompensationRepricing',
+    TX_EQUITY_COMPENSATION_RETRACTION: 'equityCompensationRetraction',
+    // Convertibles (6 types)
+    TX_CONVERTIBLE_ISSUANCE: 'convertibleIssuance',
+    TX_CONVERTIBLE_CANCELLATION: 'convertibleCancellation',
+    TX_CONVERTIBLE_TRANSFER: 'convertibleTransfer',
+    TX_CONVERTIBLE_ACCEPTANCE: 'convertibleAcceptance',
+    TX_CONVERTIBLE_CONVERSION: 'convertibleConversion',
+    TX_CONVERTIBLE_RETRACTION: 'convertibleRetraction',
+    // Warrants (6 types)
+    TX_WARRANT_ISSUANCE: 'warrantIssuance',
+    TX_WARRANT_CANCELLATION: 'warrantCancellation',
+    TX_WARRANT_TRANSFER: 'warrantTransfer',
+    TX_WARRANT_ACCEPTANCE: 'warrantAcceptance',
+    TX_WARRANT_EXERCISE: 'warrantExercise',
+    TX_WARRANT_RETRACTION: 'warrantRetraction',
+    // Stock Class Adjustments (4 types)
+    TX_STOCK_CLASS_AUTHORIZED_SHARES_ADJUSTMENT: 'stockClassAuthorizedSharesAdjustment',
+    TX_STOCK_CLASS_CONVERSION_RATIO_ADJUSTMENT: 'stockClassConversionRatioAdjustment',
+    TX_STOCK_CLASS_SPLIT: 'stockClassSplit',
+    TX_ISSUER_AUTHORIZED_SHARES_ADJUSTMENT: 'issuerAuthorizedSharesAdjustment',
+    // Stock Plan Events (2 types)
+    TX_STOCK_PLAN_POOL_ADJUSTMENT: 'stockPlanPoolAdjustment',
+    TX_STOCK_PLAN_RETURN_TO_POOL: 'stockPlanReturnToPool',
+    // Vesting Events (3 types)
+    TX_VESTING_ACCELERATION: 'vestingAcceleration',
+    TX_VESTING_EVENT: 'vestingEvent',
+    TX_VESTING_START: 'vestingStart',
+    // Stakeholder Events (2 types)
+    TX_STAKEHOLDER_RELATIONSHIP_CHANGE_EVENT: 'stakeholderRelationshipChangeEvent',
+    TX_STAKEHOLDER_STATUS_CHANGE_EVENT: 'stakeholderStatusChangeEvent',
+    // Plan Security (7 types) - aliases for Equity Compensation in legacy OCF
+    // These map to equityCompensation* types in Canton (planSecurity is an alias)
+    TX_PLAN_SECURITY_ISSUANCE: 'planSecurityIssuance',
+    TX_PLAN_SECURITY_CANCELLATION: 'planSecurityCancellation',
+    TX_PLAN_SECURITY_TRANSFER: 'planSecurityTransfer',
+    TX_PLAN_SECURITY_ACCEPTANCE: 'planSecurityAcceptance',
+    TX_PLAN_SECURITY_EXERCISE: 'planSecurityExercise',
+    TX_PLAN_SECURITY_RELEASE: 'planSecurityRelease',
+    TX_PLAN_SECURITY_RETRACTION: 'planSecurityRetraction',
+};
+/**
+ * Map database type/subtype to OcfEntityType.
+ *
+ * The database schema uses:
+ * - Direct types: STAKEHOLDER, STOCK_CLASS, STOCK_PLAN stored in `type` column
+ * - Object subtypes: type='OBJECT', actual type in `subtype` column
+ * - Transaction subtypes: type='TRANSACTION', actual type in `subtype` column (TX_ prefix)
+ *
+ * @param dbType - The database OCF type (STAKEHOLDER, OBJECT, TRANSACTION, etc.)
+ * @param dbSubtype - The database subtype for OBJECT and TRANSACTION types
+ * @returns The corresponding OcfEntityType, or null if not supported
+ *
+ * @example
+ * ```typescript
+ * mapDbTypeToEntityType('STAKEHOLDER', null); // 'stakeholder'
+ * mapDbTypeToEntityType('OBJECT', 'DOCUMENT'); // 'document'
+ * mapDbTypeToEntityType('TRANSACTION', 'TX_STOCK_ISSUANCE'); // 'stockIssuance'
+ * ```
+ */
+function mapDbTypeToEntityType(dbType, dbSubtype) {
+    // Direct mappings
+    if (dbType in DIRECT_TYPE_MAP) {
+        return DIRECT_TYPE_MAP[dbType];
+    }
+    // Object subtypes
+    if (dbType === 'OBJECT' && dbSubtype) {
+        return OBJECT_SUBTYPE_MAP[dbSubtype] ?? null;
+    }
+    // Transaction subtypes
+    if (dbType === 'TRANSACTION' && dbSubtype) {
+        return TRANSACTION_SUBTYPE_MAP[dbSubtype] ?? null;
+    }
+    return null;
+}
+// ============================================================================
+// Human-Readable Labels
+// ============================================================================
+/**
+ * Human-readable labels for each entity type: [singular, plural].
+ */
+const ENTITY_TYPE_LABELS = {
+    // Core Objects (7 types)
+    stakeholder: ['Stakeholder', 'Stakeholders'],
+    stockClass: ['Stock Class', 'Stock Classes'],
+    stockPlan: ['Stock Plan', 'Stock Plans'],
+    vestingTerms: ['Vesting Terms', 'Vesting Terms'],
+    stockLegendTemplate: ['Stock Legend Template', 'Stock Legend Templates'],
+    document: ['Document', 'Documents'],
+    valuation: ['Valuation', 'Valuations'],
+    // Stock Transactions (9 types)
+    stockIssuance: ['Stock Issuance', 'Stock Issuances'],
+    stockCancellation: ['Stock Cancellation', 'Stock Cancellations'],
+    stockTransfer: ['Stock Transfer', 'Stock Transfers'],
+    stockAcceptance: ['Stock Acceptance', 'Stock Acceptances'],
+    stockConversion: ['Stock Conversion', 'Stock Conversions'],
+    stockRepurchase: ['Stock Repurchase', 'Stock Repurchases'],
+    stockReissuance: ['Stock Reissuance', 'Stock Reissuances'],
+    stockRetraction: ['Stock Retraction', 'Stock Retractions'],
+    stockConsolidation: ['Stock Consolidation', 'Stock Consolidations'],
+    // Equity Compensation (8 types)
+    equityCompensationIssuance: ['Equity Compensation Issuance', 'Equity Compensation Issuances'],
+    equityCompensationCancellation: ['Equity Compensation Cancellation', 'Equity Compensation Cancellations'],
+    equityCompensationTransfer: ['Equity Compensation Transfer', 'Equity Compensation Transfers'],
+    equityCompensationAcceptance: ['Equity Compensation Acceptance', 'Equity Compensation Acceptances'],
+    equityCompensationExercise: ['Equity Compensation Exercise', 'Equity Compensation Exercises'],
+    equityCompensationRelease: ['Equity Compensation Release', 'Equity Compensation Releases'],
+    equityCompensationRepricing: ['Equity Compensation Repricing', 'Equity Compensation Repricings'],
+    equityCompensationRetraction: ['Equity Compensation Retraction', 'Equity Compensation Retractions'],
+    // Plan Security aliases (use same labels as Equity Compensation)
+    planSecurityIssuance: ['Plan Security Issuance', 'Plan Security Issuances'],
+    planSecurityCancellation: ['Plan Security Cancellation', 'Plan Security Cancellations'],
+    planSecurityTransfer: ['Plan Security Transfer', 'Plan Security Transfers'],
+    planSecurityAcceptance: ['Plan Security Acceptance', 'Plan Security Acceptances'],
+    planSecurityExercise: ['Plan Security Exercise', 'Plan Security Exercises'],
+    planSecurityRelease: ['Plan Security Release', 'Plan Security Releases'],
+    planSecurityRetraction: ['Plan Security Retraction', 'Plan Security Retractions'],
+    // Convertibles (6 types)
+    convertibleIssuance: ['Convertible Issuance', 'Convertible Issuances'],
+    convertibleCancellation: ['Convertible Cancellation', 'Convertible Cancellations'],
+    convertibleTransfer: ['Convertible Transfer', 'Convertible Transfers'],
+    convertibleAcceptance: ['Convertible Acceptance', 'Convertible Acceptances'],
+    convertibleConversion: ['Convertible Conversion', 'Convertible Conversions'],
+    convertibleRetraction: ['Convertible Retraction', 'Convertible Retractions'],
+    // Warrants (6 types)
+    warrantIssuance: ['Warrant Issuance', 'Warrant Issuances'],
+    warrantCancellation: ['Warrant Cancellation', 'Warrant Cancellations'],
+    warrantTransfer: ['Warrant Transfer', 'Warrant Transfers'],
+    warrantAcceptance: ['Warrant Acceptance', 'Warrant Acceptances'],
+    warrantExercise: ['Warrant Exercise', 'Warrant Exercises'],
+    warrantRetraction: ['Warrant Retraction', 'Warrant Retractions'],
+    // Stock Class Adjustments (4 types)
+    stockClassAuthorizedSharesAdjustment: [
+        'Stock Class Authorized Shares Adjustment',
+        'Stock Class Authorized Shares Adjustments',
+    ],
+    stockClassConversionRatioAdjustment: [
+        'Stock Class Conversion Ratio Adjustment',
+        'Stock Class Conversion Ratio Adjustments',
+    ],
+    stockClassSplit: ['Stock Class Split', 'Stock Class Splits'],
+    issuerAuthorizedSharesAdjustment: ['Issuer Authorized Shares Adjustment', 'Issuer Authorized Shares Adjustments'],
+    // Stock Plan Events (2 types)
+    stockPlanPoolAdjustment: ['Stock Plan Pool Adjustment', 'Stock Plan Pool Adjustments'],
+    stockPlanReturnToPool: ['Stock Plan Return to Pool', 'Stock Plan Returns to Pool'],
+    // Vesting Events (3 types)
+    vestingAcceleration: ['Vesting Acceleration', 'Vesting Accelerations'],
+    vestingEvent: ['Vesting Event', 'Vesting Events'],
+    vestingStart: ['Vesting Start', 'Vesting Starts'],
+    // Stakeholder Events (2 types)
+    stakeholderRelationshipChangeEvent: ['Stakeholder Relationship Change', 'Stakeholder Relationship Changes'],
+    stakeholderStatusChangeEvent: ['Stakeholder Status Change', 'Stakeholder Status Changes'],
+};
+/**
+ * Get a human-readable label for an entity type with count.
+ *
+ * @param type - The OcfEntityType
+ * @param count - The count (determines singular vs plural)
+ * @returns Human-readable string like "3 Stock Classes" or "1 Stakeholder"
+ *
+ * @example
+ * ```typescript
+ * getEntityTypeLabel('stockClass', 1); // "1 Stock Class"
+ * getEntityTypeLabel('stockClass', 3); // "3 Stock Classes"
+ * getEntityTypeLabel('stakeholder', 0); // "0 Stakeholders"
+ * ```
+ */
+function getEntityTypeLabel(type, count) {
+    const labels = ENTITY_TYPE_LABELS[type];
+    const [singular, plural] = labels;
+    return `${count} ${count === 1 ? singular : plural}`;
+}
+/**
+ * Compute what needs to be synced from DB to Canton.
+ *
+ * Compares a list of DB items (desired state) against Canton state (actual state)
+ * and returns operations needed to synchronize them.
+ *
+ * @param dbItems - OCF items from database (desired state)
+ * @param cantonState - Current Canton state from getCapTableState()
+ * @param options - Sync options
+ * @returns Replication diff with creates, edits, and deletes
+ *
+ * @example
+ * ```typescript
+ * const dbItems = [
+ *   { ocfId: 'stakeholder-1', entityType: 'stakeholder', data: {...} },
+ *   { ocfId: 'stock-class-1', entityType: 'stockClass', data: {...} },
+ * ];
+ * const cantonState = await getCapTableState(client, issuerPartyId);
+ * const diff = computeReplicationDiff(dbItems, cantonState, { syncDeletes: true });
+ * // diff.creates = items in DB but not Canton
+ * // diff.deletes = items in Canton but not DB
+ * ```
+ */
+function computeReplicationDiff(dbItems, cantonState, options = {}) {
+    const { syncDeletes = false, alwaysEdit = false } = options;
+    const creates = [];
+    const edits = [];
+    const deletes = [];
+    // Track DB items by type for delete detection
+    const dbIdsByType = new Map();
+    // Track seen items to prevent duplicate create/edit operations
+    const seenItems = new Set();
+    // Process each DB item
+    for (const item of dbItems) {
+        // Skip duplicate items (same ocfId + entityType)
+        const itemKey = `${item.entityType}:${item.ocfId}`;
+        if (seenItems.has(itemKey)) {
+            continue;
+        }
+        seenItems.add(itemKey);
+        // Normalize planSecurity types to equityCompensation for Canton lookup
+        // Canton stores planSecurity items under equity_compensation_* fields
+        const normalizedType = (0, planSecurityAliases_1.normalizeEntityType)(item.entityType);
+        // Track for delete detection (using normalized type to match Canton's storage)
+        let typeIds = dbIdsByType.get(normalizedType);
+        if (!typeIds) {
+            typeIds = new Set();
+            dbIdsByType.set(normalizedType, typeIds);
+        }
+        typeIds.add(item.ocfId);
+        // Check if exists in Canton (using normalized type)
+        const cantonIds = cantonState.entities.get(normalizedType) ?? new Set();
+        const existsInCanton = cantonIds.has(item.ocfId);
+        if (!existsInCanton) {
+            // Item in DB but not Canton → CREATE
+            creates.push({
+                ocfId: item.ocfId,
+                entityType: item.entityType,
+                operation: 'create',
+                data: item.data,
+            });
+        }
+        else if (alwaysEdit) {
+            // Item in both and alwaysEdit → EDIT
+            edits.push({
+                ocfId: item.ocfId,
+                entityType: item.entityType,
+                operation: 'edit',
+                data: item.data,
+            });
+        }
+        // If not alwaysEdit and exists in Canton, skip (already synced)
+    }
+    // Detect deletes (in Canton but not in DB)
+    if (syncDeletes) {
+        for (const [entityType, cantonIds] of cantonState.entities) {
+            const dbIds = dbIdsByType.get(entityType) ?? new Set();
+            for (const cantonId of cantonIds) {
+                if (!dbIds.has(cantonId)) {
+                    // Item in Canton but not DB → DELETE
+                    deletes.push({
+                        ocfId: cantonId,
+                        entityType,
+                        operation: 'delete',
+                    });
+                }
+            }
+        }
+    }
+    return {
+        creates,
+        edits,
+        deletes,
+        total: creates.length + edits.length + deletes.length,
+    };
+}
+//# sourceMappingURL=replicationHelpers.js.map

package/dist/utils/replicationHelpers.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-captable-protocol/canton",
-  "version": "0.2.192",
+  "version": "0.2.193",
   "description": "A TypeScript SDK for interacting with the Open CapTable Protocol (OCP) Factory contract on Canton blockchain",
   "license": "MIT",
   "main": "dist/index.js",