Resolve Token Standard V2 settlement factories by HardlyDifficult · Pull Request #378 · Fairmint/canton-node-sdk

HardlyDifficult · 2026-07-10T03:02:57Z

Summary

build exact CIP-112 V2 SettlementFactory_SettleBatch arguments and commands
resolve the choice-specific factory through the official /registry/allocation/v2/settlement-factory endpoint
send canonical empty context and metadata to registry lookup, then combine returned context with caller metadata
return the factory ID and validated disclosed contracts as one prepared command
keep third-party registry requests unauthenticated and reject malformed context, disclosures, Decimal values, and settlement invariants

Stacked on #374. This is protocol-level behavior with no Fairmint contracts or business rules.

Validation

43 focused allocation, settlement-factory, and Scan client tests
npm run build:lint
scoped ESLint and Prettier
generated client methods
git diff --check

The node-SDK Quickstart CI validates the package against the pinned LocalNet. A real two-token settlement using non-empty registry contexts will be covered by the downstream canton-fairmint-sdk Quickstart after the new EquityClearing package and these helpers publish.

Note

Medium Risk
Introduces protocol-level settlement command construction and trust in third-party registry responses; risk is mitigated by strict input/response validation and the same unauthenticated registry pattern as allocation factories.

Overview
Adds Token Standard V2 settlement support: callers can build SettlementFactory_SettleBatch choice arguments and ledger exercise commands, or use prepareTokenStandardV2SettlementCommand to resolve the factory in one step.

A new unauthenticated Scan/registry client operation posts to /registry/allocation/v2/settlement-factory on a caller-supplied instrument registry URL (credentials, query, and hash stripped from the URL; no Scan bearer token forwarded). prepare sends the settlement payload with empty extraArgs.context and metadata for lookup, then merges the registry-returned choice context with optional caller metadata only—caller-supplied extraArgs at prepare time is rejected.

The settlement helper layer validates settlement invariants (non-empty transfer legs and allocations, unique transferLegId, positive Daml decimals, parties/CIDs, choice context shape) and parses registry responses (factory id, disclosed contracts). Unit tests cover the Scan client call shape and the prepare/build/validation paths.

^{Reviewed by Cursor Bugbot for commit bbe685e. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

New Features
- Added Token Standard V2 settlement support for building and preparing settlement commands.
- Added registry lookup for settlement-factory details and disclosed contracts.
- Added validation for settlement arguments, transfer legs, amounts, metadata, and registry responses.
- Exposed the new settlement functionality through the public API.
Tests
- Added coverage for settlement command creation, validation, registry requests, error handling, and metadata safety.
Documentation
- Updated the wiki reference.

coderabbitai · 2026-07-10T03:03:07Z

📝 Walkthrough

Walkthrough

Adds a Token Standard V2 settlement-factory workflow, including registry lookup, validation, command construction, response handling, public exports, and unit tests. The wiki submodule pointer is also updated.

Changes

Settlement factory integration

Layer / File(s)	Summary
Registry operation and public exports `src/clients/scan-api/operations/v0/registry/...`, `src/utils/token-standard/v2/index.ts`	Adds validated unauthenticated settlement-factory registry requests, response types, URL normalization, and barrel exports.
Settlement normalization and command preparation `src/utils/token-standard/v2/settlement-factory.ts`	Validates and normalizes settlement inputs, builds ledger `ExerciseCommand` values, parses registry responses, and merges factory context into prepared commands.
Settlement factory validation coverage `test/unit/clients/scan-api.test.ts`, `test/unit/token-standard/v2/settlement-factory.test.ts`	Tests request construction, command shapes, normalization, numeric validation, cloning, context merging, malformed responses, and pre-lookup failures.

Wiki pointer update

Layer / File(s)	Summary
Wiki submodule reference `wiki`	Updates the wiki submodule reference to commit `81847096a8dcb794451d5d48eda8d36edc10f629`.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant SettlementPreparation
  participant ScanApiClient
  participant Registry
  Caller->>SettlementPreparation: settlement parameters
  SettlementPreparation->>ScanApiClient: settlement-factory lookup request
  ScanApiClient->>Registry: unauthenticated POST
  Registry-->>ScanApiClient: factory context and disclosed contracts
  ScanApiClient-->>SettlementPreparation: registry response
  SettlementPreparation-->>Caller: prepared ExerciseCommand

Possibly related PRs

Fairmint/canton-node-sdk#338: Updates the same Scan API registry barrel surface with an additional re-export.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding Token Standard V2 settlement factory resolution and command preparation.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch codex/token-standard-settlement-factory

_{Comment @coderabbitai help to get the list of available commands.}

claude · 2026-07-10T03:03:09Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

…ard-settlement-factory # Conflicts: # test/unit/clients/scan-api.test.ts

claude · 2026-07-10T04:06:48Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

…ard-settlement-factory

claude · 2026-07-10T04:15:21Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

…ard-settlement-factory

claude · 2026-07-10T04:24:25Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

…ard-settlement-factory

claude · 2026-07-10T04:45:43Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

…ard-settlement-factory

claude · 2026-07-10T04:56:30Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

…settlement-factory # Conflicts: # src/utils/token-standard/v2/allocation.ts # src/utils/token-standard/v2/index.ts # test/unit/clients/scan-api.test.ts # test/unit/token-standard/v2/allocation.test.ts

claude · 2026-07-10T13:13:33Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

Copilot

Pull request overview

Adds Token Standard V2 settlement-factory support to the SDK by building the canonical SettlementFactory_SettleBatch choice argument/command, resolving the factory + per-choice context via the registry endpoint, and returning a prepared command with validated disclosures.

Changes:

Introduces prepareTokenStandardV2SettlementCommand (and related builders/validators) to construct CIP-112 V2 settlement factory commands and merge registry choice context with caller metadata.
Adds a new unauthenticated Scan API operation POST /registry/allocation/v2/settlement-factory that canonicalizes arbitrary registry URLs (strips credentials, normalizes slashes).
Adds focused unit coverage for settlement-factory helpers and the Scan API client behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/unit/token-standard/v2/settlement-factory.test.ts	New unit tests covering settlement choice building, validation, registry lookup behavior, and disclosure handling.
test/unit/clients/scan-api.test.ts	Adds coverage for the new settlement-factory registry call and verifies it’s unauthenticated + canonicalized.
src/utils/token-standard/v2/settlement-factory.ts	New settlement-factory helper implementation: build/validate choice args, parse registry response, and prepare an exercise command.
src/utils/token-standard/v2/index.ts	Exposes the new settlement-factory helpers from the Token Standard v2 utils barrel.
src/clients/scan-api/operations/v0/registry/index.ts	Exports the new allocation registry operation group.
src/clients/scan-api/operations/v0/registry/allocation/index.ts	New barrel export for allocation registry operations.
src/clients/scan-api/operations/v0/registry/allocation/v2/index.ts	New barrel export for allocation v2 registry operations.
src/clients/scan-api/operations/v0/registry/allocation/v2/get-settlement-factory-from-registry.ts	New Scan operation definition for resolving settlement factories from arbitrary registries without auth.

HardlyDifficult · 2026-07-10T16:59:08Z

@coderabbitai review

coderabbitai · 2026-07-10T16:59:15Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 201d148. Configure here.}

claude · 2026-07-10T17:11:24Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

HardlyDifficult · 2026-07-10T17:11:30Z

Addressed all three exact-head Copilot findings in c5acfd9: ChoiceContext outer/values/nested objects now accept only plain or null-prototype JSON records, metadata/funding maps use the same guard, Map/custom-prototype silent data loss is covered, and the registry lookup test mock is interface-typed with jest.MockedFunction. All three threads are resolved. Validation: TypeScript 7 build/lint; scoped ESLint/Prettier; 61/61 focused tests; 69/69 unit suites (739/739 tests); package artifact 5.40 MB / 1325 files. Keeping draft/unassigned for fresh CI, then re-requesting current-head Copilot first, Cursor, and CodeRabbit.

HardlyDifficult · 2026-07-10T17:17:21Z

cursor review

HardlyDifficult · 2026-07-10T17:17:23Z

@coderabbitai review

coderabbitai · 2026-07-10T17:17:28Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit c5acfd9. Configure here.}

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

HardlyDifficult · 2026-07-10T17:27:37Z

Addressed the final exact-head Copilot boundary finding in bbe685e: buildTokenStandardV2SettlementChoiceArgument now validates top-level runtime input before field access, with undefined/null/scalar/string/array regressions producing the typed SDK input error. Thread resolved. Validation: TypeScript 7 build/lint; scoped ESLint/Prettier; 66/66 focused tests; 69/69 unit suites (744/744 tests); package artifact 5.40 MB / 1325 files. Keeping draft/unassigned for fresh CI, then re-requesting current-head Copilot first plus Cursor/CodeRabbit.

claude · 2026-07-10T17:27:41Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

HardlyDifficult · 2026-07-10T17:33:19Z

cursor review

HardlyDifficult · 2026-07-10T17:33:20Z

@coderabbitai review

coderabbitai · 2026-07-10T17:33:28Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit bbe685e. Configure here.}

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

HardlyDifficult added 2 commits July 9, 2026 22:52

feat: add token standard v2 allocation helpers

6a44988

feat: resolve token standard v2 settlement factories

6cd2f88

HardlyDifficult added 4 commits July 9, 2026 23:54

fix: harden token standard v2 allocation helpers

eb9d7e5

fix: enforce daml decimal bounds

0a38862

fix: resolve settlement factories through registries

6be1bee

Merge branch 'codex/token-standard-allocation' into codex/token-stand…

e8a6a69

…ard-settlement-factory # Conflicts: # test/unit/clients/scan-api.test.ts

HardlyDifficult added 2 commits July 10, 2026 00:13

style: align allocation error conventions

d92059b

Merge branch 'codex/token-standard-allocation' into codex/token-stand…

75dde9d

…ard-settlement-factory

HardlyDifficult added 3 commits July 10, 2026 00:22

fix: enforce daml json decimal syntax

4cd2a7a

fix: enforce daml json decimal syntax

1d224cf

Merge branch 'codex/token-standard-allocation' into codex/token-stand…

40513db

…ard-settlement-factory

HardlyDifficult added 2 commits July 10, 2026 00:42

fix: validate allocation helper runtime inputs

d728421

Merge branch 'codex/token-standard-allocation' into codex/token-stand…

6c2f2f0

…ard-settlement-factory

HardlyDifficult added 2 commits July 10, 2026 00:54

fix: require positive iteration funding

34346f2

Merge branch 'codex/token-standard-allocation' into codex/token-stand…

03f4fa0

…ard-settlement-factory

Base automatically changed from codex/token-standard-allocation to main July 10, 2026 11:36

Merge remote-tracking branch 'origin/main' into codex/token-standard-…

0751da8

…settlement-factory # Conflicts: # src/utils/token-standard/v2/allocation.ts # src/utils/token-standard/v2/index.ts # test/unit/clients/scan-api.test.ts # test/unit/token-standard/v2/allocation.test.ts

HardlyDifficult marked this pull request as ready for review July 10, 2026 13:33

HardlyDifficult self-assigned this Jul 10, 2026

HardlyDifficult requested a review from Copilot July 10, 2026 13:40

Copilot started reviewing on behalf of HardlyDifficult July 10, 2026 13:41 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread src/utils/token-standard/v2/settlement-factory.ts Outdated

Copilot started reviewing on behalf of HardlyDifficult July 10, 2026 16:59 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread src/utils/token-standard/v2/settlement-factory.ts Outdated

Comment thread src/utils/token-standard/v2/settlement-factory.ts Outdated

Comment thread test/unit/token-standard/v2/settlement-factory.test.ts

HardlyDifficult marked this pull request as draft July 10, 2026 17:04

cursor Bot reviewed Jul 10, 2026

View reviewed changes

fix: reject non-json settlement context

c5acfd9

HardlyDifficult marked this pull request as ready for review July 10, 2026 17:17

HardlyDifficult requested a review from Copilot July 10, 2026 17:17

Copilot started reviewing on behalf of HardlyDifficult July 10, 2026 17:17 View session

cursor Bot reviewed Jul 10, 2026

View reviewed changes

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread src/utils/token-standard/v2/settlement-factory.ts

HardlyDifficult marked this pull request as draft July 10, 2026 17:22

fix: validate settlement builder inputs

bbe685e

HardlyDifficult marked this pull request as ready for review July 10, 2026 17:33

HardlyDifficult requested a review from Copilot July 10, 2026 17:33

Copilot started reviewing on behalf of HardlyDifficult July 10, 2026 17:33 View session

cursor Bot reviewed Jul 10, 2026

View reviewed changes

Copilot AI reviewed Jul 10, 2026

View reviewed changes

HardlyDifficult self-assigned this Jul 10, 2026

Uh oh!

Conversation

HardlyDifficult commented Jul 10, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

claude Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

HardlyDifficult commented Jul 10, 2026

Uh oh!

coderabbitai Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

claude Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HardlyDifficult commented Jul 10, 2026

Uh oh!

HardlyDifficult commented Jul 10, 2026

Uh oh!

HardlyDifficult commented Jul 10, 2026

Uh oh!

coderabbitai Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

HardlyDifficult commented Jul 10, 2026

Uh oh!

claude Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

HardlyDifficult commented Jul 10, 2026 •

edited by cursor Bot

Loading

coderabbitai Bot commented Jul 10, 2026 •

edited

Loading

claude Bot commented Jul 10, 2026 •

edited

Loading

claude Bot commented Jul 10, 2026 •

edited

Loading

claude Bot commented Jul 10, 2026 •

edited

Loading

claude Bot commented Jul 10, 2026 •

edited

Loading

claude Bot commented Jul 10, 2026 •

edited

Loading

claude Bot commented Jul 10, 2026 •

edited

Loading

claude Bot commented Jul 10, 2026 •

edited

Loading

coderabbitai Bot commented Jul 10, 2026 •

edited

Loading

claude Bot commented Jul 10, 2026 •

edited

Loading

coderabbitai Bot commented Jul 10, 2026 •

edited

Loading

claude Bot commented Jul 10, 2026 •

edited

Loading

coderabbitai Bot commented Jul 10, 2026 •

edited

Loading