Skip to content
← Open Cap Table Protocol OCP Canton SDK

OCP Canton SDK

Troubleshooting

Common OCP Canton SDK failures, batch validation, and extractor edge cases — condensed from the project wiki.

Low-level Ledger / Validator behavior is implemented by @fairmint/canton-node-sdk — see Canton Node SDK docs when the failure originates below OCP (HTTP 401/403, party rights, synchronizer errors).

commands.0: Invalid input (batch parameter validation)

Symptom: CapTableBatch.execute() throws Batch execution failed: Parameter validation failed: commands.0: Invalid input.

Root cause: A converter emitted undefined for an optional field instead of null. The Canton JSON API uses strict validation; undefined is not valid JSON for those fields.

Triage:

  1. Identify the failing row from the batch log (entity type + OCF ID).
  2. Validate source data against the OCF JSON schema in Open-Cap-Format-OCF/schema/.
  3. Inspect the converter in src/functions/OpenCapTable/<entity>/ for optional fields passed through without ?? null / ?? [].

Rules:

  • Never emit undefined in converter output objects — use null for DAML optionals.
  • Normalize arrays with ?? [] and strings with helpers like optionalString().

Ambiguous legacy stakeholder relationship events (new_relationships)

Treat multi-value new_relationships as ambiguous and fail fast when canonical relationship_started / relationship_ended are missing.

Stale issuer contract reference (CONTRACT_EVENTS_NOT_FOUND)

Cap table state validation may invalidate stale issuer contract IDs; extractors should rely on validated state from getCapTableState rather than re-reading raw IDs.

Multi-repo SDK sharing (archiveFullCapTable)

Accept LedgerJsonApiClient where possible instead of the full OcpClient to keep utilities reusable across repos.

More scenarios and long-form notes: wiki Home — Troubleshooting.