Add Single Asset Vault support - XLS-65 by Patel-Raj11 · Pull Request #713 · XRPLF/xrpl4j

Patel-Raj11 · 2026-03-16T19:49:39Z

Single Asset Vault - XLS-65
Single Asset Vault had multiple PRs, so rippled/xrpld release 3.1.0 was considered as source of truth for Transactions, ledger objects, RPC and binary codec changes.

Transactions added/updated:

VaultCreate
VaultSet
VaultDelete
VaultDeposit
VaultWithdraw
VaultClawback
MpTokenIssuanceCreate
MpTokenIssuanceSet

Ledger objects added/updated:

VaultObject
MpTokenIssuanceObject

RPC added/updated:

vault_info

Binary codec added/updated:

IssueType
NumberType

MPT DEX PR and this PR both have IssueType binary codec change and Issue object refactoring change in common. Since, Single Asset Vault is up for voting, this PR would likely get merged first. So, I have kept these suggestions in mind when making changes:

…ault

sappenin · 2026-03-18T23:18:36Z

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/codec/binary/types/IssueType.java


-    UnsignedByteArray byteArray = new CurrencyType().fromJson(issue.currency()).value();
+    if (issue.mptIssuanceId().isPresent()) {
+      // MPTokenIssuanceID binary format: issuer (20 bytes) + ACCOUNT_ONE (20 bytes) + sequence (4 bytes) = 44 bytes


Remind me why rippled adds an additional ACCOUNT_ONE into the binary encoding? I feel like there was a good reason, but I can't remember it.

Also, we should update the comment description to properly describe the two different formats. Currently, the only descriptor is binary vs hex, which is confusing (generally binary and hex should be the same, but in this case they're not, which means they're describing two different values)

why rippled adds an additional ACCOUNT_ONE into the binary encoding?

IOU - currency (20 bytes) || issuer (20 bytes)
MPT - issuer (20 bytes) || ACCOUNT_ONE (20 bytes) || sequence (4 bytes)

I think ACCOUNT_ONE acts as a discriminator between IOU and MPT for deserializer. Reading first 20 bytes helps us to distinguish between XRP (all zeros) and IOU/MPT, but it won't be possible to distinguish between IOU and MPT if ACCOUNT_ONE is not present.

Updated the code comment in 5256ce8

sappenin · 2026-03-19T00:00:31Z

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/codec/binary/types/NumberType.java

+        // After rounding, mantissa may exceed MAX_INT64 again
+        if (absMantissa.compareTo(MAX_INT64) > 0) {
+          if (exponent >= MAX_EXPONENT) {
+            throw new IllegalArgumentException("Exponent overflow: value too large to represent");


This line seems uncovered by the unit test.

Addressed in 5256ce8

sappenin · 2026-03-19T00:00:47Z

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/codec/binary/types/NumberType.java

+          lastDigit = absMantissa.mod(BigInteger.TEN);
+          absMantissa = absMantissa.divide(BigInteger.TEN);
+          exponent++;
+          if (lastDigit.compareTo(BigInteger.valueOf(5)) >= 0) {


This line seems uncovered by the unit test.

Addressed in 5256ce8

sappenin · 2026-03-19T00:04:55Z

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/codec/binary/types/Issue.java

+   * @return An optionally present {@link JsonNode}.
+   */
+  @JsonProperty("mpt_issuance_id")
+  Optional<JsonNode> mptIssuanceId();


This is technically a breaking change (though I doubt any external software is using this object, but you never know).

Can we capture somewhere a list of all breaking changes in this PR? We'll want to use that to draft release notes. We should probably have (as part of this PR) something that outlines info that will eventually make its way into a migration guide, sort of like this one.

I think since mptIssuanceId is Optional, it won't be a breaking change. Any user using Issue object present in binary.types package would still be able to create Issue object the way they have been creating it, ever after the upgrade. Did I understand it incorrectly?

There is a breaking change in Issue interface present in model.ledger package this PR, and I am planning to document it.

sappenin · 2026-03-19T00:06:40Z

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/crypto/signing/SignatureUtils.java

      transactionWithSignature = PermissionedDomainDelete.builder().from((PermissionedDomainDelete) transaction)
        .transactionSignature(signature)
        .build();
+    } else if (VaultCreate.class.isAssignableFrom(transaction.getClass())) {


FYI - take a look at #712 and #715. That change will remove the need to update these types here.

I suggest we merge that before merging this PR, FWIW.

Will rebase and adjust once #712 and #715 are merged.

Added migration guide - 31ba40e

sappenin · 2026-03-20T23:08:23Z

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/jackson/modules/VaultDataDeserializer.java

+
+  @Override
+  public VaultData deserialize(JsonParser jsonParser, DeserializationContext ctxt) throws IOException {
+    return VaultData.of(jsonParser.getText());


I'm not sure VaultData should be a String, but maybe it should? It's going to be binary data, so if it's a String it will be Hex, right?

(maybe this is fine, but I'm trying to think if VaultData should actually just hold an array (e.g., List of UnsignedByte).

That said, perhaps there's prior art in xrpl4j for this kind of thing?

VaultData is a wrapper type containing String and it has checks to make sure that the content is valid Hex.
I followed the convention that we have in xrpl4j for such metadata (MpTokenMetadata, DidData etc).

We could make this type wrap List<UnsignedByte> or UnsignedByteArray and update the serializer and deserialize to do bytes <-> String (Hex) conversion, but I think doing that won't make much difference as we will anyway provide static convenience methods like fromHex for users to create an instance of VaultData from off-chain binary data that they would have stored in Hex format.

sappenin · 2026-03-20T23:30:21Z

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/ledger/VaultObject.java

+   * @return An optionally-present {@link AssetScale}.
+   */
+  @JsonProperty("Scale")
+  Optional<AssetScale> scale();


In the spec, scale and most of the other values have are required (but default to 0).

Looks like only data and assetsMaximum are actually optional.

See https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0065-single-asset-vault#212-fields

Thanks for highlighting this. I was marking all thesoeDEFAULT fields as optional just to be on safer side. But now have updated them to default to zero value of their type. From ledger_entries.macro only
Data is soeOPTIONAL other fields are either soeREQUIRED or soeDEFAULT.

Addressed in 5256ce8

sappenin · 2026-03-20T23:32:20Z

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/transactions/VaultCreate.java

+      },
+      iouIssue -> {
+        long scaleVal = scaleValue.value().longValue();
+        if (scaleVal < 0 || scaleVal > 18) {


I think this line needs some more coverage.

AssetScale wraps UnsignedInteger, so I have updated the check accordingly and now this line has full coverage.

Addressed in 5256ce8

sappenin · 2026-03-20T23:34:51Z

xrpl4j-core/src/test/java/org/xrpl/xrpl4j/codec/binary/BinarySerializationTests.java

        .issuer(Address.of("rPZtDb6ZHtfYzMmzyUGvehoi2vYhrNAPhy"))
        .build()
      )
-      .asset2(Issue.builder()


This is a breaking change - see my other comment about how we should document breakage?

Added in 95a0530

sappenin · 2026-03-20T23:37:16Z

xrpl4j-core/src/test/java/org/xrpl/xrpl4j/model/transactions/AssetAmountTest.java

+ * ========================LICENSE_START=================================
+ * xrpl4j :: core
+ * %%
+ * Copyright (C) 2020 - 2023 XRPL Foundation and its contributors


Minor nit - If you're adding new files and adding a license, can you make the date correct, like this:

Suggested change

* Copyright (C) 2020 - 2023 XRPL Foundation and its contributors

* Copyright (C) 2020 - 2026 XRPL Foundation and its contributors

(Alternatively, don't add this license and it will get taken care of, eventually, by #669)

Addressed in 5256ce8 as one off. But fixing #669 is the right approach.

…ault

codecov · 2026-03-24T04:48:37Z

Codecov Report

❌ Patch coverage is 97.59036% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.70%. Comparing base (e48a6a6) to head (5cd4613).

Files with missing lines	Patch %	Lines
...org/xrpl/xrpl4j/codec/binary/types/NumberType.java	93.97%	0 Missing and 5 partials ⚠️
...l4j/model/client/vault/VaultInfoRequestParams.java	88.23%	1 Missing and 1 partial ⚠️
.../org/xrpl/xrpl4j/model/flags/VaultCreateFlags.java	95.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #713      +/-   ##
============================================
+ Coverage     92.38%   92.70%   +0.32%     
- Complexity     2115     2259     +144     
============================================
  Files           437      459      +22     
  Lines          5594     5910     +316     
  Branches        430      479      +49     
============================================
+ Hits           5168     5479     +311     
  Misses          279      279              
- Partials        147      152       +5

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

cybele-ripple · 2026-03-24T16:25:29Z

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/codec/binary/types/NumberType.java

+  // xrpld implementation: src/libxrpl/basics/Number.cpp -> doNormalize
+  @Override
+  public NumberType fromJson(JsonNode node) {
+    String value = node.isInt() || node.isLong() ? String.valueOf(node.asLong()) : node.asText();


Can you add a test case for when node.isInt() returns true and node.isLong() returns true? Looks like just the node.asText() true case is tested

I think instead I should remove these checks as the type would always be string since AssetAmount wraps String type.

Removed these checks in 4d6b600

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/flags/VaultFlags.java

cybele-ripple · 2026-03-24T17:33:53Z

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/jackson/modules/IssueDeserializer.java

+  @Override
+  public Issue deserialize(JsonParser jsonParser, DeserializationContext ctxt) throws IOException {
+    JsonNode node = jsonParser.getCodec().readTree(jsonParser);
+


Would there be an instance where mpt_issuance_id and currency are present? If so, maybe include something like

boolean hasMpt = node.has("mpt_issuance_id"); boolean hasCurrency = node.has("currency"); // Validate mutual exclusivity if (hasMpt && hasCurrency) { throw new IOException( "Invalid Issue JSON: cannot have both 'mpt_issuance_id' and 'currency' fields" ); }

This codepath would get exercised when parsing the transaction/ledger object from rippled. The object returned would never have both mpt_issuance_id and currency present at the same time.

xrpl4j-integration-tests/src/test/java/org/xrpl/xrpl4j/tests/SingleAssetVaultIT.java

Patel-Raj11 · 2026-03-26T18:09:35Z

/ai-review

zach-source · 2026-03-26T21:27:16Z

/ai-review

xrplf-ai-reviewer

ℹ️ Note: This is a large diff (403,683 chars). Complex issues deep in the diff may receive less attention.

Four issues flagged inline: a typo in IssueType.java, an NPE risk in IssueDeserializer, a validation gap in VaultInfoRequestParams.check() that produces misleading errors, and missing codec fixtures for five of the six new vault transaction types.

Review by Claude Opus 4.6 · Prompt: V12

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/codec/binary/types/IssueType.java

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/jackson/modules/IssueDeserializer.java

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/client/vault/VaultInfoRequestParams.java

xrpl4j-core/src/test/resources/codec-fixtures.json

xrpl4j-integration-tests/src/test/java/org/xrpl/xrpl4j/tests/SingleAssetVaultIT.java

Patel-Raj11 added 12 commits March 12, 2026 10:40

initial commit

10f0f48

add tests for IssueType

0778c7e

add NumberType tests

b352310

add tests

b356de7

add DomainID to permission domain

e5c7d5d

add fixtures

38de730

rename NumberAmount to AssetAmount

1735fbe

add IssueType tests

74866b0

import IT

e04b31d

add more tests

756f6b3

Merge branch 'main' of github.com:XRPLF/xrpl4j into rp/single-asset-v…

b9a4984

…ault

fix checkstyle warnings

623ac44

Patel-Raj11 requested review from nhartner, nkramer44 and sappenin as code owners March 16, 2026 19:49

Patel-Raj11 requested review from cybele-ripple and removed request for nhartner and nkramer44 March 16, 2026 19:50

sappenin requested changes Mar 20, 2026

View reviewed changes

Patel-Raj11 mentioned this pull request Mar 23, 2026

Refactor SignatureUtils (#2-of-2) #715

Merged

Patel-Raj11 added 2 commits March 23, 2026 21:44

Merge branch 'main' of github.com:XRPLF/xrpl4j into rp/single-asset-v…

318e66c

…ault

address code review comments

5256ce8

add migration guide

95a0530

Patel-Raj11 requested a review from sappenin March 24, 2026 12:55

cybele-ripple reviewed Mar 24, 2026

View reviewed changes

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/flags/VaultFlags.java Show resolved Hide resolved

cybele-ripple reviewed Mar 24, 2026

View reviewed changes

remove unnecessary checks

4d6b600

github-code-quality bot found potential problems Mar 24, 2026

View reviewed changes

Patel-Raj11 added 2 commits March 25, 2026 12:02

merge main

41d2a8e

small refactor

e7a4a7c

github-code-quality bot found potential problems Mar 25, 2026

View reviewed changes

update migration guide

31ba40e

xrplf-ai-reviewer bot reviewed Mar 26, 2026

View reviewed changes

Patel-Raj11 added 2 commits March 27, 2026 09:20

xrpl-ai suggestions

e2f2730

disable SingleAssetVaultIT on Testnet

5cd4613

github-code-quality bot found potential problems Apr 1, 2026

View reviewed changes

cybele-ripple approved these changes Apr 2, 2026

View reviewed changes

	* Copyright (C) 2020 - 2023 XRPL Foundation and its contributors
	* Copyright (C) 2020 - 2026 XRPL Foundation and its contributors

Conversation

Patel-Raj11 commented Mar 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Patel-Raj11 Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Patel-Raj11 commented Mar 26, 2026

Uh oh!

zach-source commented Mar 26, 2026

Uh oh!

xrplf-ai-reviewer bot left a comment

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Mar 24, 2026 •

edited

Loading

Patel-Raj11 Mar 24, 2026 •

edited

Loading