Mark AssetsAvailable, AssetsTotal and LossUnrealized of Vault object as Optional

[kuan121]

High Level Overview of Change

Mark the AssetsAvailable, AssetsTotal, and LossUnrealized fields of the Vault object as optional to match the behavior introduced by the recent rippled changes (git blame), which change those fields from soeREQUIRED to soeDEFAULT.

Context of Change

Fix #3152

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Refactor (non-breaking change that only restructures code)
• Tests (You added tests for code that already exists, or your new feature included in this PR)
• Documentation Updates
• Release

Did you update HISTORY.md?

• Yes
• No, this change does not impact library users

Test Plan

• Updated existing integration tests

[coderabbitai]

Walkthrough

This PR makes three properties of the Vault interface optional (AssetsTotal, AssetsAvailable, LossUnrealized) across type definitions, updates test assertions to handle undefined values using nullish coalescing operators, and documents the changes in the release notes.

Changes

Cohort / File(s)	Summary
Type definitions packages/xrpl/src/models/ledger/Vault.ts, packages/xrpl/src/models/methods/vaultInfo.ts	Converts AssetsTotal, AssetsAvailable, and LossUnrealized from required to optional properties by adding trailing question marks
Documentation packages/xrpl/HISTORY.md	Records the Vault interface fields becoming optional in the Unreleased → Fixed section
Test assertions packages/xrpl/test/integration/requests/vaultInfo.test.ts, packages/xrpl/test/integration/transactions/singleAssetVault.test.ts	Updates assertions to apply nullish coalescing operator (?? '0') when comparing AssetsTotal and AssetsAvailable values, providing default values when undefined

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

• Verify that all test assertions referencing AssetsTotal and AssetsAvailable have been updated consistently across both test files
• Confirm the nullish coalescing default value ('0') is semantically correct for vault asset comparisons
• Check for any other code paths or files that may reference these optional properties and require defensive null/undefined checks

Possibly related PRs

• Fix serialization of Issue type when asset is MPT #3090: Modifies the same Vault.ts interface (adds VaultFlags field), requiring coordination to avoid conflicts

Suggested reviewers

• achowdhry-ripple
• ckeshava
• pdp2121

Poem

🐰 Oh, vault fields dancing in optional light,
Three question marks shining so bright,
With coalescing grace through tests we proceed,
The docker wars vanquished—success indeed! ✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: marking three Vault object fields as optional, which directly matches the code modifications across multiple files.
Linked Issues check	✅ Passed	The PR addresses the core requirement of issue #3152 by making Vault fields optional to match rippled behavior, updating integration tests to handle the new field optionality, and restoring compatibility with the new rippled release.
Out of Scope Changes check	✅ Passed	All changes are focused on the stated objective: making three Vault fields optional and updating related tests. No extraneous modifications to unrelated code or features are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The pull request description provides a clear high-level overview, context linking to the root cause (rippled changes), identifies the issue being fixed (#3152), specifies the type of change (bug fix), confirms HISTORY.md was updated, and describes the test plan (updated integration tests).

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix-vault-related-integ-tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[Patel-Raj11]

It seems like a breaking change is introduced in rippled that makes these properties optional that were once required. If someone if accessing them directly as we did in integration tests, it would break their code.

Not to block this, but should we confirm this in cpp-informal or xrpl-lending-protocol-core slack channel?

[kuan121]

Thanks for bringing this up. I asked in #cpp-informal. The conclusion is this is fine since SAV is not even up for voting yet and breaking changes are allowed.

[Patel-Raj11]

Saw the note from Mayukha, since we are releasing library even before the amendment goes live on Mainnet, we should allow such breaking changes as bug fixes OR keep releasing, the features as release candidates and only release a stable version once the amendment is live on mainnet (to follow Semver). Some thoughts...

[kuan121]

What you said makes sense. Feel free to champion this, and we should adopt it if it brings benefits to the team and the community.

[ckeshava]

we are releasing library even before the amendment goes live on Mainnet, we should allow such breaking changes as bug fixes

Where can people use the client library features for Single-Asset-Vault? Apart from standalone nodes on their local nodes, is it available for use on public networks? (The XRPLF developers have the right to introduce breaking changes into the devnet, because features are experimental, by definition on the devnet.)

[ckeshava]

Hello Kuan, the changes proposed in this file aid the passing of integration tests related to Single-Asset-Vault. Is this PR blocking the execution of other integration tests as well?

[ckeshava]

Note: These fields have been marked as "Default", not "Optional". Hence, we need to introduce a Default value for these fields. I'm not sure if there is a precedent in the xrpl.js library, we'll need to look into it.

[kuan121]

Those fields of the Vault ledger entry were updated from soeREQUIRED to soeDEFAULT, and, by definition, soeDEFAULT is optional, if present, must not have default value. The correct TypeScript representation is simply making the field optional with ?, which is what we've done in this library, e.g., AccountRoot.AccountTxnID?, AccountRoot.AMMID?, AccountRoot.BurnedNFTokens?, AccountRoot.BurnedNFTokens?

[ckeshava]

Why is the test file supplying a default value for these fields? The default value of 0 must have been provided by rippled automatically.

It is preferable to remove the ?? operator because it will inform readers about the choices for default values.

Suggested change

	vault.AssetsTotal ?? '0',
	vault.AssetsTotal,

[kuan121]

The default value of 0 must have been provided by rippled automatically.

This is no longer true, and why those tests are failing. Without the change, we are performing assert.equal(vault.AssetsTotal=undefined, '0', 'New Vault should have zero total assets')

[ckeshava]

Suggested change

	* Mark the `AssetsAvailable`, `AssetsTotal`, and `LossUnrealized` fields of the Vault object as optional.
	* Mark the `AssetsAvailable`, `AssetsTotal`, and `LossUnrealized` fields of the Vault object as Default.

[kuan121]

I don't think we need to make this change. In rippled, soeDEFAULT is an internal serialization style. In xrpl.js/Typescript, fields are either required or optional (marked with ?). There is no concept of "Default" fields in TypeScript.

[ckeshava]

Why are these fields marked as Optional in the vaultInfo RPC method? As per my understanding, the vaultInfo RPC response prints the Default values for these fields, even if the genesis VaultCreate transaction did not explicitly specify these fields.

In your experiments, did you observe that vaultInfo does not print these fields?

[kuan121]

In your experiments, did you observe that vaultInfo does not print these fields?

Correct. The existing integration tests are failing because vaultInfo RPC doesn't include those fields in the response when they have default values. This match the definition of an soeDEFAULT field, which is optional, if present, must not have default value. In other words, If they have the default values, they won't be present in rippled, and thus Vault related RPC responses.

[ckeshava]

Thanks for the clarification: I was under the misapprehension that rippled stores ledger-object fields with "Default" values, that is not true.

I have created another ticket to track the misconfiguration of other ledger-objects, with respect to the DEFAULT parameter. #3154