X: Move non-conflicting interface classes from API project

publishGitHub.sh

@@ -1,9 +1,28 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+if [ "$#" -ne 1 ]; then
+    echo "Usage: $0 <github-snapshot-branch>" >&2
+    exit 1
+fi
+
+BRANCH="$1"
+
 SOURCE="$HOME/projects/com_r35157_nenjim-hubd-impl_ref"
 TARGET="$HOME/projects/com_r35157_nenjim-hubd-impl_ref_github_snapshot"
 
+cd "$TARGET"
+
+git fetch origin
+
+if git show-ref --verify --quiet "refs/heads/$BRANCH"; then
+    git switch "$BRANCH"
+elif git show-ref --verify --quiet "refs/remotes/origin/$BRANCH"; then
+    git switch --track "origin/$BRANCH"
+else
+    git switch --create "$BRANCH"
+fi
+
 rsync -a --delete \
   --exclude '.git' \
   --exclude 'conf/*.conf' \
@@ -11,13 +30,12 @@ rsync -a --delete \
   "$SOURCE/" \
   "$TARGET/"
 
-cd "$TARGET"
 git add -A
 
 if git diff --cached --quiet; then
-    echo "No snapshot changes to publish."
+    echo "No snapshot changes to publish on branch '$BRANCH'."
     exit 0
 fi
 
 git commit -m "Mirror snapshot"
-git push
+git push -u origin "$BRANCH"

src/main/tjava/com/r35157/libs/codec/Base58Codec.tjava

@@ -0,0 +1,5 @@
+package com.r35157.libs.codec;
+
+public interface Base58Codec {
+    String encode(byte[] input);
+}

src/main/tjava/com/r35157/libs/jupiter/perps/JupiterPerpsPosition.tjava

@@ -0,0 +1,27 @@
+package com.r35157.libs.jupiter.perps;
+
+import java.math.BigDecimal;
+
+/**
+ * Represents a Jupiter Perps position.
+ *
+ * <p>A Jupiter Perps position is represented on-chain by a Solana account owned by
+ * the Jupiter Perps program. This record contains the public API view of such a
+ * position.</p>
+ *
+ * @param positionAccount the Solana account address of the Jupiter Perps position
+ * @param entryPrice the entry price of the position, denominated in USDC
+ * @param direction whether the position is long or short
+ * @param tradedTokenMint the mint address of the token being traded
+ * @param sizeUsd the size of this position in USD
+ * @param collateralUsd the amount of USD representing the collateral for this position
+ */
+public record JupiterPerpsPosition(
+        ΩJupiterPerpsPositionAccountΩ positionAccount,
+        ΩUSDCPriceΩ entryPrice,
+        JupiterPerpsPositionDirection direction,
+        ΩSPLMintAddressΩ tradedTokenMint,
+        ΩUSDCAmountΩ sizeUsd,
+        ΩUSDCAmountΩ collateralUsd
+) {
+}

src/main/tjava/com/r35157/libs/jupiter/perps/JupiterPerpsPositionDirection.tjava

@@ -0,0 +1,9 @@
+package com.r35157.libs.jupiter.perps;
+
+/**
+ * Direction of a Jupiter Perps position.
+ */
+public enum JupiterPerpsPositionDirection {
+    LONG,
+    SHORT
+}

src/main/tjava/com/r35157/libs/jupiter/perps/JupiterPerpsService.tjava

@@ -0,0 +1,45 @@
+package com.r35157.libs.jupiter.perps;
+
+import java.io.IOException;
+import java.util.Set;
+
+/**
+ * Service for reading Jupiter Perps data.
+ *
+ * <p>This service is read-only. It does not open, close, modify, or sign transactions
+ * for Jupiter Perpetual Contracts.</p>
+ *
+ * <p>NOTICE: The first supported operation is reading a known Jupiter Perps position account
+ * and returning its decoded position data.</p>
+ */
+public interface JupiterPerpsService {
+    /**
+     * Reads a Jupiter Perps position from a known position account.
+     *
+     * <p>The supplied account must be the Solana account that stores the Jupiter Perps
+     * position state. It is not the wallet address, token account, custody account, pool
+     * account, or position request account.</p>
+     *
+     * @param positionAccount the Solana account address of the Jupiter Perps position
+     * @return the decoded Jupiter Perps position
+     * @throws IOException if the position account could not be fetched or decoded
+     * @throws InterruptedException if the calling thread is interrupted while fetching
+     *                              the position account
+     */
+    JupiterPerpsPosition getPosition(ΩJupiterPerpsPositionAccountΩ positionAccount)
+            throws IOException, InterruptedException;
+
+    /**
+     * Finds open Jupiter Perps positions owned by a wallet.
+     *
+     * <p>This method returns decoded Jupiter Perps position objects. It does not return
+     * raw Solana accounts or account ids.</p>
+     *
+     * @param owner the wallet address that owns the Jupiter Perps positions
+     * @return the open Jupiter Perps positions owned by the wallet
+     * @throws IOException if the position accounts could not be fetched or decoded
+     * @throws InterruptedException if the calling thread is interrupted while fetching positions
+     */
+    Set<JupiterPerpsPosition> getOpenPositions(ΩSolanaWalletIdΩ owner)
+            throws IOException, InterruptedException;
+}

src/main/tjava/com/r35157/libs/jupiter/perps/impl/anchoridl/AnchorIdlJupiterPerpsPositionDecoder.tjava

@@ -38,11 +38,31 @@ class AnchorIdlJupiterPerpsPositionDecoder {
                 .valueOf(rawEntryPrice)
                 .movePointLeft(6);
 
+        long rawCollateralUsd = ByteBuffer
+                .wrap(data, COLLATERAL_USD_OFFSET, U64_LENGTH)
+                .order(ByteOrder.LITTLE_ENDIAN)
+                .getLong();
+
+        ΩUSDCAmountΩ collateralUsd = BigDecimal
+                .valueOf(rawCollateralUsd)
+                .movePointLeft(6);
+
+        long rawSizeUsd = ByteBuffer
+                .wrap(data, SIZE_USD_OFFSET, U64_LENGTH)
+                .order(ByteOrder.LITTLE_ENDIAN)
+                .getLong();
+
+        ΩUSDCAmountΩ sizeUsd = BigDecimal
+                .valueOf(rawSizeUsd)
+                .movePointLeft(6);
+
         JupiterPerpsPosition pos = new JupiterPerpsPosition(
                 positionAccount,
                 entryPrice,
                 direction,
-                tradedTokenMint
+                tradedTokenMint,
+                sizeUsd,
+                collateralUsd
         );
 
         return pos;
@@ -104,11 +124,13 @@ class AnchorIdlJupiterPerpsPositionDecoder {
     private static final int OWNER_OFFSET = ANCHOR_DISCRIMINATOR_LENGTH;
     private static final int POOL_OFFSET = OWNER_OFFSET + PUBLIC_KEY_LENGTH;
     private static final int CUSTODY_OFFSET = POOL_OFFSET + PUBLIC_KEY_LENGTH;
-    private static final int COLLATERAL_CUSTODY_OFFSET = CUSTODY_OFFSET + PUBLIC_KEY_LENGTH; // custody
+    private static final int COLLATERAL_CUSTODY_OFFSET = CUSTODY_OFFSET + PUBLIC_KEY_LENGTH;
     private static final int OPEN_TIME_OFFSET = COLLATERAL_CUSTODY_OFFSET + PUBLIC_KEY_LENGTH;
-    private static final int UPDATE_TIME_OFFSET = OPEN_TIME_OFFSET + I64_LENGTH; // openTime
+    private static final int UPDATE_TIME_OFFSET = OPEN_TIME_OFFSET + I64_LENGTH;
     private static final int SIDE_OFFSET = UPDATE_TIME_OFFSET + I64_LENGTH;
     private static final int PRICE_OFFSET = SIDE_OFFSET + SIDE_ENUM_LENGTH;
+    private static final int SIZE_USD_OFFSET = PRICE_OFFSET + U64_LENGTH;
+    private static final int COLLATERAL_USD_OFFSET = SIZE_USD_OFFSET + U64_LENGTH;
 
     private static final Base58Codec base58 = new Base58CodecImpl();
 }

src/main/tjava/com/r35157/libs/solana/SolanaBlockChain.tjava

@@ -0,0 +1,167 @@
+package com.r35157.libs.solana;
+
+import com.r35157.libs.solana.valuetypes.SolanaProgramDerivedAddress;
+import com.r35157.libs.solana.valuetypes.economic.SolanaSPLTokenProgram;
+import com.r35157.libs.valuetypes.basic.MoneyAmount;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * Provides read-oriented access to the Solana blockchain.
+ *
+ * <p>This interface exposes the Solana operations needed by higher-level
+ * integrations. It can fetch native SOL balances, SPL token holdings, NFT-like
+ * token holding candidates, account information and program derived addresses.</p>
+ *
+ * <p>The interface is intentionally generic and does not contain Raydium-specific
+ * logic. Higher-level integrations are expected to interpret Solana accounts,
+ * token holdings and derived addresses according to their own domain rules.</p>
+ */
+public interface SolanaBlockChain {
+    /**
+     * Fetches the native SOL balance for a Solana address.
+     *
+     * @param address the Solana address to inspect
+     * @return the native SOL balance for the address
+     * @throws IOException if the balance could not be fetched or parsed
+     * @throws InterruptedException if the calling thread is interrupted while fetching the balance
+     */
+    ΩSolanaAmountΩ getBalanceInSolana(ΩSolanaAddressΩ address) throws IOException, InterruptedException;
+
+    /**
+     * Fetches the native SOL balance for a Solana address in lamports.
+     *
+     * <p>Lamports are the smallest unit of native SOL.</p>
+     *
+     * @param address the Solana address to inspect
+     * @return the native SOL balance for the address in lamports
+     * @throws IOException if the balance could not be fetched or parsed
+     * @throws InterruptedException if the calling thread is interrupted while fetching the balance
+     */
+    ΩlamportsΩ getBalanceInLamport(ΩSolanaAddressΩ address) throws IOException, InterruptedException;
+
+    /**
+     * Fetches SPL token holdings owned by a Solana address for a specific token program.
+     *
+     * <p>The supplied token program decides which token accounts are inspected. For example,
+     * callers may query the original SPL Token Program or the Token-2022 Program depending
+     * on which token accounts they need to discover.</p>
+     *
+     * @param ownerAddress the Solana owner address whose token holdings should be inspected
+     * @param splProgramId the SPL token program to query
+     * @return a map of SPL mint addresses to token holding information
+     * @throws IOException if the token holdings could not be fetched or parsed
+     * @throws InterruptedException if the calling thread is interrupted while fetching token holdings
+     */
+    Map<ΩSPLMintAddressΩ, SPLTokenHolding> getSPLTokenHoldings(
+            ΩSolanaAddressΩ ownerAddress,
+            SolanaSPLTokenProgram splProgramId
+    ) throws IOException, InterruptedException;
+
+    /**
+     * Fetches NFT-like token mint address candidates owned by a Solana address for a specific token program.
+     *
+     * <p>This method identifies token holdings that look like NFTs within the supplied token
+     * program. A returned address is only a candidate. Higher-level integrations are responsible
+     * for deciding whether the returned address has domain-specific meaning.</p>
+     *
+     * // TODO This method currently identifies candidates from the owner's token holdings only.
+     * // A token with zero decimals and an owner balance of one is not guaranteed to be a real NFT,
+     * // because the mint's total supply may still be greater than one. A future implementation
+     * // should verify the mint supply, for example by using Solana getTokenSupply, before treating
+     * // the result as a confirmed NFT.
+     *
+     * @param ownerAddress the Solana owner address whose NFT-like holdings should be inspected
+     * @param splProgram the SPL token program to query
+     * @return the NFT-like Solana mint address candidates owned by the address
+     * @throws IOException if the NFT candidate addresses could not be fetched or parsed
+     * @throws InterruptedException if the calling thread is interrupted while fetching NFT candidate addresses
+     */
+    Set<ΩSolanaNFTAddressΩ> getSolanaNFTCandidateAddresses(
+            ΩSolanaAddressΩ ownerAddress,
+            SolanaSPLTokenProgram splProgram
+    ) throws IOException, InterruptedException;
+
+    /**
+     * Finds a Solana program derived address for a program id and a set of seeds.
+     *
+     * <p>The seeds describe the logical inputs used to derive the address. The implementation
+     * is responsible for converting each seed into the byte representation required by Solana.</p>
+     *
+     * @param programId the Solana program id used to derive the address
+     * @param seeds the seeds used when deriving the program address
+     * @return the derived Solana address together with its bump value
+     */
+    SolanaProgramDerivedAddress findProgramAddress(
+            ΩSolanaProgramIdΩ programId,
+            List<SolanaProgramAddressSeed> seeds
+    );
+
+    /**
+     * Fetches account information for a Solana account address.
+     *
+     * <p>If the account does not exist, this method returns {@code null}. If the account exists,
+     * the returned value contains the account address, the owning Solana program id and the
+     * account data encoded as Base64.</p>
+     *
+     * @param accountAddress the Solana account address to inspect
+     * @return account information, or {@code null} if the account does not exist
+     * @throws IOException if the account information could not be fetched or parsed
+     * @throws InterruptedException if the calling thread is interrupted while fetching account information
+     */
+    SolanaAccountInfo getAccountInfo(ΩSolanaAddressΩ accountAddress)
+            throws IOException, InterruptedException;
+
+    /**
+     * Encodes a raw 32-byte Solana address into its textual Solana address representation.
+     *
+     * <p>This method is intended for callers that have obtained raw Solana address bytes from
+     * account data and need the normal string representation used elsewhere in the API.</p>
+     *
+     * @param addressBytes the raw 32-byte Solana address
+     * @return the encoded Solana address
+     * @throws IllegalArgumentException if the supplied byte array is not a valid Solana address length
+     */
+    ΩSolanaAddressΩ encodeSolanaAddress(byte[] addressBytes);
+
+    /**
+     * Fetches the total supply of an SPL token mint for a specific token program.
+     *
+     * <p>The supplied token program identifies which SPL token program owns the mint,
+     * for example the original SPL Token Program or the Token-2022 Program.</p>
+     *
+     * @param mintAddress the SPL mint address whose supply should be fetched
+     * @param splProgram the SPL token program to query
+     * @return the SPL token supply for the mint
+     * @throws IOException if the token supply could not be fetched or parsed
+     * @throws InterruptedException if the calling thread is interrupted while fetching token supply
+     */
+    SPLTokenSupply getSPLTokenSupply(
+            ΩSPLMintAddressΩ mintAddress,
+            SolanaSPLTokenProgram splProgram
+    ) throws IOException, InterruptedException;
+
+    /**
+     * Fetches accounts owned by a Solana program using server-side account data filters.
+     *
+     * <p>This method uses Solana's {@code getProgramAccounts} RPC call. The supplied filters
+     * are sent to the RPC node, so matching is performed server-side instead of fetching all
+     * accounts owned by the program and filtering them locally.</p>
+     *
+     * <p>The initial supported filter type is {@link SolanaProgramAccountMemcmpFilter}, which
+     * matches bytes at a specific offset in the account data.</p>
+     *
+     * @param programId the Solana program id that owns the accounts to search
+     * @param filters the memcmp filters to apply when searching program accounts
+     * @return the matching program accounts
+     * @throws IOException if the program accounts could not be fetched or parsed
+     * @throws InterruptedException if the calling thread is interrupted while fetching program accounts
+     */
+    Set<SolanaAccountInfo> getProgramAccounts(
+            ΩSolanaProgramIdΩ programId,
+            Set<SolanaProgramAccountMemcmpFilter> filters
+    ) throws IOException, InterruptedException;
+}

src/main/tjava/com/r35157/libs/solana/SolanaProgramAccountMemcmpFilter.tjava

@@ -0,0 +1,17 @@
+package com.r35157.libs.solana;
+
+/**
+ * Filter used when fetching accounts owned by a Solana program.
+ *
+ * <p>The initial supported filter type is {@code memcmp}, which asks the
+ * Solana RPC node to only return accounts where the account data at a specific
+ * byte offset matches a base58 encoded value.</p>
+ *
+ * @param offset the byte offset in the account data where comparison starts
+ * @param bytes the base58 encoded bytes to match
+ */
+public record SolanaProgramAccountMemcmpFilter(
+        int offset,
+        String bytes
+) {
+}

src/main/tjava/com/r35157/libs/solana/valuetypes/WellKnownCurrencyTypes.tjava

@@ -0,0 +1,52 @@
+package com.r35157.libs.solana.valuetypes;
+
+import com.r35157.libs.valuetypes.basic.CurrencyType;
+
+import java.util.UUID;
+
+/**
+ * Defines well-known currency types used by the Solana integration.
+ *
+ * <p>Each enum value wraps a {@link CurrencyType} with a stable identifier and a
+ * human-readable currency name. These predefined values are intended for common
+ * currencies that the Solana-related modules need to reference consistently.</p>
+ */
+public enum WellKnownCurrencyTypes {
+    /**
+     * Native Solana currency.
+     */
+    SOLANA(new CurrencyType(
+            UUID.fromString("019e0116-fce5-792f-a647-fa6da4dffec5"),
+            "Solana",
+            "SOL")
+    ),
+
+    /**
+     * Syrup USDC token currency.
+     */
+    SYRUPUSDC(new CurrencyType(
+            UUID.fromString("019e1d51-0600-7956-8231-f3b7058a91c2"),
+            "SyrupUSDC",
+            "SyrupUSDC")
+    );
+
+    /**
+     * Creates a well-known currency type entry.
+     *
+     * @param currencyType the currency type represented by this enum value
+     */
+    WellKnownCurrencyTypes(CurrencyType currencyType) {
+        this.currencyType = currencyType;
+    }
+
+    /**
+     * Returns the currency type represented by this enum value.
+     *
+     * @return the represented currency type
+     */
+    public CurrencyType getCurrencyType() {
+        return currencyType;
+    }
+
+    private final CurrencyType currencyType;
+}

src/main/tjava/com/r35157/libs/valuetypes/basic/MoneyPrice.tjava

@@ -0,0 +1,8 @@
+package com.r35157.libs.valuetypes.basic;
+
+import java.math.BigDecimal;
+
+public record MoneyPrice(
+        ΩPriceΩ price,
+        CurrencyType currencyType
+) { }