Validate acceptance reader payloads

src/functions/OpenCapTable/capTable/acceptanceContractData.ts

@@ -0,0 +1,153 @@
+import { Fairmint } from '@fairmint/open-captable-protocol-daml-js';
+import { OcpErrorCodes, OcpParseError } from '../../../errors';
+import { toSafeDiagnosticText } from '../../../errors/OcpError';
+import { assertSafeGeneratedDamlJson } from '../../../utils/generatedDamlValidation';
+import { validatePartyId, validateRequiredString } from '../../../utils/validation';
+import { ENTITY_TEMPLATE_ID_MAP, type OcfEntityType } from './batchTypes';
+import { assertLosslessGeneratedDamlRoundTrip } from './damlCodecLosslessness';
+
+export type AcceptanceEntityType = Extract<
+  OcfEntityType,
+  'convertibleAcceptance' | 'equityCompensationAcceptance' | 'stockAcceptance' | 'warrantAcceptance'
+>;
+
+export function isAcceptanceEntityType(entityType: OcfEntityType): entityType is AcceptanceEntityType {
+  return (
+    entityType === 'convertibleAcceptance' ||
+    entityType === 'equityCompensationAcceptance' ||
+    entityType === 'stockAcceptance' ||
+    entityType === 'warrantAcceptance'
+  );
+}
+
+interface AcceptanceCreateArgumentMap {
+  convertibleAcceptance: Fairmint.OpenCapTable.OCF.ConvertibleAcceptance.ConvertibleAcceptance;
+  equityCompensationAcceptance: Fairmint.OpenCapTable.OCF.EquityCompensationAcceptance.EquityCompensationAcceptance;
+  stockAcceptance: Fairmint.OpenCapTable.OCF.StockAcceptance.StockAcceptance;
+  warrantAcceptance: Fairmint.OpenCapTable.OCF.WarrantAcceptance.WarrantAcceptance;
+}
+
+interface DecoderError {
+  readonly at: string;
+  readonly message: string;
+}
+
+interface AcceptanceCreateArgumentCodec<T> {
+  readonly decoder: {
+    run(
+      input: unknown
+    ): { readonly ok: true; readonly result: T } | { readonly ok: false; readonly error: DecoderError };
+  };
+  encode(value: T): unknown;
+}
+
+type AcceptanceDataFor<EntityType extends AcceptanceEntityType> =
+  AcceptanceCreateArgumentMap[EntityType]['acceptance_data'];
+
+type AcceptanceCreateArgumentDecoderMap = {
+  readonly [EntityType in AcceptanceEntityType]: (createArgument: unknown) => AcceptanceDataFor<EntityType>;
+};
+
+function acceptanceCreateArgumentError(
+  entityType: AcceptanceEntityType,
+  rootPath: string,
+  message: string,
+  context: Readonly<Record<string, unknown>>
+): OcpParseError {
+  return new OcpParseError(message, {
+    source: rootPath,
+    code: OcpErrorCodes.SCHEMA_MISMATCH,
+    classification: 'invalid_generated_create_argument',
+    context: {
+      entityType,
+      expectedTemplateId: ENTITY_TEMPLATE_ID_MAP[entityType],
+      ...context,
+    },
+  });
+}
+
+/** Build one exact, lossless generated-template decoder while retaining its entity correlation. */
+function createAcceptanceCreateArgumentDecoder<const EntityType extends AcceptanceEntityType>(
+  entityType: EntityType,
+  codec: AcceptanceCreateArgumentCodec<AcceptanceCreateArgumentMap[EntityType]>
+): (createArgument: unknown) => AcceptanceDataFor<EntityType> {
+  return (createArgument) => {
+    const rootPath = `damlToOcf.${entityType}.createArgument`;
+    const diagnosticContext = {
+      entityType,
+      expectedTemplateId: ENTITY_TEMPLATE_ID_MAP[entityType],
+    } as const;
+
+    // Perform the descriptor-only JSON preflight before a generated decoder can
+    // read properties or invoke behaviour supplied by an untrusted ledger value.
+    assertSafeGeneratedDamlJson(createArgument, rootPath);
+
+    const decoded = codec.decoder.run(createArgument);
+    if (!decoded.ok) {
+      const { at: decoderPath, message: decoderMessage } = decoded.error;
+      throw acceptanceCreateArgumentError(
+        entityType,
+        rootPath,
+        `Invalid generated DAML create argument for ${entityType} at ${decoderPath}: ${decoderMessage}`,
+        { decoderPath, decoderMessage }
+      );
+    }
+
+    let encoded: unknown;
+    try {
+      encoded = codec.encode(decoded.result);
+    } catch (error) {
+      throw acceptanceCreateArgumentError(
+        entityType,
+        rootPath,
+        `Unable to encode generated DAML create argument for ${entityType}: ${toSafeDiagnosticText(error)}`,
+        { phase: 'encode' }
+      );
+    }
+
+    assertSafeGeneratedDamlJson(encoded, `${rootPath}.__encoded`);
+    assertLosslessGeneratedDamlRoundTrip(createArgument, encoded, {
+      rootPath,
+      description: `${entityType} create argument`,
+      decodeSource: rootPath,
+      context: diagnosticContext,
+    });
+
+    validatePartyId(decoded.result.context.issuer, `${rootPath}.context.issuer`);
+    validatePartyId(decoded.result.context.system_operator, `${rootPath}.context.system_operator`);
+
+    const acceptanceData = decoded.result.acceptance_data;
+    validateRequiredString(acceptanceData.id, `${rootPath}.acceptance_data.id`);
+    validateRequiredString(acceptanceData.security_id, `${rootPath}.acceptance_data.security_id`);
+
+    return acceptanceData;
+  };
+}
+
+/** Generated full-template codecs correlated with each supported acceptance family. */
+const ACCEPTANCE_CREATE_ARGUMENT_DECODER_MAP = {
+  convertibleAcceptance: createAcceptanceCreateArgumentDecoder(
+    'convertibleAcceptance',
+    Fairmint.OpenCapTable.OCF.ConvertibleAcceptance.ConvertibleAcceptance
+  ),
+  equityCompensationAcceptance: createAcceptanceCreateArgumentDecoder(
+    'equityCompensationAcceptance',
+    Fairmint.OpenCapTable.OCF.EquityCompensationAcceptance.EquityCompensationAcceptance
+  ),
+  stockAcceptance: createAcceptanceCreateArgumentDecoder(
+    'stockAcceptance',
+    Fairmint.OpenCapTable.OCF.StockAcceptance.StockAcceptance
+  ),
+  warrantAcceptance: createAcceptanceCreateArgumentDecoder(
+    'warrantAcceptance',
+    Fairmint.OpenCapTable.OCF.WarrantAcceptance.WarrantAcceptance
+  ),
+} as const satisfies AcceptanceCreateArgumentDecoderMap;
+
+/** Decode the exact generated contract wrapper and return its correlated acceptance payload. */
+export function extractAndDecodeAcceptanceData<const EntityType extends AcceptanceEntityType>(
+  entityType: EntityType,
+  createArgument: unknown
+): AcceptanceDataFor<EntityType> {
+  return ACCEPTANCE_CREATE_ARGUMENT_DECODER_MAP[entityType](createArgument);
+}

src/functions/OpenCapTable/capTable/damlEntityData.ts

@@ -6,6 +6,7 @@ import { projectDamlIssuerDataToNative } from '../issuer/getIssuerAsOcf';
 import { parseDamlSafeInteger } from '../shared/damlIntegers';
 import { assertCanonicalJsonGraph, requireDecimalString } from '../shared/ocfValues';
 import { damlOptionalStakeholderRelationshipToNative } from '../stakeholderRelationshipChangeEvent/damlToOcf';
+import { extractAndDecodeAcceptanceData, isAcceptanceEntityType } from './acceptanceContractData';
 import {
   ENTITY_DATA_FIELD_MAP,
   ENTITY_TEMPLATE_ID_MAP,
@@ -309,6 +310,14 @@ export function decodeDamlEntityData(entityType: OcfEntityType, input: unknown):
 export function extractAndDecodeDamlEntityData<const EntityType extends OcfEntityType>(
   entityType: EntityType,
   createArgument: unknown
-): DamlDataTypeFor<EntityType> {
+): DamlDataTypeFor<EntityType>;
+export function extractAndDecodeDamlEntityData(
+  entityType: OcfEntityType,
+  createArgument: unknown
+): DamlDataTypeFor<OcfEntityType> {
+  if (isAcceptanceEntityType(entityType)) {
+    return extractAndDecodeAcceptanceData(entityType, createArgument);
+  }
+
   return decodeDamlEntityData(entityType, extractEntityData(entityType, createArgument));
 }

src/functions/OpenCapTable/convertibleAcceptance/convertibleAcceptanceDataToDaml.ts

@@ -25,6 +25,12 @@ export function convertibleAcceptanceDataToDaml(d: OcfConvertibleAcceptance): Re
       receivedValue: d.id,
     });
   }
+  if (!d.security_id) {
+    throw new OcpValidationError('convertibleAcceptance.security_id', 'Required field is missing or empty', {
+      expectedType: 'string',
+      receivedValue: d.security_id,
+    });
+  }
   return {
     id: d.id,
     date: dateStringToDAMLTime(d.date, 'convertibleAcceptance.date'),

src/functions/OpenCapTable/convertibleAcceptance/getConvertibleAcceptanceAsOcf.ts

@@ -1,16 +1,15 @@
 import type { LedgerJsonApiClient } from '@fairmint/canton-node-sdk';
-import { OcpErrorCodes, OcpParseError } from '../../../errors';
 import type { OcfConvertibleAcceptance } from '../../../types';
 import type { GetByContractIdParams } from '../../../types/common';
-import { damlTimeToDateString } from '../../../utils/typeConversions';
+import { ENTITY_TEMPLATE_ID_MAP } from '../capTable/batchTypes';
+import { extractAndDecodeDamlEntityData } from '../capTable/damlEntityData';
 import { readSingleContract } from '../shared/singleContractRead';
+import { damlConvertibleAcceptanceToNative } from './convertibleAcceptanceDataToDaml';
 
 /**
  * OCF Convertible Acceptance event with object_type discriminator.
  */
-export interface OcfConvertibleAcceptanceEvent extends OcfConvertibleAcceptance {
-  object_type: 'TX_CONVERTIBLE_ACCEPTANCE';
-}
+export type OcfConvertibleAcceptanceEvent = OcfConvertibleAcceptance;
 
 export type GetConvertibleAcceptanceAsOcfParams = GetByContractIdParams;
 
@@ -19,23 +18,6 @@ export interface GetConvertibleAcceptanceAsOcfResult {
   contractId: string;
 }
 
-/**
- * DAML ConvertibleAcceptance contract createArgument structure.
- */
-interface ConvertibleAcceptanceCreateArgument {
-  acceptance_data: {
-    id: string;
-    date: string;
-    security_id: string;
-    comments: string[];
-  };
-}
-
-function hasConvertibleAcceptanceData(arg: unknown): arg is ConvertibleAcceptanceCreateArgument {
-  const record = arg as { acceptance_data?: unknown };
-  return typeof record.acceptance_data === 'object' && record.acceptance_data !== null;
-}
-
 /**
  * Retrieve a Convertible Acceptance contract and convert to OCF format.
  *
@@ -49,24 +31,10 @@ export async function getConvertibleAcceptanceAsOcf(
 ): Promise<GetConvertibleAcceptanceAsOcfResult> {
   const { createArgument } = await readSingleContract(client, params, {
     operation: 'getConvertibleAcceptanceAsOcf',
+    expectedTemplateId: ENTITY_TEMPLATE_ID_MAP.convertibleAcceptance,
   });
-  if (!hasConvertibleAcceptanceData(createArgument)) {
-    throw new OcpParseError('ConvertibleAcceptance data not found in contract create argument', {
-      source: 'ConvertibleAcceptance.createArgument',
-      code: OcpErrorCodes.SCHEMA_MISMATCH,
-    });
-  }
-
-  const contract = createArgument;
-  const data = contract.acceptance_data;
-
-  const event: OcfConvertibleAcceptanceEvent = {
-    object_type: 'TX_CONVERTIBLE_ACCEPTANCE',
-    id: data.id,
-    date: damlTimeToDateString(data.date, 'convertibleAcceptance.date'),
-    security_id: data.security_id,
-    ...(Array.isArray(data.comments) && data.comments.length ? { comments: data.comments } : {}),
-  };
+  const data = extractAndDecodeDamlEntityData('convertibleAcceptance', createArgument);
+  const event = damlConvertibleAcceptanceToNative(data);
 
   return { event, contractId: params.contractId };
 }

src/functions/OpenCapTable/equityCompensationAcceptance/equityCompensationAcceptanceDataToDaml.ts

@@ -25,6 +25,12 @@ export function equityCompensationAcceptanceDataToDaml(d: OcfEquityCompensationA
       receivedValue: d.id,
     });
   }
+  if (!d.security_id) {
+    throw new OcpValidationError('equityCompensationAcceptance.security_id', 'Required field is missing or empty', {
+      expectedType: 'string',
+      receivedValue: d.security_id,
+    });
+  }
   return {
     id: d.id,
     date: dateStringToDAMLTime(d.date, 'equityCompensationAcceptance.date'),

src/functions/OpenCapTable/equityCompensationAcceptance/getEquityCompensationAcceptanceAsOcf.ts

@@ -1,16 +1,15 @@
 import type { LedgerJsonApiClient } from '@fairmint/canton-node-sdk';
-import { OcpErrorCodes, OcpParseError } from '../../../errors';
 import type { OcfEquityCompensationAcceptance } from '../../../types';
 import type { GetByContractIdParams } from '../../../types/common';
-import { damlTimeToDateString } from '../../../utils/typeConversions';
+import { ENTITY_TEMPLATE_ID_MAP } from '../capTable/batchTypes';
+import { extractAndDecodeDamlEntityData } from '../capTable/damlEntityData';
 import { readSingleContract } from '../shared/singleContractRead';
+import { damlEquityCompensationAcceptanceToNative } from './equityCompensationAcceptanceDataToDaml';
 
 /**
  * OCF Equity Compensation Acceptance event with object_type discriminator.
  */
-export interface OcfEquityCompensationAcceptanceEvent extends OcfEquityCompensationAcceptance {
-  object_type: 'TX_EQUITY_COMPENSATION_ACCEPTANCE';
-}
+export type OcfEquityCompensationAcceptanceEvent = OcfEquityCompensationAcceptance;
 
 export type GetEquityCompensationAcceptanceAsOcfParams = GetByContractIdParams;
 
@@ -19,23 +18,6 @@ export interface GetEquityCompensationAcceptanceAsOcfResult {
   contractId: string;
 }
 
-/**
- * DAML EquityCompensationAcceptance contract createArgument structure.
- */
-interface EquityCompensationAcceptanceCreateArgument {
-  acceptance_data: {
-    id: string;
-    date: string;
-    security_id: string;
-    comments: string[];
-  };
-}
-
-function hasEquityCompensationAcceptanceData(arg: unknown): arg is EquityCompensationAcceptanceCreateArgument {
-  const record = arg as { acceptance_data?: unknown };
-  return typeof record.acceptance_data === 'object' && record.acceptance_data !== null;
-}
-
 /**
  * Retrieve an Equity Compensation Acceptance contract and convert to OCF format.
  *
@@ -49,24 +31,10 @@ export async function getEquityCompensationAcceptanceAsOcf(
 ): Promise<GetEquityCompensationAcceptanceAsOcfResult> {
   const { createArgument } = await readSingleContract(client, params, {
     operation: 'getEquityCompensationAcceptanceAsOcf',
+    expectedTemplateId: ENTITY_TEMPLATE_ID_MAP.equityCompensationAcceptance,
   });
-  if (!hasEquityCompensationAcceptanceData(createArgument)) {
-    throw new OcpParseError('EquityCompensationAcceptance data not found in contract create argument', {
-      source: 'EquityCompensationAcceptance.createArgument',
-      code: OcpErrorCodes.SCHEMA_MISMATCH,
-    });
-  }
-
-  const contract = createArgument;
-  const data = contract.acceptance_data;
-
-  const event: OcfEquityCompensationAcceptanceEvent = {
-    object_type: 'TX_EQUITY_COMPENSATION_ACCEPTANCE',
-    id: data.id,
-    date: damlTimeToDateString(data.date, 'equityCompensationAcceptance.date'),
-    security_id: data.security_id,
-    ...(Array.isArray(data.comments) && data.comments.length ? { comments: data.comments } : {}),
-  };
+  const data = extractAndDecodeDamlEntityData('equityCompensationAcceptance', createArgument);
+  const event = damlEquityCompensationAcceptanceToNative(data);
 
   return { event, contractId: params.contractId };
 }