Koios gRest Changelog⚓︎
[1.1.0] - For all networks.⚓︎
This will be first major [breaking] release for Koios consumers in a while, and will be rolled out under new base prefix (/api/v1
).
The major work with this release was to start making use of newer flags in dbsync which help performance of queries under new endpoints. Please ensure to check out the release notes for 1.1.0rc
below. The list for this section is only a small addendum to 1.1.0rc
:
Chores:⚓︎
- Make use of asset-txo-cache for top assets on mainnet, and use this cache for
asset_addresses
andpolicy_asset_addresses
#250 - Add v0 RPC redirectors to keep serve v0 endpoints from v1 #250
- Convert few simple RPC functions from PLPGSQL to SQL language to help with inline filtering #250
- Address linting results from SQLFluff #250
- Move db-scripts from guild-operators repository to koios-artifacts repository #250
- Drop stale db-scripts/genesis_table.sql file #250
- Add 3 additional indexes for collateral and reference inputs based on query times #250
- Add top 3 assets for preview/preprod to asset-txo-cache #250
- Bump schema version for koios-1.1.0 #250
- Minor patch for output data type (
pool_registrations
andpool_retirements
) #249
[1.1.0rc] - For all networks.⚓︎
This will be first major [breaking] release for Koios consumers in a while, and will be rolled out under new base prefix (/api/v1
).
The major work with this release was to start making use of newer flags in dbsync which help performance of queries under new endpoints. Also, you'd see quite a few new endpoint additions below, that'd be helping out with slightly lighter version of queries. To keep migration paths easier, we will ensure both v0 and v1 versions of the release is up for a month post release, before retiring v0.
New endpoints added:⚓︎
/pool_registrations
- List of all pool registrations initiated in the requested epoch #239/pool_retirements
- List of all pool retirements initiated in the requested epoch #239/treasury_withdrawals
- List of withdrawals made from treasury #239/reserve_withdrawals
- List of withdrawals made from reserves (MIRs) #239/account_txs
- Transactions associated with a given stake address #239/address_utxos
- Get UTxO details for requested addresses #239/asset_utxos
- Get UTxO details for requested assets #239/script_utxos
- Get UTxO details for requested script hashes #239/utxo_info
- Details for requested UTxO arrays #239/script_info
- Information about a given script FROM script hashes #239/ogmios/
- Expose stateless ogmios endpoints #1690
Data Input/Output Changes:⚓︎
- Input -
/account_utxos
,/credential_utxos
- Acceptextended
as an additional flag - which enablesasset_list
,reference_script
andinline_datum
to the output #239 - Output -
/block_txs
- Flatten output with transaction details (tx_hash
,epoch_no
,block_height
,block_time
) instead oftx_hashes
array #239 - Output -
/epoch_params
- Updatecost_models
to JSON (upstream change in node) #239 - Output -
/account_assets
,/address_assets
- Flatten the output result (instead ofasset_list
array) making it easier to apply horizontal filtering based on any of the fields - Output - Align output fields for
/account_utxos
,/address_utxos
,/asset_utxos
,/script_utxos
and/utxo_info
to return same schema giving complete details about UTxOs involved, with few fields toggled based onextended
input flag #239 - Output -
/pool_list
- Add various details to the endpoint for each pool (pool_id_hex
,active_epoch_no
,margin
,fixed_cost
,pledge
,reward_addr
,owners
,relays
,ticker
,meta_url
,meta_hash
,pool_status
,retiring_epoch
) - this should mean some of the requests topool_info
should no longer be required #239 - Output -
/pool_updates
- In v0,pool_updates
only provided pool registration updates, whilepool_status
corresponded to current status of pool. With v1, we will have registration as well as deregistration transactions, and each transaction will haveupdate_type
(enum of eitherregistration
orderegistration
) instead ofpool_status
. As a side-effect, since a registration transaction only hasretiring_epoch
as metadata, all the other fields will show up asnull
for such a transaction #239 - Output -
/pool_metadata
,/pool_relays
- Addpool_status
field to denote whether pool is retired #239 - Output -
/datum_info
- Renamehash
todatum_hash
and addcreation_tx_hash
#239 - Output -
/native_script_list
- Removescript
column (as it has pretty large output better queried againstscript_info
), addsize
and changetype
to text #239 - Output -
/plutus_script_list
- Addtype
andsize
to output #239 - Output -
/asset_info
- Addcip68_metadata
JSONB field #239 - Output -
/pool_history
- Add member_rewards #225
Deprecations:⚓︎
/tx_utxos
- No longer required as replaced by/utxo_info
#239
Chores:⚓︎
- Update base version to
v1
fromv0
#1690 - Allow Bearer Authentication against endpoints #239
- Cron job to apply corrections to epoch info #239
epoch_info_cache
Remove protocol parameters, as they can be queried from live table. Accordingly update dependent queries #239- Make use of new
consumed_by_tx_in_id
column intx_out
from dbsync 13.1.1.3 across endpoints #239 - Fix
_last_active_stake_validated_epoch
in active_stake_cache #222 - Typo for pool_history_cache.sql as well as add a check to ensure epoch_info_cache has run at least once prior to pool_history_cache #223
- Move control_table entry in cache tables to the end (instead of start) #226
- Fix Asset Info Cache (include mint/burn tx rather than sum for meta consideration) #226
- Update SQLs as per SQLFluff linting guidelines #226
- Fix for tip check in cron jobs #217
- Update cron jobs to exit if the database has not received block in 5 mins #200
- Update active stake cache to use control table #196
- Update Asset Info Cache entry whenever asset registry cache has an update #194
- Bump up margin for tx rollback lookup for asset_info_cache to 1000 , as 100 is too small a margin for 2-3 blocks , which can contain more than 100 transactions (of which if oldest transaction contains a mint, it will not get into the cache) #177
- Swap grestrpcs file to list exceptions and treat everything else as RPC #1690
- Update grest-poll.sh to have stricter spec validation and add health check for asset_registry #1690
- Update guild-deploy.sh to include latest pre-release for ogmios #1690
[1.0.10] - For all networks.⚓︎
The release is effectively same as 1.0.10rc
except with one minor modification below.
Chores:⚓︎
- Replace all RPC references for JSON endpoints with JSONB, this allows filtering child members of array elements using
cs.[{"key":"value"}]
in PostgREST #172
[1.0.10rc] - For non-mainnet networks⚓︎
This release primarily focuses on ability to support better DeFi projects alongwith some value addition for existing clients by bringing in 10 new endpoints (paired with 2 deprecations), and few additional optional input parameters , and some additional output columns to existing endpoints. The only breaking change/fix is for output returned for tx_info
.
Also, dbsync 13.1.x.x has been released and is recommended to be used for this release
New endpoints added⚓︎
/asset_addresses
- Equivalent of deprecated/asset_address_list
#149/asset_nft_address
- Returns address where the specified NFT sits on #149/account_utxos
- Returns brief details on non-empty UTxOs associated with a given stake address #149/asset_info_bulk
- Bulk version of/asset_info
#142/asset_token_registry
- Returns assets registered via token registry on github #145/credential_utxos
- Returns UTxOs associated with a payment credential #149/param_updates
- Returns list of parameter update proposals applied to the network #149/policy_asset_addresses
- Returns addresses with quantity for each asset on a given policy #149/policy_asset_info
- Equivalent of deprecated/asset_policy_info
but with more details in output #149/policy_asset_list
- Returns list of asset under the given policy (including supply) #142, #149
Data Input/Output Changes⚓︎
- Input -
/account_addresses
- Add optional_first_only
and_empty
flags to show only first address with tx or to include empty addresses to output #149 - Input -
/epoch_info
- Add optional_include_next_epoch
field to show next epoch stats if available (eg: nonce, active stake) #143 - Output (addition) -
/account_assets
,/address_assets
,/address_info
,/tx_info
,/tx_utxos
- Adddecimals
to output #142 - Output (addition) -
/policy_asset_info
- Addminting_tx_hash
,total_supply
,mint_cnt
,burn_cnt
andcreation_time
fields to the output #149 - Output (breaking) -
/tx_info
- Change_invalid_before
and_invalid_after
to text field #141 - Output (breaking/removal) -
tx_info
- Remove the fieldplutus_contracts
> [array] >outputs
as there is no logic to connect it to inputs spending #163
Deprecations:⚓︎
/asset_address_list
- Renamed toasset_addresses
keeping naming line with other endpoints (old one still present, but will be deprecated in future release) #149/asset_policy_info
- Renamed topolicy_asset_info
keeping naming line with other endpoints (old one still present, but will be deprecated in future release) #149
Chores:⚓︎
/epoch_info
,/epoch_params
- Restrict output to current epoch #149/block_info
- Use/previous_id
field to show previous/next blocks (previously was using block_id/height) #145/asset_info
/asset_policy_info
- Fix mint tx data to be latest #141- Support new guild scripts revamp #1572
- Add asset token registry check 1606
- New cache table
grest.asset_info_cache
to hold mint/burn counts alongwith first/last mint tx/keys #142 - Bump to Koios 1.0.10rc #149
- Fix typo in specs for
/pool_delegators
output columnlatest_delegation_tx_hash
#149 - Add indexes for ones missing after configuring cardano-db-sync 13.1.0.0 #149
- Update PostgREST to be run as
authenticator
user, whose defaultstatement_timeout
is set to 65s and update configs accordingly #1606
[1.0.9] - For all networks⚓︎
This release is effectively same as 1.0.9rc
below (please check out the notes accordingly), just with minor bug fix on setup-grest.sh
itself.
[1.0.9rc] - For non-mainnet networks⚓︎
This release candidate is non-breaking for existing methods and inputs, but breaking for output objects for endpoints. The aim with release candidate version is to allow folks couple of weeks to test, adapt their libraries before applying to mainnet.
New endpoints added⚓︎
datum_info
- List of datum information for given datum hashesaccount_info_cached
- Same asaccount_info
, but serves cached information instead of live one
Data Input/Output changes⚓︎
address_info
,address_assets
,account_assets
,tx_info
,asset_list
asset_summary
to align outputasset_list
object to return array ofpolicy_id
,asset_name
,fingerprint
(andquantity
,minting_txs
where applicable) #120asset_history
- Fix metadata to wrap in array to refer to right object #122asset_txs
- Add optional boolean parameter_history
(default:false
) to toggle between querying current UTxO set vs entire history for asset #122pool_history
-fixed_cost
,pool_fees
,deleg_rewards
,epoch_ros
will be returned as 0 when null #122tx_info
-plutus_contracts->outputs
can be null #122
Changes for Instance Providers⚓︎
- SQL queries have been moved from
guild-operators
repository tokoios-artifacts
repository. This is to ensure that the updates made to scripts and other tooling do not have a dependency on Koios query versioning #122 block_info
- Useblock_no
instead ofid
to check for previous/next block hash #122- Add topology for preprod and preview networks #122
[1.0.8] - For all networks⚓︎
This release is contains minor bug-fixes that were discovered in koios-1.0.7. No major changes to output for this one.
Changes for API⚓︎
New endpoints added⚓︎
- None
Data Input/Output changes⚓︎
tx_info
andtx_metadata
- Align metadata for JSON output format #1542blocks
- Query Output aligned to specs (epoch
=>epoch_no
)epoch_block_protocols
- [ ** Specs only ** ] Fix Documentation schema , which was accidentally showing wrong outputpool_delegators_history
- List all epochs instead of current, if no_epoch_no
is specified #1545
Changes for Instance Providers⚓︎
asset_info
- Fix metadata aggregaton for minting transactions with multiple metadata keys #1543stake_distribution_new_accounts
- Leftover reference foraccount_info
which now accepts array, resulted in error to populate stake distribution cache for new accounts #1541grest-poll.sh
- Remove query view section from polling script, and remove grestrpcs re-creation per hour (it's already updated whensetup-grest.sh
is run) , in preparation for #1545
[1.0.7] - For all networks⚓︎
This release continues updates from koios-1.0.6 to further utilise stake-snapshot cache tables which would be useful for SPOs as well as reduce downtime post epoch transition. One largely requested feature to accept bulk inputs for many block/address/account endpoints is now complete. Additionally, koios instance providers are now recommended to use cardano-node 1.35.3 with dbsync 13.0.5.
Changes for API⚓︎
New endpoints added⚓︎
pool_delegators_history
- Provides historical record for pool's delegators #1486pool_stake_snapshot
- Provides mark, set and go snapshot values for pool being queried. #1489
Data Input/Output changes⚓︎
pool_delegators
- No longer accepts_epoch_no
as parameter, as it only returns live delegators. Additionally provideslatest_delegation_hash
in output. #1486tx_info
-epoch
=>epoch_no
#1494tx_info
- Changecollateral_outputs
(array) tocollateral_output
(object) as collateral output is only singular in current implementation #1496address_info
- Addinline_datum
andreference_script
to output #1500pool_info
- Addsigma
field to output #1511pool_updates
- Add historical metadata information to output #1503- Change block/address/account endpoints to accept bulk input where applicable. This resulted in GET requests changing to POST accepting payload of multiple blocks, addresses or accounts for respective endpoints as input (eg:
_stake_address text
becomes_stake_addresses text[]
). The additional changes in output as below: block_txs
- Now returnsblock_hash
and array oftx_hashes
address_info
- Additional fieldaddress
returned in outputaddress_assets
- Now returnsaddress
and an array ofassets
JSONaccount_addresses
- Acceptsstake_addresses
array and outputsstake_address
and array ofaddresses
account_assets
- Acceptsstake_addresses
array and outputsstake_address
and array ofassets
JSONaccount_history
- Acceptsstake_addresses
array alongwithepoch_no
integer and outputsstake_address
and array ofhistory
JSONaccount_info
- Acceptsstake_addresses
array and returns additional fieldstake_address
to outputaccount_rewards
- Now returnsstake_address
and an array ofrewards
JSONaccount_updates
- Now returnsstake_address
and an array ofupdates
JSONasset_info
- Changeminting_tx_metadata
from array to object #1533account_addresses
- Sort results by oldest address first #1538
Changes for Instance Providers⚓︎
epoch_info_cache
- Only update last_tx_id of previous epoch on epoch transition #1490 and #1502epoch_info_cache
/stake_snapshot_cache
- Store total snapshot stake to epoch stake cache, and active pool stake to stake snapshot cache #1485
[1.0.6/1.0.6m] - Interim release for all networks to upgrade to dbsync v13⚓︎
The backlog of items not being added to mainnet has been increasing due to delays with Vasil HFC event to Mainnet. As such we had to come up with a split update approach. The mainnet nodes are still not qualified to be Vasil-ready (in our opinion) for 1.35.x , but dbsync 13 can be used against node 1.34.1 fine. In order to cater for this split, we have added an intermediate koios-1.0.6m tag that brings dbsync updates while maintaining node-1.34.1.
Changes for API⚓︎
Data Output Changes⚓︎
pool_delegators
-epoch_no
=>active_epoch_no
#1454asset_history
- Addblock_time
andmetadata
fields for all previous mint transactions #1468asset_info
- Retain latest mint transaction instead of first (in line with most CIPs as well as pool metadata - latest valid meta being live) #1468- Ensure all output date formats is integer to keep in line with UNIX timestamps - to be revised in future if/when there are milliseconds #1460
/tip
,/blocks
,/block_info
=>block_time
/genesis
=>systemStart
/epoch_info
=>start_time
,first_block_time
,last_block_time
,end_time
/tx_info
=>tx_timestamp
/asset_info
=>creation_time
tx_info
- Add Vasil data #1464collaterals
=>collateral_inputs
- Add
collateral_outputs
,reference_inputs
totx_info
- Add
datum_hash
,inline_datum
,reference_script
to collateral input/outputs, reference inputs & inputs/outputs JSON. - Add complete
cost_model
instead ofcost_model_id
reference epoch_params
- Update leftover lovelace references to text for consistency: #1484key_deposit
pool_deposit
min_utxo_value
min_pool_cost
coins_per_utxo_size
Changes for Instance Providers⚓︎
get-metrics.sh
- Add active/idle connections to database #1459grest-poll.sh
: Bump haproxy to 2.6.1 and set default value of API_STRUCT_DEFINITION to be dependent on network used. #1450- Lighten
grest.account_active_stake_cache
- optimise code and delete historical view (beyond 4 epochs). [#1451(https://github.com/cardano-community/guild-operators/pull/1451) tx_metalabels
- Move metalabels from view to RPC using lose indexscan (much better performance) #1474- Major re-work to artificially add last epoch's active stake cache data (brings in latest snapshot information without depending on node), not used in endpoints for this release #1452
grest.stake_snapshot_cache
- Fix rewards for new accounts #1476
[1.0.5] - alpha networks only⚓︎
Since there have been a few deviations wrt Vasil for testnet and mainnet, this version only targets networks except Mainnet!
Changes for API⚓︎
Data Output Changes⚓︎
/epoch_info
- Addtotal_rewards
andavg_block_reward
for a given epoch #43- Update all date output formats to return UNIX timestamp (as per poll held in discussions group): #45
/tip
,/blocks
,/block_info
=>block_time
/genesis
=>systemStart
/epoch_info
=>start_time
,first_block_time
,last_block_time
,end_time
/tx_info
=>tx_timestamp
/asset_info
=>creation_time
/blocks
,/block_info
=> Addproto_major
andproto_minor
for a given block to output #55
Changes for Instance Providers⚓︎
- For consistency between date formats, we highly recommend you to upgrade your instance to use Postgres 14 (prolly a good time, since you would already need to recreate DB for dbsync v13). You can find sample instructions to do so here
- Various changes to backend scripts and performance optimisations that can be found here
[1.0.1]⚓︎
- Modify
asset_registry_update.sh
script to rely on commit hash instead of POSIX timestamps, and performance bump. #1428
[1.0.0]⚓︎
- First Production release for Koios gRest
[1.0.0-rc1]⚓︎
Changes for API⚓︎
Data Output Changes⚓︎
- Improve: Add
epoch_no
,block_no
to/address_txs
,/credential_txs
and/asset_txs
endpoints. #1409 - Fix: Remove redundant policy_info for
/asset_txs
, returning transactions as an array - allows for leveraging native PostgREST filtering. #1409 - Fix: Pool Metadata sorting was incorrect for
/pool_info
. #1414
Input Parameter Changes⚓︎
- None
Changes for Instance Providers⚓︎
Added⚓︎
- Add setup-grest.sh versioning. When running setup-grest.sh against a branch/tag, it will now populate the version information on control table, the health checks will be able to use this versioning for downstream connections. #1403
Fixed⚓︎
- Delete token token-registry folder when running
setup-grest.sh
with-r
(reset flag), as the delta registry records to insert depends on file (POSIX) timestamps. #1410 - Remove duplicate tip check in
grest-poll.sh
.
[1.0.0-rc0] - 2022-04-29⚓︎
- Initial Release Candidate for Koios gRest API layer with 43 endpoints to query the chain.