feat(dapp): reserve only the granted amount when a grant is created

[lmcorbalan]

Summary

Closes #180

VestingFactory_CreateVesting now splits the funder's inputs itself, so a grant reserves its
own amount instead of every holding it names. Consumes canton-vesting-forge v0.2.0.

Changes

• A grant reserves exactly the granted amount, and the rest of the funder's balance stays spendable
• Creating a grant discloses the instrument config and passes it to the factory, still one approval
• Accept discloses the single holding the proposal names
• The funder records that holding's blob after the write, reconciling every outstanding grant
• Pending grants are filtered by instrument, like grants and claims
• Vendored vesting.dar moves to v0.2.0

Deviations

• The blob Accept needs is read after the submit rather than off the inputs: the holding it belongs to is created by that submission
• Every outstanding grant is reconciled, not only the new one, so a read that failed once is picked up by the next grant
• Pending grants gained the instrument filter, which the proposal's new admin and instrumentId fields made possible
• vendor/PROVENANCE.md records why an existing ledger refuses the new package

Acceptance criteria

• Creating a grant fetches the instrument config and passes it to the factory
• Only the granted amount is withheld from the funder's available balance
• Creating a grant remains one submission and one wallet approval
• Accepting a grant discloses one holding rather than every holding it named
• No copy or doc still explains a whole-holding reservation

Test plan

Automated tests

1. Run pnpm install
2. Run pnpm -C dapp/frontend test
3. Expect 200 passing tests

Manual verification

1. Run ./scripts/dev-stack.sh down, then ( cd .canton-localnet && ../node_modules/.bin/canton-barebones reset )
2. Run ./scripts/dev-stack.sh up and open http://localhost:3012 with a CIP-0103 wallet
3. Tap 1000 DBT, then create a grant of 400 to a second account
4. Expect the balance to read 600 while the grant is pending, and the receiver to accept in one approval

Breaking changes

A ledger that already carries vesting 0.0.1 rejects the new DAR with NOT_VALID_UPGRADE_PACKAGE.
Reset the LocalNet before up, as step 1 of the manual verification does.

Checklist

• Self-reviewed my own diff
• Tests added or updated
• Docs updated (if applicable)
• No unrelated changes bundled in

Screenshots

To be added before review.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
demo.canton-dappbooster	Ready	Preview	Sep 9, 2026 12:58pm UTC
docs.canton-dappbooster	Ready	Preview	Sep 9, 2026 12:58pm UTC

[Copilot]

🔵 Needs a closer look

It reworks critical ledger/state-reconciliation logic and relies on a breaking upgrade to an external vendored DAR whose split semantics and tokenCid field cannot be verified from the diff, warranting human review.

Pull request overview

This PR changes the vesting dApp so that creating a grant reserves only the granted amount rather than the whole holdings it names. This is possible because the upgraded canton-vesting-forge v0.2.0 DAR makes VestingFactory_CreateVesting split the funder's inputs itself (transferring exactly the grant amount into one holding and returning the change in the same transaction), which is why creating a grant now also discloses the InstrumentConfig. The frontend follows suit: a pending grant now names a single reserved holding (tokenCid), disclosure blobs are read back and reconciled after the write, and pending grants gain an instrument filter now that the proposal carries admin/instrumentId.

Changes:

• Backend now reserves the single split-off holding per grant (reservedToken), passes configCid to buildCreateVestingCommand, and reconciles funder disclosure blobs in localStorage after the submit (with a bounded read-miss guard so a permanently-missing holding stops costing a read).
• accept and freeTokens/balanceOf updated to the one-holding model; pending grants are now filtered by instrument like grants/claims.
• Vendored vesting.dar moved to v0.2.0, with PROVENANCE.md documenting the NOT_VALID_UPGRADE_PACKAGE reset requirement, and user copy/architecture docs updated to the "reserve exactly this amount" behavior.

File summaries

File	Description
vendor/PROVENANCE.md	Bumps vendored vesting.dar to v0.2.0 and records why an existing ledger must be reset before upload.
dapp/frontend/src/components/CreateGrant/index.tsx	Updates the amount-field copy to reflect that only the granted amount is reserved.
dapp/frontend/src/backend/VestingBackend.ts	Replaces pledgedTokens with reservedToken (single holding), adds fundedBy, updates selectHoldings rationale.
dapp/frontend/src/backend/VestingBackend.test.ts	Adjusts tests to the single reserved-token model.
dapp/frontend/src/backend/LedgerBackend.ts	Adds disclosure-blob reconciliation (storeFunding/reconcileFunding/miss-limit), returns disclosed set from submitWithConfig, reworks createVesting/accept/freeTokens, filters pending grants by instrument.
dapp/frontend/src/backend/LedgerBackend.test.ts	Rewrites the harness to model the factory split and adds coverage for reconciliation, miss-limit, overlap, and instrument filtering.
dapp/frontend/src/backend/commands.ts	Adds configCid to the VestingFactory_CreateVesting choice arguments.
dapp/frontend/src/backend/commands.test.ts	Adds configCid assertions to the command-builder test.
dapp/frontend/architecture.md	Rewrites the "one approval" section to describe the factory split, reconciliation, and instrument filtering.

Review details

• Files reviewed: 8/10 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.