Add Token Standard V2 allocation state recovery by HardlyDifficult · Pull Request #380 · Fairmint/canton-node-sdk

HardlyDifficult · 2026-07-10T05:08:34Z

Summary

add generic Token Standard V2 allocation-state recovery from one interface-filtered ACS snapshot
distinguish active Completed and Pending states while keeping absence as Unknown, never Failed
add exact-contract-ID batch reads that return each active allocation CID with its decoded interface view
fail closed on failed views, incomplete reassignments, missing contracts, duplicate inputs, ambiguous matches, inconsistent visibility rows, and sparse arrays
semantically parse Daml decimals, timestamps, metadata, accounts, settlement details, allocation details, requested time, and input holdings
preserve the merged Token Standard V2 holding-selection surface alongside allocation-state exports
expose the optional interface implementation package ID using a strict Zod 4 object schema

Why

After an allocation submission has an unknown outcome, callers need reusable state recovery without Fairmint-specific database or route logic. The active contract set can prove Completed or Pending, but cannot reconstruct a transient Failed result.

Atomic-settlement callers also need to validate the exact allocation contracts they will submit. Returning CIDs and decoded views from one required activeAtOffset snapshot prevents an off-ledger snapshot from being paired with different contract IDs later.

Validation

Exact head d225cf5:

TypeScript 7 core and lint typechecks passed
focused allocation-state, holding-selection, and interface-view suite: 47 tests passed
full unit suite: 69 suites, 738 tests passed
scoped ESLint, Prettier, and diff checks passed
package artifact gate: 5.41 MB unpacked across 1,313 files
all GitHub checks passed, including pinned CN Quickstart LocalNet, package artifacts, dependencies, CodeQL, and security
GitHub reports CLEAN/MERGEABLE and all eight review threads are resolved before the final latest-head reviewer pass

Dependencies

The allocation helpers from PR #374 and holding selection from PR #376 are merged into main.

…ard-allocation-state

coderabbitai · 2026-07-10T05:08:41Z

📝 Walkthrough

Walkthrough

Adds Token Standard V2 allocation-state types, decoding and validation, ACS-based Completed/Pending discovery, contract-ID lookup, public exports, interface-view schema support, and comprehensive unit tests.

Changes

Allocation state

Layer / File(s)	Summary
Allocation contracts and view decoding `src/utils/token-standard/v2/allocation-state.ts`, `src/clients/ledger-json-api/schemas/api/interface-view.ts`, `src/utils/token-standard/v2/index.ts`, `test/unit/schemas/interface-view.test.ts`, `test/unit/token-standard/v2/allocation-state.test.ts`	Defines allocation-state contracts, errors, identifiers, validation and decoding helpers, state types, public re-exports, and interface-view package-ID parsing coverage.
Identity matching and ACS normalization `src/utils/token-standard/v2/allocation-state.ts`	Normalizes requests and ledger rows, compares decoded identities canonically, and rejects inconsistent duplicate or incomplete rows.
Allocation view lookup `src/utils/token-standard/v2/allocation-state.ts`, `test/unit/token-standard/v2/allocation-state.test.ts`	Adds contract-ID lookup from one AllocationV2 ACS snapshot, including ordered results, missing-CID errors, and input validation.
Completed and pending state discovery `src/utils/token-standard/v2/allocation-state.ts`, `test/unit/token-standard/v2/allocation-state.test.ts`	Discovers matching Completed or Pending states, handles ambiguity and invalid views, and tests Unknown results and pre-query validation.

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

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant discoverTokenStandardV2AllocationState
  participant CantonLedger
  participant AllocationViewDecoder
  Caller->>discoverTokenStandardV2AllocationState: Submit allocation request
  discoverTokenStandardV2AllocationState->>CantonLedger: Query active AllocationV2 interfaces
  CantonLedger-->>discoverTokenStandardV2AllocationState: Return ACS rows
  discoverTokenStandardV2AllocationState->>AllocationViewDecoder: Decode and match identities
  AllocationViewDecoder-->>discoverTokenStandardV2AllocationState: Completed, Pending, or no match
  discoverTokenStandardV2AllocationState-->>Caller: Return state or Unknown

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 summarizes the main change: adding Token Standard V2 allocation state recovery.

✨ 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-allocation-state

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

claude · 2026-07-10T05:08:46Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

claude · 2026-07-10T06:37:12Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

claude · 2026-07-10T07:20:34Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

…allocation-state # Conflicts: # src/utils/token-standard/v2/allocation.ts # src/utils/token-standard/v2/index.ts # test/unit/token-standard/v2/allocation.test.ts

claude · 2026-07-10T13:01:11Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

claude · 2026-07-10T13:23:29Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/clients/ledger-json-api/schemas/api/interface-view.ts`:
- Line 16: Modernize the schema’s deprecated strict-object declaration by
replacing the `.strict()` usage in the relevant interface schema with Zod 4’s
`z.strictObject()` while preserving all existing fields and validation behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: b254ea5d-1e2c-4cfe-b039-0ae6d16aa18c

📥 Commits

Reviewing files that changed from the base of the PR and between c6883b0 and b108f2c.

📒 Files selected for processing (4)

src/clients/ledger-json-api/schemas/api/interface-view.ts
src/utils/token-standard/v2/allocation-state.ts
test/unit/schemas/interface-view.test.ts
test/unit/token-standard/v2/allocation-state.test.ts

claude · 2026-07-10T13:46:02Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

claude · 2026-07-10T16:24:13Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

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 3bccc22. Configure here.}

HardlyDifficult · 2026-07-10T16:30:04Z

cursor review

HardlyDifficult · 2026-07-10T16:30:05Z

@coderabbitai review

HardlyDifficult · 2026-07-10T16:30:06Z

Stage 2 on exact head 6bbf3bb: all checks are green including CN Quickstart, GitHub is CLEAN/MERGEABLE, and all five review threads are resolved. Latest-head Copilot was explicitly requested first, followed by Cursor and CodeRabbit; the PR remains unassigned while those reviewers respond.

coderabbitai · 2026-07-10T16:30:11Z

✅ 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 6bbf3bb. Configure here.}

Copilot

Pull request overview

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

HardlyDifficult · 2026-07-10T16:34:25Z

Resetting to draft after latest-head Copilot review: sparse arrays can bypass both string-array validation and equality checks, one interface-view failure message misidentifies instruction views, and current main has advanced into a merge conflict. I am merging current main with a normal merge commit, addressing all three findings with regressions, and rerunning the full gate before requesting fresh reviews.

claude · 2026-07-10T16:41:52Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

HardlyDifficult · 2026-07-10T16:41:57Z

Merged current main at a70bd54 with normal merge commit d225cf5, preserving both allocation-state recovery and holding-selection exports. Addressed all three latest-head Copilot findings and proactively closed the same sparse-array bypass for transfer-leg and allocation-CID inputs. Local validation passed: TypeScript 7 core/lint, 47 focused tests, targeted ESLint/Prettier, package artifact 5.41 MB / 1,313 files, and diff hygiene. Full unit and fresh CI are now running; the PR remains draft and unassigned.

HardlyDifficult · 2026-07-10T16:47:42Z

cursor review

HardlyDifficult · 2026-07-10T16:47:44Z

@coderabbitai review

HardlyDifficult · 2026-07-10T16:47:45Z

Stage 2 restarted on exact head d225cf5: all checks pass including CN Quickstart, GitHub is CLEAN/MERGEABLE, focused validation is 47/47, full unit validation is 69 suites / 738 tests, and all eight review threads are resolved. Latest-head Copilot was explicitly requested first, followed by Cursor and CodeRabbit; the PR remains unassigned while they respond.

coderabbitai · 2026-07-10T16:47:49Z

✅ 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 d225cf5. Configure here.}

Copilot

Pull request overview

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

HardlyDifficult · 2026-07-10T16:51:44Z

Final readiness sweep on exact head d225cf5: all checks pass, including CN Quickstart; GitHub reports CLEAN/MERGEABLE against main a70bd54; focused validation is 47/47 and the full unit suite is 69 suites / 738 tests; Copilot reviewed 5/5 changed files with no new comments; Cursor found no issues; CodeRabbit completed its latest incremental review; all eight threads are resolved; the worktree is clean. The PR is ready for final human review. It remains unassigned because no standing thumbs-up merge authorization is present.

HardlyDifficult added 9 commits July 9, 2026 22:52

feat: add token standard v2 allocation helpers

6a44988

fix: harden token standard v2 allocation helpers

eb9d7e5

fix: enforce daml decimal bounds

0a38862

style: align allocation error conventions

d92059b

fix: enforce daml json decimal syntax

4cd2a7a

fix: validate allocation helper runtime inputs

d728421

fix: require positive iteration funding

34346f2

feat: recover token allocation state from ACS

52c81c6

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

4be2c42

…ard-allocation-state

feat: read token allocations by contract id

c6883b0

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

cursor Bot reviewed Jul 10, 2026

View reviewed changes

Comment thread src/utils/token-standard/v2/allocation-state.ts Outdated

HardlyDifficult marked this pull request as draft July 10, 2026 07:12

fix: accept omitted optional allocation fields

4c044c9

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

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-…

dbc5712

…allocation-state # Conflicts: # src/utils/token-standard/v2/allocation.ts # src/utils/token-standard/v2/index.ts # test/unit/token-standard/v2/allocation.test.ts

HardlyDifficult marked this pull request as draft July 10, 2026 13:00

fix: accept implementation package IDs in interface views

b108f2c

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

coderabbitai Bot reviewed Jul 10, 2026

View reviewed changes

Comment thread src/clients/ledger-json-api/schemas/api/interface-view.ts Outdated

HardlyDifficult marked this pull request as draft July 10, 2026 13:43

refactor: use strict object for interface views

a5037f8

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread src/utils/token-standard/v2/allocation-state.ts

Comment thread src/utils/token-standard/v2/allocation-state.ts

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

fix(token-standard): harden recovered string maps

6bbf3bb

cursor Bot reviewed Jul 10, 2026

View reviewed changes

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

HardlyDifficult requested a review from Copilot July 10, 2026 16:30

Copilot started reviewing on behalf of HardlyDifficult July 10, 2026 16:30 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/allocation-state.ts

Comment thread src/utils/token-standard/v2/allocation-state.ts

Comment thread src/utils/token-standard/v2/allocation-state.ts

HardlyDifficult marked this pull request as draft July 10, 2026 16:34

Merge current main and harden allocation state arrays

d225cf5

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

HardlyDifficult requested a review from Copilot July 10, 2026 16:47

Copilot started reviewing on behalf of HardlyDifficult July 10, 2026 16:48 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 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

Validation

Dependencies

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)

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!

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!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

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

Uh oh!

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!

cursor Bot left a comment

Choose a reason for hiding this comment

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!

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.

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!

HardlyDifficult commented Jul 10, 2026 •

edited

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