17: Add mint address field in JupiterPerpsPosition

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,23 @@
+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
+ */
+public record JupiterPerpsPosition(
+        ΩJupiterPerpsPositionAccountΩ positionAccount,
+        ΩUSDCPriceΩ entryPrice,
+        JupiterPerpsPositionDirection direction,
+        ΩSPLMintAddressΩ tradedTokenMint
+) {
+}

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/solana/SolanaBlockChain.tjava

@@ -143,4 +143,25 @@ public interface SolanaBlockChain {
             Ω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
+) {
+}