Merge branch 'main' into worktree-fix-validated-ledger-optional-age

Author: sappenin

.github/workflows/workflow.yml

@@ -216,6 +216,92 @@ jobs:
       - name: Build
         run: mvn clean install -Dmaven.javadoc.skip=true -Pandroid
 
+  # Verifies the mpt-crypto native libraries (loaded via JNA) on each platform we ship binaries for.
+  build_confidential_native_its:
+    name: confidential_native_${{ matrix.platform }}_${{ matrix.network }}
+    needs: resolve_xrpld_image
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Linux x86-64 runners have Docker, so the confidential MPT ITs run against the local
+          # rippled Testcontainer and exercise the real native library end-to-end.
+          - os: ubuntu-latest
+            platform: linux-x86-64
+            java: '8'
+            network: local-rippled
+            it_flags: ''
+          # The rippleci/xrpld image is published for linux/amd64 only, so the ARM Linux runner
+          # registers QEMU binfmt handlers to run the amd64 rippled container under emulation.
+          - os: ubuntu-24.04-arm
+            platform: linux-aarch64
+            java: '8'
+            network: local-rippled
+            it_flags: ''
+            setup_qemu: true
+          # Intel macOS runners have no Docker preinstalled, but support virtualization, so
+          # Colima provides a Docker engine for the rippled Testcontainer.
+          - os: macos-15-intel
+            platform: darwin-x86-64
+            java: '8'
+            network: local-rippled
+            it_flags: ''
+            setup_docker_via_colima: true
+          # ARM macOS runners cannot run Docker at all (Apple's Virtualization Framework does not
+          # support nested virtualization), and Windows runners cannot run Linux containers, so
+          # these platforms run the confidential MPT ITs against Devnet instead of a local rippled.
+          # Temurin doesn't ship JDK 8 for macOS ARM64, so we use JDK 11 there.
+          - os: macos-14
+            platform: darwin-aarch64
+            java: '11'
+            network: devnet
+            it_flags: '-DuseDevnet'
+          - os: windows-latest
+            platform: win32-x86-64
+            java: '8'
+            network: devnet
+            it_flags: '-DuseDevnet'
+    runs-on: ${{ matrix.os }}
+    env:
+      XRPLD_DOCKER_IMAGE: ${{ needs.resolve_xrpld_image.outputs.image }}
+    defaults:
+      run:
+        shell: bash
+    steps:
+      # Checks-out the repository under $GITHUB_WORKSPACE
+      - uses: actions/checkout@v6
+      - name: Set up JDK ${{ matrix.java }}
+        uses: actions/setup-java@v5
+        with:
+          distribution: 'temurin'
+          java-version: ${{ matrix.java }}
+          cache: 'maven'
+      - name: Set up QEMU for amd64 emulation
+        if: matrix.setup_qemu
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: amd64
+      - name: Set up Docker via Colima
+        if: matrix.setup_docker_via_colima
+        run: |
+          brew install colima docker
+          colima start --cpus 3 --memory 8
+          echo "DOCKER_HOST=unix://$HOME/.colima/default/docker.sock" >> "$GITHUB_ENV"
+          echo "TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock" >> "$GITHUB_ENV"
+      # Only the local-rippled rows pull an xrpld image, so only they need the registry login. This step must follow
+      # the Colima setup above, which is what provides the Docker daemon on the macOS Intel runner.
+      - name: Log in to private registry
+        if: matrix.network == 'local-rippled'
+        uses: ./.github/actions/xrpld-login
+        with:
+          is_private: ${{ needs.resolve_xrpld_image.outputs.is_private }}
+          username: ${{ vars.GITLAB_REGISTRY_USERNAME }}
+          token: ${{ secrets.GITLAB_REGISTRY_TOKEN }}
+      - name: Build and run unit tests
+        run: mvn clean install -DskipITs -Dmaven.javadoc.skip=true
+      - name: Run Confidential MPT ITs
+        run: mvn -pl xrpl4j-integration-tests verify -Dit.test='Confidential*IT' -Dfailsafe.failIfNoSpecifiedTests=true ${{ matrix.it_flags }} -Dmaven.javadoc.skip=true
+
   build_devnet_its:
     runs-on: ubuntu-latest
     steps:

pom.xml

@@ -51,6 +51,11 @@
         <artifactId>xrpl4j-client</artifactId>
         <version>${project.version}</version>
       </dependency>
+      <dependency>
+        <groupId>${project.groupId}</groupId>
+        <artifactId>xrpl4j-mpt-crypto</artifactId>
+        <version>${project.version}</version>
+      </dependency>
       <dependency>
         <groupId>com.fasterxml.jackson</groupId>
         <artifactId>jackson-bom</artifactId>
@@ -172,6 +177,11 @@
         <artifactId>bcprov-jdk18on</artifactId>
         <version>1.84</version>
       </dependency>
+      <dependency>
+        <groupId>net.java.dev.jna</groupId>
+        <artifactId>jna</artifactId>
+        <version>5.18.1</version>
+      </dependency>
       <dependency>
         <groupId>org.awaitility</groupId>
         <artifactId>awaitility</artifactId>
@@ -278,6 +288,7 @@
 
   <modules>
     <module>xrpl4j-core</module>
+    <module>xrpl4j-mpt-crypto</module>
     <module>xrpl4j-integration-tests</module>
     <module>xrpl4j-client</module>
     <module>xrpl4j-bom</module>
@@ -314,6 +325,8 @@
                   <ignoredDependency>com.google.code.findbugs:annotations</ignoredDependency>
                   <ignoredDependency>com.google.errorprone:error_prone_annotations</ignoredDependency>
                   <ignoredDependency>ch.qos.logback:logback-classic</ignoredDependency>
+                  <!-- Loaded via reflection-->
+                  <ignoredDependency>org.xrpl:xrpl4j-mpt-crypto</ignoredDependency>
                   <!-- As part of SkyStreamer, but only for test scope-->
                   <ignoredDependency>com.vaadin.external.google:android-json</ignoredDependency>
                   <ignoredDependency>org.junit.jupiter:junit-jupiter-engine</ignoredDependency>
@@ -494,7 +507,7 @@
         <plugin>
           <groupId>org.sonatype.central</groupId>
           <artifactId>central-publishing-maven-plugin</artifactId>
-          <version>0.5.0</version>
+          <version>0.11.0</version>
           <extensions>true</extensions>
           <configuration>
             <publishingServerId>central</publishingServerId>

xrpl4j-bom/pom.xml

@@ -25,6 +25,11 @@
         <artifactId>xrpl4j-core</artifactId>
         <version>${project.version}</version>
       </dependency>
+      <dependency>
+        <groupId>${project.groupId}</groupId>
+        <artifactId>xrpl4j-mpt-crypto</artifactId>
+        <version>${project.version}</version>
+      </dependency>
     </dependencies>
   </dependencyManagement>
 </project>

xrpl4j-core/pom.xml

@@ -91,6 +91,10 @@
       <groupId>org.bouncycastle</groupId>
       <artifactId>bcprov-jdk18on</artifactId>
     </dependency>
+    <dependency>
+      <groupId>net.java.dev.jna</groupId>
+      <artifactId>jna</artifactId>
+    </dependency>
     <dependency>
       <groupId>com.jayway.jsonpath</groupId>
       <artifactId>json-path-assert</artifactId>

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/codec/addresses/SeedCodec.java

@@ -20,8 +20,10 @@
  * =========================LICENSE_END==================================
  */
 
+import com.google.common.collect.ImmutableSet;
 import com.google.common.collect.Lists;
 import com.google.common.primitives.UnsignedInteger;
+import org.xrpl.xrpl4j.codec.addresses.exceptions.DecodeException;
 import org.xrpl.xrpl4j.codec.addresses.exceptions.EncodeException;
 import org.xrpl.xrpl4j.codec.addresses.exceptions.EncodingFormatException;
 
@@ -36,6 +38,11 @@ public class SeedCodec {
 
   private static final SeedCodec INSTANCE = new SeedCodec();
 
+  // A 16-byte ED25519 or SECP256K1 seed Base58Check-encodes to 31 or 29 characters, respectively; a 32-byte
+  // SECP256K1 seed (used only for ElGamal seeds; see #encodeSeed) encodes to 51 characters. No other length is
+  // decodable -- e.g. a 32-byte ED25519 seed would encode to 53 characters, but #encodeSeed refuses to produce one.
+  private static final ImmutableSet<Integer> VALID_SEED_LENGTHS = ImmutableSet.of(29, 31, 51);
+
   public static SeedCodec getInstance() {
     return INSTANCE;
   }
@@ -52,6 +59,24 @@ public static SeedCodec getInstance() {
   public Decoded decodeSeed(final String base58EncodedSeed) throws EncodingFormatException {
     Objects.requireNonNull(base58EncodedSeed);
 
+    if (!VALID_SEED_LENGTHS.contains(base58EncodedSeed.length())) {
+      throw new DecodeException(
+        String.format("Invalid seed length %s; expected %s.", base58EncodedSeed.length(), VALID_SEED_LENGTHS)
+      );
+    }
+
+    // A 32-byte secp256k1 seed (used only for ElGamal seeds; see #encodeSeed) Base58Check-encodes to 51 characters,
+    // versus 29 for the standard 16-byte payload. Detect that length here since AddressBase58.decode needs the
+    // expected payload size up front to pick the right branch.
+    if (base58EncodedSeed.length() == 51) {
+      return AddressBase58.decode(
+        base58EncodedSeed,
+        Lists.newArrayList(KeyType.SECP256K1),
+        Lists.newArrayList(Version.FAMILY_SEED),
+        Optional.of(UnsignedInteger.valueOf(32))
+      );
+    }
+
     return AddressBase58.decode(
       base58EncodedSeed,
       Lists.newArrayList(KeyType.ED25519, KeyType.SECP256K1),
@@ -72,11 +97,22 @@ public String encodeSeed(final UnsignedByteArray entropy, final KeyType type) {
     Objects.requireNonNull(entropy);
     Objects.requireNonNull(type);
 
-    if (entropy.getUnsignedBytes().size() != 16) {
-      throw new EncodeException("entropy must have length 16.");
+    if (entropy.getUnsignedBytes().size() != 16 && entropy.getUnsignedBytes().size() != 32) {
+      throw new EncodeException("entropy must have length 16 or 32.");
+    }
+
+    // 32-byte entropy exists only to support ElGamal secp256k1 seeds (see Seed#elGamalSecp256k1SeedFromEntropy).
+    // Encoding 32 bytes under any non-secp256k1 prefix yields a seed that decodeSeed cannot decode -- e.g. the ED25519
+    // prefix produces a 53-character seed that matches neither the 51-character secp256k1 branch nor the 16-byte
+    // fallback -- so it would be silently unrecoverable. Gate on SECP256K1 (rather than excluding ED25519) so a
+    // future KeyType with 32-byte entropy is rejected by default rather than mistakenly accepted.
+    if (entropy.getUnsignedBytes().size() == 32 && !type.equals(KeyType.SECP256K1)) {
+      throw new EncodeException("32-byte entropy is only supported for SECP256K1 seeds, but was " + type + ".");
     }
 
     Version version = type.equals(KeyType.ED25519) ? Version.ED25519_SEED : Version.FAMILY_SEED;
-    return AddressBase58.encode(entropy, Lists.newArrayList(version), UnsignedInteger.valueOf(16));
+    return AddressBase58.encode(
+      entropy, Lists.newArrayList(version), UnsignedInteger.valueOf(entropy.getUnsignedBytes().size())
+    );
   }
 }

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

@@ -1,6 +1,7 @@
 package org.xrpl.xrpl4j.codec.binary.types;
 
 import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.node.TextNode;
 import org.xrpl.xrpl4j.codec.addresses.UnsignedByteArray;
 import org.xrpl.xrpl4j.codec.binary.serdes.BinaryParser;
 
@@ -28,4 +29,9 @@ public UInt192Type fromParser(BinaryParser parser) {
   public UInt192Type fromJson(JsonNode node) {
     return new UInt192Type(UnsignedByteArray.fromHex(node.asText()));
   }
+
+  @Override
+  public JsonNode toJson() {
+    return new TextNode(toHex());
+  }
 }

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

@@ -38,7 +38,7 @@ public class UInt64Type extends UIntType<UInt64Type> {
    * These fields are represented as base 10 Strings in JSON, whereas all other STUInt64s are represented in base16.
    */
   protected static final Set<String> BASE_10_UINT64_FIELD_NAMES = Sets.newHashSet(
-    "MaximumAmount", "OutstandingAmount", "MPTAmount", "LockedAmount"
+    "MaximumAmount", "OutstandingAmount", "MPTAmount", "LockedAmount", "ConfidentialOutstandingAmount"
   );
 
   public UInt64Type() {

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/crypto/confidential/ConfidentialBatchInner.java

@@ -0,0 +1,89 @@
+package org.xrpl.xrpl4j.crypto.confidential;
+
+/*-
+ * ========================LICENSE_START=================================
+ * xrpl4j :: core
+ * %%
+ * Copyright (C) 2020 - 2026 XRPL Foundation and its contributors
+ * %%
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * =========================LICENSE_END==================================
+ */
+
+import com.google.common.base.Preconditions;
+import org.immutables.value.Value;
+import org.xrpl.xrpl4j.model.transactions.Transaction;
+
+import java.util.Optional;
+
+/**
+ * One entry in a confidential Batch: either a {@link ConfidentialMptOp} the assembler builds into a transaction and
+ * proof, or a pre-built plain (non-confidential) {@link Transaction} to interleave.
+ *
+ * <p>A plain inner is passed through untouched, so the caller must supply it already shaped as an inner-batch
+ * transaction — {@code Fee: 0}, the {@code tfInnerBatchTxn} flag, an empty {@code SigningPubKey}, and its own
+ * {@code Sequence} or {@code TicketSequence} (the assembler cannot re-shape an arbitrary immutable transaction, and
+ * xrpl4j has no autofill). The {@code RawTransactionWrapper}/{@code Batch} validation rejects a malformed plain inner.
+ * The assembler advances the submitter's sequence counter past a plain inner that consumed a regular sequence, so a
+ * later confidential inner for the same account is numbered correctly.</p>
+ */
+@Value.Immutable
+public interface ConfidentialBatchInner {
+
+  /**
+   * A confidential-operation inner.
+   *
+   * @param operation The {@link ConfidentialMptOp} to build.
+   *
+   * @return A {@link ConfidentialBatchInner} wrapping {@code operation}.
+   */
+  static ConfidentialBatchInner of(final ConfidentialMptOp operation) {
+    return ImmutableConfidentialBatchInner.builder().operation(operation).build();
+  }
+
+  /**
+   * A pre-built plain (non-confidential) inner, already shaped as an inner-batch transaction.
+   *
+   * @param plainTransaction The plain {@link Transaction} to pass through.
+   *
+   * @return A {@link ConfidentialBatchInner} wrapping {@code plainTransaction}.
+   */
+  static ConfidentialBatchInner ofPlain(final Transaction plainTransaction) {
+    return ImmutableConfidentialBatchInner.builder().plainTransaction(plainTransaction).build();
+  }
+
+  /**
+   * The confidential operation, if this inner is a confidential op-spec.
+   *
+   * @return An optionally-present {@link ConfidentialMptOp}.
+   */
+  Optional<ConfidentialMptOp> operation();
+
+  /**
+   * The plain transaction, if this inner is a pre-built plain transaction.
+   *
+   * @return An optionally-present {@link Transaction}.
+   */
+  Optional<Transaction> plainTransaction();
+
+  /**
+   * Enforces that exactly one of {@link #operation()} or {@link #plainTransaction()} is present.
+   */
+  @Value.Check
+  default void check() {
+    Preconditions.checkArgument(
+      operation().isPresent() ^ plainTransaction().isPresent(),
+      "a ConfidentialBatchInner must hold exactly one of a confidential operation or a plain transaction"
+    );
+  }
+}