Skip to content

v1.2.0a
Compare
Choose a tag to compare
@rdlrt rdlrt released this 24 Aug 06:49
· 7 commits to main since this release
v1.2.0a
41bcff5
This commit was signed with the committer’s verified signature.
rdlrt RdLrT
SSH Key Fingerprint: aZVmiT4rSEUotzK55mDlHXpj+4cnDCAEziGl0tW6Izk Learn about vigilant mode.

Koios 1.2.0a

This release marks initial support for Conway era , with special impetus on Governance data. It brings with it 14 new endpoints enhancing ways to fetch data pertaining to new governance objects. Also, based on community feedback - it includes a minor breaking change (to block_tx_info and tx_info - to whitelist flags desired in output). Also, note that this release is based off cardano-db-sync 13.4.0.2 and node 9.1.0

This release is marked as alpha, as the governance artefacts on Sanchonet are incomplete and there are open questions raised against teams around significance/validation of some fields. Based on inputs we receive, we will follow-up a final version that may contain some minor updates - primarily on governance endpoints.

API Docs and Schedule for release:

The schedule for monitoring layers to apply update , as well as live documentation can be browsed as per table below:

Network Date URL Specs Release gRest Instance Release DBSync Node
GuildNet 23-08-2024 12:00 UTC https://guild.koios.rest/ v1.2.0a koios-1.2.0a 13.4.0.2 9.1.0
Preview 23-08-2024 12:00 UTC https://preview.koios.rest/ v1.2.0a koios-1.2.0a 13.4.0.2 9.1.0
PreProd 23-08-2024 13:00 UTC https://preprod.koios.rest/ v1.2.0a koios-1.2.0a 13.4.0.2 9.1.0
Mainnet* 30-08-2024 08:00 UTC https://api.koios.rest/ v1.2.0a koios-1.2.0a 13.4.0.2 9.1.0

Changes for API

Expand

New endpoints added:

  • /tx_cbor - Raw transaction CBOR against a transaction [#298]
  • /drep_epoch_summary - Summary of voting power and DRep count for each epoch [#298]
  • /drep_list - List of all active delegated representatives (DReps) [#298]
  • /drep_info - Get detailed information about requested delegated representatives (DReps) [#298]
  • /drep_metadata - List metadata for requested delegated representatives (DReps) [#298]
  • /drep_updates - List of updates for requested (or all) delegated representatives (DReps) [#298]
  • /drep_votes - List of all votes casted by requested delegated representative (DRep) [#298]
  • /drep_delegators - List of all delegators to requested delegated representative (DRep) [#298]
  • /committee_info - Information about active committee and its members [#298]
  • /committee_votes - List of all votes casted by given committee member or collective [#298]
  • /proposal_list - List of all governance proposals [#298]
  • /voter_proposal_list - List of all governance proposals for specified DRep, SPO or Committee credential [#298]
  • /proposal_votes - List of all votes cast on specified governance action [#298]
  • /pool_votes - List of all votes casted by a pool [#298]

Data Input/Output Changes:

  • Input - /block_tx_info, /tx_info - collateral_tx_out -> asset_list - Outputs for collateral tx out are never created on-chain and thus, cannot be queried from ma_tx_out. Instead a rough description of assets involved are saved , which is now returned as info from ledger. This is returned as-is from dbsync and does not adhere to asset_list schema we use in other endpoints. [#298]
  • Input - /tx_info , /block_tx_info - These endpoints now require you to specify what all information you'd like to retrieve from a transaction, providing flags _inputs , _metadata, _assets , _withdrawals, _certs, _scripts, _bytecode, _governance [#298]
  • Output - /policy_asset_mints , /policy_asset_info, /asset_info - Will return latest mint transaction that has metadata (instead of latest mint transaction) details (excluding burn transactions) [#298]
  • Output - /account_info , /pool_info , /pool_list - Add deposit field to output for deposit associated with registration [#298]
  • Output - /account_info - Add delegated_drep field to the output [#298]
  • Output - /block_tx_info , /tx_info - Add treasury_deposit, voting_procedures and proposal_procedures to the output [#298]
  • Output - /epoch_params - Add various fields to epoch_params as per Conway protocol parameters [#298]
  • Output - /pool_metadata, /pool_relays - Remove pool_status field from output (it's already listed in pool_info and list) [#298]
  • Output - /pool_updates - owners is now a JSONB field instead of JSONB array [#298]

Deprecations:

  • None

Retirements:

  • None

Chores:

  • Remove unused info from asset_info_cache - first_mint_tx_id , first_mint_keys , last_mint_keys are not used/required [#286]
  • Add last_mint_meta_tx_id field to asset_info_cache - to return latest asset that does have metadata [#286]
  • Reduce redundant cache information for pool stake as we now only retain 3 epochs in pool_active_stake_cache as the rest is already in pool_history_cache [#289]
  • Retire v0 SQL files (endpoints were already removed) from repository [#286]
  • Overwrite next epoch once on every execution (this is to avoid nonce mismatch if calculated too early from node) [#286]
  • Reduce reliance on pool_info_cache where possible to query live metadata [#298]
  • Make use of pool_stat instead of epoch_stake for pool_history_cache [#294]
  • instant_reward table in dbsync moved to reward_rest
  • ada_pots : deposit now split into three different types of deposits

Full Changelog can be found here for SQL queries and Specs , and here for scripts used.

Instructions for Instance Providers

Expand

If you're setting up as a new instance provider, you can find instructions here. The tag to use for setup-grest.sh would be koios-1.2.0a

The update process as usual would be:

  1. Update your node, submitapi, dbsync and ogmios binaries. You can use the sample below as reference (change network and top folder according to your environment):
./guild-deploy.sh -n $NETWORK -t cnode -b koios-1.2.0a -s plfdo

Note that the use of f above is to force overwrite your configs , as newer node includes ConwayGenesis placeholder keys. The above command will overwrite your config.json, topology.json as well as user variables, and save them original ones backups, you'd want to copy your user variables into the files modified and re-add port customisations to config.json or topology peering.

  1. Shutdown your node and dbsync services - and start node back up (replace cnode as per your environment in instructions):
sudo systemctl stop cnode cnode-dbsync
sudo rm -f /etc/cron.d/cnode-*
sudo systemctl start cnode

Expect node to take a few hours to startup, you can short-circuit the process by copying $CNODE_HOME/db folder from already upgraded node - while both source and destination node folders were against node being in shutdown state (or use mithril-client or use https://csnapshots.io). You can also check node startup status by viewing node logs (tail -100f $CNODE_HOME/logs/node0.json)

  1. While you Wait for your node to be in sync (you can monitor via gLiveView), you can proceed with dropping current dbsync DB and restoring from snapshot. To do so, use the below (execute commands one by one - verifying output):

We'd recommend using Postgres 16 and above, but it's up to individuals.

cd ~/git/cardano-db-sync
git fetch
git checkout 13.4.0.2
./scripts/postgresql-scripts.sh --recreatedb
rm -rf ${CNODE_HOME}/guild-db/ledger-state ; mkdir -p ${CNODE_HOME}/guild-db/ledger-state
ln -s ~/git/cardano-db-sync/schema ${CNODE_HOME}/guild-db/schema 
cd $CNODE_HOME/scripts ; ./dbsync.sh -d

If you're on mainnet, you'd likely want to restore from snapshot:

wget https://share.koios.rest/api/public/dl/xFdZDfM4%2Fdbsync%2Fmainnet-dbsnap-epoch504-x86_64.tgz -O /tmp/dbsyncsnap.tgz
scripts/postgresql-setup.sh --restore-snapshot /tmp/dbsyncsnap.tgz ${CNODE_HOME}/guild-db/ledger-state

Once the above is complete, you can start dbsync by sudo systemctl start cnode-dbsync. Wait for dbsync to finish synching, you can tail logs via tail -10f $CNODE_HOME/logs/dbsync.json - on mainnet in particular, this could take up to 2 days).

  1. With dbsync updated and on tip, you'd now be ready to go to the next step - updating koios. You'd want to update all components and reset your grest schema, sample command below:
./setup-grest.sh -b koios-1.2.0a -r -i prmcd
sudo systemctl restart cnode-postgrest cnode-haproxy

Due to difference in script provisioning versions, it is possible that you might have trouble starting cnode-postgrest - if so, check and ensure that you can access $CNODE_HOME/priv/grest.conf file as authenticator user - you can use command as test : sudo -u authenticator cat /opt/cardano/gnode/priv/grest.conf

Since we're again re-building cache, expect the cache to take a bit (few minutes on non-mainnet, while a few hours on mainnet).

Other Notes

Expand

Bug Reports/Feature Requests

Everyone is invited to create future feature requests here to help us triage issues.

Support/Discussions Group

Please ensure to join the Koios Support/Discussions group.
We're open to have meetings to work together as well as discuss future additions, feel free to ask

Contributors

We are blessed to have community who contribute in various ways, be it by serving community instances, library implementations, testing, or feedbacks. Special thanks to all the contributors that have been helping us improve the query layer along the way
@Scitz0 , @rdlrt , @redoracle, @hodlonaut, @reqlez , @huths0lo , @chadle-git , @gufmar , @dostrelith678, @ray-wallet, @edridudi , @mkungla , @xray-robot , @nothingalike, @safestak-keith , @QuixoteSystems, @abdelkrimdev, @cardano-apexpool , @AlexDochioiu , @DCOneCrypto , @PatrickTobler , @agaffney , @rcmorano , @gitmachtl, @Crypto2099, @robinboening, @fallen-icarus , @M4rc0Russ0 , @HT-Moh , @ducpm2303 , @michele-nuzzi , @maxee , @Jack-0, @larestrepo

Contributors

rcmorano, robinboening, and 31 other contributors
Assets 2
Loading