Skip to content

Add new governance endpoints and enhance model structuring #188

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
edridudi merged 1 commit into from
Apr 15, 2025
Merged

Add new governance endpoints and enhance model structuring #188

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 41 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Resource and maintenance requirements for Cardano blockchain components (e.g. ca
</thead>
<tbody>
<tr>
<td rowspan="6">Network</td>
<td rowspan="7">Network</td>
<td>Chain Tip</td>
<td>Get the tip info about the latest block seen by chain</td>
</tr>
Expand All @@ -58,6 +58,10 @@ Resource and maintenance requirements for Cardano blockchain components (e.g. ca
<td>Param Update Proposals</td>
<td>Get all parameter update proposals submitted to the chain starting Shelley era</td>
</tr>
<tr>
<td>CLI Protocol Parameters</td>
<td>Get Current Protocol Parameters as published by cardano-cli.</td>
</tr>
<tr>
<td>Reserve Withdrawals</td>
<td>List of all withdrawals from reserves against stake accounts</td>
Expand Down Expand Up @@ -93,8 +97,8 @@ Resource and maintenance requirements for Cardano blockchain components (e.g. ca
<td>Get a list of all transactions included in a provided block</td>
</tr>
<tr>
<td>Block Transactions (Detailed Info)</td>
<td>Get detailed information about transaction(s) for requested blocks</td>
<td>Block Transactions (Raw CBOR)</td>
<td>Get raw CBOR data for all transaction(s) within requested blocks</td>
</tr>
<tr>
<td rowspan="7">Transactions</td>
Expand Down Expand Up @@ -126,14 +130,18 @@ Resource and maintenance requirements for Cardano blockchain components (e.g. ca
<td>Get the number of block confirmations for a given transaction hash list</td>
</tr>
<tr>
<td rowspan="6">Address</td>
<td rowspan="7">Address</td>
<td>Address Information</td>
<td>Get address info - balance, associated stake address (if any) and UTxO set</td>
</tr>
<tr>
<td>Address UTxOs</td>
<td>Get UTxO set for given addresses</td>
</tr>
<tr>
<td>Address Outputs</td>
<td>Basic transaction output info for given addresses</td>
</tr>
<tr>
<td>UTxOs from payment credentials</td>
<td>Get UTxO details for requested payment credentials</td>
Expand Down Expand Up @@ -172,11 +180,11 @@ Resource and maintenance requirements for Cardano blockchain components (e.g. ca
<td>Get a list of all Txs for a given stake address (account)</td>
</tr>
<tr>
<td>Account Rewards</td>
<td>Account Reward History</td>
<td>Get the full rewards history (including MIR) for a stake address, or certain epoch if specified</td>
</tr>
<tr>
<td>Account Updates</td>
<td>Account Update History</td>
<td>Get the account updates (registration, deregistration, delegation and withdrawals)</td>
</tr>
<tr>
Expand All @@ -188,11 +196,11 @@ Resource and maintenance requirements for Cardano blockchain components (e.g. ca
<td>Get the native asset balance of an account</td>
</tr>
<tr>
<td>Account History</td>
<td>Account Stake History</td>
<td>Get the staking history of an account</td>
</tr>
<tr>
<td rowspan="14">Asset</td>
<td rowspan="13">Asset</td>
<td>Asset List</td>
<td>Get the list of all native assets (paginated)</td>
</tr>
Expand All @@ -204,10 +212,6 @@ Resource and maintenance requirements for Cardano blockchain components (e.g. ca
<td>Asset Token Registry</td>
<td>Get a list of assets registered via token registry on github</td>
</tr>
<tr>
<td>Asset Information</td>
<td>Get the information of an asset including first minting & token registry metadata</td>
</tr>
<tr>
<td>Asset Information (Bulk)</td>
<td>Get the information of a list of assets including first minting & token registry metadata</td>
Expand Down Expand Up @@ -249,7 +253,7 @@ Resource and maintenance requirements for Cardano blockchain components (e.g. ca
<td>Get the list of all asset transaction hashes (newest first)</td>
</tr>
<tr>
<td rowspan="14">Governance</td>
<td rowspan="15">Governance</td>
<td>DReps Epoch Summary</td>
<td>Summary of voting power and DRep count for each epoch</td>
</tr>
Expand All @@ -270,8 +274,8 @@ Resource and maintenance requirements for Cardano blockchain components (e.g. ca
<td>List of updates for requested (or all) delegated representatives (DReps)</td>
</tr>
<tr>
<td>DReps Votes</td>
<td>List of all votes casted by requested delegated representative (DRep)</td>
<td>DReps Voting Power History</td>
<td>History of DReps voting power against each (or requested) epoch</td>
</tr>
<tr>
<td>DReps Delegators</td>
Expand Down Expand Up @@ -302,11 +306,15 @@ Resource and maintenance requirements for Cardano blockchain components (e.g. ca
<td>List of all votes cast on specified governance action</td>
</tr>
<tr>
<td>Pool Votes</td>
<td>List of all votes casted by a pool</td>
<td>Vote List</td>
<td>List of all votes posted on-chain</td>
</tr>
<tr>
<td>Pool's Voting Power History</td>
<td>History of Pool voting power against each (or requested) epoch</td>
</tr>
<tr>
<td rowspan="12">Pool</td>
<td rowspan="15">Pool</td>
<td>Pool List</td>
<td>A list of all currently registered/retiring (not retired) pools</td>
</tr>
Expand All @@ -330,6 +338,10 @@ Resource and maintenance requirements for Cardano blockchain components (e.g. ca
<td>Pool Blocks</td>
<td>Return information about blocks minted by a given pool in current epoch (or _epoch_no if provided)</td>
</tr>
<tr>
<td>Pool Owner History</td>
<td>List of Cardano pool IDs (bech32 format)</td>
</tr>
<tr>
<td>Pool Stake, Block and Reward History</td>
<td>Return information about pool stake, block and reward history in a given epoch _epoch_no (or all epochs that pool existed for, in descending order if no _epoch_no was provided)</td>
Expand All @@ -350,10 +362,18 @@ Resource and maintenance requirements for Cardano blockchain components (e.g. ca
<td>Pool Relays</td>
<td>A list of registered relays for all currently registered/retiring (not retired) pools</td>
</tr>
<tr>
<td>Pool Groups</td>
<td>List of all registered pool and their groups across sources from pool_groups repository. This is only relevant for mainnet</td>
</tr>
<tr>
<td>Pool Metadata</td>
<td>Metadata (on & off-chain) for all currently registered/retiring (not retired) pools</td>
</tr>
<tr>
<td>Pool Calidus Keys</td>
<td>List of valid calidus keys for all pools</td>
</tr>
<tr>
<td rowspan="6">Script</td>
<td>Script Information</td>
Expand Down Expand Up @@ -388,6 +408,7 @@ Resource and maintenance requirements for Cardano blockchain components (e.g. ca

| Koios Instance | Koios Java Client |
|:--------------:|:-----------------:|
| 1.3.2 | 1.21.0 |
| 1.3.0 | 1.20.1 |
| 1.2.0 | 1.19.3 |
| 1.1.2 | 1.18.2 |
Expand All @@ -407,13 +428,13 @@ Resource and maintenance requirements for Cardano blockchain components (e.g. ca
<dependency>
<groupId>io.github.cardano-community</groupId>
<artifactId>koios-java-client</artifactId>
<version>1.20.1</version>
<version>1.21.0</version>
</dependency>
```

- For Gradle, add the following dependency to build.gradle
```
compile group: 'io.github.cardano-community', name: 'koios-java-client', version: '1.20.1'
compile group: 'io.github.cardano-community', name: 'koios-java-client', version: '1.21.0'
```

### Get Koios Backend Service (No API Token)
Expand Down
2 changes: 1 addition & 1 deletion SPONSORS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ We'll be happy to show your name in the sponsor list.
<p align="center">

<br/>
<img src=".github/qr.png" />
<img src=".github/qr.png" alt="qr" />
<br/>
<br/>
<a href="web+cardano:addr1qy9m8j6jp32fgnqjljk6ert9hlndcnptwhruzjamyevzgspgewr0dw33mfjfm72t8a2et6w48u4k5uwq2hgltxxs4a6sg6ptd9"><code>addr1qy9m8j6jp32fgnqjljk6ert9hlndcnptwhruzjamyevzgspgewr0dw33mfjfm72t8a2et6w48u4k5uwq2hgltxxs4a6sg6ptd9</code></a>
Expand Down
10 changes: 5 additions & 5 deletions pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<modelVersion>4.0.0</modelVersion>
<groupId>io.github.cardano-community</groupId>
<artifactId>koios-java-client</artifactId>
<version>1.20.1</version>
<version>1.21.0</version>
<name>${project.groupId}:${project.artifactId}</name>
<description>Koios Java Client is a Java REST Client library which allows interacting with Koios Server Instances using Java Objects</description>
<url>https://github.com/cardano-community/koios-java-client</url>
Expand All @@ -20,12 +20,12 @@
<slf4j-api.version>2.0.16</slf4j-api.version>
<slf4j-reload4j.version>2.0.16</slf4j-reload4j.version>
<commons-collections4.version>4.4</commons-collections4.version>
<lombok.version>1.18.34</lombok.version>
<bcprov-jdk15to18.version>1.79</bcprov-jdk15to18.version>
<lombok.version>1.18.36</lombok.version>
<bcprov-jdk15to18.version>1.80</bcprov-jdk15to18.version>
<junit-jupiter.version>5.11.3</junit-jupiter.version>
<maven-compiler-plugin.version>3.13.0</maven-compiler-plugin.version>
<maven-javadoc-plugin.version>3.11.1</maven-javadoc-plugin.version>
<maven-surefire-plugin.version>3.5.1</maven-surefire-plugin.version>
<maven-javadoc-plugin.version>3.11.2</maven-javadoc-plugin.version>
<maven-surefire-plugin.version>3.5.2</maven-surefire-plugin.version>
<junit-platform-surefire-provider.version>1.3.2</junit-platform-surefire-provider.version>
<jacoco-maven-plugin.version>0.8.12</jacoco-maven-plugin.version>
<maven-source-plugin.version>3.3.1</maven-source-plugin.version>
Expand Down
48 changes: 47 additions & 1 deletion src/main/java/rest/koios/client/backend/api/account/AccountService.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ public interface AccountService {
* <p><b>404</b> - The server does not recognise the combination of endpoint and parameters provided
*
* @param stakeAddresses List of Cardano stake address(es) in bech32 format
* @param extended Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call
* @param extended Controls whether certain optional fields supported by a given endpoint are populated as a part of the call
* @param options Filtering and Pagination options (optional)
* @return Result of Type List of {@link UTxO} associated with stake address
* @throws ApiException if an error occurs while attempting to invoke the API
Expand Down Expand Up @@ -99,8 +99,24 @@ public interface AccountService {
* @return Result of Type List of {@link AccountRewards}
* @throws ApiException if an error occurs while attempting to invoke the API
*/
@Deprecated
Result<List<AccountRewards>> getAccountRewards(List<String> addressList, Integer epochNo, Options options) throws ApiException;

/**
* Account Reward History
* Get the full rewards history (including MIR) for given stake addresses (accounts)
* <p><b>200</b> - Success!
* <p><b>401</b> - The selected server has restricted the endpoint to be only usable via authentication. The authentication supplied was not authorized to access the endpoint
* <p><b>404</b> - The server does not recognise the combination of endpoint and parameters provided
*
* @param addressList Array of Cardano stake address(es) in bech32 format
* @param epochNo Only fetch information for a specific epoch (optional)
* @param options Filtering and Pagination options (optional)
* @return Result of Type List of {@link AccountRewardHistory}
* @throws ApiException if an error occurs while attempting to invoke the API
*/
Result<List<AccountRewardHistory>> getAccountRewardHistory(List<String> addressList, Integer epochNo, Options options) throws ApiException;

/**
* Account Updates (History)
* Get the account updates (registration, deregistration, delegation and withdrawals)
Expand All @@ -113,8 +129,23 @@ public interface AccountService {
* @return Result of Type List of {@link AccountUpdates}
* @throws ApiException if an error occurs while attempting to invoke the API
*/
@Deprecated
Result<List<AccountUpdates>> getAccountUpdates(List<String> addressList, Options options) throws ApiException;

/**
* Account Updates History
* Get the account updates (registration, deregistration, delegation and withdrawals)
* <p><b>200</b> - Success!
* <p><b>401</b> - The selected server has restricted the endpoint to be only usable via authentication. The authentication supplied was not authorized to access the endpoint
* <p><b>404</b> - The server does not recognise the combination of endpoint and parameters provided
*
* @param addressList Array of Cardano stake address(es) in bech32 format (required)
* @param options Filtering and Pagination options (optional)
* @return Result of Type List of {@link AccountUpdateHistory}
* @throws ApiException if an error occurs while attempting to invoke the API
*/
Result<List<AccountUpdateHistory>> getAccountUpdateHistory(List<String> addressList, Options options) throws ApiException;

/**
* Account Addresses
* Get all addresses associated with given staking accounts
Expand Down Expand Up @@ -160,5 +191,20 @@ public interface AccountService {
* @return Result of Type List of {@link AccountHistory} active stake values per epoch
* @throws ApiException if an error occurs while attempting to invoke the API
*/
@Deprecated
Result<List<AccountHistory>> getAccountHistory(List<String> addressList, Integer epochNo, Options options) throws ApiException;

/**
* Account Stake History
* Get the staking history of given stake addresses (accounts)
* <p><b>200</b> - Array of active stake values per epoch
* <p><b>401</b> - The selected server has restricted the endpoint to be only usable via authentication. The authentication supplied was not authorized to access the endpoint
* <p><b>404</b> - The server does not recognise the combination of endpoint and parameters provided
*
* @param addressList Array of Cardano stake address(es) in bech32 format
* @param options Filtering and Pagination options (optional)
* @return Result of Type List of {@link AccountStakeHistory} active stake values per epoch
* @throws ApiException if an error occurs while attempting to invoke the API
*/
Result<List<AccountStakeHistory>> getAccountStakeHistory(List<String> addressList, Options options) throws ApiException;
}
33 changes: 33 additions & 0 deletions src/main/java/rest/koios/client/backend/api/account/api/AccountApi.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,19 +70,41 @@ public interface AccountApi {
* @param paramsMap Query Params
* @return Full rewards history (including MIR) for a stake address, or certain epoch if specified
*/
@Deprecated
@POST("account_rewards")
Call<List<AccountRewards>> getAccountRewards(@Body Map<String, Object> requestBody, @QueryMap Map<String, String> paramsMap);

/**
* Account Reward History
*
* @param requestBody Array of Cardano stake address(es) in bech32 format
* @param paramsMap Query Params
* @return Full rewards history (including MIR) for a stake address, or certain epoch if specified
*/
@POST("account_reward_history")
Call<List<AccountRewardHistory>> getAccountRewardHistory(@Body Map<String, Object> requestBody, @QueryMap Map<String, String> paramsMap);

/**
* Get Account Updates
*
* @param requestBody Array of Cardano stake address(es) in bech32 format
* @param paramsMap Query Params
* @return Account updates (registration, deregistration, delegation and withdrawals)
*/
@Deprecated
@POST("account_updates")
Call<List<AccountUpdates>> getAccountUpdates(@Body Map<String, Object> requestBody, @QueryMap Map<String, String> paramsMap);

/**
* Account Update History
*
* @param requestBody Array of Cardano stake address(es) in bech32 format
* @param paramsMap Query Params
* @return Account updates (registration, deregistration, delegation and withdrawals)
*/
@POST("account_update_history")
Call<List<AccountUpdateHistory>> getAccountUpdateHistory(@Body Map<String, Object> requestBody, @QueryMap Map<String, String> paramsMap);

/**
* Get Account Addresses
*
Expand Down Expand Up @@ -110,6 +132,17 @@ public interface AccountApi {
* @param paramsMap Query Params
* @return Staking history of an account
*/
@Deprecated
@POST("account_history")
Call<List<AccountHistory>> getAccountHistory(@Body Map<String, Object> requestBody, @QueryMap Map<String, String> paramsMap);

/**
* Get Account Stake History
*
* @param requestBody List of Cardano stake address(es) in bech32 format
* @param paramsMap Query Params
* @return List of active stake values per epoch
*/
@POST("account_stake_history")
Call<List<AccountStakeHistory>> getAccountStakeHistory(@Body Map<String, Object> requestBody, @QueryMap Map<String, String> paramsMap);
}
Loading
Loading