Skip to content

Commit

Permalink
Add misssing javadocs
Browse files Browse the repository at this point in the history
  • Loading branch information
ml-james committed Nov 24, 2024
1 parent 6011147 commit 07ba83f
Show file tree
Hide file tree
Showing 12 changed files with 336 additions and 44 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,12 @@ public interface AccountInfo
*/
String getOwner();

/**
* Retrieves the data associated with the account.
* This data includes both encoded and parsed representations of the account's information.
*
* @return an instance of {@link AccountInfoData} containing the account's data
*/
AccountInfoData getData();

/**
Expand All @@ -48,15 +54,12 @@ public interface AccountInfo
/**
* Returns the amount of space, in bytes, allocated to the account.
* The space is used to store data for the account, and the size is determined by the
* program that owns the account. The amount of space is a key factor in determining
* the rent required to keep the account alive, as larger accounts typically require
* more rent.
* program that owns the account.
*
* @return the number of bytes allocated for the account's data
*/
long getSpace();

/**
/**
* Represents account information data in a Solana transaction.
* This interface provides access to both encoded and parsed account information,
Expand Down
Original file line number Diff line number Diff line change
@@ -1,16 +1,59 @@
package com.lmax.solana4j.client.api;

/**
* Represents a transaction signature associated with a specific address on the Solana blockchain.
* This interface provides access to details such as errors, memos, signatures, slots, block times,
* and confirmation statuses.
*/
public interface SignatureForAddress
{

/**
* Retrieves the error information associated with the transaction, if any.
* If the transaction was successful, this method returns {@code null}.
*
* @return an object representing the error, or {@code null} if the transaction was successful
*/
Object getErr();

/**
* Retrieves the memo associated with the transaction.
* If no memo is present, this method returns {@code null}.
*
* @return a string containing the memo, or {@code null} if no memo is present
*/
String getMemo();

/**
* Retrieves the base58-encoded signature of the transaction.
*
* @return a string representing the transaction's signature
*/
String getSignature();

/**
* Retrieves the slot number in which the transaction was confirmed.
* The slot is a specific point in the Solana blockchain where the transaction was processed.
*
* @return the slot number where the transaction was confirmed
*/
Long getSlot();

/**
* Retrieves the estimated production time of the block containing the transaction.
* The block time is represented as a Unix timestamp (seconds since the Unix epoch).
* If the block time is not available, this method returns {@code null}.
*
* @return the block time as a Unix timestamp, or {@code null} if not available
*/
Long getBlockTime();

/**
* Retrieves the confirmation status of the transaction.
* The confirmation status indicates the level of finality reached for the transaction,
* such as processed, confirmed, or finalized.
*
* @return the {@link Commitment} representing the confirmation status of the transaction
*/
Commitment getConfirmationStatus();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -44,5 +44,11 @@ public interface SignatureStatus
*/
Commitment getConfirmationStatus();

/**
* Returns the status of the transaction as a key-value pair.
* The key represents the status type, and the value provides additional information about the status.
*
* @return a {@link Map.Entry} containing the status type and corresponding information
*/
Map.Entry<String, Object> getStatus();
}
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,93 @@

import java.util.List;

/**
* Represents the response from simulating a transaction on the Solana blockchain.
* This interface provides access to various details resulting from the simulation,
* including errors, logs, account information, inner instructions, replacement blockhash,
* return data, and the number of compute units consumed.
*/
public interface SimulateTransactionResponse
{

/**
* Retrieves the error information resulting from the transaction simulation, if any.
* If the simulation was successful, this method returns {@code null}.
*
* @return an object representing the error, or {@code null} if the simulation was successful
*/
Object getErr();

/**
* Retrieves the list of log messages generated during the transaction simulation.
* These logs provide insights into the execution flow and can be useful for debugging.
*
* @return a list of log messages as strings
*/
List<String> getLogs();

/**
* Retrieves the account information data resulting from the transaction simulation.
* This includes details about the accounts involved in the transaction.
*
* @return an {@link AccountInfo.AccountInfoData} object representing the account information
*/
AccountInfo.AccountInfoData getAccounts();

/**
* Retrieves the list of inner instructions executed during the transaction simulation.
* Inner instructions are program invocations that occur within the main transaction.
*
* @return a list of {@link TransactionResponse.InnerInstruction} objects representing the inner instructions
*/
List<TransactionResponse.InnerInstruction> getInnerInstructions();

/**
* Retrieves the replacement blockhash used during the transaction simulation.
* The blockhash ensures the transaction is processed within a specific timeframe
* and prevents it from being replayed.
*
* @return a {@link Blockhash} object representing the replacement blockhash
*/
Blockhash getReplacementBlockhash();

/**
* Retrieves the return data generated by an instruction during the transaction simulation.
* This data includes the program ID and the associated data returned by the instruction.
*
* @return a {@link Data} object representing the return data
*/
Data getReturnData();

/**
* Retrieves the number of compute units consumed during the transaction simulation.
* Compute units represent the computational resources used to process the transaction.
*
* @return the number of compute units consumed
*/
int getUnitsConsumed();

/**
* Represents the return data generated by an instruction during the transaction simulation.
* This interface provides access to the program ID and the associated data.
*/
interface Data
{

/**
* Retrieves the program ID that generated the return data.
* The program ID is a base-58 encoded string representing the program's public key.
*
* @return the base-58 encoded string representing the program ID
*/
String getProgramId();

/**
* Retrieves the data returned by the instruction during the transaction simulation.
* This data is represented as a list of base-64 encoded strings.
*
* @return a list of base-64 encoded strings representing the return data
*/
List<String> getData();
}
}
}
80 changes: 74 additions & 6 deletions client/src/main/java/com/lmax/solana4j/client/api/SolanaApi.java
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,7 @@ public interface SolanaApi
* with additional parameters to customize the request.
* This is the minimum balance needed to ensure the account is rent-exempt.
*
* @param size the size of the account in bytes
* @param size the size of the account in bytes
* @param optionalParams additional parameters to customize the rent exemption query
* @return the minimum balance in lamports for rent exemption
* @throws SolanaJsonRpcClientException if there is an error with the JSON-RPC request
Expand All @@ -213,40 +213,108 @@ public interface SolanaApi
* Returns the lowest slot that the node has information about in its ledger.
*
* @return a {@link SolanaClientResponse} containing the minimum slot as a {@link Long}, or an error
* if the operation was unsuccessful.
* if the operation was unsuccessful.
* @throws SolanaJsonRpcClientException if there is an error in the JSON-RPC request or response.
*/
SolanaClientResponse<Long> minimumLedgerSlot() throws SolanaJsonRpcClientException;


/**
* Returns the current health of the node. A healthy node is one that is within
* HEALTH_CHECK_SLOT_DISTANCE slots of the latest cluster confirmed slot.
* HEALTH_CHECK_SLOT_DISTANCE slots of the latest cluster confirmed slot.
*
* @return a {@link SolanaClientResponse} containing the health status as a {@link String}. A
* response of "ok" typically indicates a healthy node.
* response of "ok" typically indicates a healthy node.
* @throws SolanaJsonRpcClientException if there is an error in the JSON-RPC request or response.
*/
SolanaClientResponse<String> getHealth() throws SolanaJsonRpcClientException;

// probably refactor this to a parent object
/**
* Retrieves a list of transaction signatures for a specified address.
* This method is used to query the transaction history of the given address.
*
* @param addressBase58 the base58-encoded public key of the address.
* @return a {@link SolanaClientResponse} containing a list of {@link SignatureForAddress} objects.
* @throws SolanaJsonRpcClientException if the request fails.
*/
SolanaClientResponse<List<SignatureForAddress>> getSignaturesForAddress(String addressBase58) throws SolanaJsonRpcClientException;

/**
* Retrieves a list of transaction signatures for a specified address with optional parameters.
* Allows for additional filters or customizations when querying the transaction history.
*
* @param addressBase58 the base58-encoded public key of the address.
* @param optionalParams optional parameters for the query, such as limiting results or setting commitment levels.
* @return a {@link SolanaClientResponse} containing a list of {@link SignatureForAddress} objects.
* @throws SolanaJsonRpcClientException if the request fails.
*/
SolanaClientResponse<List<SignatureForAddress>> getSignaturesForAddress(String addressBase58, SolanaClientOptionalParams optionalParams) throws SolanaJsonRpcClientException;

// probably refactor this to a parent object
/**
* Retrieves the statuses of one or more transaction signatures.
* The statuses include confirmation levels, error information, and slot numbers.
*
* @param transactionSignatures a list of base58-encoded transaction signatures.
* @return a {@link SolanaClientResponse} containing a list of {@link SignatureStatus} objects.
* @throws SolanaJsonRpcClientException if the request fails.
*/
SolanaClientResponse<List<SignatureStatus>> getSignatureStatuses(List<String> transactionSignatures) throws SolanaJsonRpcClientException;

/**
* Retrieves the statuses of one or more transaction signatures with optional parameters.
* Allows for additional filters or customizations when querying transaction statuses.
*
* @param transactionSignatures a list of base58-encoded transaction signatures.
* @param optionalParams optional parameters for the query, such as searching transaction history.
* @return a {@link SolanaClientResponse} containing a list of {@link SignatureStatus} objects.
* @throws SolanaJsonRpcClientException if the request fails.
*/
SolanaClientResponse<List<SignatureStatus>> getSignatureStatuses(List<String> transactionSignatures, SolanaClientOptionalParams optionalParams) throws SolanaJsonRpcClientException;

/**
* Retrieves token accounts owned by a specific address, filtered by criteria.
* Useful for finding SPL token accounts based on token mint or program ID.
*
* @param accountDelegate the base58-encoded public key of the account owner.
* @param filter a key-value pair specifying the filter criteria (e.g., token mint or program ID).
* @return a {@link SolanaClientResponse} containing a list of {@link TokenAccount} objects.
* @throws SolanaJsonRpcClientException if the request fails.
*/
SolanaClientResponse<List<TokenAccount>> getTokenAccountsByOwner(String accountDelegate, Map.Entry<String, String> filter) throws SolanaJsonRpcClientException;

/**
* Retrieves token accounts owned by a specific address, filtered by criteria, with optional parameters.
* Allows for additional customization, such as setting a specific commitment level.
*
* @param accountDelegate the base58-encoded public key of the account owner.
* @param filter a key-value pair specifying the filter criteria (e.g., token mint or program ID).
* @param optionalParams optional parameters for the query.
* @return a {@link SolanaClientResponse} containing a list of {@link TokenAccount} objects.
* @throws SolanaJsonRpcClientException if the request fails.
*/
SolanaClientResponse<List<TokenAccount>> getTokenAccountsByOwner(
String accountDelegate,
Map.Entry<String, String> filter,
SolanaClientOptionalParams optionalParams) throws SolanaJsonRpcClientException;

/**
* Simulates a transaction without broadcasting it to the Solana blockchain.
* This method is useful for debugging or testing transaction execution.
*
* @param transaction the base64-encoded string representing the transaction.
* @return a {@link SolanaClientResponse} containing a {@link SimulateTransactionResponse} object with the simulation results.
* @throws SolanaJsonRpcClientException if the request fails.
*/
SolanaClientResponse<SimulateTransactionResponse> simulateTransaction(String transaction) throws SolanaJsonRpcClientException;

/**
* Simulates a transaction without broadcasting it to the Solana blockchain, with optional parameters.
* This allows for additional customizations, such as setting the commitment level or enabling signature verification.
*
* @param transaction the base64-encoded string representing the transaction.
* @param optionalParams additional parameters for the simulation.
* @return a {@link SolanaClientResponse} containing a {@link SimulateTransactionResponse} object with the simulation results.
* @throws SolanaJsonRpcClientException if the request fails.
*/
SolanaClientResponse<SimulateTransactionResponse> simulateTransaction(String transaction, SolanaClientOptionalParams optionalParams) throws SolanaJsonRpcClientException;
}
Original file line number Diff line number Diff line change
@@ -1,17 +1,50 @@
package com.lmax.solana4j.client.api;

/**
* Represents a response from the Solana client, encapsulating either a successful result or an error.
*
* @param <T> the type of the successful response payload
*/
public interface SolanaClientResponse<T>
{
/**
* Retrieves the response payload in case of a successful operation.
*
* @return the response payload, or {@code null} if the operation was not successful
*/
T getResponse();

/**
* Retrieves the error details in case of a failed operation.
*
* @return an instance of {@link SolanaClientError} containing error information, or {@code null} if the operation was successful
*/
SolanaClientError getError();

/**
* Indicates whether the operation was successful.
*
* @return {@code true} if the operation was successful; {@code false} otherwise
*/
boolean isSuccess();

/**
* Represents an error encountered during a Solana client operation.
*/
interface SolanaClientError
{
/**
* Retrieves the error code associated with the failure.
*
* @return the error code
*/
long getErrorCode();

/**
* Retrieves the error message providing details about the failure.
*
* @return the error message
*/
String getErrorMessage();
}
}
}
Loading

0 comments on commit 07ba83f

Please sign in to comment.