diff --git a/README.md b/README.md index 57bd3a15..7b48637b 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,30 @@ # Koios Artifacts Repository -Various Artifacts related to [Koios project](https://www.koios.rest) management and assets that are used for website, monitoring services as well as public-facing topology files. +Various Artifacts related to [Koios project](https://www.koios.rest) management and assets that are used for website - look at repository map below for further info. +Provisioning scripts to run an instance are part of [guild-operators repo](https://cardano-community.github.io/guild-operators/Build/grest/) alongwith Koios SPO tools ## Repository Map + ``` . ├── grafana-dashboards/ # Grafana dashboards used for monitoring Koios nodes ├── html/ # HTML Page(s) used for https://api.koios.rest website -├── images/ # Images (logos, Design diagram, etc) used for Koios +├── images/ # Images used for website (incl. projects building on Koios) ├── specs/ # Files used for creation of API Specs with examples ├── tests/ # Test suites for Koios nodes ├── topology/ # Topology files of public Koios nodes ├── topology-guild.json ├── topology-mainnet.json - └── topology-testnet.json -├── LICENSE # License for use of artifacts within this repository -├── README.md # This file -└── projects.json # List of projects (in JSON format) that are using Koios + └── topology-preprod.json + └── topology-preview.json +├── LICENSE # License for use of artifacts within this repository +├── README.md # This file +└── projects.json # List of projects (in JSON format) that are using Koios ``` + ## Project Management -Koios team operates gRest layer in a transparent manner and progress/millestones can be accessed at any time (accessible [here](https://github.com/orgs/cardano-community/projects/1)) +Koios team operates gRest layer in a transparent manner and progress/millestones can be accessed at any time (accessible [here](https://github.com/orgs/cardano-community/projects/1/views/2)) ## API Specs @@ -35,4 +39,4 @@ The specs can be browsed for each network using below: ## Further discussions -You can connect and discuss with Koios teams on [Telegram](https://t.me/+zE4Lce_QUepiY2U1), or feel free to contribute to any of the repositories. +You can connect and discuss with Koios teams on [Telegram](https://t.me/CardanoKoios/1), or feel free to contribute to any of the repositories. diff --git a/files/grest/cron/jobs/epoch-info-cache-update.sh b/files/grest/cron/jobs/epoch-info-cache-update.sh index 19012f81..c63aa739 100644 --- a/files/grest/cron/jobs/epoch-info-cache-update.sh +++ b/files/grest/cron/jobs/epoch-info-cache-update.sh @@ -1,12 +1,12 @@ #!/bin/bash DB_NAME=cexplorer -tip=$(psql ${DB_NAME} -qbt -c "select extract(epoch from time)::integer from block order by id desc limit 1;" | xargs) +tip=$(psql ${DB_NAME} -qbt -c "SELECT EXTRACT(EPOCH FROM time)::integer FROM block ORDER BY id DESC LIMIT 1;" | xargs) if [[ $(( $(date +%s) - tip )) -gt 300 ]]; then echo "$(date +%F_%H:%M:%S) Skipping as database has not received a new block in past 300 seconds!" && exit 1 fi echo "$(date +%F_%H:%M:%S) Running epoch info cache update..." -psql ${DB_NAME} -qbt -c "SELECT GREST.EPOCH_INFO_CACHE_UPDATE();" 1>/dev/null 2>&1 +psql ${DB_NAME} -qbt -c "SELECT grest.epoch_info_cache_update();" 1>/dev/null 2>&1 echo "$(date +%F_%H:%M:%S) Job done!" diff --git a/files/grest/cron/jobs/epoch-summary-corrections-update.sh b/files/grest/cron/jobs/epoch-summary-corrections-update.sh new file mode 100644 index 00000000..7bc9c9e4 --- /dev/null +++ b/files/grest/cron/jobs/epoch-summary-corrections-update.sh @@ -0,0 +1,12 @@ +#!/bin/bash +DB_NAME=cexplorer + +tip=$(psql ${DB_NAME} -qbt -c "SELECT EXTRACT(EPOCH FROM time)::integer FROM block ORDER BY id DESC LIMIT 1;" | xargs) + +if [[ $(( $(date +%s) - tip )) -gt 300 ]]; then + echo "$(date +%F_%H:%M:%S) Skipping as database has not received a new block in past 300 seconds!" && exit 1 +fi + +echo "$(date +%F_%H:%M:%S) Running epoch summary corrections update..." +psql ${DB_NAME} -qbt -c "SELECT GREST.EPOCH_SUMMARY_CORRECTIONS_UPDATE();" 1>/dev/null 2>&1 +echo "$(date +%F_%H:%M:%S) Job done!" diff --git a/files/grest/rpc/00_blockchain/reserve_withdrawals.sql b/files/grest/rpc/00_blockchain/reserve_withdrawals.sql new file mode 100644 index 00000000..4c0f3c18 --- /dev/null +++ b/files/grest/rpc/00_blockchain/reserve_withdrawals.sql @@ -0,0 +1,27 @@ +CREATE OR REPLACE FUNCTION grest.reserve_withdrawals() +RETURNS TABLE ( + epoch_no word31type, + epoch_slot word31type, + tx_hash text, + block_hash text, + block_height word31type, + amount text, + stake_address text +) +LANGUAGE SQL STABLE +AS $$ + SELECT + b.epoch_no, + b.epoch_slot_no, + ENCODE(tx.hash,'hex'), + ENCODE(b.hash,'hex'), + b.block_no, + r.amount::text, + sa.view + FROM reserve AS r + LEFT JOIN tx ON r.tx_id = tx.id + INNER JOIN block AS b ON tx.block_id = b.id + LEFT JOIN stake_address AS sa ON sa.id = r.addr_id; +$$; + +COMMENT ON FUNCTION grest.reserve_withdrawals IS 'A list of withdrawals made from reserves (MIRs)'; --noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/00_blockchain/treasury_withdrawals.sql b/files/grest/rpc/00_blockchain/treasury_withdrawals.sql new file mode 100644 index 00000000..b9919831 --- /dev/null +++ b/files/grest/rpc/00_blockchain/treasury_withdrawals.sql @@ -0,0 +1,27 @@ +CREATE OR REPLACE FUNCTION grest.treasury_withdrawals() +RETURNS TABLE ( + epoch_no word31type, + epoch_slot word31type, + tx_hash text, + block_hash text, + block_height word31type, + amount text, + stake_address text +) +LANGUAGE SQL STABLE +AS $$ + SELECT + b.epoch_no, + b.epoch_slot_no, + ENCODE(tx.hash,'hex'), + ENCODE(b.hash,'hex'), + b.block_no, + t.amount::text, + sa.view + FROM treasury AS t + LEFT JOIN tx ON t.tx_id = tx.id + INNER JOIN block AS b ON tx.block_id = b.id + LEFT JOIN stake_address AS sa ON sa.id = t.addr_id; +$$; + +COMMENT ON FUNCTION grest.treasury_withdrawals IS 'A list of withdrawals made from treasury'; --noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/01_cached_tables/asset_info_cache.sql b/files/grest/rpc/01_cached_tables/asset_info_cache.sql index 9dd11d16..41be3082 100644 --- a/files/grest/rpc/01_cached_tables/asset_info_cache.sql +++ b/files/grest/rpc/01_cached_tables/asset_info_cache.sql @@ -30,7 +30,7 @@ BEGIN WHERE state = 'active' AND query ILIKE '%grest.asset_info_cache_update%' AND datname = (SELECT current_database()) - ) THEN + ) THEN RAISE EXCEPTION 'Previous asset_info_cache_update query still running but should have completed! Exiting...'; END IF; @@ -56,7 +56,7 @@ BEGIN tx_mint_meta AS ( SELECT mtm.ident, - MIN(mtm.tx_id) AS first_mint_tx_id, + MIN(mtm.tx_id) AS first_mint_tx_id, MAX(mtm.tx_id) AS last_mint_tx_id FROM ma_tx_mint AS mtm INNER JOIN tx_metadata AS tm ON tm.tx_id = mtm.tx_id @@ -74,7 +74,7 @@ BEGIN tx_mint_nometa AS ( SELECT mtm.ident, - MIN(mtm.tx_id) AS first_mint_tx_id, + MIN(mtm.tx_id) AS first_mint_tx_id, MAX(mtm.tx_id) AS last_mint_tx_id FROM ma_tx_mint AS mtm LEFT JOIN tx_mint_meta ON tx_mint_meta.ident = mtm.ident @@ -111,7 +111,7 @@ BEGIN FROM tx_mint_nometa ) - INSERT INTO grest.asset_info_cache + INSERT INTO grest.asset_info_cache SELECT ma.id, MIN(B.time) AS creation_time, diff --git a/files/grest/rpc/01_cached_tables/asset_registry_cache.sql b/files/grest/rpc/01_cached_tables/asset_registry_cache.sql index 7d1ce37f..afc2fbe3 100644 --- a/files/grest/rpc/01_cached_tables/asset_registry_cache.sql +++ b/files/grest/rpc/01_cached_tables/asset_registry_cache.sql @@ -38,7 +38,7 @@ BEGIN decimals ) VALUES( - _asset_policy, + _asset_policy, _asset_name, _name, _description, diff --git a/files/grest/rpc/01_cached_tables/epoch_info_cache.sql b/files/grest/rpc/01_cached_tables/epoch_info_cache.sql index c6a2fc00..c210d664 100644 --- a/files/grest/rpc/01_cached_tables/epoch_info_cache.sql +++ b/files/grest/rpc/01_cached_tables/epoch_info_cache.sql @@ -9,37 +9,8 @@ CREATE TABLE IF NOT EXISTS grest.epoch_info_cache ( i_total_rewards lovelace, i_avg_blk_reward lovelace, i_last_tx_id bigint, - p_min_fee_a word31type, - p_min_fee_b word31type, - p_max_block_size word31type, - p_max_tx_size word31type, - p_max_bh_size word31type, - p_key_deposit lovelace, - p_pool_deposit lovelace, - p_max_epoch word31type, - p_optimal_pool_count word31type, - p_influence double precision, - p_monetary_expand_rate double precision, - p_treasury_growth_rate double precision, - p_decentralisation double precision, - p_extra_entropy text, - p_protocol_major word31type, - p_protocol_minor word31type, - p_min_utxo_value lovelace, - p_min_pool_cost lovelace, p_nonce text, - p_block_hash text, - p_cost_models character varying, - p_price_mem double precision, - p_price_step double precision, - p_max_tx_ex_mem word64type, - p_max_tx_ex_steps word64type, - p_max_block_ex_mem word64type, - p_max_block_ex_steps word64type, - p_max_val_size word64type, - p_collateral_percent word31type, - p_max_collateral_inputs word31type, - p_coins_per_utxo_size lovelace + p_block_hash text ); COMMENT ON TABLE grest.epoch_info_cache IS 'Contains detailed info for epochs including protocol parameters'; @@ -105,6 +76,20 @@ BEGIN DELETE FROM grest.epoch_info_cache WHERE epoch_no >= _epoch_no_to_insert_from; + DROP TABLE IF EXISTS last_tx_id_subset; + CREATE TEMP TABLE last_tx_id_subset ( + epoch_no bigint, + tx_id bigint + ); + + INSERT INTO last_tx_id_subset + SELECT b.epoch_no, MAX(tx.id) + FROM block AS b + INNER JOIN tx ON tx.block_id = b.id + WHERE b.block_no IS NOT NULL + AND b.tx_count != 0 + GROUP BY b.epoch_no; + INSERT INTO grest.epoch_info_cache SELECT DISTINCT ON (b.time) e.no AS epoch_no, @@ -115,45 +100,20 @@ BEGIN EXTRACT(EPOCH FROM e.start_time) AS i_first_block_time, EXTRACT(EPOCH FROM e.end_time) AS i_last_block_time, CASE -- populated in epoch n + 2 - WHEN e.no <= _curr_epoch - 2 THEN reward_pot.amount + WHEN e.no <= _curr_epoch - 2 THEN reward_pot.amount ELSE NULL END AS i_total_rewards, CASE -- populated in epoch n + 2 WHEN e.no <= _curr_epoch THEN ROUND(reward_pot.amount / e.blk_count) ELSE NULL - END AS i_avg_blk_reward, - last_tx.tx_id AS i_last_tx_id, - ep.min_fee_a AS p_min_fee_a, - ep.min_fee_b AS p_min_fee_b, - ep.max_block_size AS p_max_block_size, - ep.max_tx_size AS p_max_tx_size, - ep.max_bh_size AS p_max_bh_size, - ep.key_deposit AS p_key_deposit, - ep.pool_deposit AS p_pool_deposit, - ep.max_epoch AS p_max_epoch, - ep.optimal_pool_count AS p_optimal_pool_count, - ep.influence AS p_influence, - ep.monetary_expand_rate AS p_monetary_expand_rate, - ep.treasury_growth_rate AS p_treasury_growth_rate, - ep.decentralisation AS p_decentralisation, - ENCODE(ep.extra_entropy, 'hex') AS p_extra_entropy, - ep.protocol_major AS p_protocol_major, - ep.protocol_minor AS p_protocol_minor, - ep.min_utxo_value AS p_min_utxo_value, - ep.min_pool_cost AS p_min_pool_cost, + END AS i_avg_blk_reward, + ( + SELECT MAX(tx_id) + FROM last_tx_id_subset + WHERE epoch_no <= e.no + ) AS i_last_tx_id, ENCODE(ep.nonce, 'hex') AS p_nonce, - ENCODE(b.hash, 'hex') AS p_block_hash, - cm.costs AS p_cost_models, - ep.price_mem AS p_price_mem, - ep.price_step AS p_price_step, - ep.max_tx_ex_mem AS p_max_tx_ex_mem, - ep.max_tx_ex_steps AS p_max_tx_ex_steps, - ep.max_block_ex_mem AS p_max_block_ex_mem, - ep.max_block_ex_steps AS p_max_block_ex_steps, - ep.max_val_size AS p_max_val_size, - ep.collateral_percent AS p_collateral_percent, - ep.max_collateral_inputs AS p_max_collateral_inputs, - ep.coins_per_utxo_size AS p_coins_per_utxo_size + ENCODE(b.hash, 'hex') AS p_block_hash FROM epoch AS e LEFT JOIN epoch_param AS ep ON ep.epoch_no = e.no LEFT JOIN cost_model AS cm ON cm.id = ep.cost_model_id @@ -167,14 +127,6 @@ BEGIN GROUP BY e.no ) AS reward_pot ON TRUE - LEFT JOIN LATERAL ( - SELECT MAX(tx.id) AS tx_id - FROM block AS b - INNER JOIN tx ON tx.block_id = b.id - WHERE b.epoch_no <= e.no - AND b.block_no IS NOT NULL - AND b.tx_count != 0 - ) AS last_tx ON TRUE WHERE e.no >= _epoch_no_to_insert_from ORDER BY b.time ASC, diff --git a/files/grest/rpc/01_cached_tables/pool_history_cache.sql b/files/grest/rpc/01_cached_tables/pool_history_cache.sql index 9644e847..e4a0951b 100644 --- a/files/grest/rpc/01_cached_tables/pool_history_cache.sql +++ b/files/grest/rpc/01_cached_tables/pool_history_cache.sql @@ -39,9 +39,9 @@ BEGIN IF ( SELECT COUNT(key) != 1 FROM GREST.CONTROL_TABLE - WHERE key = 'epoch_info_cache_last_updated' + WHERE key = 'last_active_stake_validated_epoch' ) THEN - RAISE EXCEPTION 'Epoch Info Cache not yet populated! Exiting...'; + RAISE EXCEPTION 'Active stake cache not yet populated! Exiting...'; END IF; IF _epoch_no_to_insert_from IS NULL THEN @@ -153,9 +153,9 @@ BEGIN ROUND( (act.amount / ( SELECT supply::bigint / ( - SELECT eic.p_optimal_pool_count - FROM grest.epoch_info_cache AS eic - WHERE eic.epoch_no = act.epoch_no + SELECT ep.optimal_pool_count + FROM epoch_param AS ep + WHERE ep.epoch_no = act.epoch_no ) FROM grest.totals (act.epoch_no) ) * 100 diff --git a/files/grest/rpc/01_cached_tables/pool_info_cache.sql b/files/grest/rpc/01_cached_tables/pool_info_cache.sql index 39beb5f8..ca50c57d 100644 --- a/files/grest/rpc/01_cached_tables/pool_info_cache.sql +++ b/files/grest/rpc/01_cached_tables/pool_info_cache.sql @@ -55,7 +55,7 @@ BEGIN ORDER BY pr.id LIMIT 1; - IF _retiring_epoch IS NULL THEN + IF _retiring_epoch IS NULL THEN _pool_status := 'registered'; ELSIF _retiring_epoch > _current_epoch_no THEN _pool_status := 'retiring'; @@ -69,7 +69,7 @@ BEGIN tx_hash, block_time, pool_hash_id, - pool_id_bech32, + pool_id_bech32, pool_id_hex, active_epoch_no, vrf_key_hash, @@ -88,7 +88,7 @@ BEGIN SELECT _tx_id, _update_id, - encode(tx.hash::bytea, 'hex'), + encode(tx.hash::bytea, 'hex'), EXTRACT(EPOCH FROM b.time), _hash_id, ph.view, @@ -174,7 +174,7 @@ BEGIN ORDER BY pr.id LIMIT 1; - IF _retiring_epoch IS NULL THEN + IF _retiring_epoch IS NULL THEN _pool_status := 'registered'; ELSIF _retiring_epoch > _current_epoch_no THEN _pool_status := 'retiring'; @@ -222,8 +222,8 @@ BEGIN END IF; ELSIF (tg_table_name = 'pool_relay') THEN - SELECT pic.id INTO _latest_pool_update_id - FROM grest.pool_info_cache AS pic + SELECT pic.id INTO _latest_pool_update_id + FROM grest.pool_info_cache AS pic INNER JOIN public.pool_update AS pu ON pu.hash_id = pic.pool_hash_id AND pu.registered_tx_id = pic.tx_id WHERE pu.id = new.update_id; diff --git a/files/grest/rpc/01_cached_tables/stake_distribution_cache.sql b/files/grest/rpc/01_cached_tables/stake_distribution_cache.sql index 74cc44a9..e7d6960f 100644 --- a/files/grest/rpc/01_cached_tables/stake_distribution_cache.sql +++ b/files/grest/rpc/01_cached_tables/stake_distribution_cache.sql @@ -266,7 +266,7 @@ BEGIN SELECT (_current_block_height - _last_update_block_height) INTO _last_update_block_diff; -- Do nothing until there is a 180 blocks difference in height - 60 minutes theoretical time -- 185 in check because last block height considered is 5 blocks behind tip - + Raise NOTICE 'Last stake distribution update was % blocks ago...', _last_update_block_diff; IF (_last_update_block_diff >= 180 diff --git a/files/grest/rpc/02_indexes/13_1_00.sql b/files/grest/rpc/02_indexes/13_1_00.sql index 545c0985..39d471ca 100644 --- a/files/grest/rpc/02_indexes/13_1_00.sql +++ b/files/grest/rpc/02_indexes/13_1_00.sql @@ -5,7 +5,7 @@ CREATE UNIQUE INDEX IF NOT EXISTS unique_col_txout ON public.collateral_tx_out U CREATE UNIQUE INDEX IF NOT EXISTS unique_delegation ON public.delegation USING btree (tx_id, cert_index); CREATE UNIQUE INDEX IF NOT EXISTS unique_epoch_param ON public.epoch_param USING btree (epoch_no, block_id); CREATE UNIQUE INDEX IF NOT EXISTS unique_ma_tx_mint ON public.ma_tx_mint USING btree (ident, tx_id); -CREATE UNIQUE INDEX IF NOT EXISTS unique_ma_tx_out ON public.ma_tx_out USING btree (ident, tx_out_id); +CREATE UNIQUE INDEX IF NOT EXISTS unique_ma_tx_out ON public.ma_tx_out USING btree (ident, tx_out_id DESC); CREATE UNIQUE INDEX IF NOT EXISTS unique_param_proposal ON public.param_proposal USING btree (key, registered_tx_id); CREATE UNIQUE INDEX IF NOT EXISTS unique_pool_owner ON public.pool_owner USING btree (addr_id, pool_update_id); CREATE UNIQUE INDEX IF NOT EXISTS unique_pool_relay ON public.pool_relay USING btree (update_id, ipv4, ipv6, dns_name); diff --git a/files/grest/rpc/account/account_addresses.sql b/files/grest/rpc/account/account_addresses.sql index 51f9a7b6..b3039088 100644 --- a/files/grest/rpc/account/account_addresses.sql +++ b/files/grest/rpc/account/account_addresses.sql @@ -27,13 +27,9 @@ BEGIN txo.address, txo.stake_address_id, txo.id - FROM - tx_out AS txo - LEFT JOIN tx_in ON txo.tx_id = tx_in.tx_out_id - AND txo.index::smallint = tx_in.tx_out_index::smallint - WHERE - txo.stake_address_id = ANY(sa_id_list) - AND tx_in.tx_out_id IS NULL + FROM tx_out AS txo + WHERE txo.stake_address_id = ANY(sa_id_list) + AND txo.consumed_by_tx_in_id IS NULL ) AS x ) @@ -57,10 +53,8 @@ BEGIN txo.address, txo.stake_address_id, txo.id - FROM - tx_out AS txo - WHERE - txo.stake_address_id = ANY(sa_id_list) + FROM tx_out AS txo + WHERE txo.stake_address_id = ANY(sa_id_list) LIMIT (CASE WHEN _first_only IS TRUE THEN 1 ELSE NULL END) ) AS x ) diff --git a/files/grest/rpc/account/account_assets.sql b/files/grest/rpc/account/account_assets.sql index 06397515..0ead9fc8 100644 --- a/files/grest/rpc/account/account_assets.sql +++ b/files/grest/rpc/account/account_assets.sql @@ -1,20 +1,17 @@ CREATE OR REPLACE FUNCTION grest.account_assets(_stake_addresses text []) RETURNS TABLE ( stake_address varchar, - asset_list jsonb + policy_id text, + asset_name text, + fingerprint varchar, + decimals integer, + quantity text ) LANGUAGE plpgsql AS $$ -DECLARE - sa_id_list integer[]; BEGIN - SELECT INTO sa_id_list - ARRAY_AGG(stake_address.id) - FROM - stake_address - WHERE - stake_address.view = ANY(_stake_addresses); RETURN QUERY + WITH _all_assets AS ( SELECT sa.view, @@ -23,42 +20,27 @@ BEGIN ma.fingerprint, COALESCE(aic.decimals, 0) AS decimals, SUM(mtx.quantity) AS quantity - FROM - ma_tx_out AS mtx - INNER JOIN multi_asset AS ma ON ma.id = mtx.ident - INNER JOIN tx_out AS txo ON txo.id = mtx.tx_out_id - INNER JOIN stake_address AS sa ON sa.id = txo.stake_address_id - LEFT JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id - LEFT JOIN tx_in ON txo.tx_id = tx_in.tx_out_id - AND txo.index::smallint = tx_in.tx_out_index::smallint - WHERE - sa.id = ANY(sa_id_list) - AND tx_in.tx_out_id IS NULL + FROM ma_tx_out AS mtx + INNER JOIN multi_asset AS ma ON ma.id = mtx.ident + LEFT JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id + INNER JOIN tx_out AS txo ON txo.id = mtx.tx_out_id + INNER JOIN stake_address AS sa ON sa.id = txo.stake_address_id + WHERE sa.view = ANY(_stake_addresses) + AND txo.consumed_by_tx_in_id IS NULL GROUP BY sa.view, ma.policy, ma.name, ma.fingerprint, aic.decimals ) SELECT - assets_grouped.view AS stake_address, - assets_grouped.assets - FROM ( - SELECT - aa.view, - JSONB_AGG( - JSONB_BUILD_OBJECT( - 'policy_id', ENCODE(aa.policy, 'hex'), - 'asset_name', ENCODE(aa.name, 'hex'), - 'fingerprint', aa.fingerprint, - 'decimals', COALESCE(aa.decimals, 0), - 'quantity', aa.quantity::text - ) - ) AS assets - FROM - _all_assets AS aa - GROUP BY - aa.view - ) AS assets_grouped; + aa.view AS stake_address, + ENCODE(aa.policy, 'hex') AS policy_id, + ENCODE(aa.name, 'hex') AS asset_name, + aa.fingerprint AS fingerprint, + aa.decimals AS decimals, + aa.quantity::text AS quantity + FROM _all_assets AS aa + ORDER BY aa.view; END; $$; -COMMENT ON FUNCTION grest.account_assets IS 'Get the native asset balance of given accounts'; -- noqa: LT01 +COMMENT ON FUNCTION grest.account_assets IS 'Get the native asset balance of given accounts'; -- noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/account/account_info.sql b/files/grest/rpc/account/account_info.sql index e2149b5b..213e3aaa 100644 --- a/files/grest/rpc/account/account_info.sql +++ b/files/grest/rpc/account/account_info.sql @@ -109,15 +109,10 @@ BEGIN SELECT tx_out.stake_address_id, COALESCE(SUM(VALUE), 0) AS utxo - FROM - tx_out - LEFT JOIN tx_in ON tx_out.tx_id = tx_in.tx_out_id - AND tx_out.index::smallint = tx_in.tx_out_index::smallint - WHERE - tx_out.stake_address_id = ANY(sa_id_list) - AND tx_in.tx_out_id IS NULL - GROUP BY - tx_out.stake_address_id + FROM tx_out + WHERE tx_out.stake_address_id = ANY(sa_id_list) + AND tx_out.consumed_by_tx_in_id IS NULL + GROUP BY tx_out.stake_address_id ) AS utxo_t ON utxo_t.stake_address_id = status_t.id LEFT JOIN ( SELECT diff --git a/files/grest/rpc/account/account_txs.sql b/files/grest/rpc/account/account_txs.sql new file mode 100644 index 00000000..8a1f9d44 --- /dev/null +++ b/files/grest/rpc/account/account_txs.sql @@ -0,0 +1,51 @@ +CREATE OR REPLACE FUNCTION grest.account_txs(_stake_address text, _after_block_height integer DEFAULT 0) +RETURNS TABLE ( + tx_hash text, + epoch_no word31type, + block_height word31type, + block_time integer +) +LANGUAGE plpgsql +AS $$ +DECLARE + _tx_id_min bigint; + _tx_id_list bigint[]; +BEGIN + SELECT INTO _tx_id_min id + FROM tx + WHERE block_id >= (SELECT id FROM block WHERE block_no >= _after_block_height ORDER BY id limit 1) + ORDER BY id limit 1; + + -- all tx_out & tx_in tx ids + SELECT INTO _tx_id_list ARRAY_AGG(tx_id) + FROM ( + SELECT tx_id + FROM tx_out + WHERE stake_address_id = ANY(SELECT id FROM stake_address WHERE view = _stake_address) + AND tx_id >= _tx_id_min + -- + UNION + -- + SELECT consumed_by_tx_in_id AS tx_id + FROM tx_out + WHERE + tx_out.consumed_by_tx_in_id IS NULL + AND tx_out.stake_address_id = ANY(SELECT id FROM stake_address WHERE view = _stake_address) + AND tx_out.consumed_by_tx_in_id >= _tx_id_min + ) AS tmp; + + RETURN QUERY + SELECT + DISTINCT(ENCODE(tx.hash, 'hex')) AS tx_hash, + b.epoch_no, + b.block_no AS block_height, + EXTRACT(EPOCH FROM b.time)::integer AS block_time + FROM public.tx + INNER JOIN public.block AS b ON b.id = tx.block_id + WHERE tx.id = ANY(_tx_id_list) + AND b.block_no >= _after_block_height + ORDER BY b.block_no DESC; +END; +$$; + +COMMENT ON FUNCTION grest.account_txs IS 'Get transactions associated with a given stake address'; -- noqa: LT01 diff --git a/files/grest/rpc/account/account_updates.sql b/files/grest/rpc/account/account_updates.sql index 371829d6..3a851529 100644 --- a/files/grest/rpc/account/account_updates.sql +++ b/files/grest/rpc/account/account_updates.sql @@ -9,7 +9,7 @@ DECLARE sa_id_list integer[] DEFAULT NULL; BEGIN SELECT INTO sa_id_list - ARRAY_AGG(stake_address.id) + ARRAY_AGG(stake_address.id) FROM stake_address WHERE diff --git a/files/grest/rpc/account/account_utxos.sql b/files/grest/rpc/account/account_utxos.sql index 2692104d..5efa664e 100644 --- a/files/grest/rpc/account/account_utxos.sql +++ b/files/grest/rpc/account/account_utxos.sql @@ -1,34 +1,94 @@ -CREATE OR REPLACE FUNCTION grest.account_utxos(_stake_address text) +CREATE OR REPLACE FUNCTION grest.account_utxos(_stake_addresses text [], _extended boolean DEFAULT false) RETURNS TABLE ( tx_hash text, tx_index smallint, - address varchar, + address text, value text, + stake_address text, + payment_cred text, + epoch_no word31type, block_height word31type, - block_time integer + block_time integer, + datum_hash text, + inline_datum jsonb, + reference_script jsonb, + asset_list jsonb, + is_spent boolean ) LANGUAGE plpgsql AS $$ +DECLARE + known_addresses varchar[]; BEGIN RETURN QUERY - SELECT - ENCODE(tx.hash,'hex') AS tx_hash, - tx_out.index::smallint AS tx_index, - tx_out.address, - tx_out.value::text AS value, - b.block_no AS block_height, - EXTRACT(EPOCH FROM b.time)::integer AS block_time - FROM - tx_out - LEFT JOIN tx_in ON tx_in.tx_out_id = tx_out.tx_id - AND tx_in.tx_out_index = tx_out.index - INNER JOIN tx ON tx.id = tx_out.tx_id + WITH + _assets AS ( + SELECT + txo.id, + JSONB_AGG(CASE WHEN ma.policy IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'policy_id', ENCODE(ma.policy, 'hex'), + 'asset_name', ENCODE(ma.name, 'hex'), + 'fingerprint', ma.fingerprint, + 'decimals', aic.decimals, + 'quantity', mto.quantity::text + ) + END) as assets + FROM tx_out AS txo + INNER JOIN ma_tx_out AS mto ON mto.tx_out_id = txo.id + LEFT JOIN multi_asset AS ma ON ma.id = mto.ident + LEFT JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id + WHERE txo.stake_address_id IN (SELECT sa.id FROM stake_address AS sa WHERE sa.view = ANY(_stake_addresses)) + AND txo.consumed_by_tx_in_id IS NULL + GROUP BY txo.id + ) + SELECT + ENCODE(tx.hash, 'hex')::text AS tx_hash, + tx_out.index::smallint, + tx_out.address::text, + tx_out.value::text, + sa.view::text as stake_address, + ENCODE(tx_out.payment_cred, 'hex') AS payment_cred, + b.epoch_no, + b.block_no, + EXTRACT(EPOCH FROM b.time)::integer AS block_time, + ENCODE(tx_out.data_hash, 'hex') AS datum_hash, + (CASE + WHEN _extended = false OR tx_out.inline_datum_id IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'bytes', ENCODE(datum.bytes, 'hex'), + 'value', datum.value + ) + END) AS inline_datum, + (CASE + WHEN _extended = false OR tx_out.reference_script_id IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'hash', ENCODE(script.hash, 'hex'), + 'bytes', ENCODE(script.bytes, 'hex'), + 'value', script.json, + 'type', script.type::text, + 'size', script.serialised_size + ) + END) AS reference_script, + CASE + WHEN _extended = false THEN NULL + ELSE COALESCE(assets, JSONB_BUILD_ARRAY()) + END AS asset_list, + (CASE + WHEN tx_out.consumed_by_tx_in_id IS NULL THEN false + ELSE true + END) AS is_spent + FROM tx_out + INNER JOIN tx ON tx_out.tx_id = tx.id + LEFT JOIN stake_address AS sa ON tx_out.stake_address_id = sa.id LEFT JOIN block AS b ON b.id = tx.block_id - WHERE - tx_in.tx_out_id IS NULL - AND - tx_out.stake_address_id = (SELECT id FROM stake_address WHERE view = _stake_address); + LEFT JOIN datum ON datum.id = tx_out.inline_datum_id + LEFT JOIN script ON script.tx_id = tx_out.reference_script_id + LEFT JOIN _assets ON tx_out.id = _assets.id + WHERE tx_out.stake_address_id IN (SELECT sa.id FROM stake_address AS sa WHERE sa.view = ANY(_stake_addresses)) + AND tx_out.consumed_by_tx_in_id IS NULL + ; END; $$; -COMMENT ON FUNCTION grest.account_utxos IS 'Get non-empty UTxOs associated with a given stake address'; -- noqa: LT01 +COMMENT ON FUNCTION grest.account_utxos IS 'Get UTxO details for requested stake account'; -- noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/address/address_assets.sql b/files/grest/rpc/address/address_assets.sql index badacf1d..ea1bea11 100644 --- a/files/grest/rpc/address/address_assets.sql +++ b/files/grest/rpc/address/address_assets.sql @@ -1,55 +1,44 @@ CREATE OR REPLACE FUNCTION grest.address_assets(_addresses text []) RETURNS TABLE ( address varchar, - asset_list jsonb + policy_id text, + asset_name text, + fingerprint varchar, + decimals integer, + quantity text ) LANGUAGE plpgsql AS $$ BEGIN RETURN QUERY - WITH _all_assets AS ( - SELECT - txo.address, - ma.policy, - ma.name, - ma.fingerprint, - COALESCE(aic.decimals, 0) AS decimals, - SUM(mtx.quantity) AS quantity - FROM - ma_tx_out AS mtx + WITH _all_assets AS ( + SELECT + txo.address, + ma.policy, + ma.name, + ma.fingerprint, + COALESCE(aic.decimals, 0) AS decimals, + SUM(mtx.quantity) AS quantity + FROM ma_tx_out AS mtx INNER JOIN multi_asset AS ma ON ma.id = mtx.ident LEFT JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id INNER JOIN tx_out AS txo ON txo.id = mtx.tx_out_id - LEFT JOIN tx_in ON txo.tx_id = tx_in.tx_out_id - AND txo.index::smallint = tx_in.tx_out_index::smallint - WHERE - txo.address = ANY(_addresses) - AND tx_in.tx_out_id IS NULL - GROUP BY - txo.address, ma.policy, ma.name, ma.fingerprint, aic.decimals - ) + WHERE txo.address = ANY(_addresses) + AND txo.consumed_by_tx_in_id IS NULL + GROUP BY + txo.address, ma.policy, ma.name, ma.fingerprint, aic.decimals + ) - SELECT - assets_grouped.address, - assets_grouped.asset_list - FROM ( SELECT aa.address, - JSONB_AGG( - JSONB_BUILD_OBJECT( - 'policy_id', ENCODE(aa.policy, 'hex'), - 'asset_name', ENCODE(aa.name, 'hex'), - 'fingerprint', aa.fingerprint, - 'decimals', aa.decimals, - 'quantity', aa.quantity::text - ) - ) AS asset_list - FROM - _all_assets AS aa - GROUP BY - aa.address - ) assets_grouped; + ENCODE(aa.policy, 'hex') AS policy_id, + ENCODE(aa.name, 'hex') AS asset_name, + aa.fingerprint AS fingerprint, + aa.decimals AS decimals, + aa.quantity::text AS quantity + FROM _all_assets AS aa + ORDER BY aa.address; END; $$; diff --git a/files/grest/rpc/address/address_info.sql b/files/grest/rpc/address/address_info.sql index e4388cba..3c4ee367 100644 --- a/files/grest/rpc/address/address_info.sql +++ b/files/grest/rpc/address/address_info.sql @@ -16,11 +16,9 @@ BEGIN DISTINCT ON (tx_out.address) tx_out.address, sa.view AS stake_address, COALESCE(tx_out.address_has_script, 'false') AS script_address - FROM - tx_out - LEFT JOIN stake_address sa ON sa.id = tx_out.stake_address_id - WHERE - tx_out.address = ANY(_addresses); + FROM tx_out + LEFT JOIN stake_address AS sa ON sa.id = tx_out.stake_address_id + WHERE tx_out.address = ANY(_addresses); RETURN QUERY WITH _all_utxos AS ( @@ -35,15 +33,10 @@ BEGIN tx_out.data_hash, tx_out.inline_datum_id, tx_out.reference_script_id - FROM - tx_out - LEFT JOIN tx_in ON tx_in.tx_out_id = tx_out.tx_id - AND tx_in.tx_out_index = tx_out.index - INNER JOIN tx ON tx.id = tx_out.tx_id - WHERE - tx_in.tx_out_id IS NULL - AND - tx_out.address = ANY(_addresses) + FROM tx_out + INNER JOIN tx ON tx.id = tx_out.tx_id + WHERE tx_out.consumed_by_tx_in_id IS NULL + AND tx_out.address = ANY(_addresses) ) SELECT @@ -57,7 +50,7 @@ BEGIN ) THEN JSONB_AGG( JSONB_BUILD_OBJECT( - 'tx_hash', ENCODE(au.hash, 'hex'), + 'tx_hash', ENCODE(au.hash, 'hex'), 'tx_index', au.index, 'block_height', block.block_no, 'block_time', EXTRACT(EPOCH FROM block.time)::integer, @@ -98,12 +91,10 @@ BEGIN 'decimals', COALESCE(aic.decimals, 0), 'quantity', mtx.quantity::text )) - FROM - ma_tx_out AS mtx - INNER JOIN multi_asset AS ma ON ma.id = mtx.ident - LEFT JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id - WHERE - mtx.tx_out_id = au.txo_id + FROM ma_tx_out AS mtx + INNER JOIN multi_asset AS ma ON ma.id = mtx.ident + LEFT JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id + WHERE mtx.tx_out_id = au.txo_id ), JSONB_BUILD_ARRAY() ) @@ -112,16 +103,17 @@ BEGIN ELSE '[]'::jsonb END AS utxo_set - FROM - _known_addresses AS ka - LEFT OUTER JOIN _all_utxos AS au ON au.address = ka.address - LEFT JOIN public.block ON block.id = au.block_id - LEFT JOIN datum ON datum.id = au.inline_datum_id - LEFT JOIN script ON script.id = au.reference_script_id + FROM _known_addresses AS ka + LEFT OUTER JOIN _all_utxos AS au ON au.address = ka.address + LEFT JOIN public.block ON block.id = au.block_id + LEFT JOIN datum ON datum.id = au.inline_datum_id + LEFT JOIN script ON script.id = au.reference_script_id GROUP BY - ka.address, ka.stake_address, ka.script_address; + ka.address, + ka.stake_address, + ka.script_address; DROP TABLE _known_addresses; END; $$; -COMMENT ON FUNCTION grest.address_info IS 'Get bulk address info - balance, associated stake address (if any) and UTXO set'; -- noqa: LT01 +COMMENT ON FUNCTION grest.address_info IS 'Get bulk address info - balance, associated stake address (if any) and UTXO set'; -- noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/address/address_txs.sql b/files/grest/rpc/address/address_txs.sql index 840be398..dee58b22 100644 --- a/files/grest/rpc/address/address_txs.sql +++ b/files/grest/rpc/address/address_txs.sql @@ -19,42 +19,33 @@ BEGIN -- all tx_out & tx_in tx ids SELECT INTO _tx_id_list ARRAY_AGG(tx_id) FROM ( - SELECT - tx_id - FROM - tx_out - WHERE - address = ANY(_addresses) + SELECT tx_id + FROM tx_out + WHERE address = ANY(_addresses) AND tx_id >= _tx_id_min -- UNION -- - SELECT - tx_in_id AS tx_id - FROM - tx_out - LEFT JOIN tx_in ON tx_out.tx_id = tx_in.tx_out_id - AND tx_out.index = tx_in.tx_out_index - WHERE - tx_in.tx_in_id IS NOT NULL + SELECT consumed_by_tx_in_id AS tx_id + FROM tx_out + LEFT JOIN tx_in ON tx_out.tx_id = tx_in.tx_out_id + AND tx_out.index = tx_in.tx_out_index + WHERE tx_out.consumed_by_tx_in_id IS NOT NULL AND tx_out.address = ANY(_addresses) - AND tx_in.tx_in_id >= _tx_id_min + AND tx_out.consumed_by_tx_in_id >= _tx_id_min ) AS tmp; RETURN QUERY SELECT DISTINCT(ENCODE(tx.hash, 'hex')) AS tx_hash, - block.epoch_no, - block.block_no, - EXTRACT(EPOCH FROM block.time)::integer - FROM - public.tx - INNER JOIN public.block ON block.id = tx.block_id - WHERE - tx.id = ANY(_tx_id_list) - AND block.block_no >= _after_block_height - ORDER BY - block.block_no DESC; + b.epoch_no, + b.block_no AS block_height, + EXTRACT(EPOCH FROM b.time)::integer AS block_time + FROM public.tx + INNER JOIN public.block AS b ON b.id = tx.block_id + WHERE tx.id = ANY(_tx_id_list) + AND b.block_no >= _after_block_height + ORDER BY b.block_no DESC; END; $$; diff --git a/files/grest/rpc/address/address_utxos.sql b/files/grest/rpc/address/address_utxos.sql new file mode 100644 index 00000000..e0a322d6 --- /dev/null +++ b/files/grest/rpc/address/address_utxos.sql @@ -0,0 +1,94 @@ +CREATE OR REPLACE FUNCTION grest.address_utxos(_addresses text [], _extended boolean DEFAULT false) +RETURNS TABLE ( + tx_hash text, + tx_index smallint, + address text, + value text, + stake_address text, + payment_cred text, + epoch_no word31type, + block_height word31type, + block_time integer, + datum_hash text, + inline_datum jsonb, + reference_script jsonb, + asset_list jsonb, + is_spent boolean +) +LANGUAGE plpgsql +AS $$ +DECLARE + known_addresses varchar[]; +BEGIN + RETURN QUERY + WITH + _assets AS ( + SELECT + txo.id, + JSONB_AGG(CASE WHEN ma.policy IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'policy_id', ENCODE(ma.policy, 'hex'), + 'asset_name', ENCODE(ma.name, 'hex'), + 'fingerprint', ma.fingerprint, + 'decimals', aic.decimals, + 'quantity', mto.quantity::text + ) + END) as assets + FROM tx_out AS txo + INNER JOIN ma_tx_out AS mto ON mto.tx_out_id = txo.id + LEFT JOIN multi_asset AS ma ON ma.id = mto.ident + LEFT JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id + WHERE txo.address = ANY(_addresses) + AND txo.consumed_by_tx_in_id IS NULL + GROUP BY txo.id + ) + SELECT + ENCODE(tx.hash, 'hex')::text AS tx_hash, + tx_out.index::smallint, + tx_out.address::text, + tx_out.value::text, + sa.view::text as stake_address, + ENCODE(tx_out.payment_cred, 'hex') AS payment_cred, + b.epoch_no, + b.block_no, + EXTRACT(EPOCH FROM b.time)::integer AS block_time, + ENCODE(tx_out.data_hash, 'hex') AS datum_hash, + (CASE + WHEN _extended = false OR tx_out.inline_datum_id IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'bytes', ENCODE(datum.bytes, 'hex'), + 'value', datum.value + ) + END) AS inline_datum, + (CASE + WHEN _extended = false OR tx_out.reference_script_id IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'hash', ENCODE(script.hash, 'hex'), + 'bytes', ENCODE(script.bytes, 'hex'), + 'value', script.json, + 'type', script.type::text, + 'size', script.serialised_size + ) + END) AS reference_script, + CASE + WHEN _extended = false THEN NULL + ELSE COALESCE(assets, JSONB_BUILD_ARRAY()) + END AS asset_list, + (CASE + WHEN tx_out.consumed_by_tx_in_id IS NULL THEN false + ELSE true + END) AS is_spent + FROM tx_out + INNER JOIN tx ON tx_out.tx_id = tx.id + LEFT JOIN stake_address AS sa ON tx_out.stake_address_id = sa.id + LEFT JOIN block AS b ON b.id = tx.block_id + LEFT JOIN datum ON datum.id = tx_out.inline_datum_id + LEFT JOIN script ON script.tx_id = tx_out.reference_script_id + LEFT JOIN _assets ON tx_out.id = _assets.id + WHERE tx_out.address = ANY(_addresses) + AND tx_out.consumed_by_tx_in_id IS NULL + ; +END; +$$; + +COMMENT ON FUNCTION grest.address_utxos IS 'Get UTxO details for requested addresses'; -- noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/address/credential_txs.sql b/files/grest/rpc/address/credential_txs.sql index d581858a..21763479 100644 --- a/files/grest/rpc/address/credential_txs.sql +++ b/files/grest/rpc/address/credential_txs.sql @@ -16,53 +16,43 @@ BEGIN SELECT INTO _payment_cred_bytea ARRAY_AGG(cred_bytea) FROM ( SELECT DECODE(cred_hex, 'hex') AS cred_bytea - FROM - UNNEST(_payment_credentials) AS cred_hex + FROM UNNEST(_payment_credentials) AS cred_hex ) AS tmp; SELECT INTO _tx_id_min id - FROM tx - WHERE block_id >= (SELECT id FROM block WHERE block_no = _after_block_height) - ORDER BY id limit 1; + FROM tx + WHERE block_id >= (SELECT id FROM block WHERE block_no >= _after_block_height ORDER BY id limit 1) + ORDER BY id limit 1; -- all tx_out & tx_in tx ids SELECT INTO _tx_id_list ARRAY_AGG(tx_id) FROM ( SELECT tx_id - FROM - tx_out - WHERE - payment_cred = ANY(_payment_cred_bytea) + FROM tx_out + WHERE payment_cred = ANY(_payment_cred_bytea) AND tx_id >= _tx_id_min -- UNION -- - SELECT tx_in_id AS tx_id - FROM - tx_out - LEFT JOIN tx_in ON tx_out.tx_id = tx_in.tx_out_id - AND tx_out.index = tx_in.tx_out_index - WHERE - tx_in.tx_in_id IS NOT NULL + SELECT consumed_by_tx_in_id AS tx_id + FROM tx_out + WHERE tx_out.consumed_by_tx_in_id IS NOT NULL AND tx_out.payment_cred = ANY(_payment_cred_bytea) - AND tx_in.tx_in_id >= _tx_id_min + AND tx_out.consumed_by_tx_in_id >= _tx_id_min ) AS tmp; RETURN QUERY SELECT DISTINCT(ENCODE(tx.hash, 'hex')) AS tx_hash, - block.epoch_no, - block.block_no, - EXTRACT(EPOCH FROM block.time)::integer - FROM - public.tx - INNER JOIN public.block ON block.id = tx.block_id - WHERE - tx.id = ANY(_tx_id_list) - AND block.block_no >= _after_block_height - ORDER BY - block.block_no DESC; + b.epoch_no, + b.block_no AS block_height, + EXTRACT(EPOCH FROM b.time)::integer AS block_time + FROM public.tx + INNER JOIN public.block AS b ON b.id = tx.block_id + WHERE tx.id = ANY(_tx_id_list) + AND b.block_no >= _after_block_height + ORDER BY b.block_no DESC; END; $$; -COMMENT ON FUNCTION grest.address_txs IS 'Get the transaction hash list of a payment credentials array, optionally filtering after specified block height (inclusive).'; --noqa: LT01 +COMMENT ON FUNCTION grest.credential_txs IS 'Get the transaction hash list of a payment credentials array, optionally filtering after specified block height (inclusive).'; --noqa: LT01 diff --git a/files/grest/rpc/address/credential_utxos.sql b/files/grest/rpc/address/credential_utxos.sql index 6d9d4677..8d4d4520 100644 --- a/files/grest/rpc/address/credential_utxos.sql +++ b/files/grest/rpc/address/credential_utxos.sql @@ -1,34 +1,100 @@ -CREATE OR REPLACE FUNCTION grest.credential_utxos(_payment_credentials text []) +CREATE OR REPLACE FUNCTION grest.credential_utxos(_payment_credentials text [], _extended boolean DEFAULT false) RETURNS TABLE ( tx_hash text, tx_index smallint, - value text + address text, + value text, + stake_address text, + payment_cred text, + epoch_no word31type, + block_height word31type, + block_time integer, + datum_hash text, + inline_datum jsonb, + reference_script jsonb, + asset_list jsonb, + is_spent boolean ) LANGUAGE plpgsql AS $$ DECLARE _payment_cred_bytea bytea[]; - BEGIN SELECT INTO _payment_cred_bytea ARRAY_AGG(cred_bytea) FROM ( - SELECT - DECODE(cred_hex, 'hex') AS cred_bytea - FROM - UNNEST(_payment_credentials) AS cred_hex + SELECT DECODE(cred_hex, 'hex') AS cred_bytea + FROM UNNEST(_payment_credentials) AS cred_hex ) AS tmp; RETURN QUERY + WITH + _assets AS ( + SELECT + txo.id, + JSONB_AGG(CASE WHEN ma.policy IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'policy_id', ENCODE(ma.policy, 'hex'), + 'asset_name', ENCODE(ma.name, 'hex'), + 'fingerprint', ma.fingerprint, + 'decimals', aic.decimals, + 'quantity', mto.quantity::text + ) + END) as assets + FROM tx_out AS txo + INNER JOIN ma_tx_out AS mto ON mto.tx_out_id = txo.id + LEFT JOIN multi_asset AS ma ON ma.id = mto.ident + LEFT JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id + WHERE txo.payment_cred = ANY(_payment_cred_bytea) + AND txo.consumed_by_tx_in_id IS NULL + GROUP BY txo.id + ) SELECT ENCODE(tx.hash, 'hex')::text AS tx_hash, tx_out.index::smallint, - tx_out.value::text AS balance + tx_out.address::text, + tx_out.value::text, + sa.view::text as stake_address, + ENCODE(tx_out.payment_cred, 'hex') AS payment_cred, + b.epoch_no, + b.block_no, + EXTRACT(EPOCH FROM b.time)::integer AS block_time, + ENCODE(tx_out.data_hash, 'hex') AS datum_hash, + (CASE + WHEN _extended = false OR tx_out.inline_datum_id IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'bytes', ENCODE(datum.bytes, 'hex'), + 'value', datum.value + ) + END) AS inline_datum, + (CASE + WHEN _extended = false OR tx_out.reference_script_id IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'hash', ENCODE(script.hash, 'hex'), + 'bytes', ENCODE(script.bytes, 'hex'), + 'value', script.json, + 'type', script.type::text, + 'size', script.serialised_size + ) + END) AS reference_script, + CASE + WHEN _extended = false THEN NULL + ELSE COALESCE(assets, JSONB_BUILD_ARRAY()) + END AS asset_list, + (CASE + WHEN tx_out.consumed_by_tx_in_id IS NULL THEN false + ELSE true + END) AS is_spent FROM tx_out - INNER JOIN tx ON tx_out.tx_id = tx.id - LEFT JOIN tx_in ON tx_out.tx_id = tx_in.tx_out_id - AND tx_out.index = tx_in.tx_out_index - WHERE - payment_cred = ANY(_payment_cred_bytea) - AND tx_in.tx_out_id IS NULL; + INNER JOIN tx ON tx_out.tx_id = tx.id + LEFT JOIN stake_address AS sa ON tx_out.stake_address_id = sa.id + LEFT JOIN block AS b ON b.id = tx.block_id + LEFT JOIN datum ON datum.id = tx_out.inline_datum_id + LEFT JOIN script ON script.tx_id = tx_out.reference_script_id + LEFT JOIN _assets ON tx_out.id = _assets.id + WHERE tx_out.payment_cred = ANY(_payment_cred_bytea) + AND tx_out.consumed_by_tx_in_id IS NULL + ; END; $$; + +COMMENT ON FUNCTION grest.credential_utxos IS 'Get UTxO details for requested payment credentials'; -- noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/assets/asset_addresses.sql b/files/grest/rpc/assets/asset_addresses.sql index 3344d395..dd6d605d 100644 --- a/files/grest/rpc/assets/asset_addresses.sql +++ b/files/grest/rpc/assets/asset_addresses.sql @@ -24,15 +24,15 @@ DECLARE _asset_id int; BEGIN SELECT DECODE(_asset_policy, 'hex') INTO _asset_policy_decoded; - SELECT DECODE( - CASE WHEN _asset_name IS NULL - THEN '' - ELSE - _asset_name - END, - 'hex' - ) INTO _asset_name_decoded; - SELECT id INTO _asset_id FROM multi_asset AS ma WHERE ma.policy = _asset_policy_decoded AND ma.name = _asset_name_decoded; + SELECT DECODE(CASE + WHEN _asset_name IS NULL THEN '' + ELSE _asset_name + END, 'hex') INTO _asset_name_decoded; + SELECT id INTO _asset_id + FROM multi_asset AS ma + WHERE ma.policy = _asset_policy_decoded + AND ma.name = _asset_name_decoded; + RETURN QUERY SELECT x.address, @@ -42,17 +42,12 @@ BEGIN SELECT txo.address, mto.quantity - FROM - ma_tx_out AS mto - INNER JOIN tx_out AS txo ON txo.id = mto.tx_out_id - LEFT JOIN tx_in ON txo.tx_id = tx_in.tx_out_id - AND txo.index::smallint = tx_in.tx_out_index::smallint - WHERE - mto.ident = _asset_id - AND tx_in.tx_out_id IS NULL + FROM ma_tx_out AS mto + INNER JOIN tx_out AS txo ON txo.id = mto.tx_out_id + WHERE mto.ident = _asset_id + AND txo.consumed_by_tx_in_id IS NULL ) AS x - GROUP BY - x.address; + GROUP BY x.address; END; $$; diff --git a/files/grest/rpc/assets/asset_history.sql b/files/grest/rpc/assets/asset_history.sql index cef2e8b5..77833621 100644 --- a/files/grest/rpc/assets/asset_history.sql +++ b/files/grest/rpc/assets/asset_history.sql @@ -13,10 +13,8 @@ DECLARE BEGIN SELECT DECODE(_asset_policy, 'hex') INTO _asset_policy_decoded; SELECT DECODE( - CASE WHEN _asset_name IS NULL - THEN '' - ELSE - _asset_name + CASE WHEN _asset_name IS NULL THEN '' + ELSE _asset_name END, 'hex' ) INTO _asset_name_decoded; @@ -48,16 +46,15 @@ BEGIN 'key', tm.key::text, 'json', tm.json ) - ) + ) END ) AS metadata - FROM - ma_tx_mint AS mtm - INNER JOIN multi_asset AS ma ON ma.id = mtm.ident - INNER JOIN tx ON tx.id = MTM.tx_id - INNER JOIN block AS b ON b.id = tx.block_id - LEFT JOIN tx_metadata AS tm ON tm.tx_id = tx.id - WHERE ma.policy = _asset_policy_decoded + FROM ma_tx_mint AS mtm + INNER JOIN multi_asset AS ma ON ma.id = mtm.ident + INNER JOIN tx ON tx.id = MTM.tx_id + INNER JOIN block AS b ON b.id = tx.block_id + LEFT JOIN tx_metadata AS tm ON tm.tx_id = tx.id + WHERE ma.policy = _asset_policy_decoded AND ma.name = _asset_name_decoded GROUP BY ma.fingerprint, @@ -66,8 +63,7 @@ BEGIN mtm.quantity, tm.key ) AS minting_data - GROUP BY - minting_data.fingerprint; + GROUP BY minting_data.fingerprint; END; $$; diff --git a/files/grest/rpc/assets/asset_info_bulk.sql b/files/grest/rpc/assets/asset_info_bulk.sql index f03c37c1..7e079c97 100644 --- a/files/grest/rpc/assets/asset_info_bulk.sql +++ b/files/grest/rpc/assets/asset_info_bulk.sql @@ -10,7 +10,8 @@ RETURNS TABLE ( burn_cnt bigint, creation_time integer, minting_tx_metadata jsonb, - token_registry_metadata jsonb + token_registry_metadata jsonb, + cip68_metadata jsonb ) LANGUAGE plpgsql AS $$ @@ -52,7 +53,8 @@ BEGIN 'logo', arc.logo, 'decimals', arc.decimals ) - END + END, + cip68.metadata FROM multi_asset AS ma INNER JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id @@ -69,6 +71,52 @@ BEGIN WHERE tm.tx_id = tx.id ) metadata ON TRUE + LEFT JOIN LATERAL ( + -- CIP-68 supported labels + -- 100 = 000643b0 (ref, metadata) + -- 222 = 000de140 (NFT) + -- 333 = 0014df10 (FT) + -- 444 = 001bc280 (RFT) + SELECT + CASE + WHEN datum.value IS NULL THEN NULL + ELSE + JSONB_BUILD_OBJECT( + CASE + WHEN STARTS_WITH(ENCODE(ma.name, 'hex'), '000de140') THEN '222' + WHEN STARTS_WITH(ENCODE(ma.name, 'hex'), '0014df10') THEN '333' + WHEN STARTS_WITH(ENCODE(ma.name, 'hex'), '001bc280') THEN '444' + ELSE '0' + END, + datum.value + ) + END AS metadata + FROM + tx_out + INNER JOIN datum ON datum.hash = tx_out.data_hash + WHERE + tx_out.id = ( + SELECT + (SELECT MAX(tx_out_id) FROM ma_tx_out WHERE ident = _ma.id) as tx_id + FROM + multi_asset _ma + WHERE + _ma.policy = MA.policy + AND + _ma.name = ( + SELECT + CASE WHEN + STARTS_WITH(ENCODE(ma.name, 'hex'), '000de140') + OR + STARTS_WITH(ENCODE(ma.name, 'hex'), '0014df10') + OR + STARTS_WITH(ENCODE(ma.name, 'hex'), '001bc280') + THEN CONCAT('\x000643b0', SUBSTRING(ENCODE(ma.name, 'hex'), 9))::bytea + ELSE null + END + ) + ) + ) cip68 ON TRUE WHERE ma.id = ANY(_asset_id_list); diff --git a/files/grest/rpc/assets/asset_nft_address.sql b/files/grest/rpc/assets/asset_nft_address.sql index daaedab2..221d6cc4 100644 --- a/files/grest/rpc/assets/asset_nft_address.sql +++ b/files/grest/rpc/assets/asset_nft_address.sql @@ -10,27 +10,27 @@ DECLARE BEGIN SELECT DECODE(_asset_policy, 'hex') INTO _asset_policy_decoded; SELECT DECODE( - CASE WHEN _asset_name IS NULL - THEN '' - ELSE - _asset_name + CASE WHEN _asset_name IS NULL THEN '' + ELSE _asset_name END, 'hex' ) INTO _asset_name_decoded; - SELECT id INTO _asset_id - FROM - multi_asset AS ma - INNER JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id - WHERE - ma.policy = _asset_policy_decoded + SELECT id INTO _asset_id + FROM multi_asset AS ma + INNER JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id + WHERE ma.policy = _asset_policy_decoded AND ma.name = _asset_name_decoded AND aic.total_supply = 1; RETURN QUERY SELECT address FROM tx_out - WHERE id = (SELECT MAX(tx_out_id) FROM ma_tx_out WHERE ident = _asset_id); + WHERE id = ( + SELECT MAX(tx_out_id) + FROM ma_tx_out + WHERE ident = _asset_id + ); END; $$; diff --git a/files/grest/rpc/assets/asset_summary.sql b/files/grest/rpc/assets/asset_summary.sql index 04ae7d96..68ac5ba8 100644 --- a/files/grest/rpc/assets/asset_summary.sql +++ b/files/grest/rpc/assets/asset_summary.sql @@ -16,14 +16,15 @@ DECLARE BEGIN SELECT DECODE(_asset_policy, 'hex') INTO _asset_policy_decoded; SELECT DECODE( - CASE WHEN _asset_name IS NULL - THEN '' - ELSE - _asset_name + CASE WHEN _asset_name IS NULL THEN '' + ELSE _asset_name END, 'hex' ) INTO _asset_name_decoded; - SELECT id INTO _asset_id FROM multi_asset AS ma WHERE ma.policy = _asset_policy_decoded AND ma.name = _asset_name_decoded; + SELECT id INTO _asset_id + FROM multi_asset AS ma + WHERE ma.policy = _asset_policy_decoded + AND ma.name = _asset_name_decoded; RETURN QUERY with _asset_utxos AS ( SELECT @@ -32,48 +33,34 @@ BEGIN txo.index AS tx_out_idx, txo.address AS address, txo.stake_address_id AS sa_id - FROM - ma_tx_out AS mto - INNER JOIN tx_out AS txo ON txo.id = mto.tx_out_id - LEFT JOIN tx_in AS txi ON txi.tx_out_id = txo.tx_id - WHERE - mto.ident = _asset_id - AND - txi.tx_out_id IS NULL) - + FROM ma_tx_out AS mto + INNER JOIN tx_out AS txo ON txo.id = mto.tx_out_id + LEFT JOIN tx_in AS txi ON txi.tx_out_id = txo.tx_id + WHERE mto.ident = _asset_id + AND txi.tx_out_id IS NULL) + SELECT _asset_policy, _asset_name, ma.fingerprint, ( - SELECT - COUNT(DISTINCT(txo.tx_id)) - FROM - ma_tx_out mto - INNER JOIN tx_out txo ON txo.id = mto.tx_out_id - WHERE - ident = _asset_id + SELECT COUNT(DISTINCT(txo.tx_id)) + FROM ma_tx_out mto + INNER JOIN tx_out txo ON txo.id = mto.tx_out_id + WHERE ident = _asset_id ) AS total_transactions, ( - SELECT - COUNT(DISTINCT(_asset_utxos.sa_id)) - FROM - _asset_utxos - WHERE - _asset_utxos.sa_id IS NOT NULL + SELECT COUNT(DISTINCT(_asset_utxos.sa_id)) + FROM _asset_utxos + WHERE _asset_utxos.sa_id IS NOT NULL ) AS staked_wallets, ( - SELECT - COUNT(DISTINCT(_asset_utxos.address)) - FROM - _asset_utxos - WHERE - _asset_utxos.sa_id IS NULL + SELECT COUNT(DISTINCT(_asset_utxos.address)) + FROM _asset_utxos + WHERE _asset_utxos.sa_id IS NULL ) AS unstaked_addresses - FROM - multi_asset AS ma - WHERE - ma.id = _asset_id; + FROM multi_asset AS ma + WHERE ma.id = _asset_id; END; $$; diff --git a/files/grest/rpc/assets/asset_txs.sql b/files/grest/rpc/assets/asset_txs.sql index e34fc924..aaa7f6b7 100644 --- a/files/grest/rpc/assets/asset_txs.sql +++ b/files/grest/rpc/assets/asset_txs.sql @@ -19,14 +19,15 @@ DECLARE BEGIN SELECT DECODE(_asset_policy, 'hex') INTO _asset_policy_decoded; SELECT DECODE( - CASE WHEN _asset_name IS NULL - THEN '' - ELSE - _asset_name + CASE + WHEN _asset_name IS NULL THEN '' + ELSE _asset_name END, 'hex' ) INTO _asset_name_decoded; - SELECT id INTO _asset_id FROM multi_asset AS ma WHERE ma.policy = _asset_policy_decoded AND ma.name = _asset_name_decoded; + SELECT id INTO _asset_id + FROM multi_asset AS ma + WHERE ma.policy = _asset_policy_decoded AND ma.name = _asset_name_decoded; RETURN QUERY SELECT @@ -35,25 +36,23 @@ BEGIN tx_hashes.block_no, EXTRACT(EPOCH FROM tx_hashes.time)::integer FROM ( - SELECT DISTINCT ON (tx.hash) + SELECT DISTINCT ON (tx.hash,txo.index::smallint) tx.hash, block.epoch_no, block.block_no, block.time - FROM - ma_tx_out AS mto - INNER JOIN tx_out AS txo ON txo.id = mto.tx_out_id - INNER JOIN tx ON tx.id = txo.tx_id - INNER JOIN block ON block.id = tx.block_id - LEFT JOIN tx_in AS txi ON txo.tx_id = txi.tx_out_id - AND txo.index::smallint = txi.tx_out_index::smallint + FROM ma_tx_out AS mto + INNER JOIN tx_out AS txo ON txo.id = mto.tx_out_id + INNER JOIN tx ON tx.id = txo.tx_id + INNER JOIN block ON block.id = tx.block_id WHERE mto.ident = _asset_id AND block.block_no >= _after_block_height - AND (_history = TRUE OR txi.id IS NULL) + AND (_history = TRUE OR txo.consumed_by_tx_in_id IS NULL) GROUP BY ident, tx.hash, + txo.index::smallint, block.epoch_no, block.block_no, block.time diff --git a/files/grest/rpc/assets/asset_utxos.sql b/files/grest/rpc/assets/asset_utxos.sql new file mode 100644 index 00000000..d91d2785 --- /dev/null +++ b/files/grest/rpc/assets/asset_utxos.sql @@ -0,0 +1,106 @@ +CREATE OR REPLACE FUNCTION grest.asset_utxos(_asset_list text [] [], _extended boolean DEFAULT false) +RETURNS TABLE ( + tx_hash text, + tx_index smallint, + address text, + value text, + stake_address text, + payment_cred text, + epoch_no word31type, + block_height word31type, + block_time integer, + datum_hash text, + inline_datum jsonb, + reference_script jsonb, + asset_list jsonb, + is_spent boolean +) +LANGUAGE plpgsql +AS $$ +DECLARE + _asset_id_list bigint[]; +BEGIN + -- find all asset id's based ON nested array input + SELECT INTO _asset_id_list ARRAY_AGG(id) + FROM ( + SELECT DISTINCT mu.id + FROM ( + SELECT + DECODE(al->>0, 'hex') AS policy, + DECODE(al->>1, 'hex') AS name + FROM JSONB_ARRAY_ELEMENTS(TO_JSONB(_asset_list)) AS al + ) AS ald + INNER JOIN multi_asset AS mu ON mu.policy = ald.policy AND mu.name = ald.name + ) AS tmp; + + RETURN QUERY + WITH + _assets AS ( + SELECT + txo.id, + JSONB_AGG(CASE WHEN ma.policy IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'policy_id', ENCODE(ma.policy, 'hex'), + 'asset_name', ENCODE(ma.name, 'hex'), + 'fingerprint', ma.fingerprint, + 'decimals', aic.decimals, + 'quantity', mto.quantity::text + ) + END) as assets + FROM tx_out AS txo + INNER JOIN ma_tx_out AS mto ON mto.tx_out_id = txo.id + LEFT JOIN multi_asset AS ma ON ma.id = mto.ident + LEFT JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id + WHERE mto.ident = ANY(_asset_id_list) + AND txo.consumed_by_tx_in_id IS NULL + GROUP BY txo.id + ) + SELECT + ENCODE(tx.hash, 'hex')::text AS tx_hash, + tx_out.index::smallint, + tx_out.address::text, + tx_out.value::text, + sa.view::text as stake_address, + ENCODE(tx_out.payment_cred, 'hex') AS payment_cred, + b.epoch_no, + b.block_no, + EXTRACT(EPOCH FROM b.time)::integer AS block_time, + ENCODE(tx_out.data_hash, 'hex') AS datum_hash, + (CASE + WHEN _extended = false OR tx_out.inline_datum_id IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'bytes', ENCODE(datum.bytes, 'hex'), + 'value', datum.value + ) + END) AS inline_datum, + (CASE + WHEN _extended = false OR tx_out.reference_script_id IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'hash', ENCODE(script.hash, 'hex'), + 'bytes', ENCODE(script.bytes, 'hex'), + 'value', script.json, + 'type', script.type::text, + 'size', script.serialised_size + ) + END) AS reference_script, + CASE + WHEN _extended = false THEN NULL + ELSE COALESCE(assets, JSONB_BUILD_ARRAY()) + END AS asset_list, + (CASE + WHEN tx_out.consumed_by_tx_in_id IS NULL THEN false + ELSE true + END) AS is_spent + FROM tx_out + INNER JOIN tx ON tx_out.tx_id = tx.id + INNER JOIN _assets ON tx_out.id = _assets.id + LEFT JOIN stake_address AS sa ON tx_out.stake_address_id = sa.id + LEFT JOIN block AS b ON b.id = tx.block_id + LEFT JOIN datum ON datum.id = tx_out.inline_datum_id + LEFT JOIN script ON script.tx_id = tx_out.reference_script_id + WHERE tx_out.consumed_by_tx_in_id IS NULL + ; +END; +$$; + +COMMENT ON FUNCTION grest.asset_utxos IS 'Get UTxO details for requested assets'; -- noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/assets/policy_asset_addresses.sql b/files/grest/rpc/assets/policy_asset_addresses.sql index 478b1527..0ac2ac4f 100644 --- a/files/grest/rpc/assets/policy_asset_addresses.sql +++ b/files/grest/rpc/assets/policy_asset_addresses.sql @@ -6,42 +6,20 @@ RETURNS TABLE ( ) LANGUAGE plpgsql AS $$ -DECLARE - _asset_policy_decoded bytea; BEGIN - SELECT DECODE(_asset_policy, 'hex') INTO _asset_policy_decoded; RETURN QUERY - WITH - _all_assets AS ( - SELECT - id, - ENCODE(name, 'hex') AS asset_name - FROM - multi_asset AS ma - WHERE ma.policy = _asset_policy_decoded - ) - SELECT - x.asset_name, - x.address, - SUM(x.quantity)::text - FROM - ( - SELECT - aa.asset_name, - txo.address, - mto.quantity - FROM - _all_assets AS aa - INNER JOIN ma_tx_out AS mto ON mto.ident = aa.id - INNER JOIN tx_out AS txo ON txo.id = mto.tx_out_id - LEFT JOIN tx_in ON txo.tx_id = tx_in.tx_out_id - AND txo.index::smallint = tx_in.tx_out_index::smallint - WHERE - tx_in.tx_out_id IS NULL - ) AS x + ENCODE(ma.name, 'hex') AS asset_name, + txo.address, + SUM(mto.quantity)::text + FROM multi_asset AS ma + INNER JOIN ma_tx_out AS mto ON mto.ident = ma.id + INNER JOIN tx_out AS txo ON txo.id = mto.tx_out_id + WHERE ma.policy = DECODE(_asset_policy, 'hex') + AND txo.consumed_by_tx_in_id IS NULL GROUP BY - x.asset_name, x.address; + ma.name, + txo.address; END; $$; diff --git a/files/grest/rpc/assets/policy_asset_info.sql b/files/grest/rpc/assets/policy_asset_info.sql index 5c1e910b..9683479c 100644 --- a/files/grest/rpc/assets/policy_asset_info.sql +++ b/files/grest/rpc/assets/policy_asset_info.sql @@ -34,12 +34,8 @@ RETURNS TABLE ( ) LANGUAGE plpgsql AS $$ -DECLARE - _asset_policy_decoded bytea; - _policy_asset_ids bigint[]; BEGIN - SELECT DECODE(_asset_policy, 'hex') INTO _asset_policy_decoded; - RETURN QUERY + RETURN QUERY SELECT ENCODE(ma.name, 'hex') AS asset_name, ENCODE(ma.name, 'escape') AS asset_name_ascii, @@ -61,24 +57,19 @@ BEGIN 'decimals', arc.decimals ) END - FROM - multi_asset AS ma - INNER JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id - INNER JOIN tx ON tx.id = aic.last_mint_tx_id - LEFT JOIN grest.asset_registry_cache AS arc ON arc.asset_policy = ENCODE(ma.policy,'hex') AND arc.asset_name = ENCODE(ma.name, 'hex') - LEFT JOIN LATERAL ( - SELECT - JSONB_OBJECT_AGG( - key::text, - json - ) AS minting_tx_metadata - FROM - tx_metadata AS tm - WHERE - tm.tx_id = tx.id - ) metadata ON TRUE - WHERE - ma.policy = _asset_policy_decoded; + FROM multi_asset AS ma + INNER JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id + INNER JOIN tx ON tx.id = aic.last_mint_tx_id + LEFT JOIN grest.asset_registry_cache AS arc ON arc.asset_policy = ENCODE(ma.policy,'hex') AND arc.asset_name = ENCODE(ma.name, 'hex') + LEFT JOIN LATERAL ( + SELECT JSONB_OBJECT_AGG( + key::text, + json + ) AS minting_tx_metadata + FROM tx_metadata AS tm + WHERE tm.tx_id = tx.id + ) AS metadata ON TRUE + WHERE ma.policy = DECODE(_asset_policy, 'hex'); END; $$; diff --git a/files/grest/rpc/assets/policy_asset_list.sql b/files/grest/rpc/assets/policy_asset_list.sql index 630b9aa2..9893a2ea 100644 --- a/files/grest/rpc/assets/policy_asset_list.sql +++ b/files/grest/rpc/assets/policy_asset_list.sql @@ -17,11 +17,9 @@ BEGIN ma.fingerprint AS fingerprint, aic.total_supply::text, aic.decimals - FROM - multi_asset AS ma - INNER JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id - WHERE - ma.policy = _asset_policy_decoded; + FROM multi_asset AS ma + INNER JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id + WHERE ma.policy = _asset_policy_decoded; END; $$; diff --git a/files/grest/rpc/blocks/block_txs.sql b/files/grest/rpc/blocks/block_txs.sql index 8bdeeaf6..daf45adf 100644 --- a/files/grest/rpc/blocks/block_txs.sql +++ b/files/grest/rpc/blocks/block_txs.sql @@ -1,7 +1,10 @@ CREATE OR REPLACE FUNCTION grest.block_txs(_block_hashes text []) RETURNS TABLE ( block_hash text, - tx_hashes text [] + tx_hash text, + epoch_no word31type, + block_height word31type, + block_time integer ) LANGUAGE plpgsql AS $$ @@ -21,13 +24,15 @@ BEGIN RETURN QUERY SELECT - encode(b.hash, 'hex'), - ARRAY_AGG(ENCODE(tx.hash::bytea, 'hex')) - FROM - public.block AS b - INNER JOIN public.tx ON tx.block_id = b.id + ENCODE(b.hash, 'hex'), + ENCODE(tx.hash, 'hex') AS tx_hash, + b.epoch_no, + b.block_no AS block_height, + EXTRACT(EPOCH FROM b.time)::integer AS block_time + FROM public.block AS b + INNER JOIN public.tx ON tx.block_id = b.id WHERE b.id = ANY(_block_ids) - GROUP BY b.hash; + ; END; $$; diff --git a/files/grest/rpc/epoch/epoch_info.sql b/files/grest/rpc/epoch/epoch_info.sql index da9e5018..471235fd 100644 --- a/files/grest/rpc/epoch/epoch_info.sql +++ b/files/grest/rpc/epoch/epoch_info.sql @@ -44,9 +44,8 @@ BEGIN eas.amount::text AS active_stake, ei.i_total_rewards::text AS total_rewards, ei.i_avg_blk_reward::text AS avg_blk_reward - FROM - grest.epoch_info_cache AS ei - LEFT JOIN grest.epoch_active_stake_cache AS eas ON eas.epoch_no = ei.epoch_no + FROM grest.epoch_info_cache AS ei + LEFT JOIN grest.epoch_active_stake_cache AS eas ON eas.epoch_no = ei.epoch_no WHERE CASE WHEN _epoch_no IS NULL THEN ei.epoch_no <= (SELECT MAX(epoch.no) FROM public.epoch) @@ -54,7 +53,7 @@ BEGIN ei.epoch_no = _epoch_no END AND - (_include_next_epoch OR ei.i_first_block_time::integer is not null); + (_include_next_epoch OR ei.i_first_block_time::integer IS NOT NULL); END; $$; diff --git a/files/grest/rpc/epoch/epoch_params.sql b/files/grest/rpc/epoch/epoch_params.sql index 9807a468..93534925 100644 --- a/files/grest/rpc/epoch/epoch_params.sql +++ b/files/grest/rpc/epoch/epoch_params.sql @@ -21,7 +21,7 @@ RETURNS TABLE ( min_pool_cost text, nonce text, block_hash text, - cost_models character varying, + cost_models jsonb, price_mem double precision, price_step double precision, max_tx_ex_mem word64type, @@ -36,87 +36,52 @@ RETURNS TABLE ( LANGUAGE plpgsql AS $$ BEGIN - IF _epoch_no IS NULL THEN - RETURN QUERY + RETURN QUERY SELECT - ei.epoch_no, - ei.p_min_fee_a AS min_fee_a, - ei.p_min_fee_b AS min_fee_b, - ei.p_max_block_size AS max_block_size, - ei.p_max_tx_size AS max_tx_size, - ei.p_max_bh_size AS max_bh_size, - ei.p_key_deposit::text AS key_deposit, - ei.p_pool_deposit::text AS pool_deposit, - ei.p_max_epoch AS max_epoch, - ei.p_optimal_pool_count AS optimal_pool_count, - ei.p_influence AS influence, - ei.p_monetary_expand_rate AS monetary_expand_rate, - ei.p_treasury_growth_rate AS treasury_growth_rate, - ei.p_decentralisation AS decentralisation, - ei.p_extra_entropy AS extra_entropy, - ei.p_protocol_major AS protocol_major, - ei.p_protocol_minor AS protocol_minor, - ei.p_min_utxo_value::text AS min_utxo_value, - ei.p_min_pool_cost::text AS min_pool_cost, + ep.epoch_no, + ep.min_fee_a AS min_fee_a, + ep.min_fee_b AS min_fee_b, + ep.max_block_size AS max_block_size, + ep.max_tx_size AS max_tx_size, + ep.max_bh_size AS max_bh_size, + ep.key_deposit::text AS key_deposit, + ep.pool_deposit::text AS pool_deposit, + ep.max_epoch AS max_epoch, + ep.optimal_pool_count AS optimal_pool_count, + ep.influence AS influence, + ep.monetary_expand_rate AS monetary_expand_rate, + ep.treasury_growth_rate AS treasury_growth_rate, + ep.decentralisation AS decentralisation, + ENCODE(ep.extra_entropy, 'hex') AS extra_entropy, + ep.protocol_major AS protocol_major, + ep.protocol_minor AS protocol_minor, + ep.min_utxo_value::text AS min_utxo_value, + ep.min_pool_cost::text AS min_pool_cost, ei.p_nonce AS nonce, ei.p_block_hash AS block_hash, - ei.p_cost_models AS cost_models, - ei.p_price_mem AS price_mem, - ei.p_price_step AS price_step, - ei.p_max_tx_ex_mem AS max_tx_ex_mem, - ei.p_max_tx_ex_steps AS max_tx_ex_steps, - ei.p_max_block_ex_mem AS max_block_ex_mem, - ei.p_max_block_ex_steps AS max_block_ex_steps, - ei.p_max_val_size AS max_val_size, - ei.p_collateral_percent AS collateral_percent, - ei.p_max_collateral_inputs AS max_collateral_inputs, - ei.p_coins_per_utxo_size::text AS coins_per_utxo_size - FROM - grest.epoch_info_cache AS ei - WHERE - ei.epoch_no <= (SELECT MAX(epoch.no) FROM public.epoch) + cm.costs AS cost_models, + ep.price_mem AS price_mem, + ep.price_step AS price_step, + ep.max_tx_ex_mem AS max_tx_ex_mem, + ep.max_tx_ex_steps AS max_tx_ex_steps, + ep.max_block_ex_mem AS max_block_ex_mem, + ep.max_block_ex_steps AS max_block_ex_steps, + ep.max_val_size AS max_val_size, + ep.collateral_percent AS collateral_percent, + ep.max_collateral_inputs AS max_collateral_inputs, + ep.coins_per_utxo_size::text AS coins_per_utxo_size + FROM epoch_param AS ep + LEFT JOIN grest.epoch_info_cache AS ei ON ei.epoch_no = ep.epoch_no + LEFT JOIN cost_model AS cm ON cm.id = ep.cost_model_id + WHERE + CASE + WHEN _epoch_no IS NULL THEN + ep.epoch_no <= (SELECT MAX(epoch.no) FROM public.epoch) + ELSE + ep.epoch_no = _epoch_no + END ORDER BY ei.epoch_no DESC; - ELSE - RETURN QUERY - SELECT - ei.epoch_no, - ei.p_min_fee_a AS min_fee_a, - ei.p_min_fee_b AS min_fee_b, - ei.p_max_block_size AS max_block_size, - ei.p_max_tx_size AS max_tx_size, - ei.p_max_bh_size AS max_bh_size, - ei.p_key_deposit::text AS key_deposit, - ei.p_pool_deposit::text AS pool_deposit, - ei.p_max_epoch AS max_epoch, - ei.p_optimal_pool_count AS optimal_pool_count, - ei.p_influence AS influence, - ei.p_monetary_expand_rate AS monetary_expand_rate, - ei.p_treasury_growth_rate AS treasury_growth_rate, - ei.p_decentralisation AS decentralisation, - ei.p_extra_entropy AS extra_entropy, - ei.p_protocol_major AS protocol_major, - ei.p_protocol_minor AS protocol_minor, - ei.p_min_utxo_value::text AS min_utxo_value, - ei.p_min_pool_cost::text AS min_pool_cost, - ei.p_nonce AS nonce, - ei.p_block_hash AS block_hash, - ei.p_cost_models AS cost_models, - ei.p_price_mem AS price_mem, - ei.p_price_step AS price_step, - ei.p_max_tx_ex_mem AS max_tx_ex_mem, - ei.p_max_tx_ex_steps AS max_tx_ex_steps, - ei.p_max_block_ex_mem AS max_block_ex_mem, - ei.p_max_block_ex_steps AS max_block_ex_steps, - ei.p_max_val_size AS max_val_size, - ei.p_collateral_percent AS collateral_percent, - ei.p_max_collateral_inputs AS max_collateral_inputs, - ei.p_coins_per_utxo_size::text AS coins_per_utxo_size - FROM - grest.epoch_info_cache AS ei - WHERE - ei.epoch_no = _epoch_no; - END IF; END; $$; diff --git a/files/grest/rpc/epoch/epoch_summary_corrections_update.sql b/files/grest/rpc/epoch/epoch_summary_corrections_update.sql new file mode 100644 index 00000000..48b5559c --- /dev/null +++ b/files/grest/rpc/epoch/epoch_summary_corrections_update.sql @@ -0,0 +1,65 @@ +CREATE OR REPLACE function grest.epoch_summary_corrections_update() +RETURNS void +LANGUAGE plpgsql +AS $$ +DECLARE + curr_epoch_record record := null; + latest_epoch bigint = (SELECT MAX(no) FROM epoch); + last_epoch_checked bigint = coalesce((SELECT last_value::bigint FROM grest.control_table WHERE key = 'last_epoch_summary_data_checked'), -1); +BEGIN + RAISE NOTICE 'Last validated epoch was %', last_epoch_checked; + IF last_epoch_checked < 0 THEN + RAISE NOTICE 'Inserting initial record for key last_epoch_summary_data_checked'; + INSERT INTO grest.control_table values('last_epoch_summary_data_checked', 0, null); + END IF; + FOR curr_epoch_record IN ( + SELECT b.epoch_no + FROM + (SELECT + no, + blk_count AS epoch_blk_count, + tx_count AS epoch_tx_count + FROM epoch + WHERE no > last_epoch_checked - 2) AS e, + (SELECT + epoch_no, + COUNT(block_no) AS block_blk_count, + SUM(tx_count) AS block_tx_count + FROM block + WHERE epoch_no > (last_epoch_checked - 2) + GROUP BY epoch_no) AS b + WHERE e.no = b.epoch_no + AND (e.epoch_blk_count != b.block_blk_count OR e.epoch_tx_count != b.block_tx_count) + ORDER BY b.epoch_no + ) LOOP + RAISE NOTICE 'Need to fix up data for epoch %', curr_epoch_record; + WITH agg_table AS + ( SELECT + MIN(block.epoch_no) AS epoch_no, + SUM(tx.out_sum) AS out_sum, + SUM(tx.fee) AS fee_sum, + MIN(block.time) AS start_time, + MAX(block.time) AS end_time, + COUNT(tx.id) AS tx_count, + COUNT(distinct block.block_no) AS blk_count + FROM block + LEFT JOIN tx ON block.id = tx.block_id + WHERE block.epoch_no = curr_epoch_record.epoch_no + ) + + UPDATE epoch + SET + out_sum = COALESCE(agg_table.out_sum, 0), + fees = COALESCE(agg_table.fee_sum, 0), + tx_count = agg_table.tx_count, + blk_count = agg_table.blk_count, + start_time = agg_table.start_time, + end_time = agg_table.end_time + FROM agg_table + WHERE no = agg_table.epoch_no ; + + RAISE NOTICE 'Epoch row for epoch % corrected', curr_epoch_record; + END LOOP; + UPDATE grest.control_table SET last_value = latest_epoch::text WHERE key = 'last_epoch_summary_data_checked'; +END; +$$; diff --git a/files/grest/rpc/pool/pool_delegators.sql b/files/grest/rpc/pool/pool_delegators.sql index df1fe119..e9145a0c 100644 --- a/files/grest/rpc/pool/pool_delegators.sql +++ b/files/grest/rpc/pool/pool_delegators.sql @@ -11,8 +11,8 @@ AS $$ DECLARE _pool_id bigint; BEGIN - RETURN QUERY - WITH + RETURN QUERY + WITH _all_delegations AS ( SELECT sa.id AS stake_address_id, diff --git a/files/grest/rpc/pool/pool_history.sql b/files/grest/rpc/pool/pool_history.sql index 5fe43755..82c3e603 100644 --- a/files/grest/rpc/pool/pool_history.sql +++ b/files/grest/rpc/pool/pool_history.sql @@ -34,8 +34,8 @@ BEGIN COALESCE(member_rewards, 0)::text, COALESCE(epoch_ros, 0) FROM grest.pool_history_cache AS phc - WHERE phc.pool_id = _pool_bech32 and - (_epoch_no IS NULL OR + WHERE phc.pool_id = _pool_bech32 and + (_epoch_no IS NULL OR phc.epoch_no = _epoch_no) ORDER by phc.epoch_no desc; END; diff --git a/files/grest/rpc/pool/pool_info.sql b/files/grest/rpc/pool/pool_info.sql index fea544df..b295c4b0 100644 --- a/files/grest/rpc/pool/pool_info.sql +++ b/files/grest/rpc/pool/pool_info.sql @@ -34,21 +34,20 @@ DECLARE BEGIN SELECT MAX(epoch.no) INTO _epoch_no FROM public.epoch; SELECT FLOOR(supply::bigint / ( - SELECT p_optimal_pool_count - FROM grest.epoch_info_cache - WHERE epoch_no = _epoch_no + SELECT ep.optimal_pool_count + FROM epoch_param AS ep + WHERE ep.epoch_no = _epoch_no ))::bigint INTO _saturation_limit FROM grest.totals(_epoch_no); RETURN QUERY WITH _all_pool_info AS ( SELECT DISTINCT ON (pic.pool_id_bech32) * - FROM - grest.pool_info_cache AS pic - WHERE - pic.pool_id_bech32 = ANY(SELECT UNNEST(_pool_bech32_ids)) + FROM grest.pool_info_cache AS pic + WHERE pic.pool_id_bech32 = ANY(SELECT UNNEST(_pool_bech32_ids)) ORDER BY - pic.pool_id_bech32, pic.tx_id DESC + pic.pool_id_bech32, + pic.tx_id DESC ) SELECT @@ -76,66 +75,40 @@ BEGIN live.stake::text, live.delegators, ROUND((live.stake / _saturation_limit) * 100, 2) - FROM - _all_pool_info AS api + FROM _all_pool_info AS api LEFT JOIN LATERAL ( - ( - SELECT pod.json - FROM - public.pool_offline_data AS pod - WHERE - pod.pool_id = api.pool_hash_id - AND - pod.pmr_id = api.meta_id - ) - UNION ALL - ( - SELECT pod.json - FROM - public.pool_offline_data AS pod - WHERE - pod.pool_id = api.pool_hash_id - AND - pod.json IS NOT NULL - ORDER BY - pod.pmr_id DESC - ) + SELECT pod.json + FROM public.pool_offline_data AS pod + WHERE pod.pool_id = api.pool_hash_id + AND pod.pmr_id = api.meta_id + ORDER BY pod.pmr_id DESC LIMIT 1 - ) offline_data ON TRUE + ) AS offline_data ON TRUE LEFT JOIN LATERAL ( SELECT SUM(COUNT(b.id)) OVER () AS cnt, b.op_cert, b.op_cert_counter - FROM - public.block AS b - INNER JOIN - public.slot_leader AS sl ON b.slot_leader_id = sl.id - WHERE - sl.pool_hash_id = api.pool_hash_id + FROM public.block AS b + INNER JOIN public.slot_leader AS sl ON b.slot_leader_id = sl.id + WHERE sl.pool_hash_id = api.pool_hash_id GROUP BY b.op_cert, b.op_cert_counter - ORDER BY - b.op_cert_counter DESC + ORDER BY b.op_cert_counter DESC LIMIT 1 - ) block_data ON TRUE + ) AS block_data ON TRUE LEFT JOIN LATERAL( SELECT amount::lovelace AS as_sum - FROM - grest.pool_active_stake_cache AS pasc - WHERE - pasc.pool_id = api.pool_id_bech32 - AND - pasc.epoch_no = _epoch_no - ) active_stake ON TRUE + FROM grest.pool_active_stake_cache AS pasc + WHERE pasc.pool_id = api.pool_id_bech32 + AND pasc.epoch_no = _epoch_no + ) AS active_stake ON TRUE LEFT JOIN LATERAL( SELECT amount::lovelace AS es_sum - FROM - grest.epoch_active_stake_cache AS easc - WHERE - easc.epoch_no = _epoch_no - ) epoch_stake ON TRUE + FROM grest.epoch_active_stake_cache AS easc + WHERE easc.epoch_no = _epoch_no + ) AS epoch_stake ON TRUE LEFT JOIN LATERAL( SELECT CASE WHEN api.pool_status = 'retired' @@ -154,11 +127,9 @@ BEGIN ELSE SUM(CASE WHEN sdc.stake_address = ANY(api.owners) THEN total_balance ELSE 0 END)::lovelace END AS pledge - FROM - grest.stake_distribution_cache AS sdc - WHERE - sdc.pool_id = api.pool_id_bech32 - ) live ON TRUE; + FROM grest.stake_distribution_cache AS sdc + WHERE sdc.pool_id = api.pool_id_bech32 + ) AS live ON TRUE; END; $$; diff --git a/files/grest/rpc/pool/pool_list.sql b/files/grest/rpc/pool/pool_list.sql index c656d274..3d8ce843 100644 --- a/files/grest/rpc/pool/pool_list.sql +++ b/files/grest/rpc/pool/pool_list.sql @@ -1,7 +1,19 @@ CREATE OR REPLACE FUNCTION grest.pool_list() RETURNS TABLE ( pool_id_bech32 character varying, - ticker character varying + pool_id_hex text, + active_epoch_no bigint, + margin double precision, + fixed_cost text, + pledge text, + reward_addr character varying, + owners character varying [], + relays jsonb [], + ticker character varying, + meta_url character varying, + meta_hash text, + pool_status text, + retiring_epoch word31type ) LANGUAGE plpgsql AS $$ @@ -12,36 +24,49 @@ BEGIN -- Get last pool update for each pool _pool_list AS ( SELECT - DISTINCT ON (pic.pool_id_bech32) pool_id_bech32, - pool_status - FROM - grest.pool_info_cache AS pic - ORDER BY - pic.pool_id_bech32, - pic.tx_id DESC + ph.view as pool_id_bech32, + ph.hash_raw as pool_id_hex + FROM pool_hash AS ph ), _pool_meta AS ( - SELECT - DISTINCT ON (pic.pool_id_bech32) pool_id_bech32, - pod.ticker_name - FROM - grest.pool_info_cache AS pic - LEFT JOIN public.pool_offline_data AS pod ON pod.pmr_id = pic.meta_id - WHERE pod.ticker_name IS NOT NULL + SELECT DISTINCT ON (pic.pool_id_bech32) + pic.pool_id_bech32, + pic.active_epoch_no, + pic.margin, + pic.fixed_cost, + pic.pledge, + pic.reward_addr, + pic.owners, + pic.relays, + pod.ticker_name, + pic.meta_url, + pic.meta_hash, + pic.pool_status, + pic.retiring_epoch + FROM grest.pool_info_cache AS pic + LEFT JOIN public.pool_offline_data AS pod ON pod.pmr_id = pic.meta_id ORDER BY pic.pool_id_bech32, pic.tx_id DESC ) - SELECT pl.pool_id_bech32, - pm.ticker_name - FROM - _pool_list AS pl - LEFT JOIN _pool_meta AS pm ON pl.pool_id_bech32 = pm.pool_id_bech32 - WHERE - pool_status != 'retired' + encode(pl.pool_id_hex,'hex') as pool_id_hex, + pm.active_epoch_no, + pm.margin, + pm.fixed_cost::text, + pm.pledge::text, + pm.reward_addr, + pm.owners, + pm.relays, + pm.ticker_name, + pm.meta_url, + pm.meta_hash, + pm.pool_status, + pm.retiring_epoch + FROM _pool_list AS pl + LEFT JOIN _pool_meta AS pm ON pl.pool_id_bech32 = pm.pool_id_bech32 ); END; $$; diff --git a/files/grest/rpc/pool/pool_metadata.sql b/files/grest/rpc/pool/pool_metadata.sql index 872baf18..c919791c 100644 --- a/files/grest/rpc/pool/pool_metadata.sql +++ b/files/grest/rpc/pool/pool_metadata.sql @@ -3,32 +3,32 @@ RETURNS TABLE ( pool_id_bech32 character varying, meta_url character varying, meta_hash text, - meta_json jsonb + meta_json jsonb, + pool_status text ) LANGUAGE plpgsql AS $$ #variable_conflict use_column BEGIN RETURN QUERY - SELECT - DISTINCT ON (pic.pool_id_bech32) pool_id_bech32, + SELECT DISTINCT ON (pic.pool_id_bech32) + ph.view AS pool_id_bech32, pic.meta_url, pic.meta_hash, - pod.json - FROM - grest.pool_info_cache AS pic - LEFT JOIN - public.pool_offline_data AS pod ON pod.pmr_id = pic.meta_id + pod.json, + pic.pool_status + FROM public.pool_hash AS ph + LEFT JOIN grest.pool_info_cache AS pic ON ph.view = pic.pool_id_bech32 + LEFT JOIN public.pool_offline_data AS pod ON pod.pmr_id = pic.meta_id WHERE - pic.pool_status != 'retired' - AND CASE WHEN _pool_bech32_ids IS NULL THEN TRUE WHEN _pool_bech32_ids IS NOT NULL THEN pic.pool_id_bech32 = ANY(SELECT UNNEST(_pool_bech32_ids)) END ORDER BY - pic.pool_id_bech32, pic.tx_id DESC; + pic.pool_id_bech32, + pic.tx_id DESC; END; $$; -COMMENT ON FUNCTION grest.pool_metadata IS 'Metadata(on & off-chain) for all currently registered/retiring (not retired) pools'; -- noqa: LT01 +COMMENT ON FUNCTION grest.pool_metadata IS 'Metadata(on & off-chain) for all pools'; -- noqa: LT01 diff --git a/files/grest/rpc/pool/pool_registrations.sql b/files/grest/rpc/pool/pool_registrations.sql new file mode 100644 index 00000000..855ff4bd --- /dev/null +++ b/files/grest/rpc/pool/pool_registrations.sql @@ -0,0 +1,28 @@ +CREATE OR REPLACE FUNCTION grest.pool_registrations(_epoch_no numeric) +RETURNS TABLE ( + pool_id_bech32 text, + tx_hash text, + block_hash text, + block_height word31type, + epoch_no word31type, + epoch_slot word31type, + active_epoch_no word31type +) +LANGUAGE SQL STABLE +AS $$ + SELECT + ph.view, + ENCODE(tx.hash,'hex'), + ENCODE(b.hash,'hex'), + b.block_no, + b.epoch_no, + b.epoch_slot_no, + pu.active_epoch_no + FROM pool_update AS pu + LEFT JOIN tx ON pu.registered_tx_id = tx.id + INNER JOIN block AS b ON tx.block_id = b.id + LEFT JOIN pool_hash AS ph ON ph.id = pu.hash_id + WHERE b.epoch_no = _epoch_no; +$$; + +COMMENT ON FUNCTION grest.pool_registrations IS 'A list of all pool registrations initiated in the requested epoch'; --noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/pool/pool_relays.sql b/files/grest/rpc/pool/pool_relays.sql index 29fd8c28..84b70ab9 100644 --- a/files/grest/rpc/pool/pool_relays.sql +++ b/files/grest/rpc/pool/pool_relays.sql @@ -1,23 +1,23 @@ CREATE OR REPLACE FUNCTION grest.pool_relays() RETURNS TABLE ( pool_id_bech32 character varying, - relays jsonb [] + relays jsonb [], + pool_status text ) LANGUAGE plpgsql AS $$ #variable_conflict use_column BEGIN RETURN QUERY - SELECT - DISTINCT ON (pool_id_bech32) pool_id_bech32, - relays - FROM - grest.pool_info_cache - WHERE - pool_status != 'retired' + SELECT DISTINCT ON (pool_id_bech32) + pool_id_bech32, + relays, + pool_status + FROM grest.pool_info_cache ORDER BY - pool_id_bech32, tx_id DESC; + pool_id_bech32, + tx_id DESC; END; $$; -COMMENT ON FUNCTION grest.pool_relays IS 'A list of registered relays for all currently registered/retiring (not retired) pools'; --noqa: LT01 +COMMENT ON FUNCTION grest.pool_relays IS 'A list of registered relays for all pools'; --noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/pool/pool_retirements.sql b/files/grest/rpc/pool/pool_retirements.sql new file mode 100644 index 00000000..d2e7a16a --- /dev/null +++ b/files/grest/rpc/pool/pool_retirements.sql @@ -0,0 +1,28 @@ +CREATE OR REPLACE FUNCTION grest.pool_retirements(_epoch_no numeric) +RETURNS TABLE ( + pool_id_bech32 text, + tx_hash text, + block_hash text, + block_height word31type, + epoch_no word31type, + epoch_slot word31type, + active_epoch_no word31type +) +LANGUAGE SQL STABLE +AS $$ + SELECT + ph.view, + ENCODE(tx.hash,'hex'), + ENCODE(b.hash,'hex'), + b.block_no, + b.epoch_no, + b.epoch_slot_no, + pr.retiring_epoch + FROM pool_retire AS pr + LEFT JOIN tx ON pr.announced_tx_id = tx.id + INNER JOIN block AS b ON tx.block_id = b.id + LEFT JOIN pool_hash AS ph ON ph.id = pr.hash_id + WHERE b.epoch_no = _epoch_no; +$$; + +COMMENT ON FUNCTION grest.pool_registrations IS 'A list of all pool retirements initiated in the requested epoch'; --noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/pool/pool_updates.sql b/files/grest/rpc/pool/pool_updates.sql index ac4ca722..4cd4c48d 100644 --- a/files/grest/rpc/pool/pool_updates.sql +++ b/files/grest/rpc/pool/pool_updates.sql @@ -15,42 +15,77 @@ RETURNS TABLE ( meta_url character varying, meta_hash text, meta_json jsonb, - pool_status text, + update_type text, retiring_epoch word31type ) LANGUAGE plpgsql AS $$ -#variable_conflict use_column +DECLARE + _current_epoch_no word31type; BEGIN + SELECT COALESCE(MAX(no), 0) INTO _current_epoch_no FROM public.epoch; RETURN QUERY - SELECT - tx_hash, - block_time::integer, - pool_id_bech32, - pool_id_hex, - active_epoch_no, - vrf_key_hash, - margin, - fixed_cost::text, - pledge::text, - reward_addr, - owners, - relays, - meta_url, - meta_hash, - pod.json, - pool_status, - retiring_epoch - FROM - grest.pool_info_cache AS pic - LEFT JOIN public.pool_offline_data AS pod ON pod.pmr_id = pic.meta_id - WHERE - _pool_bech32 IS NULL - OR - pool_id_bech32 = _pool_bech32 + WITH + pool_reg AS ( + SELECT + pic.tx_hash, + pic.block_time::integer, + pic.pool_id_bech32, + pic.pool_id_hex, + pic.active_epoch_no, + pic.vrf_key_hash, + pic.margin, + pic.fixed_cost::text, + pic.pledge::text, + pic.reward_addr, + pic.owners, + pic.relays, + pic.meta_url, + pic.meta_hash, + pod.json, + 'registration' AS update_type, + NULL::word31type AS retiring_epoch + FROM + grest.pool_info_cache AS pic + LEFT JOIN public.pool_offline_data AS pod ON pod.pmr_id = pic.meta_id + LEFT JOIN public.pool_retire AS pr ON pic.pool_hash_id = pr.hash_id + WHERE _pool_bech32 IS NULL + OR pic.pool_id_bech32 = _pool_bech32), + pool_dereg AS ( + SELECT + ENCODE(tx.hash::bytea, 'hex') AS tx_hash, + EXTRACT(EPOCH FROM b.time)::integer AS block_time, + ph.view AS pool_id_bech32, + ENCODE(ph.hash_raw::bytea, 'hex') AS pool_id_hex, + NULL::bigint AS active_epoch_no, + NULL AS vrf_key_hash, + NULL::bigint AS margin, + NULL as fixed_cost, + NULL AS pledge, + NULL AS reward_addr, + NULL::text[] AS owners, + NULL::jsonb[] AS relays, + NULL AS meta_url, + NULL AS meta_hash, + NULL::jsonb AS json, + CASE + WHEN pr.retiring_epoch IS NULL THEN 'registration' + ELSE 'deregistration' + END AS update_type, + pr.retiring_epoch::word31type + FROM public.pool_hash AS ph + LEFT JOIN pool_retire AS pr ON pr.hash_id = ph.id + INNER JOIN public.tx ON tx.id = pr.announced_tx_id + INNER JOIN public.block AS b ON b.id = tx.block_id + WHERE _pool_bech32 IS NULL + OR ph.view = _pool_bech32) + SELECT * FROM pool_reg + UNION SELECT * FROM pool_dereg ORDER BY - tx_id DESC; + block_time DESC; END; $$; COMMENT ON FUNCTION grest.pool_updates IS 'Return all pool_updates for all pools or only updates for specific pool if specified'; -- noqa: LT01 + +SELECT grest.pool_updates(); \ No newline at end of file diff --git a/files/grest/rpc/script/datum_info.sql b/files/grest/rpc/script/datum_info.sql index 663a1913..c09c7d81 100644 --- a/files/grest/rpc/script/datum_info.sql +++ b/files/grest/rpc/script/datum_info.sql @@ -1,6 +1,7 @@ CREATE OR REPLACE FUNCTION grest.datum_info(_datum_hashes text []) RETURNS TABLE ( - hash text, + datum_hash text, + creation_tx_hash text, value jsonb, bytes text ) @@ -13,14 +14,14 @@ BEGIN FROM UNNEST(_datum_hashes) AS d_hash; RETURN QUERY SELECT - ENCODE(d.hash, 'hex'), + ENCODE(d.hash,'hex'), + ENCODE(tx.hash,'hex') AS creation_tx_hash, d.value, - ENCODE(d.bytes, 'hex') - FROM - datum AS d - WHERE - d.hash = ANY(_datum_hashes_decoded); + ENCODE(d.bytes,'hex') + FROM datum AS d + INNER JOIN tx ON tx.id = d.tx_id + WHERE d.hash = ANY(_datum_hashes_decoded); END; $$; -COMMENT ON FUNCTION grest.datum_info IS 'Get information about a given data FROM hashes.'; -- noqa: LT01 +COMMENT ON FUNCTION grest.datum_info IS 'Get information about a given datum FROM hashes.'; -- noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/script/native_script_list.sql b/files/grest/rpc/script/native_script_list.sql index a0af9728..7f0482e1 100644 --- a/files/grest/rpc/script/native_script_list.sql +++ b/files/grest/rpc/script/native_script_list.sql @@ -2,22 +2,22 @@ CREATE OR REPLACE FUNCTION grest.native_script_list() RETURNS TABLE ( script_hash text, creation_tx_hash text, - type scripttype, - script jsonb + type text, + size word31type ) LANGUAGE plpgsql AS $$ BEGIN RETURN QUERY SELECT - ENCODE(script.hash, 'hex'), - ENCODE(tx.hash, 'hex'), - script.type, - script.json - FROM script - INNER JOIN tx ON tx.id = script.tx_id - WHERE script.type IN ('timelock', 'multisig'); + ENCODE(s.hash, 'hex')::text AS script_hash, + ENCODE(tx.hash, 'hex')::text AS creation_tx_hash, + s.type::text AS type, + s.serialised_size AS size + FROM script AS s + INNER JOIN tx ON tx.id = s.tx_id + WHERE s.type IN ('timelock', 'multisig'); END; $$; -COMMENT ON FUNCTION grest.native_script_list IS 'Get a list of all native(multisig/timelock) script hashes with creation tx hash, type and script in json format.'; --noqa: LT01 +COMMENT ON FUNCTION grest.native_script_list IS 'Get a list of all native(multisig/timelock) script hashes with creation tx hash, type and script size.'; --noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/script/plutus_script_list.sql b/files/grest/rpc/script/plutus_script_list.sql index e149f5d8..b7f66b56 100644 --- a/files/grest/rpc/script/plutus_script_list.sql +++ b/files/grest/rpc/script/plutus_script_list.sql @@ -1,19 +1,23 @@ CREATE OR REPLACE FUNCTION grest.plutus_script_list() RETURNS TABLE ( script_hash text, - creation_tx_hash text + creation_tx_hash text, + type text, + size word31type ) LANGUAGE plpgsql AS $$ BEGIN RETURN QUERY SELECT - ENCODE(script.hash, 'hex') AS script_hash, - ENCODE(tx.hash, 'hex') AS creation_tx_hash - FROM script - INNER JOIN tx ON tx.id = script.tx_id - WHERE script.type IN ('plutusV1', 'plutusV2'); + ENCODE(s.hash,'hex')::text AS script_hash, + ENCODE(tx.hash,'hex')::text AS creation_tx_hash, + s.type::text AS type, + s.serialised_size AS size + FROM script AS s + INNER JOIN tx ON tx.id = s.tx_id + WHERE s.type IN ('plutusV1', 'plutusV2'); END; $$; -COMMENT ON FUNCTION grest.plutus_script_list IS 'Get a list of all plutus script hashes with creation tx hash.'; --noqa: LT01 +COMMENT ON FUNCTION grest.plutus_script_list IS 'Get a list of all plutus script hashes with creation tx hash.'; --noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/script/script_info.sql b/files/grest/rpc/script/script_info.sql new file mode 100644 index 00000000..c7322d4b --- /dev/null +++ b/files/grest/rpc/script/script_info.sql @@ -0,0 +1,32 @@ +CREATE OR REPLACE FUNCTION grest.script_info(_script_hashes text []) +RETURNS TABLE ( + script_hash text, + creation_tx_hash text, + type text, + value jsonb, + bytes text, + size word31type +) +LANGUAGE plpgsql +AS $$ +DECLARE + _script_hashes_decoded bytea[]; +BEGIN + SELECT INTO _script_hashes_decoded ARRAY_AGG(DECODE(s_hash, 'hex')) + FROM UNNEST(_script_hashes) AS s_hash; + RETURN QUERY + SELECT + ENCODE(s.hash,'hex') AS script_hash, + ENCODE(tx.hash,'hex') AS creation_tx_hash, + s.type::text AS type, + s.json AS value, + ENCODE(s.bytes,'hex')::text AS bytes, + s.serialised_size AS size + FROM script AS s + INNER JOIN tx ON tx.id = s.tx_id + WHERE s.hash = ANY(_script_hashes_decoded) + ; +END; +$$; + +COMMENT ON FUNCTION grest.script_info IS 'Get information about a given script FROM hashes.'; -- noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/script/script_utxos.sql b/files/grest/rpc/script/script_utxos.sql new file mode 100644 index 00000000..65ba9890 --- /dev/null +++ b/files/grest/rpc/script/script_utxos.sql @@ -0,0 +1,81 @@ +CREATE OR REPLACE FUNCTION grest.script_utxos(_script_hash text, _extended boolean DEFAULT false) +RETURNS TABLE ( + tx_hash text, + tx_index smallint, + address text, + value text, + stake_address text, + payment_cred text, + epoch_no word31type, + block_height word31type, + block_time integer, + datum_hash text, + inline_datum jsonb, + reference_script jsonb, + asset_list jsonb, + is_spent boolean +) +LANGUAGE plpgsql +AS $$ +DECLARE + known_addresses varchar[]; +BEGIN + RETURN QUERY + SELECT + ENCODE(tx.hash, 'hex')::text AS tx_hash, + tx_out.index::smallint, + tx_out.address::text, + tx_out.value::text, + sa.view::text as stake_address, + ENCODE(tx_out.payment_cred, 'hex') AS payment_cred, + b.epoch_no, + b.block_no, + EXTRACT(EPOCH FROM b.time)::integer AS block_time, + ENCODE(tx_out.data_hash, 'hex') AS datum_hash, + (CASE + WHEN _extended = false OR tx_out.inline_datum_id IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'bytes', ENCODE(datum.bytes, 'hex'), + 'value', datum.value + ) + END) AS inline_datum, + (CASE + WHEN _extended = false OR tx_out.reference_script_id IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'hash', ENCODE(script.hash, 'hex'), + 'bytes', ENCODE(script.bytes, 'hex'), + 'value', script.json, + 'type', script.type::text, + 'size', script.serialised_size + ) + END) AS reference_script, + (CASE + WHEN _extended = false OR ma.policy IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'policy_id', ENCODE(ma.policy, 'hex'), + 'asset_name', ENCODE(ma.name, 'hex'), + 'fingerprint', ma.fingerprint, + 'decimals', aic.decimals, + 'quantity', mto.quantity::text + ) + END + ) AS asset_list, + (CASE + WHEN tx_out.consumed_by_tx_in_id IS NULL THEN false + ELSE true + END) AS is_spent + FROM tx_out + INNER JOIN tx ON tx_out.tx_id = tx.id + INNER JOIN script ON script.tx_id = tx.id + LEFT JOIN stake_address AS sa ON tx_out.stake_address_id = sa.id + LEFT JOIN block AS b ON b.id = tx.block_id + LEFT JOIN ma_tx_out AS mto ON mto.tx_out_id = tx_out.id + LEFT JOIN multi_asset AS ma ON ma.id = mto.ident + LEFT JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id + LEFT JOIN datum ON datum.id = tx_out.inline_datum_id + WHERE script.hash = DECODE(_script_hash,'hex') + ; +END; +$$; + +COMMENT ON FUNCTION grest.script_utxos IS 'Get UTxO details for requested scripts'; -- noqa: LT01 \ No newline at end of file diff --git a/files/grest/rpc/transactions/tx_info.sql b/files/grest/rpc/transactions/tx_info.sql index 7719947c..44b3c78c 100644 --- a/files/grest/rpc/transactions/tx_info.sql +++ b/files/grest/rpc/transactions/tx_info.sql @@ -663,9 +663,9 @@ BEGIN ind.hash AS ind_hash, ind.value AS ind_value FROM redeemer - INNER JOIN tx_in ON tx_in.redeemer_id = redeemer.id - INNER JOIN tx_out AS inutxo ON inutxo.tx_id = tx_in.tx_out_id AND inutxo.index = tx_in.tx_out_index - INNER JOIN datum AS ind ON ind.hash = inutxo.data_hash + INNER JOIN tx_in ON tx_in.redeemer_id = redeemer.id + INNER JOIN tx_out AS inutxo ON inutxo.tx_id = tx_in.tx_out_id AND inutxo.index = tx_in.tx_out_index + INNER JOIN datum AS ind ON ind.hash = inutxo.data_hash WHERE redeemer.tx_id = ANY(_tx_id_list) ) @@ -845,7 +845,7 @@ BEGIN COALESCE((SELECT ans.list FROM _all_native_scripts AS ans WHERE ans.tx_id = atx.id), JSONB_BUILD_ARRAY()), COALESCE((SELECT apc.list FROM _all_plutus_contracts AS apc WHERE apc.tx_id = atx.id), JSONB_BUILD_ARRAY()) FROM _all_tx AS atx - WHERE atx.tx_hash = ANY(_tx_hashes_bytea) + WHERE atx.id = ANY(_tx_id_list) ); END; diff --git a/files/grest/rpc/transactions/tx_utxos.sql b/files/grest/rpc/transactions/tx_utxos.sql index af477a70..bda74b2e 100644 --- a/files/grest/rpc/transactions/tx_utxos.sql +++ b/files/grest/rpc/transactions/tx_utxos.sql @@ -66,7 +66,7 @@ BEGIN LEFT JOIN ma_tx_out AS mto ON mto.tx_out_id = tx_out.id LEFT JOIN multi_asset AS ma ON ma.id = mto.ident LEFT JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id - WHERE + WHERE tx_in.tx_in_id = ANY(_tx_id_list) ), @@ -97,12 +97,12 @@ BEGIN LEFT JOIN ma_tx_out AS mto ON mto.tx_out_id = tx_out.id LEFT JOIN multi_asset AS ma ON ma.id = mto.ident LEFT JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id - WHERE + WHERE tx_out.tx_id = ANY(_tx_id_list) ) SELECT - ENCODE(atx.tx_hash, 'hex'), + ENCODE(atx.tx_hash, 'hex'), COALESCE(( SELECT JSONB_AGG(tx_inputs) FROM ( diff --git a/files/grest/rpc/transactions/utxo_info.sql b/files/grest/rpc/transactions/utxo_info.sql new file mode 100644 index 00000000..22b9fb7f --- /dev/null +++ b/files/grest/rpc/transactions/utxo_info.sql @@ -0,0 +1,113 @@ +CREATE OR REPLACE FUNCTION grest.utxo_info(_utxo_refs text [], _extended boolean DEFAULT false) +RETURNS TABLE ( + tx_hash text, + tx_index smallint, + address text, + value text, + stake_address text, + payment_cred text, + epoch_no word31type, + block_height word31type, + block_time integer, + datum_hash text, + inline_datum jsonb, + reference_script jsonb, + asset_list jsonb, + is_spent boolean +) +LANGUAGE plpgsql +AS $$ +DECLARE + _tx_hashes_bytea bytea[]; + _tx_id_list bigint[]; +BEGIN + -- convert input _tx_hashes array into bytea array + DROP TABLE IF EXISTS utxo_refs; + CREATE TEMP TABLE utxo_refs AS ( + SELECT + DECODE(SPLIT_PART(ur,'#',1), 'hex') AS tx_hashes, + SPLIT_PART(ur,'#',2) AS tx_index + FROM UNNEST(_utxo_refs) AS ur + ); + + -- all tx ids + SELECT INTO _tx_id_list ARRAY_AGG(id) + FROM ( + SELECT txo.id + FROM tx_out AS txo + INNER JOIN tx ON tx.id = txo.tx_id + INNER JOIN utxo_refs AS ur ON ur.tx_hashes = tx.hash + AND ur.tx_index::smallint = txo.index + ) AS tmp; + + RETURN QUERY + WITH + _assets AS ( + SELECT + txo.id, + JSONB_AGG(CASE WHEN ma.policy IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'policy_id', ENCODE(ma.policy, 'hex'), + 'asset_name', ENCODE(ma.name, 'hex'), + 'fingerprint', ma.fingerprint, + 'decimals', aic.decimals, + 'quantity', mto.quantity::text + ) + END) as assets + FROM tx_out AS txo + INNER JOIN ma_tx_out AS mto ON mto.tx_out_id = txo.id + LEFT JOIN multi_asset AS ma ON ma.id = mto.ident + LEFT JOIN grest.asset_info_cache AS aic ON aic.asset_id = ma.id + WHERE txo.id = ANY(_tx_id_list) + GROUP BY txo.id + ) + SELECT + ENCODE(tx.hash, 'hex')::text AS tx_hash, + tx_out.index::smallint, + tx_out.address::text, + tx_out.value::text, + sa.view::text as stake_address, + ENCODE(tx_out.payment_cred, 'hex') AS payment_cred, + b.epoch_no, + b.block_no, + EXTRACT(EPOCH FROM b.time)::integer AS block_time, + ENCODE(tx_out.data_hash, 'hex') AS datum_hash, + (CASE + WHEN _extended = false OR tx_out.inline_datum_id IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'bytes', ENCODE(datum.bytes, 'hex'), + 'value', datum.value + ) + END) AS inline_datum, + (CASE + WHEN _extended = false OR tx_out.reference_script_id IS NULL THEN NULL + ELSE JSONB_BUILD_OBJECT( + 'hash', ENCODE(script.hash, 'hex'), + 'bytes', ENCODE(script.bytes, 'hex'), + 'value', script.json, + 'type', script.type::text, + 'size', script.serialised_size + ) + END) AS reference_script, + CASE + WHEN _extended = false THEN NULL + ELSE COALESCE(assets, JSONB_BUILD_ARRAY()) + END AS asset_list, + (CASE + WHEN tx_out.consumed_by_tx_in_id IS NULL THEN false + ELSE true + END) AS is_spent + FROM tx_out + INNER JOIN tx ON tx_out.tx_id = tx.id + LEFT JOIN stake_address AS sa ON tx_out.stake_address_id = sa.id + LEFT JOIN block AS b ON b.id = tx.block_id + LEFT JOIN datum ON datum.id = tx_out.inline_datum_id + LEFT JOIN script ON script.tx_id = tx_out.reference_script_id + LEFT JOIN _assets ON tx_out.id = _assets.id + WHERE tx_out.id = ANY(_tx_id_list) + ; + +END; +$$; + +COMMENT ON FUNCTION grest.utxo_info IS 'Get details for requested UTxO arrays (UTxOs accepted in # format).'; -- noqa: LT01 \ No newline at end of file diff --git a/html/index.html b/html/index.html index cd6e9a17..05404915 100644 --- a/html/index.html +++ b/html/index.html @@ -22,7 +22,7 @@
- +
diff --git a/specs/results/koiosapi-guild.yaml b/specs/results/koiosapi-guild.yaml index 2027146d..1bfb461d 100644 --- a/specs/results/koiosapi-guild.yaml +++ b/specs/results/koiosapi-guild.yaml @@ -1,7 +1,7 @@ openapi: 3.0.2 info: title: Koios API - version: 1.0.10 + version: v1.1.0rc description: | Koios is best described as a Decentralized and Elastic RESTful query layer for exploring data on Cardano blockchain to consume within applications/wallets/explorers/etc. This page not only provides an OpenAPI Spec for live implementation, but also ability to execute live demo from client browser against each endpoint with pre-filled examples. @@ -14,11 +14,11 @@ info: Instead of returning entire row, you can elect which rows you would like to fetch from the endpoint by using the `select` parameter with corresponding columns separated by commas. See example below (first is complete information for tip, while second command gives us 3 columns we are interested in):

``` bash - curl "https://api.koios.rest/api/v0/tip" + curl "https://api.koios.rest/api/v1/tip" # [{"hash":"4d44c8a453e677f933c3df42ebcf2fe45987c41268b9cfc9b42ae305e8c3d99a","epoch":317,"abs_slot":51700871,"epoch_slot":120071,"block_height":6806994,"block_time":1643267162}] - curl "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_height" + curl "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_height" # [{"epoch":317,"epoch_slot":120071,"block_height":6806994}] ``` @@ -27,7 +27,7 @@ info: You can filter the returned output based on specific conditions using operators against a column within returned result. Consider an example where you would want to query blocks minted in first 3 minutes of epoch 250 (i.e. epoch_slot was less than 180). To do so your query would look like below:

``` bash - curl "https://api.koios.rest/api/v0/blocks?epoch=eq.250&epoch_slot=lt.180" + curl "https://api.koios.rest/api/v1/blocks?epoch=eq.250&epoch_slot=lt.180" # [{"hash":"8fad2808ac6b37064a0fa69f6fe065807703d5235a57442647bbcdba1c02faf8","epoch":250,"abs_slot":22636942,"epoch_slot":142,"block_height":5385757,"block_time":1614203233,"tx_count":65,"vrf_key":"vrf_vk14y9pjprzlsjvjt66mv5u7w7292sxp3kn4ewhss45ayjga5vurgaqhqknuu","pool":null,"op_cert_counter":2}, # {"hash":"9d33b02badaedc0dedd0d59f3e0411e5fb4ac94217fb5ee86719e8463c570e16","epoch":250,"abs_slot":22636800,"epoch_slot":0,"block_height":5385756,"block_time":1614203091,"tx_count":10,"vrf_key":"vrf_vk1dkfsejw3h2k7tnguwrauqfwnxa7wj3nkp3yw2yw3400c4nlkluwqzwvka6","pool":null,"op_cert_counter":2}] @@ -62,7 +62,7 @@ info: Consider a simple case where I want query `blocks` endpoint for `block_height` column and focus on `content-range` header to monitor the rows we discussed above.

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height" -I | grep -i content-range # content-range: 0-999/* @@ -71,7 +71,7 @@ info: As we can see above, the number of observations returned was 1000 (range being 0-999), but the total size was not queried to avoid wait times. Now, let's modify this default behaviour to query rows beyond the first 999, but this time - also add another clause to limit results by 500. We can do this using `offset=1000` and `limit=500` as below:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height&offset=1000&limit=500" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height&offset=1000&limit=500" -I | grep -i content-range # content-range: 1000-1499/* @@ -80,7 +80,7 @@ info: For GET endpoints, there is also another method to achieve the above, instead of adding parameters to the URL itself, you can specify a `Range` header as below to achieve something similar:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height" -H "Range: 1000-1499" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height" -H "Range: 1000-1499" -I | grep -i content-range # content-range: 1000-1499/* @@ -94,7 +94,7 @@ info: Consider example where you want to check `epoch` and `epoch_slot` for the first 5 blocks created by a particular pool, i.e. you can set order to ascending based on block_height column and add horizontal filter for that pool ID as below:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?pool=eq.pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc&order=block_height.asc&limit=5" + curl -s "https://api.koios.rest/api/v1/blocks?pool=eq.pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc&order=block_height.asc&limit=5" # [{"hash":"610b4c7bbebeeb212bd002885048cc33154ba29f39919d62a3d96de05d315706","epoch":236,"abs_slot":16594295,"epoch_slot":5495,"block_height":5086774,"block_time":1608160586,"tx_count":1,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1}, # {"hash":"d93d1db5275329ab695d30c06a35124038d8d9af64fc2b0aa082b8aa43da4164","epoch":236,"abs_slot":16597729,"epoch_slot":8929,"block_height":5086944,"block_time":1608164020,"tx_count":7,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1}, @@ -109,13 +109,13 @@ info: Below is an example of JSON/CSV output making use of above to print first in JSON (default), and then override response format to CSV.

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_time&limit=3" + curl -s "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_time&limit=3" # [{"epoch":318,"epoch_slot":27867,"block_time":1643606958}, # {"epoch":318,"epoch_slot":27841,"block_time":1643606932}, # {"epoch":318,"epoch_slot":27839,"block_time":1643606930}] - curl -s "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_time&limit=3" -H "Accept: text/csv" + curl -s "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_time&limit=3" -H "Accept: text/csv" # epoch,epoch_slot,block_time # 318,28491,1643607582 @@ -134,6 +134,10 @@ info: Yet, there may be cases where the above restrictions may need exceptions (for example, an explorer or a wallet might need more connections than above - going beyond the Burst Limit). For such cases, it is best to approach the team and we can work towards a solution. + # Authentication + + While Koios public tier remains unauthenticated and allows queries without any authentication, it has low limits to prevent actions against an erroraneous query/loop from a consumer. There is also a Free tier which requires setting up Bearer Auth token that is linked to the owner's wallet account (which can be connected to via [Koios website](https://koios.rest/pricing/Pricing.html) ). + The examples across this API site already [supports authentication](/#auth), for you to use in the queries. # Community projects @@ -142,11 +146,12 @@ info: x-logo: url: "https://api.koios.rest/images/koios.png" servers: - - url: https://api.koios.rest/api/v0 - - url: https://guild.koios.rest/api/v0 - - url: https://preview.koios.rest/api/v0 - - url: https://preprod.koios.rest/api/v0 + - url: https://api.koios.rest/api/v1 + - url: https://guild.koios.rest/api/v1 + - url: https://preview.koios.rest/api/v1 + - url: https://preprod.koios.rest/api/v1 paths: + /tip: #RPC get: tags: @@ -227,6 +232,45 @@ paths: $ref: "#/components/responses/NotFound" summary: Param Update Proposals description: Get all parameter update proposals submitted to the chain starting Shelley era + /reserve_withdrawals: #RPC + get: + tags: + - Network + responses: + "200": + description: Array of withdrawals from reserves against stake accounts + content: + application/json: + schema: + $ref: "#/components/schemas/reserve_withdrawals" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Reserve Withdrawals + description: List of all withdrawals from reserves against stake accounts + /treasury_withdrawals: #RPC + get: + tags: + - Network + responses: + "200": + description: Array of withdrawals from treasury against stake accounts + content: + application/json: + schema: + $ref: "#/components/schemas/reserve_withdrawals" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Treasury Withdrawals + description: List of all withdrawals from treasury against stake accounts + /epoch_info: #RPC get: tags: @@ -294,6 +338,7 @@ paths: summary: Epoch's Block Protocols description: >- Get the information about block protocol distribution in epoch + /blocks: get: tags: @@ -355,28 +400,29 @@ paths: $ref: "#/components/responses/NotFound" summary: Block Transactions description: Get a list of all transactions included in provided blocks - /tx_info: #RPC + + /utxo_info: #RPC post: tags: - Transactions requestBody: - $ref: "#/components/requestBodies/tx_ids" + $ref: "#/components/requestBodies/utxo_refs_with_extended" responses: "200": - description: Array of detailed information about transaction(s) + description: Array of UTXO details content: application/json: schema: - $ref: "#/components/schemas/tx_info" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction Information - description: Get detailed information about transaction(s) - /tx_utxos: #RPC + summary: UTxO Info + description: Get UTxO set for requested UTxO references + /tx_info: #RPC post: tags: - Transactions @@ -384,19 +430,19 @@ paths: $ref: "#/components/requestBodies/tx_ids" responses: "200": - description: Array of inputs and outputs for given transaction(s) + description: Array of detailed information about transaction(s) content: application/json: schema: - $ref: "#/components/schemas/tx_utxos" + $ref: "#/components/schemas/tx_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction UTxOs [DEPRECATED] - description: Get UTxO set (inputs/outputs) of transactions. + summary: Transaction Information + description: Get detailed information about transaction(s) /tx_metadata: #RPC post: tags: @@ -450,7 +496,7 @@ paths: # If using a CLI-generated tx file, please ensure to deserialise (using `xxd -p -r <<< $(jq .cborHex ${tx.signed}) > ${data}`) first before submitting. curl -X POST \ --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/v0/submittx + --data-binary @${data} https://api.koios.rest/api/v1/submittx responses: "202": description: OK @@ -486,8 +532,31 @@ paths: $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction Status (Block Confirmations) + summary: Transaction Status description: Get the number of block confirmations for a given transaction hash list + /tx_utxos: #RPC + post: + tags: + - Transactions + deprecated: true + requestBody: + $ref: "#/components/requestBodies/tx_ids" + responses: + "200": + description: Array of inputs and outputs for given transaction(s) + content: + application/json: + schema: + $ref: "#/components/schemas/tx_utxos" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Transaction UTxOs + description: Get UTxO set (inputs/outputs) of transactions [DEPRECATED - Use /utxo_info instead]. + /address_info: #RPC post: tags: @@ -509,27 +578,27 @@ paths: $ref: "#/components/responses/NotFound" summary: Address Information description: Get address info - balance, associated stake address (if any) and UTxO set for given addresses - /address_txs: #RPC + /address_utxos: #RPC post: tags: - Address requestBody: - $ref: "#/components/requestBodies/address_txs" + $ref: "#/components/requestBodies/payment_addresses_with_extended" responses: "200": - description: Array of transaction hashes + description: Array of address UTXOs content: application/json: schema: - $ref: "#/components/schemas/address_txs" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Address Transactions - description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive) + summary: Address UTXOs + description: Get UTxO set for given addresses /credential_utxos: #RPC post: tags: @@ -542,7 +611,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/credential_utxos" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": @@ -550,28 +619,28 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: UTxOs from payment credentials - description: Get a list of UTxO against input payment credential array including their balances - /address_assets: #RPC + description: Get UTxO details for requested payment credentials + /address_txs: #RPC post: tags: - Address requestBody: - $ref: "#/components/requestBodies/payment_addresses" + $ref: "#/components/requestBodies/address_txs" responses: "200": - description: Array of address-owned assets + description: Array of transaction hashes content: application/json: schema: - $ref: "#/components/schemas/address_assets" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Address Assets - description: Get the list of all the assets (policy, name and quantity) for given addresses + summary: Address Transactions + description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive) /credential_txs: #RPC post: tags: @@ -584,7 +653,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/credential_txs" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": @@ -593,6 +662,28 @@ paths: $ref: "#/components/responses/NotFound" summary: Transactions from payment credentials description: Get the transaction hash list of input payment credential array, optionally filtering after specified block height (inclusive) + /address_assets: #RPC + post: + tags: + - Address + requestBody: + $ref: "#/components/requestBodies/payment_addresses" + responses: + "200": + description: Array of address-owned assets + content: + application/json: + schema: + $ref: "#/components/schemas/address_assets" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Address Assets + description: Get the list of all the assets (policy, name and quantity) for given addresses + /account_list: get: tags: @@ -633,48 +724,70 @@ paths: $ref: "#/components/responses/NotFound" summary: Account Information description: Get the account information for given stake addresses - /account_utxos: #RPC - get: + /account_info_cached: #RPC + post: tags: - Stake Account - parameters: - - $ref: "#/components/parameters/_stake_address" + requestBody: + $ref: "#/components/requestBodies/stake_addresses" responses: "200": - description: Array of account UTxOs associated with stake address + description: Array of account information content: application/json: schema: - $ref: "#/components/schemas/account_utxos" + $ref: "#/components/schemas/account_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Account UTxOs - description: Get a list of all UTxOs for a given stake address (account) - /account_info_cached: #RPC + summary: Account Information (Cached) + description: Get the cached account information for given stake addresses (effective for performance query against registered accounts) + /account_utxos: #RPC post: tags: - Stake Account requestBody: - $ref: "#/components/requestBodies/stake_addresses" + $ref: "#/components/requestBodies/stake_addresses_with_extended" responses: "200": - description: Array of account information + description: Array of account UTxOs associated with given stake addresses content: application/json: schema: - $ref: "#/components/schemas/account_info" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Account Information (Cached) - description: Get the cached account information for given stake addresses, effective for registered accounts + summary: UTxOs for stake addresses (accounts) + description: Get a list of all UTxOs for given stake addresses (account)s + /account_txs: #RPC + get: + tags: + - Stake Account + parameters: + - $ref: "#/components/parameters/_stake_address" + - $ref: "#/components/parameters/_after_block_height" + responses: + "200": + description: Array of Txs associated with stake address (account) + content: + application/json: + schema: + $ref: "#/components/schemas/address_txs" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Account Txs + description: Get a list of all Txs for a given stake address (account) /account_rewards: #RPC post: tags: @@ -783,6 +896,7 @@ paths: $ref: "#/components/responses/NotFound" summary: Account History description: Get the staking history of given stake addresses (accounts) + /asset_list: get: tags: @@ -802,95 +916,89 @@ paths: $ref: "#/components/responses/NotFound" summary: Asset List description: Get the list of all native assets (paginated) - /asset_token_registry: + /policy_asset_list: #RPC get: tags: - Asset + parameters: + - $ref: "#/components/parameters/_asset_policy" responses: "200": - description: Array of token registry information for each asset + description: Array of detailed information of assets under the same policy content: application/json: schema: - $ref: "#/components/schemas/asset_token_registry" + $ref: "#/components/schemas/policy_asset_list" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Token Registry - description: Get a list of assets registered via token registry on github - /asset_addresses: #RPC + summary: Policy Asset List + description: Get the list of asset under the given policy (including balances) + /asset_token_registry: get: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of payment addresses holding the given token (including balances) + description: Array of token registry information for each asset content: application/json: schema: - $ref: "#/components/schemas/asset_addresses" + $ref: "#/components/schemas/asset_token_registry" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Addresses - description: Get the list of all addresses holding a given asset

- `Note - Due to cardano's UTxO design and usage from projects, asset to addresses map can be infinite. Thus, for a small subset of active projects - with millions of transactions, these might end up with timeouts (HTTP code 504) on free layer. Such large-scale projects are free to subscribe to - query layers to have a dedicated cache table for themselves served via Koios.` - /asset_address_list: #RPC - get: + summary: Asset Token Registry + description: Get a list of assets registered via token registry on github + /asset_info: #RPC + post: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" + requestBody: + $ref: "#/components/requestBodies/asset_list" responses: "200": - description: Array of payment addresses holding the given token (including balances) + description: Array of detailed asset information content: application/json: schema: - $ref: "#/components/schemas/asset_addresses" + $ref: "#/components/schemas/asset_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Address List [DEPRECATED] - description: Get the list of all addresses holding a given asset (replaced by asset_addresses) - /asset_nft_address: #RPC - get: + summary: Asset Information (Bulk) + description: Get the information of a list of assets including first minting & token registry metadata + /asset_utxos: #RPC + post: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy_nft" - - $ref: "#/components/parameters/_asset_name_nft" + requestBody: + $ref: "#/components/requestBodies/asset_list_with_extended" responses: "200": - description: Payment addresses currently holding the given NFT + description: Array of UTXOs for given asset list content: application/json: schema: - $ref: "#/components/schemas/asset_nft_address" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: NFT Address - description: Get the address where specified NFT currently reside on. - /asset_info: #RPC + summary: Asset UTXOs + description: Get the UTXO information of a list of assets including + /asset_history: #RPC get: tags: - Asset @@ -899,61 +1007,66 @@ paths: - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed asset information + description: Array of asset mint/burn history content: application/json: schema: - $ref: "#/components/schemas/asset_info" + $ref: "#/components/schemas/asset_history" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Information - description: Get the information of an asset including first minting & token registry metadata - post: + summary: Asset History + description: Get the mint/burn history of an asset + /asset_addresses: #RPC + get: tags: - Asset - requestBody: - $ref: "#/components/requestBodies/asset_list" + parameters: + - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed asset information + description: Array of payment addresses holding the given token (including balances) content: application/json: schema: - $ref: "#/components/schemas/asset_info" + $ref: "#/components/schemas/asset_addresses" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Information (Bulk) - description: Get the information of a list of assets including first minting & token registry metadata - /asset_history: #RPC + summary: Asset Addresses + description: Get the list of all addresses holding a given asset

+ `Note - Due to cardano's UTxO design and usage from projects, asset to addresses map can be infinite. Thus, for a small subset of active projects + with millions of transactions, these might end up with timeouts (HTTP code 504) on free layer. Such large-scale projects are free to subscribe to + query layers to have a dedicated cache table for themselves served via Koios.` + /asset_nft_address: #RPC get: tags: - Asset parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" + - $ref: "#/components/parameters/_asset_policy_nft" + - $ref: "#/components/parameters/_asset_name_nft" responses: "200": - description: Array of asset mint/burn history + description: Payment addresses currently holding the given NFT content: application/json: schema: - $ref: "#/components/schemas/asset_history" + $ref: "#/components/schemas/asset_nft_address" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset History - description: Get the mint/burn history of an asset + summary: NFT Address + description: Get the address where specified NFT currently reside on. /policy_asset_addresses: #RPC get: tags: @@ -999,94 +1112,98 @@ paths: $ref: "#/components/responses/NotFound" summary: Policy Asset Information description: Get the information for all assets under the same policy - /asset_policy_info: #RPC + /asset_summary: #RPC get: tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed information of assets under the same policy + description: Array of asset summary information content: application/json: schema: - $ref: "#/components/schemas/policy_asset_info" + $ref: "#/components/schemas/asset_summary" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Policy Information [DEPRECATED] - description: Get the information for all assets under the same policy (replaced by asset_addresses) - /policy_asset_list: #RPC + summary: Asset Summary + description: Get the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance) + /asset_txs: #RPC get: tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" + - $ref: "#/components/parameters/_after_block_height" + - $ref: "#/components/parameters/_history" responses: "200": - description: Array of detailed information of assets under the same policy + description: An array of Tx hashes that included the given asset (latest first) content: application/json: schema: - $ref: "#/components/schemas/policy_asset_list" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Policy Asset List - description: Get the list of asset under the given policy (including balances) - /asset_summary: #RPC + summary: Asset Transactions + description: Get the list of current or all asset transaction hashes (newest first) + /asset_address_list: #RPC get: tags: - Asset + deprecated: true parameters: - $ref: "#/components/parameters/_asset_policy" - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of asset summary information + description: Array of payment addresses holding the given token (including balances) content: application/json: schema: - $ref: "#/components/schemas/asset_summary" + $ref: "#/components/schemas/asset_addresses" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Summary - description: Get the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance) - /asset_txs: #RPC + summary: Asset Address List + description: Get the list of all addresses holding a given asset [DEPRECATED - replaced by asset_addresses] + /asset_policy_info: #RPC get: + deprecated: true tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" - - $ref: "#/components/parameters/_after_block_height" - - $ref: "#/components/parameters/_history" responses: "200": - description: Array of Tx hashes that included the given asset + description: Array of detailed information of assets under the same policy content: application/json: schema: - $ref: "#/components/schemas/asset_txs" + $ref: "#/components/schemas/policy_asset_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Transactions - description: Get the list of current or all asset transaction hashes (newest first) + summary: Asset Policy Information + description: Get the information for all assets under the same policy (DEPRECATED - replaced by policy_asset_info) + /pool_list: #RPC get: tags: @@ -1105,7 +1222,7 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool List - description: A list of all currently registered/retiring (not retired) pools + description: List of brief info for all pools /pool_info: #RPC post: tags: @@ -1261,6 +1378,48 @@ paths: $ref: "#/components/responses/NotFound" summary: Pool Updates (History) description: Return all pool updates for all pools or only updates for specific pool if specified + /pool_registrations: #RPC + get: + tags: + - Pool + parameters: + - $ref: "#/components/parameters/_epoch_no" + responses: + "200": + description: Array of historical pool updates + content: + application/json: + schema: + $ref: "#/components/schemas/pool_registrations" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Pool Registrations + description: Return all pool registrations initiated in the requested epoch + /pool_retirements: #RPC + get: + tags: + - Pool + parameters: + - $ref: "#/components/parameters/_epoch_no" + responses: + "200": + description: Array of historical pool updates + content: + application/json: + schema: + $ref: "#/components/schemas/pool_registrations" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Pool Retirements + description: Return all pool retirements initiated in the requested epoch /pool_relays: #RPC get: tags: @@ -1279,7 +1438,7 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool Relays - description: A list of registered relays for all currently registered/retiring (not retired) pools + description: A list of registered relays for all pools /pool_metadata: #RPC post: tags: @@ -1300,7 +1459,29 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool Metadata - description: Metadata (on & off-chain) for all currently registered/retiring (not retired) pools + description: Metadata (on & off-chain) for all pools + + /script_info: #RPC + post: + tags: + - Script + requestBody: + $ref: "#/components/requestBodies/script_hashes" + responses: + "200": + description: List of datum information for given datum hashes + content: + application/json: + schema: + $ref: "#/components/schemas/script_info" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Datum Information + description: List of datum information for given datum hashes /native_script_list: #RPC get: tags: @@ -1311,7 +1492,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/native_script_list" + $ref: "#/components/schemas/script_list" "400": $ref: "#/components/responses/BadRequest" "401": @@ -1330,7 +1511,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/plutus_script_list" + $ref: "#/components/schemas/script_list" "400": $ref: "#/components/responses/BadRequest" "401": @@ -1360,6 +1541,28 @@ paths: $ref: "#/components/responses/NotFound" summary: Script Redeemers description: List of all redeemers for a given script hash + /script_utxos: #RPC + get: + tags: + - Script + parameters: + - $ref: "#/components/parameters/_script_hash" + - $ref: "#/components/parameters/_extended" + responses: + "200": + description: List of UTXOs for a given script hash + content: + application/json: + schema: + $ref: "#/components/schemas/utxo_infos" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Script UTXOs + description: List of all UTXOs for a given script hash /datum_info: #RPC post: tags: @@ -1381,6 +1584,43 @@ paths: $ref: "#/components/responses/NotFound" summary: Datum Information description: List of datum information for given datum hashes + /ogmios/?EvaluateTransaction: #ogmios-api + post: + tags: + - Ogmios + x-code-samples: + - lang: "Shell" + source: | + # Assuming ${data} contains EvaluateTransaction payload as documented on Ogmios v6 site. + curl -X POST \ + --header "Content-Type: application/cbor" \ + --data-binary ${data} https://api.koios.rest/api/ogmios/?EvaluateTransaction + responses: + "200": + description: OK + "400": + description: An error occured while submitting transaction. + summary: Evaluate Transaction + description: Evaluate execution units of scripts in a well-formed transaction. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?EvaluateTransaction) for complete spec + /ogmios/?SubmitTransaction: #ogmios-api + post: + tags: + - Ogmios + x-code-samples: + - lang: "Shell" + source: | + # Assuming ${data} contains a CBOR-serialized signed transaction (base16-encoded) as documented on Ogmios v6 site. + curl -X POST \ + --header "Content-Type: application/cbor" \ + --data-binary ${data} https://api.koios.rest/api/ogmios/?SubmitTransaction + responses: + "200": + description: OK + "400": + description: An error occured while querying transaction. + summary: Submit Transaction + description: Submit a signed and serialized transaction to the network. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?SubmitTransaction) for complete spec + components: parameters: select: @@ -1460,7 +1700,7 @@ components: description: Epoch Number to fetch details for schema: type: string - example: 1950 + example: 6219 in: query required: false allowEmptyValue: true @@ -1554,6 +1794,16 @@ components: in: query required: false allowEmptyValue: true + _extended: + deprecated: false + name: _extended + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + schema: + type: boolean + example: "false" + in: query + required: false + allowEmptyValue: true _history: deprecated: false name: _history @@ -1600,7 +1850,7 @@ components: description: Script hash in hexadecimal format (hex) schema: type: string - example: 160301a01ee86d8e46cbe3aef1e3bf69bfa28c65d5be2dde56a37af8 + example: 1392eec7d575292ae1523da65ff1b4b021886e917c8c43de54aa7cbd in: query required: true allowEmptyValue: false @@ -1661,6 +1911,29 @@ components: _addresses: - addr_test1qzmtfv43a8ncx6ve92ja6yy25npn9raz9pu5a2tfxsqv9gy9ktf0pu6yu4zjh9r37fzx3h4tsxqdjhu3t4d5ffdsfz9s6ska3z - addr_test1vq67g5u8ls4vm4wdvs0r8xvsuej66nvaqedyrj2tcz6tuycz275pu + payment_addresses_with_extended: + content: + application/json: + schema: + required: + - _addresses + type: object + properties: + _addresses: + format: text + type: array + items: + type: string + description: Array of Cardano payment address(es) in bech32 format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _addresses: + - addr_test1qzmtfv43a8ncx6ve92ja6yy25npn9raz9pu5a2tfxsqv9gy9ktf0pu6yu4zjh9r37fzx3h4tsxqdjhu3t4d5ffdsfz9s6ska3z + - addr_test1vq67g5u8ls4vm4wdvs0r8xvsuej66nvaqedyrj2tcz6tuycz275pu + _extended: true address_txs: content: application/json: @@ -1733,6 +2006,32 @@ components: _stake_addresses: - stake_test17zt9x005zkd2usz2vhvktyzqsuwz25gmgnaqdka5hcj9m2qfg2py2 - stake_test1uzzm95hs7dzw23ftj3cly3rgm64crqxet7g46k6y5kcy3zcs3mpjd + _first_only: false + _empty: false + + stake_addresses_with_extended: + content: + application/json: + schema: + required: + - _stake_addresses + type: object + properties: + _stake_addresses: + format: text + type: array + items: + type: string + description: Array of Cardano stake address(es) in bech32 format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _stake_addresses: + - stake_test17zt9x005zkd2usz2vhvktyzqsuwz25gmgnaqdka5hcj9m2qfg2py2 + - stake_test1uzzm95hs7dzw23ftj3cly3rgm64crqxet7g46k6y5kcy3zcs3mpjd + _extended: true stake_addresses: content: application/json: @@ -1788,10 +2087,15 @@ components: items: type: string description: Array of Cardano payment credential(s) in hex format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call example: _payment_credentials: - b6b4b2b1e9e78369992aa5dd108aa4c3328fa228794ea9693400c2a0 - 35e45387fc2acdd5cd641e339990e665ad4d9d065a41c94bc0b4be13 + _extended: true tx_ids: content: application/json: @@ -1853,6 +2157,22 @@ components: - pool19st4a2vvu78tjtyywjte2eml3kx6ynersgd2nyw0y4jvyhlfu0u - pool1uul8pytp2p0xq4ckjn3l294km0m7fuef46teehvh3x5tk46sfx3 - pool1us9ww725p0vygae5zaydme3apt7wg9se2yemhl8mgwkes3tlrqp + script_hashes: + content: + application/json: + schema: + type: object + properties: + _script_hashes: + format: text + type: array + items: + type: string + description: Array of Cardano script hashes + example: + _script_hashes: + - a08a267e92456ba48e157dd7e77bdd35aba0fc50fe625a10a6a7fc5e + - 1f3a4aa08cfa0e47fff200578f0d4847b6890b7093a765773feb35de datum_hashes: content: application/json: @@ -1866,10 +2186,30 @@ components: type: string description: Array of Cardano datum hashes example: - _datum_hashes: - - 964af1ff2a66ce472d34ac39b47f356b6d971d62c794a89ec12825d5de30f3aa - - 17bdb9c96b77c7718d546be50193a80bc9d72081b7375e5e16891db196af14fc - asset_list: + _datum_hashes: + - 964af1ff2a66ce472d34ac39b47f356b6d971d62c794a89ec12825d5de30f3aa + - 17bdb9c96b77c7718d546be50193a80bc9d72081b7375e5e16891db196af14fc + asset_list: + content: + application/json: + schema: + required: + - _asset_list + type: object + properties: + _asset_list: + format: text + type: array + description: Array of array of policy ID and asset names (hex) + items: + type: array + items: + type: string + example: + _asset_list: + - ['313534a537bc476c86ff7c57ec511bd7f24a9d15654091b24e9c606e','41484c636f696e'] + - ['313534a537bc476c86ff7c57ec511bd7f24a9d15654091b24e9c606e','41484c636f696e'] + asset_list_with_extended: content: application/json: schema: @@ -1885,11 +2225,43 @@ components: type: array items: type: string + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call example: _asset_list: - ['313534a537bc476c86ff7c57ec511bd7f24a9d15654091b24e9c606e','41484c636f696e'] - ['313534a537bc476c86ff7c57ec511bd7f24a9d15654091b24e9c606e','41484c636f696e'] - securitySchemes: {} + _extended: true + utxo_refs_with_extended: + content: + application/json: + schema: + required: + - _utxo_refs + type: object + properties: + _utxo_refs: + format: text + type: array + items: + type: string + description: Array of Cardano utxo references in the form "hash#index" + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _utxo_refs: + - f82e568d42604fd71424d193c86ec00c97aead2b8f018e81c3139d9e3770c735#0 + - 88ae22495123c7ee37a0bbe865243757185a302ed5359d1eae9347030628290a#0 + _extended: false + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT schemas: tip: type: array @@ -2003,20 +2375,59 @@ components: type: string description: JSON encoded data with details about the parameter update example: {"decentralisation": 0.9} + reserve_withdrawals: + type: array + items: + properties: + epoch_no: + $ref: "#/components/schemas/epoch_info/items/properties/epoch_no" + epoch_slot: + $ref: "#/components/schemas/blocks/items/properties/epoch_slot" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + block_hash: + $ref: "#/components/schemas/blocks/items/properties/hash" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + amount: + $ref: "#/components/schemas/pool_delegators/items/properties/amount" + stake_address: + $ref: "#/components/schemas/account_history/items/properties/stake_address" pool_list: type: array items: properties: pool_id_bech32: - type: string - nullable: true - description: Bech32 representation of pool ID - example: pool1z5uqdk7dzdxaae5633fqfcu2eqzy3a3rgtuvy087fdld7yws0xt + $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" + pool_id_hex: + $ref: "#/components/schemas/pool_info/items/properties/pool_id_hex" + active_epoch_no: + $ref: "#/components/schemas/pool_info/items/properties/active_epoch_no" + margin: + $ref: "#/components/schemas/pool_info/items/properties/margin" + fixed_cost: + $ref: "#/components/schemas/pool_info/items/properties/fixed_cost" + pledge: + $ref: "#/components/schemas/pool_info/items/properties/pledge" + reward_addr: + $ref: "#/components/schemas/pool_info/items/properties/reward_addr" + owners: + $ref: "#/components/schemas/pool_info/items/properties/margin" + relays: + $ref: "#/components/schemas/pool_info/items/properties/margin" ticker: type: string nullable: true description: Pool ticker - example: JAZZ + example: AHL + meta_url: + $ref: "#/components/schemas/pool_info/items/properties/margin" + meta_hash: + $ref: "#/components/schemas/pool_info/items/properties/margin" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/margin" + retiring_epoch: + $ref: "#/components/schemas/pool_info/items/properties/margin" pool_history_info: type: array items: @@ -2088,26 +2499,32 @@ components: $ref: "#/components/schemas/pool_updates/items/properties/active_epoch_no" vrf_key_hash: type: string + nullable: true description: Pool VRF key hash example: 25efdad1bc12944d38e4e3c26c43565bec84973a812737b163b289e87d0d5ed3 margin: type: number + nullable: true description: Margin (decimal format) example: 0.1 fixed_cost: type: string + nullable: true description: Pool fixed cost per epoch example: "500000000" pledge: type: string + nullable: true description: Pool pledge in lovelace example: "64000000000000" reward_addr: type: string + nullable: true description: Pool reward address example: stake1uy6yzwsxxc28lfms0qmpxvyz9a7y770rtcqx9y96m42cttqwvp4m5 owners: type: array + nullable: true items: type: string description: Pool (co)owner address @@ -2270,6 +2687,26 @@ components: type: string description: Latest transaction hash used for delegation by the account example: 368d08fe86804d637649341d3aec4a9baa7dffa6d00f16de2ba9dba814f1c948 + pool_registrations: + type: array + nullable: true + items: + type: object + properties: + pool_id_bech32: + $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + block_hash: + $ref: "#/components/schemas/blocks/items/properties/hash" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + epoch_no: + $ref: "#/components/schemas/epoch_info/items/properties/epoch_no" + epoch_slot: + $ref: "#/components/schemas/blocks/items/properties/epoch_slot" + active_epoch_no: + $ref: "#/components/schemas/pool_updates/items/properties/active_epoch_no" pool_delegators_history: type: array nullable: true @@ -2318,6 +2755,7 @@ components: active_epoch_no: type: integer description: Epoch number in which the update becomes active + nullable: true example: 324 vrf_key_hash: $ref: "#/components/schemas/pool_info/items/properties/vrf_key_hash" @@ -2339,8 +2777,11 @@ components: $ref: "#/components/schemas/pool_info/items/properties/meta_hash" meta_json: $ref: "#/components/schemas/pool_info/items/properties/meta_json" - pool_status: - $ref: "#/components/schemas/pool_info/items/properties/pool_status" + update_type: + type: string + description: Type of update task + enum: ["registration", "deregistration"] + example: registered retiring_epoch: $ref: "#/components/schemas/pool_info/items/properties/retiring_epoch" pool_relays: @@ -2352,6 +2793,8 @@ components: $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" relays: $ref: "#/components/schemas/pool_info/items/properties/relays" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/pool_status" pool_metadata: type: array items: @@ -2365,6 +2808,8 @@ components: $ref: "#/components/schemas/pool_info/items/properties/meta_hash" meta_json: $ref: "#/components/schemas/pool_info/items/properties/meta_json" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/pool_status" epoch_info: type: array items: @@ -2533,8 +2978,8 @@ components: description: The hash of the first block where these parameters are valid example: f9dc2a2fc3a2db09a71af007a740261de585afc9e3022b8e30535592ff4dd9e5 cost_models: - type: string - description: The per language cost models + type: object + description: The per language cost model in JSON example: null nullable: true price_mem: @@ -2724,17 +3169,21 @@ components: properties: block_hash: $ref: "#/components/schemas/blocks/items/properties/hash" - tx_hashes: - type: array - items: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + epoch_no: + $ref: "#/components/schemas/blocks/items/properties/epoch_no" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + block_time: + $ref: "#/components/schemas/blocks/items/properties/block_time" address_info: type: array items: type: object properties: address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" balance: type: string description: Sum of all UTxO values beloning to address @@ -2753,9 +3202,9 @@ components: type: object properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" block_height: $ref: "#/components/schemas/blocks/items/properties/block_height" block_time: @@ -2769,7 +3218,7 @@ components: reference_script: $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/reference_script" asset_list: - $ref: "#/components/schemas/account_assets/items/properties/asset_list" + $ref: "#/components/schemas/utxo_infos/items/properties/asset_list" address_txs: type: array items: @@ -2789,22 +3238,17 @@ components: type: object properties: address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" - asset_list: - $ref: "#/components/schemas/account_assets/items/properties/asset_list" - credential_txs: - $ref: "#/components/schemas/address_txs" - credential_utxos: - type: array - items: - type: object - properties: - tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" - tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" - value: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value" + $ref: "#/components/schemas/utxo_infos/items/properties/address" + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + $ref: "#/components/schemas/asset_addresses/items/properties/quantity" account_list: type: array items: @@ -2825,7 +3269,9 @@ components: enum: ["registered", "not registered"] example: registered delegated_pool: - $ref: "#/components/schemas/pool_list/items/properties/pool_id_bech32" + nullable: true + allOf: + - $ref: "#/components/schemas/pool_list/items/properties/pool_id_bech32" total_balance: type: string description: Total balance of the account including UTxO, rewards and MIRs (in lovelace) @@ -2854,23 +3300,67 @@ components: type: string description: Total treasury MIR value of the account example: "0" - account_utxos: + utxo_infos: type: array items: type: object properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" + type: string + description: Hash identifier of the transaction + example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" + type: integer + description: Index of UTxO in the transaction + example: 0 address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + type: string + description: A Cardano payment/base address (bech32 encoded) + example: addr1qxkfe8s6m8qt5436lec3f0320hrmpppwqgs2gah4360krvyssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqdc3cxp value: $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value" + stake_address: + $ref: "#/components/schemas/address_info/items/properties/stake_address" + payment_cred: + type: string + description: Payment credential + example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 + nullable: true + epoch_no: + $ref: "#/components/schemas/blocks/items/properties/epoch_no" block_height: $ref: "#/components/schemas/blocks/items/properties/block_height" block_time: $ref: "#/components/schemas/blocks/items/properties/block_time" + datum_hash: + $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_hash" + inline_datum: + $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/inline_datum" + reference_script: + $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/reference_script" + asset_list: + type: array + nullable: true + description: An array of assets on the UTxO + items: + properties: + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + type: string + description: Quantity of assets on the UTxO + example: 1 + is_spent: + type: boolean + description: True if the UTXO has been spent + example: true + account_rewards: type: array items: @@ -2915,7 +3405,7 @@ components: enum: ["registration", "delegation", "withdrawal", "deregistration"] example: "registration" tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" epoch_no: $ref: "#/components/schemas/blocks/items/properties/epoch_no" epoch_slot: @@ -2934,7 +3424,7 @@ components: addresses: type: array items: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" account_assets: type: array items: @@ -2942,25 +3432,16 @@ components: properties: stake_address: $ref: "#/components/schemas/account_history/items/properties/stake_address" - asset_list: - type: array - items: - type: object - properties: - policy_id: - $ref: "#/components/schemas/asset_info/items/properties/policy_id" - asset_name: - $ref: "#/components/schemas/asset_info/items/properties/asset_name" - fingerprint: - $ref: "#/components/schemas/asset_info/items/properties/fingerprint" - decimals: - type: integer - description: Asset decimals - example: 6 - quantity: - type: string - description: Asset quantity owned by account - example: 990000 + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + $ref: "#/components/schemas/asset_addresses/items/properties/quantity" account_history: type: array items: @@ -2992,9 +3473,7 @@ components: type: object properties: tx_hash: - type: string - description: Hash identifier of the transaction - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" block_hash: $ref: "#/components/schemas/blocks/items/properties/hash" block_height: @@ -3061,25 +3540,17 @@ components: type: object properties: bech32: - type: string - description: A Cardano payment/base address (bech32 encoded) where funds were sent or change to be returned - example: addr1q80rc8zj06yzdwwdyqc03rm4l3zv6n89rxuaak0t099n09yssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqad9mkw + $ref: "#/components/schemas/utxo_infos/items/properties/address" cred: type: string description: Payment credential example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 stake_addr: - nullable: true - allOf: - - $ref: "#/components/schemas/account_history/items/properties/stake_address" + $ref: "#/components/schemas/address_info/items/properties/stake_address" tx_hash: - type: string - description: Hash of transaction for UTxO - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: Index of UTxO in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" value: type: string description: Total sum of ADA on the UTxO @@ -3129,23 +3600,7 @@ components: description: Value (json) example: null asset_list: - type: array - nullable: true - description: An array of assets on the UTxO - items: - properties: - policy_id: - $ref: "#/components/schemas/asset_info/items/properties/policy_id" - asset_name: - $ref: "#/components/schemas/asset_info/items/properties/asset_name" - fingerprint: - $ref: "#/components/schemas/asset_info/items/properties/fingerprint" - decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" - quantity: - type: string - description: Quantity of assets on the UTxO - example: 1 + $ref: "#/components/schemas/utxo_infos/items/properties/asset_list" withdrawals: type: array description: Array of withdrawals with-in a transaction @@ -3174,7 +3629,7 @@ components: fingerprint: $ref: "#/components/schemas/asset_info/items/properties/fingerprint" decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" quantity: type: string description: Quantity of minted assets (negative on burn) @@ -3212,7 +3667,7 @@ components: items: properties: script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + $ref: "#/components/schemas/script_info/items/properties/script_hash" script_json: type: object description: JSON representation of the timelock script (null for other script types) @@ -3237,6 +3692,7 @@ components: } plutus_contracts: type: array + nullable: true description: Plutus contracts present in transaction (if any) items: properties: @@ -3246,15 +3702,11 @@ components: example: addr1w999n67e86jn6xal07pzxtrmqynspgx0fwmcmpua4wc6yzsxpljz3 nullable: true script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + $ref: "#/components/schemas/script_info/items/properties/script_hash" bytecode: - type: string - description: CBOR-encoded Plutus script data - example: 5911ea010000332333222332233223322332232323332223233322232333333332222222232333222323333222232323322323332223233322232323322332232323333322222332233223322332233223322223223223232533530333330083333573466e1cd55cea8032400046460a000264646464646666ae68cdc39aab9d5004480008cccc8888cccc16c01000c008004dd71aba15004375c6ae85400cdd71aba15002375a6ae84d5d1280111a8279a982819ab9c491035054310005149926135744a00226ae8940044d55cf280089baa001357426aae79401c8d4124d4c128cd5ce2481035054310004b499263333573466e1d40112002205323333573466e1d40152000205523504a35304b335738921035054310004c49926498cccd5cd19b8735573aa004900011980599191919191919191919191999ab9a3370e6aae754029200023333333333019335027232323333573466e1cd55cea8012400046603e60746ae854008c0b0d5d09aba2500223505935305a3357389201035054310005b49926135573ca00226ea8004d5d0a80519a8138141aba150093335502e75ca05a6ae854020ccd540b9d728169aba1500733502704335742a00c66a04e66aa0a8098eb4d5d0a8029919191999ab9a3370e6aae754009200023350213232323333573466e1cd55cea80124000466a05266a084eb4d5d0a80118239aba135744a00446a0ba6a60bc66ae712401035054310005f49926135573ca00226ea8004d5d0a8011919191999ab9a3370e6aae7540092000233502733504275a6ae854008c11cd5d09aba2500223505d35305e3357389201035054310005f49926135573ca00226ea8004d5d09aba2500223505935305a3357389201035054310005b49926135573ca00226ea8004d5d0a80219a813bae35742a00666a04e66aa0a8eb88004d5d0a801181c9aba135744a00446a0aa6a60ac66ae71241035054310005749926135744a00226ae8940044d5d1280089aba25001135744a00226ae8940044d5d1280089aba25001135573ca00226ea8004d5d0a8011919191999ab9a3370ea00290031180f181d9aba135573ca00646666ae68cdc3a801240084603a608a6ae84d55cf280211999ab9a3370ea00690011180e98181aba135573ca00a46666ae68cdc3a80224000460406eb8d5d09aab9e50062350503530513357389201035054310005249926499264984d55cea80089baa001357426ae8940088d4124d4c128cd5ce249035054310004b49926104a1350483530493357389201035054350004a4984d55cf280089baa001135573a6ea80044dd50009109198008018011000911111111109199999999980080580500480400380300280200180110009109198008018011000891091980080180109000891091980080180109000891091980080180109000909111180200290911118018029091111801002909111180080290008919118011bac0013200135503b2233335573e0024a01c466a01a60086ae84008c00cd5d100101991919191999ab9a3370e6aae75400d200023330073232323333573466e1cd55cea8012400046601a60626ae854008cd404c0b4d5d09aba25002235036353037335738921035054310003849926135573ca00226ea8004d5d0a801999aa805bae500a35742a00466a01eeb8d5d09aba25002235032353033335738921035054310003449926135744a00226aae7940044dd50009110919980080200180110009109198008018011000899aa800bae75a224464460046eac004c8004d540d488c8cccd55cf80112804919a80419aa81898031aab9d5002300535573ca00460086ae8800c0b84d5d08008891001091091198008020018900089119191999ab9a3370ea002900011a80418029aba135573ca00646666ae68cdc3a801240044a01046a0526a605466ae712401035054310002b499264984d55cea80089baa001121223002003112200112001232323333573466e1cd55cea8012400046600c600e6ae854008dd69aba135744a00446a0466a604866ae71241035054310002549926135573ca00226ea80048848cc00400c00880048c8cccd5cd19b8735573aa002900011bae357426aae7940088d407cd4c080cd5ce24810350543100021499261375400224464646666ae68cdc3a800a40084a00e46666ae68cdc3a8012400446a014600c6ae84d55cf280211999ab9a3370ea00690001280511a8111a981199ab9c490103505431000244992649926135573aa00226ea8004484888c00c0104488800844888004480048c8cccd5cd19b8750014800880188cccd5cd19b8750024800080188d4068d4c06ccd5ce249035054310001c499264984d55ce9baa0011220021220012001232323232323333573466e1d4005200c200b23333573466e1d4009200a200d23333573466e1d400d200823300b375c6ae854014dd69aba135744a00a46666ae68cdc3a8022400c46601a6eb8d5d0a8039bae357426ae89401c8cccd5cd19b875005480108cc048c050d5d0a8049bae357426ae8940248cccd5cd19b875006480088c050c054d5d09aab9e500b23333573466e1d401d2000230133016357426aae7940308d407cd4c080cd5ce2481035054310002149926499264992649926135573aa00826aae79400c4d55cf280109aab9e500113754002424444444600e01044244444446600c012010424444444600a010244444440082444444400644244444446600401201044244444446600201201040024646464646666ae68cdc3a800a400446660106eb4d5d0a8021bad35742a0066eb4d5d09aba2500323333573466e1d400920002300a300b357426aae7940188d4040d4c044cd5ce2490350543100012499264984d55cea80189aba25001135573ca00226ea80048488c00800c888488ccc00401401000c80048c8c8cccd5cd19b875001480088c018dd71aba135573ca00646666ae68cdc3a80124000460106eb8d5d09aab9e500423500a35300b3357389201035054310000c499264984d55cea80089baa001212230020032122300100320011122232323333573466e1cd55cea80124000466aa016600c6ae854008c014d5d09aba25002235007353008335738921035054310000949926135573ca00226ea8004498480048004448848cc00400c008448004848c0040088004888848cccc00401401000c00880044880084880048004448c8c00400488cc00cc008008004c8ccc888c8c8cc88cc88ccc888c8c8c8c8cc88c8c8cc88c8cccc8888c8c8c8c8c8c8c8c8ccc888c8ccc888ccc888cccccccc88888888cc88ccccc88888cccc8888cc88cc88cc88ccc888cc88cc88cc88cc88cc88c8c8c8cc88c8c8c8c8c8c8cc88c8c8c8c8c8c8cc888c888c8c94cd4c1240104cc0352401297369676e617475726520646f6573206e6f74206d617463682063726561746f7220696e20646174756d0033223530200022222222222533535032333553068120015027253353079333573466e3c0300041ec1e84d40d4004540d000c841ec41e54008c04540144cc054cc03524012f65787065637465642063726561746f7220746f2067657420616c6c206f66207768617420736865206f72646572656400330153350133335500e305c12001504f350481223335501b2253353070333505006353353502a3235302900122335304c0022350300012502f300e00221001132635300b335738920117696e76616c6964207075626c6963206b657920686173680000c498c05540244cc010c0340080044004004c8d4c08400488888888880254010ccd41354138c1894014c04920c08db7013350133335500e305c12001504f350481223335501b22533530703005002133004335506500d30100020011001001300d5004333504d504e30625005333504d504e533535026301a00321300a300d0011630124830236dc04cc0352401276f6e6c79206d617463686573206f66207061697273206f66206f726465727320616c6c6f77656400533535063350481223335501b225335307030050021330040020011001001300d50041306a162215335350650011306c16221533535067001107222130701623253353502732353024001222001500121333504e223530280022235302a0032232335304e0052335304f004253353077333573466e3c0080041e41e05400c41e081e08cd4c13c01081e094cd4c1dcccd5cd19b8f002001079078150031078153353502e0032153353502f00221335304c0022335304d002233530510022335305200223306d002001207b23353052002207b23306d00200122207b222335304f004207b2225335307c333573466e1c01800c1f81f454cd4c1f0ccd5cd19b8700500207e07d1333573466e1c0100041f81f441f441f441d854cd4d40b8004841d841d8c03140094cd4d40a0c07001484cd54190034c03c0045841b84c0300044d4c068004880084d4c02800480044800480048d4c0680048880088d4c06400488800c8d4c05000488888888880288d4c05400488004894cd4c184004418c4cd5ce001031089119aa8011a82600090009091800801100091a982c0009111002119a82999aa82b245003350533355056489000015054505412233355304b120013500550032353550560012233355304e120013500850062353550590012233353550490012330614800000488cc1880080048cc184005200000133040002001133500400105a22533530590021001105a123350492233353500400322002002001353500200122001122123300100300212001112232001320013550582253353504e00110032213300600230040012353003001223530070022222222222533335302600b21501b21501b21501b2133355305012001500f2353015001225335306353353063333573466e3cd4c0bc00888008d4c0bc010880081941904ccd5cd19b8735302f0022200135302f00422001065064106413501f0031501e00b13350432253353500d002210031001500c2212330010030022001222222222212333333333300100b00a009008007006005004003002200122123300100300220012221233300100400300220012212330010030022001121223002003112200112001122123300100300212001122123300100300212001122123300100300212001121222300300411222002112220011200121222230040052122223003005212222300200521222230010052001221233001003002200121222222230070082212222222330060090082122222223005008122222220041222222200322122222223300200900822122222223300100900820012122300200322212233300100500400320012122300200321223001003200112335001501d501e1220021220012001120011200113002012133500b2233300301300200150162223355300e1200123535501a00122335501d002335530111200123535501d001223355020002333535500d00123300a4800000488cc02c0080048cc028005200000133004002001223355300c1200123535501800122335501b00233353550080012335530101200123535501c00122335501f00235500f001001223335550080150020012335530101200123535501c00122335501f00235500d0010013335550030100020011112223335530041200150153355300c1200123535501800122335501b00235500b0013335530041200122353550190022253353021333553011120013500d33500f22533530230021025100102223535501c001223300a0020050061003133501900400350160013355300c120012353550180012232335501c00330010053200135502322533535019001135500b0032213535501e00222533530263300c00200813355010007001130060030023200135501c221122253353501500110022213300500233355300712001005004001112122230030041122122233002005004112122230010041120011233500722333535004003220020020013535002001220011221233001003002120013200135501422112253353500c0011500e22133500f3004002335530061200100400132001355013221122253353500c00113535006003220012213335350080052200230040023335530071200100500400112212330010030021200122333573466e3c00800404404088cdc000100088911801000919991119a80319aa80480199a80319aa804801000a803a8039a980380091110019a980380091110011a98038009111000889100109109119800802001890008891091980080180108900091110919998008028020018011000900211199ab9a3371000400200800a244004244002400222464600200244660066004004003 + $ref: "#/components/schemas/script_info/items/properties/bytes" size: - type: integer - description: The size of the CBOR serialised script (in bytes) - example: 234895 + $ref: "#/components/schemas/script_info/items/properties/size" valid_contract: type: boolean description: True if the contract is valid or there is no contract @@ -3314,17 +3766,11 @@ components: description: Payment credential example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 stake_addr: - nullable: true - allOf: - - $ref: "#/components/schemas/account_history/items/properties/stake_address" + $ref: "#/components/schemas/address_info/items/properties/stake_address" tx_hash: - type: string - description: Hash of transaction for UTxO - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: Index of UTxO in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" value: type: string description: Total sum of ADA on the UTxO @@ -3339,7 +3785,7 @@ components: items: properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" metadata: type: object nullable: true @@ -3360,7 +3806,7 @@ components: items: properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" num_confirmations: type: integer description: Number of block confirmations @@ -3414,9 +3860,7 @@ components: items: properties: payment_address: - type: string - description: A Cardano payment/base address (bech32 encoded) for transaction's input UTxO - example: addr1qxkfe8s6m8qt5436lec3f0320hrmpppwqgs2gah4360krvyssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqdc3cxp + $ref: "#/components/schemas/utxo_infos/items/properties/address" quantity: type: string description: Asset balance on the payment address @@ -3427,7 +3871,7 @@ components: items: properties: payment_address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" asset_summary: type: array items: @@ -3519,6 +3963,11 @@ components: decimals: type: integer example: 0 + cip68_metadata: + type: object + description: CIP 68 metadata if present for asset + nullable: true + example: {"222": {"fields": [{"map": [{"k": {"bytes": "6e616d65"}, "v": {"bytes": "74657374"}}]}], "constructor": 0}} asset_history: type: array items: @@ -3559,7 +4008,7 @@ components: asset_name: $ref: "#/components/schemas/asset_info/items/properties/asset_name" payment_address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" quantity: $ref: "#/components/schemas/asset_addresses/items/properties/quantity" policy_asset_info: @@ -3599,67 +4048,65 @@ components: total_supply: $ref: "#/components/schemas/asset_info/items/properties/total_supply" decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" - asset_txs: - type: array - description: An array of Tx hashes that included the given asset (latest first) - items: - properties: - tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" - epoch_no: - $ref: "#/components/schemas/blocks/items/properties/epoch_no" - block_height: - $ref: "#/components/schemas/blocks/items/properties/block_height" - block_time: - $ref: "#/components/schemas/blocks/items/properties/block_time" - native_script_list: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + script_info: type: array items: properties: script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + type: string + description: Hash of a script + example: bfa7ffa9b2e164873db6ac6d0528c82e212963bc62e10fd1d81da4af creation_tx_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/creation_tx_hash" + type: string + description: Hash of the script creation transaction + example: 255f061502ad83230351fbcf2d9fade1b5d118d332f92c9861075010a1fe3fbe type: type: string description: Type of the script - enum: ["timelock", "multisig"] - example: timelock - plutus_script_list: + enum: ["plutusV1","plutusV2","timelock","multisig"] + example: plutusV1 + value: + type: object + nullable: true + description: Data in JSON format + example: null + bytes: + type: string + description: Script bytes (cborSeq) + example: 5907f4010000332323232323232323233223232323232332232323232322223232533532533533355300712001323212330012233350052200200200100235001220011233001225335002101710010142325335333573466e3cd400488008d4020880080580544ccd5cd19b873500122001350082200101601510153500122002353500122002222222222200a101413357389201115554784f206e6f7420636f6e73756d6564000133333573466e1cd55cea8012400046644246600200600464646464646464646464646666ae68cdc39aab9d500a480008cccccccccc888888888848cccccccccc00402c02802402001c01801401000c008cd40508c8c8cccd5cd19b8735573aa0049000119910919800801801180f9aba150023019357426ae8940088c98d4cd5ce01581501481409aab9e5001137540026ae854028cd4050054d5d0a804999aa80bbae501635742a010666aa02eeb94058d5d0a80399a80a0109aba15006335014335502402275a6ae854014c8c8c8cccd5cd19b8735573aa00490001199109198008018011919191999ab9a3370e6aae754009200023322123300100300233502575a6ae854008c098d5d09aba2500223263533573805e05c05a05826aae7940044dd50009aba150023232323333573466e1cd55cea8012400046644246600200600466a04aeb4d5d0a80118131aba135744a004464c6a66ae700bc0b80b40b04d55cf280089baa001357426ae8940088c98d4cd5ce01581501481409aab9e5001137540026ae854010cd4051d71aba15003335014335502475c40026ae854008c070d5d09aba2500223263533573804e04c04a04826ae8940044d5d1280089aba25001135744a00226ae8940044d5d1280089aba25001135744a00226aae7940044dd50009aba150023232323333573466e1d400520062321222230040053019357426aae79400c8cccd5cd19b875002480108c848888c008014c06cd5d09aab9e500423333573466e1d400d20022321222230010053015357426aae7940148cccd5cd19b875004480008c848888c00c014dd71aba135573ca00c464c6a66ae7008808408007c0780740704d55cea80089baa001357426ae8940088c98d4cd5ce00d80d00c80c080c89931a99ab9c4910350543500019018135573ca00226ea8004c8004d5405888448894cd40044d400c88004884ccd401488008c010008ccd54c01c4800401401000448c88c008dd6000990009aa80b111999aab9f00125009233500830043574200460066ae880080548c8c8c8cccd5cd19b8735573aa00690001199911091998008020018011919191999ab9a3370e6aae7540092000233221233001003002301735742a00466a01c02c6ae84d5d1280111931a99ab9c01b01a019018135573ca00226ea8004d5d0a801999aa803bae500635742a00466a014eb8d5d09aba2500223263533573802e02c02a02826ae8940044d55cf280089baa0011335500175ceb44488c88c008dd5800990009aa80a11191999aab9f0022500823350073355017300635573aa004600a6aae794008c010d5d100180a09aba100111220021221223300100400312232323333573466e1d4005200023212230020033005357426aae79400c8cccd5cd19b8750024800884880048c98d4cd5ce00980900880800789aab9d500113754002464646666ae68cdc39aab9d5002480008cc8848cc00400c008c014d5d0a8011bad357426ae8940088c98d4cd5ce00800780700689aab9e5001137540024646666ae68cdc39aab9d5001480008dd71aba135573ca004464c6a66ae7003803403002c4dd500089119191999ab9a3370ea00290021091100091999ab9a3370ea00490011190911180180218031aba135573ca00846666ae68cdc3a801a400042444004464c6a66ae7004404003c0380340304d55cea80089baa0012323333573466e1d40052002200523333573466e1d40092000200523263533573801a01801601401226aae74dd5000891001091000919191919191999ab9a3370ea002900610911111100191999ab9a3370ea004900510911111100211999ab9a3370ea00690041199109111111198008048041bae35742a00a6eb4d5d09aba2500523333573466e1d40112006233221222222233002009008375c6ae85401cdd71aba135744a00e46666ae68cdc3a802a400846644244444446600c01201060186ae854024dd71aba135744a01246666ae68cdc3a8032400446424444444600e010601a6ae84d55cf280591999ab9a3370ea00e900011909111111180280418071aba135573ca018464c6a66ae7004c04804404003c03803403002c0284d55cea80209aab9e5003135573ca00426aae7940044dd50009191919191999ab9a3370ea002900111999110911998008028020019bad35742a0086eb4d5d0a8019bad357426ae89400c8cccd5cd19b875002480008c8488c00800cc020d5d09aab9e500623263533573801801601401201026aae75400c4d5d1280089aab9e500113754002464646666ae68cdc3a800a400446424460020066eb8d5d09aab9e500323333573466e1d400920002321223002003375c6ae84d55cf280211931a99ab9c009008007006005135573aa00226ea800444888c8c8cccd5cd19b8735573aa0049000119aa80518031aba150023005357426ae8940088c98d4cd5ce00480400380309aab9e5001137540029309000a490350543100112212330010030021123230010012233003300200200133512233002489209366f09fe40eaaeb17d3cb6b0b61e087d664174c39a48a986f86b2b0ba6e2a7b00480008848cc00400c0088005 + size: + type: integer + description: The size of the CBOR serialised script (in bytes) + example: 2039 + script_list: type: array items: properties: script_hash: - type: string - description: Hash of a script - example: d8480dc869b94b80e81ec91b0abe307279311fe0e7001a9488f61ff8 + $ref: "#/components/schemas/script_info/items/properties/script_hash" creation_tx_hash: - type: string - description: Hash of the script creation transaction - example: fda6c7697009237975ffc30f36666addf4c6e2a2c6f90411a24431b700baaab1 + $ref: "#/components/schemas/script_info/items/properties/creation_tx_hash" + type: + $ref: "#/components/schemas/script_info/items/properties/type" + size: + $ref: "#/components/schemas/script_info/items/properties/size" script_redeemers: type: array items: type: object properties: script_hash: - type: string - description: Hash of Transaction for which details are being shown - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/script_info/items/properties/script_hash" redeemers: type: array items: type: object properties: tx_hash: - type: string - description: Hash of Transaction containing the redeemer - example: fda6c7697009237975ffc30f36666addf4c6e2a2c6f90411a24431b700baaab1 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: The index of the redeemer pointer in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" unit_mem: description: The budget in Memory to run a script example: 520448 @@ -3691,20 +4138,20 @@ components: nullable: true example: 5a595ce795815e81d22a1a522cf3987d546dc5bb016de61b002edd63a5413ec4 datum_value: - type: object - description: The actual data in json format - example: { "bytes": "3c33" } + $ref: "#/components/schemas/script_info/items/properties/value" datum_info: type: array items: type: object properties: - hash: + datum_hash: $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_hash" + creation_tx_hash: + $ref: "#/components/schemas/script_info/items/properties/creation_tx_hash" value: - $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_value" + $ref: "#/components/schemas/script_info/items/properties/value" bytes: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/inline_datum/properties/bytes" + $ref: "#/components/schemas/script_info/items/properties/bytes" headers: {} responses: OK: @@ -3712,7 +4159,7 @@ components: NotFound: description: The server does not recognise the combination of endpoint and parameters provided Unauthorized: - description: The selected server has restricted the endpoint to be only usable via authentication. The authentication supplied was not authorized to access the endpoint + description: Access token is missing or invalid PartialContent: description: The result was truncated BadRequest: @@ -3730,12 +4177,12 @@ tags: - name: Transactions description: Query blockchain transaction details x-tag-expanded: false + - name: Stake Account + description: Query details about specific stake account addresses + x-tag-expanded: false - name: Address description: Query information about specific address(es) x-tag-expanded: false - - name: Account - description: Query details about specific stake account addresses - x-tag-expanded: false - name: Asset description: Query Asset related informations x-tag-expanded: false @@ -3745,4 +4192,5 @@ tags: - name: Script description: Query information about specific scripts (Smart Contracts) x-tag-expanded: false -security: [] +security: + - bearerAuth: [] diff --git a/specs/results/koiosapi-mainnet.yaml b/specs/results/koiosapi-mainnet.yaml index f9d5c3e0..f8005196 100644 --- a/specs/results/koiosapi-mainnet.yaml +++ b/specs/results/koiosapi-mainnet.yaml @@ -1,7 +1,7 @@ openapi: 3.0.2 info: title: Koios API - version: 1.0.10 + version: v1.1.0rc description: | Koios is best described as a Decentralized and Elastic RESTful query layer for exploring data on Cardano blockchain to consume within applications/wallets/explorers/etc. This page not only provides an OpenAPI Spec for live implementation, but also ability to execute live demo from client browser against each endpoint with pre-filled examples. @@ -14,11 +14,11 @@ info: Instead of returning entire row, you can elect which rows you would like to fetch from the endpoint by using the `select` parameter with corresponding columns separated by commas. See example below (first is complete information for tip, while second command gives us 3 columns we are interested in):

``` bash - curl "https://api.koios.rest/api/v0/tip" + curl "https://api.koios.rest/api/v1/tip" # [{"hash":"4d44c8a453e677f933c3df42ebcf2fe45987c41268b9cfc9b42ae305e8c3d99a","epoch":317,"abs_slot":51700871,"epoch_slot":120071,"block_height":6806994,"block_time":1643267162}] - curl "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_height" + curl "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_height" # [{"epoch":317,"epoch_slot":120071,"block_height":6806994}] ``` @@ -27,7 +27,7 @@ info: You can filter the returned output based on specific conditions using operators against a column within returned result. Consider an example where you would want to query blocks minted in first 3 minutes of epoch 250 (i.e. epoch_slot was less than 180). To do so your query would look like below:

``` bash - curl "https://api.koios.rest/api/v0/blocks?epoch=eq.250&epoch_slot=lt.180" + curl "https://api.koios.rest/api/v1/blocks?epoch=eq.250&epoch_slot=lt.180" # [{"hash":"8fad2808ac6b37064a0fa69f6fe065807703d5235a57442647bbcdba1c02faf8","epoch":250,"abs_slot":22636942,"epoch_slot":142,"block_height":5385757,"block_time":1614203233,"tx_count":65,"vrf_key":"vrf_vk14y9pjprzlsjvjt66mv5u7w7292sxp3kn4ewhss45ayjga5vurgaqhqknuu","pool":null,"op_cert_counter":2}, # {"hash":"9d33b02badaedc0dedd0d59f3e0411e5fb4ac94217fb5ee86719e8463c570e16","epoch":250,"abs_slot":22636800,"epoch_slot":0,"block_height":5385756,"block_time":1614203091,"tx_count":10,"vrf_key":"vrf_vk1dkfsejw3h2k7tnguwrauqfwnxa7wj3nkp3yw2yw3400c4nlkluwqzwvka6","pool":null,"op_cert_counter":2}] @@ -62,7 +62,7 @@ info: Consider a simple case where I want query `blocks` endpoint for `block_height` column and focus on `content-range` header to monitor the rows we discussed above.

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height" -I | grep -i content-range # content-range: 0-999/* @@ -71,7 +71,7 @@ info: As we can see above, the number of observations returned was 1000 (range being 0-999), but the total size was not queried to avoid wait times. Now, let's modify this default behaviour to query rows beyond the first 999, but this time - also add another clause to limit results by 500. We can do this using `offset=1000` and `limit=500` as below:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height&offset=1000&limit=500" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height&offset=1000&limit=500" -I | grep -i content-range # content-range: 1000-1499/* @@ -80,7 +80,7 @@ info: For GET endpoints, there is also another method to achieve the above, instead of adding parameters to the URL itself, you can specify a `Range` header as below to achieve something similar:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height" -H "Range: 1000-1499" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height" -H "Range: 1000-1499" -I | grep -i content-range # content-range: 1000-1499/* @@ -94,7 +94,7 @@ info: Consider example where you want to check `epoch` and `epoch_slot` for the first 5 blocks created by a particular pool, i.e. you can set order to ascending based on block_height column and add horizontal filter for that pool ID as below:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?pool=eq.pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc&order=block_height.asc&limit=5" + curl -s "https://api.koios.rest/api/v1/blocks?pool=eq.pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc&order=block_height.asc&limit=5" # [{"hash":"610b4c7bbebeeb212bd002885048cc33154ba29f39919d62a3d96de05d315706","epoch":236,"abs_slot":16594295,"epoch_slot":5495,"block_height":5086774,"block_time":1608160586,"tx_count":1,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1}, # {"hash":"d93d1db5275329ab695d30c06a35124038d8d9af64fc2b0aa082b8aa43da4164","epoch":236,"abs_slot":16597729,"epoch_slot":8929,"block_height":5086944,"block_time":1608164020,"tx_count":7,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1}, @@ -109,13 +109,13 @@ info: Below is an example of JSON/CSV output making use of above to print first in JSON (default), and then override response format to CSV.

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_time&limit=3" + curl -s "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_time&limit=3" # [{"epoch":318,"epoch_slot":27867,"block_time":1643606958}, # {"epoch":318,"epoch_slot":27841,"block_time":1643606932}, # {"epoch":318,"epoch_slot":27839,"block_time":1643606930}] - curl -s "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_time&limit=3" -H "Accept: text/csv" + curl -s "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_time&limit=3" -H "Accept: text/csv" # epoch,epoch_slot,block_time # 318,28491,1643607582 @@ -134,6 +134,10 @@ info: Yet, there may be cases where the above restrictions may need exceptions (for example, an explorer or a wallet might need more connections than above - going beyond the Burst Limit). For such cases, it is best to approach the team and we can work towards a solution. + # Authentication + + While Koios public tier remains unauthenticated and allows queries without any authentication, it has low limits to prevent actions against an erroraneous query/loop from a consumer. There is also a Free tier which requires setting up Bearer Auth token that is linked to the owner's wallet account (which can be connected to via [Koios website](https://koios.rest/pricing/Pricing.html) ). + The examples across this API site already [supports authentication](/#auth), for you to use in the queries. # Community projects @@ -142,11 +146,12 @@ info: x-logo: url: "https://api.koios.rest/images/koios.png" servers: - - url: https://api.koios.rest/api/v0 - - url: https://guild.koios.rest/api/v0 - - url: https://preview.koios.rest/api/v0 - - url: https://preprod.koios.rest/api/v0 + - url: https://api.koios.rest/api/v1 + - url: https://guild.koios.rest/api/v1 + - url: https://preview.koios.rest/api/v1 + - url: https://preprod.koios.rest/api/v1 paths: + /tip: #RPC get: tags: @@ -227,6 +232,45 @@ paths: $ref: "#/components/responses/NotFound" summary: Param Update Proposals description: Get all parameter update proposals submitted to the chain starting Shelley era + /reserve_withdrawals: #RPC + get: + tags: + - Network + responses: + "200": + description: Array of withdrawals from reserves against stake accounts + content: + application/json: + schema: + $ref: "#/components/schemas/reserve_withdrawals" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Reserve Withdrawals + description: List of all withdrawals from reserves against stake accounts + /treasury_withdrawals: #RPC + get: + tags: + - Network + responses: + "200": + description: Array of withdrawals from treasury against stake accounts + content: + application/json: + schema: + $ref: "#/components/schemas/reserve_withdrawals" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Treasury Withdrawals + description: List of all withdrawals from treasury against stake accounts + /epoch_info: #RPC get: tags: @@ -294,6 +338,7 @@ paths: summary: Epoch's Block Protocols description: >- Get the information about block protocol distribution in epoch + /blocks: get: tags: @@ -355,28 +400,29 @@ paths: $ref: "#/components/responses/NotFound" summary: Block Transactions description: Get a list of all transactions included in provided blocks - /tx_info: #RPC + + /utxo_info: #RPC post: tags: - Transactions requestBody: - $ref: "#/components/requestBodies/tx_ids" + $ref: "#/components/requestBodies/utxo_refs_with_extended" responses: "200": - description: Array of detailed information about transaction(s) + description: Array of UTXO details content: application/json: schema: - $ref: "#/components/schemas/tx_info" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction Information - description: Get detailed information about transaction(s) - /tx_utxos: #RPC + summary: UTxO Info + description: Get UTxO set for requested UTxO references + /tx_info: #RPC post: tags: - Transactions @@ -384,19 +430,19 @@ paths: $ref: "#/components/requestBodies/tx_ids" responses: "200": - description: Array of inputs and outputs for given transaction(s) + description: Array of detailed information about transaction(s) content: application/json: schema: - $ref: "#/components/schemas/tx_utxos" + $ref: "#/components/schemas/tx_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction UTxOs [DEPRECATED] - description: Get UTxO set (inputs/outputs) of transactions. + summary: Transaction Information + description: Get detailed information about transaction(s) /tx_metadata: #RPC post: tags: @@ -450,7 +496,7 @@ paths: # If using a CLI-generated tx file, please ensure to deserialise (using `xxd -p -r <<< $(jq .cborHex ${tx.signed}) > ${data}`) first before submitting. curl -X POST \ --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/v0/submittx + --data-binary @${data} https://api.koios.rest/api/v1/submittx responses: "202": description: OK @@ -486,8 +532,31 @@ paths: $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction Status (Block Confirmations) + summary: Transaction Status description: Get the number of block confirmations for a given transaction hash list + /tx_utxos: #RPC + post: + tags: + - Transactions + deprecated: true + requestBody: + $ref: "#/components/requestBodies/tx_ids" + responses: + "200": + description: Array of inputs and outputs for given transaction(s) + content: + application/json: + schema: + $ref: "#/components/schemas/tx_utxos" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Transaction UTxOs + description: Get UTxO set (inputs/outputs) of transactions [DEPRECATED - Use /utxo_info instead]. + /address_info: #RPC post: tags: @@ -509,27 +578,27 @@ paths: $ref: "#/components/responses/NotFound" summary: Address Information description: Get address info - balance, associated stake address (if any) and UTxO set for given addresses - /address_txs: #RPC + /address_utxos: #RPC post: tags: - Address requestBody: - $ref: "#/components/requestBodies/address_txs" + $ref: "#/components/requestBodies/payment_addresses_with_extended" responses: "200": - description: Array of transaction hashes + description: Array of address UTXOs content: application/json: schema: - $ref: "#/components/schemas/address_txs" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Address Transactions - description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive) + summary: Address UTXOs + description: Get UTxO set for given addresses /credential_utxos: #RPC post: tags: @@ -542,7 +611,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/credential_utxos" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": @@ -550,28 +619,28 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: UTxOs from payment credentials - description: Get a list of UTxO against input payment credential array including their balances - /address_assets: #RPC + description: Get UTxO details for requested payment credentials + /address_txs: #RPC post: tags: - Address requestBody: - $ref: "#/components/requestBodies/payment_addresses" + $ref: "#/components/requestBodies/address_txs" responses: "200": - description: Array of address-owned assets + description: Array of transaction hashes content: application/json: schema: - $ref: "#/components/schemas/address_assets" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Address Assets - description: Get the list of all the assets (policy, name and quantity) for given addresses + summary: Address Transactions + description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive) /credential_txs: #RPC post: tags: @@ -584,7 +653,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/credential_txs" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": @@ -593,6 +662,28 @@ paths: $ref: "#/components/responses/NotFound" summary: Transactions from payment credentials description: Get the transaction hash list of input payment credential array, optionally filtering after specified block height (inclusive) + /address_assets: #RPC + post: + tags: + - Address + requestBody: + $ref: "#/components/requestBodies/payment_addresses" + responses: + "200": + description: Array of address-owned assets + content: + application/json: + schema: + $ref: "#/components/schemas/address_assets" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Address Assets + description: Get the list of all the assets (policy, name and quantity) for given addresses + /account_list: get: tags: @@ -633,48 +724,70 @@ paths: $ref: "#/components/responses/NotFound" summary: Account Information description: Get the account information for given stake addresses - /account_utxos: #RPC - get: + /account_info_cached: #RPC + post: tags: - Stake Account - parameters: - - $ref: "#/components/parameters/_stake_address" + requestBody: + $ref: "#/components/requestBodies/stake_addresses" responses: "200": - description: Array of account UTxOs associated with stake address + description: Array of account information content: application/json: schema: - $ref: "#/components/schemas/account_utxos" + $ref: "#/components/schemas/account_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Account UTxOs - description: Get a list of all UTxOs for a given stake address (account) - /account_info_cached: #RPC + summary: Account Information (Cached) + description: Get the cached account information for given stake addresses (effective for performance query against registered accounts) + /account_utxos: #RPC post: tags: - Stake Account requestBody: - $ref: "#/components/requestBodies/stake_addresses" + $ref: "#/components/requestBodies/stake_addresses_with_extended" responses: "200": - description: Array of account information + description: Array of account UTxOs associated with given stake addresses content: application/json: schema: - $ref: "#/components/schemas/account_info" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Account Information (Cached) - description: Get the cached account information for given stake addresses, effective for registered accounts + summary: UTxOs for stake addresses (accounts) + description: Get a list of all UTxOs for given stake addresses (account)s + /account_txs: #RPC + get: + tags: + - Stake Account + parameters: + - $ref: "#/components/parameters/_stake_address" + - $ref: "#/components/parameters/_after_block_height" + responses: + "200": + description: Array of Txs associated with stake address (account) + content: + application/json: + schema: + $ref: "#/components/schemas/address_txs" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Account Txs + description: Get a list of all Txs for a given stake address (account) /account_rewards: #RPC post: tags: @@ -783,6 +896,7 @@ paths: $ref: "#/components/responses/NotFound" summary: Account History description: Get the staking history of given stake addresses (accounts) + /asset_list: get: tags: @@ -802,95 +916,89 @@ paths: $ref: "#/components/responses/NotFound" summary: Asset List description: Get the list of all native assets (paginated) - /asset_token_registry: + /policy_asset_list: #RPC get: tags: - Asset + parameters: + - $ref: "#/components/parameters/_asset_policy" responses: "200": - description: Array of token registry information for each asset + description: Array of detailed information of assets under the same policy content: application/json: schema: - $ref: "#/components/schemas/asset_token_registry" + $ref: "#/components/schemas/policy_asset_list" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Token Registry - description: Get a list of assets registered via token registry on github - /asset_addresses: #RPC + summary: Policy Asset List + description: Get the list of asset under the given policy (including balances) + /asset_token_registry: get: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of payment addresses holding the given token (including balances) + description: Array of token registry information for each asset content: application/json: schema: - $ref: "#/components/schemas/asset_addresses" + $ref: "#/components/schemas/asset_token_registry" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Addresses - description: Get the list of all addresses holding a given asset

- `Note - Due to cardano's UTxO design and usage from projects, asset to addresses map can be infinite. Thus, for a small subset of active projects - with millions of transactions, these might end up with timeouts (HTTP code 504) on free layer. Such large-scale projects are free to subscribe to - query layers to have a dedicated cache table for themselves served via Koios.` - /asset_address_list: #RPC - get: + summary: Asset Token Registry + description: Get a list of assets registered via token registry on github + /asset_info: #RPC + post: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" + requestBody: + $ref: "#/components/requestBodies/asset_list" responses: "200": - description: Array of payment addresses holding the given token (including balances) + description: Array of detailed asset information content: application/json: schema: - $ref: "#/components/schemas/asset_addresses" + $ref: "#/components/schemas/asset_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Address List [DEPRECATED] - description: Get the list of all addresses holding a given asset (replaced by asset_addresses) - /asset_nft_address: #RPC - get: + summary: Asset Information (Bulk) + description: Get the information of a list of assets including first minting & token registry metadata + /asset_utxos: #RPC + post: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy_nft" - - $ref: "#/components/parameters/_asset_name_nft" + requestBody: + $ref: "#/components/requestBodies/asset_list_with_extended" responses: "200": - description: Payment addresses currently holding the given NFT + description: Array of UTXOs for given asset list content: application/json: schema: - $ref: "#/components/schemas/asset_nft_address" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: NFT Address - description: Get the address where specified NFT currently reside on. - /asset_info: #RPC + summary: Asset UTXOs + description: Get the UTXO information of a list of assets including + /asset_history: #RPC get: tags: - Asset @@ -899,61 +1007,66 @@ paths: - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed asset information + description: Array of asset mint/burn history content: application/json: schema: - $ref: "#/components/schemas/asset_info" + $ref: "#/components/schemas/asset_history" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Information - description: Get the information of an asset including first minting & token registry metadata - post: + summary: Asset History + description: Get the mint/burn history of an asset + /asset_addresses: #RPC + get: tags: - Asset - requestBody: - $ref: "#/components/requestBodies/asset_list" + parameters: + - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed asset information + description: Array of payment addresses holding the given token (including balances) content: application/json: schema: - $ref: "#/components/schemas/asset_info" + $ref: "#/components/schemas/asset_addresses" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Information (Bulk) - description: Get the information of a list of assets including first minting & token registry metadata - /asset_history: #RPC + summary: Asset Addresses + description: Get the list of all addresses holding a given asset

+ `Note - Due to cardano's UTxO design and usage from projects, asset to addresses map can be infinite. Thus, for a small subset of active projects + with millions of transactions, these might end up with timeouts (HTTP code 504) on free layer. Such large-scale projects are free to subscribe to + query layers to have a dedicated cache table for themselves served via Koios.` + /asset_nft_address: #RPC get: tags: - Asset parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" + - $ref: "#/components/parameters/_asset_policy_nft" + - $ref: "#/components/parameters/_asset_name_nft" responses: "200": - description: Array of asset mint/burn history + description: Payment addresses currently holding the given NFT content: application/json: schema: - $ref: "#/components/schemas/asset_history" + $ref: "#/components/schemas/asset_nft_address" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset History - description: Get the mint/burn history of an asset + summary: NFT Address + description: Get the address where specified NFT currently reside on. /policy_asset_addresses: #RPC get: tags: @@ -999,94 +1112,98 @@ paths: $ref: "#/components/responses/NotFound" summary: Policy Asset Information description: Get the information for all assets under the same policy - /asset_policy_info: #RPC + /asset_summary: #RPC get: tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed information of assets under the same policy + description: Array of asset summary information content: application/json: schema: - $ref: "#/components/schemas/policy_asset_info" + $ref: "#/components/schemas/asset_summary" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Policy Information [DEPRECATED] - description: Get the information for all assets under the same policy (replaced by asset_addresses) - /policy_asset_list: #RPC + summary: Asset Summary + description: Get the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance) + /asset_txs: #RPC get: tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" + - $ref: "#/components/parameters/_after_block_height" + - $ref: "#/components/parameters/_history" responses: "200": - description: Array of detailed information of assets under the same policy + description: An array of Tx hashes that included the given asset (latest first) content: application/json: schema: - $ref: "#/components/schemas/policy_asset_list" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Policy Asset List - description: Get the list of asset under the given policy (including balances) - /asset_summary: #RPC + summary: Asset Transactions + description: Get the list of current or all asset transaction hashes (newest first) + /asset_address_list: #RPC get: tags: - Asset + deprecated: true parameters: - $ref: "#/components/parameters/_asset_policy" - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of asset summary information + description: Array of payment addresses holding the given token (including balances) content: application/json: schema: - $ref: "#/components/schemas/asset_summary" + $ref: "#/components/schemas/asset_addresses" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Summary - description: Get the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance) - /asset_txs: #RPC + summary: Asset Address List + description: Get the list of all addresses holding a given asset [DEPRECATED - replaced by asset_addresses] + /asset_policy_info: #RPC get: + deprecated: true tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" - - $ref: "#/components/parameters/_after_block_height" - - $ref: "#/components/parameters/_history" responses: "200": - description: Array of Tx hashes that included the given asset + description: Array of detailed information of assets under the same policy content: application/json: schema: - $ref: "#/components/schemas/asset_txs" + $ref: "#/components/schemas/policy_asset_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Transactions - description: Get the list of current or all asset transaction hashes (newest first) + summary: Asset Policy Information + description: Get the information for all assets under the same policy (DEPRECATED - replaced by policy_asset_info) + /pool_list: #RPC get: tags: @@ -1105,7 +1222,7 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool List - description: A list of all currently registered/retiring (not retired) pools + description: List of brief info for all pools /pool_info: #RPC post: tags: @@ -1261,6 +1378,48 @@ paths: $ref: "#/components/responses/NotFound" summary: Pool Updates (History) description: Return all pool updates for all pools or only updates for specific pool if specified + /pool_registrations: #RPC + get: + tags: + - Pool + parameters: + - $ref: "#/components/parameters/_epoch_no" + responses: + "200": + description: Array of historical pool updates + content: + application/json: + schema: + $ref: "#/components/schemas/pool_registrations" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Pool Registrations + description: Return all pool registrations initiated in the requested epoch + /pool_retirements: #RPC + get: + tags: + - Pool + parameters: + - $ref: "#/components/parameters/_epoch_no" + responses: + "200": + description: Array of historical pool updates + content: + application/json: + schema: + $ref: "#/components/schemas/pool_registrations" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Pool Retirements + description: Return all pool retirements initiated in the requested epoch /pool_relays: #RPC get: tags: @@ -1279,7 +1438,7 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool Relays - description: A list of registered relays for all currently registered/retiring (not retired) pools + description: A list of registered relays for all pools /pool_metadata: #RPC post: tags: @@ -1300,7 +1459,29 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool Metadata - description: Metadata (on & off-chain) for all currently registered/retiring (not retired) pools + description: Metadata (on & off-chain) for all pools + + /script_info: #RPC + post: + tags: + - Script + requestBody: + $ref: "#/components/requestBodies/script_hashes" + responses: + "200": + description: List of datum information for given datum hashes + content: + application/json: + schema: + $ref: "#/components/schemas/script_info" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Datum Information + description: List of datum information for given datum hashes /native_script_list: #RPC get: tags: @@ -1311,7 +1492,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/native_script_list" + $ref: "#/components/schemas/script_list" "400": $ref: "#/components/responses/BadRequest" "401": @@ -1330,7 +1511,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/plutus_script_list" + $ref: "#/components/schemas/script_list" "400": $ref: "#/components/responses/BadRequest" "401": @@ -1360,6 +1541,28 @@ paths: $ref: "#/components/responses/NotFound" summary: Script Redeemers description: List of all redeemers for a given script hash + /script_utxos: #RPC + get: + tags: + - Script + parameters: + - $ref: "#/components/parameters/_script_hash" + - $ref: "#/components/parameters/_extended" + responses: + "200": + description: List of UTXOs for a given script hash + content: + application/json: + schema: + $ref: "#/components/schemas/utxo_infos" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Script UTXOs + description: List of all UTXOs for a given script hash /datum_info: #RPC post: tags: @@ -1381,6 +1584,43 @@ paths: $ref: "#/components/responses/NotFound" summary: Datum Information description: List of datum information for given datum hashes + /ogmios/?EvaluateTransaction: #ogmios-api + post: + tags: + - Ogmios + x-code-samples: + - lang: "Shell" + source: | + # Assuming ${data} contains EvaluateTransaction payload as documented on Ogmios v6 site. + curl -X POST \ + --header "Content-Type: application/cbor" \ + --data-binary ${data} https://api.koios.rest/api/ogmios/?EvaluateTransaction + responses: + "200": + description: OK + "400": + description: An error occured while submitting transaction. + summary: Evaluate Transaction + description: Evaluate execution units of scripts in a well-formed transaction. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?EvaluateTransaction) for complete spec + /ogmios/?SubmitTransaction: #ogmios-api + post: + tags: + - Ogmios + x-code-samples: + - lang: "Shell" + source: | + # Assuming ${data} contains a CBOR-serialized signed transaction (base16-encoded) as documented on Ogmios v6 site. + curl -X POST \ + --header "Content-Type: application/cbor" \ + --data-binary ${data} https://api.koios.rest/api/ogmios/?SubmitTransaction + responses: + "200": + description: OK + "400": + description: An error occured while querying transaction. + summary: Submit Transaction + description: Submit a signed and serialized transaction to the network. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?SubmitTransaction) for complete spec + components: parameters: select: @@ -1554,6 +1794,16 @@ components: in: query required: false allowEmptyValue: true + _extended: + deprecated: false + name: _extended + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + schema: + type: boolean + example: "false" + in: query + required: false + allowEmptyValue: true _history: deprecated: false name: _history @@ -1661,6 +1911,29 @@ components: _addresses: - addr1qy2jt0qpqz2z2z9zx5w4xemekkce7yderz53kjue53lpqv90lkfa9sgrfjuz6uvt4uqtrqhl2kj0a9lnr9ndzutx32gqleeckv - addr1q9xvgr4ehvu5k5tmaly7ugpnvekpqvnxj8xy50pa7kyetlnhel389pa4rnq6fmkzwsaynmw0mnldhlmchn2sfd589fgsz9dd0y + payment_addresses_with_extended: + content: + application/json: + schema: + required: + - _addresses + type: object + properties: + _addresses: + format: text + type: array + items: + type: string + description: Array of Cardano payment address(es) in bech32 format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _addresses: + - addr1qy2jt0qpqz2z2z9zx5w4xemekkce7yderz53kjue53lpqv90lkfa9sgrfjuz6uvt4uqtrqhl2kj0a9lnr9ndzutx32gqleeckv + - addr1q9xvgr4ehvu5k5tmaly7ugpnvekpqvnxj8xy50pa7kyetlnhel389pa4rnq6fmkzwsaynmw0mnldhlmchn2sfd589fgsz9dd0y + _extended: true address_txs: content: application/json: @@ -1706,7 +1979,7 @@ components: _stake_addresses: - stake1uyrx65wjqjgeeksd8hptmcgl5jfyrqkfq0xe8xlp367kphsckq250 - stake1uxpdrerp9wrxunfh6ukyv5267j70fzxgw0fr3z8zeac5vyqhf9jhy - _epoch_no: 350 + _epoch_no: 409 stake_addresses_with_first_only_and_empty: content: application/json: @@ -1733,6 +2006,32 @@ components: _stake_addresses: - stake1uyrx65wjqjgeeksd8hptmcgl5jfyrqkfq0xe8xlp367kphsckq250 - stake1uxpdrerp9wrxunfh6ukyv5267j70fzxgw0fr3z8zeac5vyqhf9jhy + _first_only: false + _empty: false + + stake_addresses_with_extended: + content: + application/json: + schema: + required: + - _stake_addresses + type: object + properties: + _stake_addresses: + format: text + type: array + items: + type: string + description: Array of Cardano stake address(es) in bech32 format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _stake_addresses: + - stake1uyrx65wjqjgeeksd8hptmcgl5jfyrqkfq0xe8xlp367kphsckq250 + - stake1uxpdrerp9wrxunfh6ukyv5267j70fzxgw0fr3z8zeac5vyqhf9jhy + _extended: true stake_addresses: content: application/json: @@ -1788,10 +2087,15 @@ components: items: type: string description: Array of Cardano payment credential(s) in hex format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call example: _payment_credentials: - 025b0a8f85cb8a46e1dda3fae5d22f07e2d56abb4019a2129c5d6c52 - 13f6870c5e4f3b242463e4dc1f2f56b02a032d3797d933816f15e555 + _extended: true tx_ids: content: application/json: @@ -1853,6 +2157,22 @@ components: - pool100wj94uzf54vup2hdzk0afng4dhjaqggt7j434mtgm8v2gfvfgp - pool102s2nqtea2hf5q0s4amj0evysmfnhrn4apyyhd4azcmsclzm96m - pool102vsulhfx8ua2j9fwl2u7gv57fhhutc3tp6juzaefgrn7ae35wm + script_hashes: + content: + application/json: + schema: + type: object + properties: + _script_hashes: + format: text + type: array + items: + type: string + description: Array of Cardano script hashes + example: + _script_hashes: + - bd2119ee2bfb8c8d7c427e8af3c35d537534281e09e23013bca5b138 + - c0c671fba483641a71bb92d3a8b7c52c90bf1c01e2b83116ad7d4536 datum_hashes: content: application/json: @@ -1866,10 +2186,30 @@ components: type: string description: Array of Cardano datum hashes example: - _datum_hashes: - - 818ee3db3bbbd04f9f2ce21778cac3ac605802a4fcb00c8b3a58ee2dafc17d46 - - 45b0cfc220ceec5b7c1c62c4d4193d38e4eba48e8815729ce75f9c0ab0e4c1c0 - asset_list: + _datum_hashes: + - 818ee3db3bbbd04f9f2ce21778cac3ac605802a4fcb00c8b3a58ee2dafc17d46 + - 45b0cfc220ceec5b7c1c62c4d4193d38e4eba48e8815729ce75f9c0ab0e4c1c0 + asset_list: + content: + application/json: + schema: + required: + - _asset_list + type: object + properties: + _asset_list: + format: text + type: array + description: Array of array of policy ID and asset names (hex) + items: + type: array + items: + type: string + example: + _asset_list: + - ['750900e4999ebe0d58f19b634768ba25e525aaf12403bfe8fe130501','424f4f4b'] + - ['f0ff48bbb7bbe9d59a40f1ce90e9e9d0ff5002ec48f232b49ca0fb9a','6b6f696f732e72657374'] + asset_list_with_extended: content: application/json: schema: @@ -1885,11 +2225,43 @@ components: type: array items: type: string + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call example: _asset_list: - ['750900e4999ebe0d58f19b634768ba25e525aaf12403bfe8fe130501','424f4f4b'] - - ['1d7f33bd23d85e1a25d87d86fac4f199c3197a2f7afeb662a0f34e1e','776f726c646d6f62696c65746f6b656e'] - securitySchemes: {} + - ['f0ff48bbb7bbe9d59a40f1ce90e9e9d0ff5002ec48f232b49ca0fb9a','6b6f696f732e72657374'] + _extended: true + utxo_refs_with_extended: + content: + application/json: + schema: + required: + - _utxo_refs + type: object + properties: + _utxo_refs: + format: text + type: array + items: + type: string + description: Array of Cardano utxo references in the form "hash#index" + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _utxo_refs: + - f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e#0 + - 0b8ba3bed976fa4913f19adc9f6dd9063138db5b4dd29cecde369456b5155e94#0 + _extended: false + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT schemas: tip: type: array @@ -2003,20 +2375,59 @@ components: type: string description: JSON encoded data with details about the parameter update example: {"decentralisation": 0.9} + reserve_withdrawals: + type: array + items: + properties: + epoch_no: + $ref: "#/components/schemas/epoch_info/items/properties/epoch_no" + epoch_slot: + $ref: "#/components/schemas/blocks/items/properties/epoch_slot" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + block_hash: + $ref: "#/components/schemas/blocks/items/properties/hash" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + amount: + $ref: "#/components/schemas/pool_delegators/items/properties/amount" + stake_address: + $ref: "#/components/schemas/account_history/items/properties/stake_address" pool_list: type: array items: properties: pool_id_bech32: - type: string - nullable: true - description: Bech32 representation of pool ID - example: pool1z5uqdk7dzdxaae5633fqfcu2eqzy3a3rgtuvy087fdld7yws0xt + $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" + pool_id_hex: + $ref: "#/components/schemas/pool_info/items/properties/pool_id_hex" + active_epoch_no: + $ref: "#/components/schemas/pool_info/items/properties/active_epoch_no" + margin: + $ref: "#/components/schemas/pool_info/items/properties/margin" + fixed_cost: + $ref: "#/components/schemas/pool_info/items/properties/fixed_cost" + pledge: + $ref: "#/components/schemas/pool_info/items/properties/pledge" + reward_addr: + $ref: "#/components/schemas/pool_info/items/properties/reward_addr" + owners: + $ref: "#/components/schemas/pool_info/items/properties/margin" + relays: + $ref: "#/components/schemas/pool_info/items/properties/margin" ticker: type: string nullable: true description: Pool ticker - example: JAZZ + example: AHL + meta_url: + $ref: "#/components/schemas/pool_info/items/properties/margin" + meta_hash: + $ref: "#/components/schemas/pool_info/items/properties/margin" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/margin" + retiring_epoch: + $ref: "#/components/schemas/pool_info/items/properties/margin" pool_history_info: type: array items: @@ -2088,26 +2499,32 @@ components: $ref: "#/components/schemas/pool_updates/items/properties/active_epoch_no" vrf_key_hash: type: string + nullable: true description: Pool VRF key hash example: 25efdad1bc12944d38e4e3c26c43565bec84973a812737b163b289e87d0d5ed3 margin: type: number + nullable: true description: Margin (decimal format) example: 0.1 fixed_cost: type: string + nullable: true description: Pool fixed cost per epoch example: "500000000" pledge: type: string + nullable: true description: Pool pledge in lovelace example: "64000000000000" reward_addr: type: string + nullable: true description: Pool reward address example: stake1uy6yzwsxxc28lfms0qmpxvyz9a7y770rtcqx9y96m42cttqwvp4m5 owners: type: array + nullable: true items: type: string description: Pool (co)owner address @@ -2270,6 +2687,26 @@ components: type: string description: Latest transaction hash used for delegation by the account example: 368d08fe86804d637649341d3aec4a9baa7dffa6d00f16de2ba9dba814f1c948 + pool_registrations: + type: array + nullable: true + items: + type: object + properties: + pool_id_bech32: + $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + block_hash: + $ref: "#/components/schemas/blocks/items/properties/hash" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + epoch_no: + $ref: "#/components/schemas/epoch_info/items/properties/epoch_no" + epoch_slot: + $ref: "#/components/schemas/blocks/items/properties/epoch_slot" + active_epoch_no: + $ref: "#/components/schemas/pool_updates/items/properties/active_epoch_no" pool_delegators_history: type: array nullable: true @@ -2318,6 +2755,7 @@ components: active_epoch_no: type: integer description: Epoch number in which the update becomes active + nullable: true example: 324 vrf_key_hash: $ref: "#/components/schemas/pool_info/items/properties/vrf_key_hash" @@ -2339,8 +2777,11 @@ components: $ref: "#/components/schemas/pool_info/items/properties/meta_hash" meta_json: $ref: "#/components/schemas/pool_info/items/properties/meta_json" - pool_status: - $ref: "#/components/schemas/pool_info/items/properties/pool_status" + update_type: + type: string + description: Type of update task + enum: ["registration", "deregistration"] + example: registered retiring_epoch: $ref: "#/components/schemas/pool_info/items/properties/retiring_epoch" pool_relays: @@ -2352,6 +2793,8 @@ components: $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" relays: $ref: "#/components/schemas/pool_info/items/properties/relays" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/pool_status" pool_metadata: type: array items: @@ -2365,6 +2808,8 @@ components: $ref: "#/components/schemas/pool_info/items/properties/meta_hash" meta_json: $ref: "#/components/schemas/pool_info/items/properties/meta_json" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/pool_status" epoch_info: type: array items: @@ -2533,8 +2978,8 @@ components: description: The hash of the first block where these parameters are valid example: f9dc2a2fc3a2db09a71af007a740261de585afc9e3022b8e30535592ff4dd9e5 cost_models: - type: string - description: The per language cost models + type: object + description: The per language cost model in JSON example: null nullable: true price_mem: @@ -2724,17 +3169,21 @@ components: properties: block_hash: $ref: "#/components/schemas/blocks/items/properties/hash" - tx_hashes: - type: array - items: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + epoch_no: + $ref: "#/components/schemas/blocks/items/properties/epoch_no" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + block_time: + $ref: "#/components/schemas/blocks/items/properties/block_time" address_info: type: array items: type: object properties: address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" balance: type: string description: Sum of all UTxO values beloning to address @@ -2753,9 +3202,9 @@ components: type: object properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" block_height: $ref: "#/components/schemas/blocks/items/properties/block_height" block_time: @@ -2769,7 +3218,7 @@ components: reference_script: $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/reference_script" asset_list: - $ref: "#/components/schemas/account_assets/items/properties/asset_list" + $ref: "#/components/schemas/utxo_infos/items/properties/asset_list" address_txs: type: array items: @@ -2789,22 +3238,17 @@ components: type: object properties: address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" - asset_list: - $ref: "#/components/schemas/account_assets/items/properties/asset_list" - credential_txs: - $ref: "#/components/schemas/address_txs" - credential_utxos: - type: array - items: - type: object - properties: - tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" - tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" - value: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value" + $ref: "#/components/schemas/utxo_infos/items/properties/address" + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + $ref: "#/components/schemas/asset_addresses/items/properties/quantity" account_list: type: array items: @@ -2825,7 +3269,9 @@ components: enum: ["registered", "not registered"] example: registered delegated_pool: - $ref: "#/components/schemas/pool_list/items/properties/pool_id_bech32" + nullable: true + allOf: + - $ref: "#/components/schemas/pool_list/items/properties/pool_id_bech32" total_balance: type: string description: Total balance of the account including UTxO, rewards and MIRs (in lovelace) @@ -2854,23 +3300,67 @@ components: type: string description: Total treasury MIR value of the account example: "0" - account_utxos: + utxo_infos: type: array items: type: object properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" + type: string + description: Hash identifier of the transaction + example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" + type: integer + description: Index of UTxO in the transaction + example: 0 address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + type: string + description: A Cardano payment/base address (bech32 encoded) + example: addr1qxkfe8s6m8qt5436lec3f0320hrmpppwqgs2gah4360krvyssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqdc3cxp value: $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value" + stake_address: + $ref: "#/components/schemas/address_info/items/properties/stake_address" + payment_cred: + type: string + description: Payment credential + example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 + nullable: true + epoch_no: + $ref: "#/components/schemas/blocks/items/properties/epoch_no" block_height: $ref: "#/components/schemas/blocks/items/properties/block_height" block_time: $ref: "#/components/schemas/blocks/items/properties/block_time" + datum_hash: + $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_hash" + inline_datum: + $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/inline_datum" + reference_script: + $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/reference_script" + asset_list: + type: array + nullable: true + description: An array of assets on the UTxO + items: + properties: + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + type: string + description: Quantity of assets on the UTxO + example: 1 + is_spent: + type: boolean + description: True if the UTXO has been spent + example: true + account_rewards: type: array items: @@ -2915,7 +3405,7 @@ components: enum: ["registration", "delegation", "withdrawal", "deregistration"] example: "registration" tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" epoch_no: $ref: "#/components/schemas/blocks/items/properties/epoch_no" epoch_slot: @@ -2934,7 +3424,7 @@ components: addresses: type: array items: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" account_assets: type: array items: @@ -2942,25 +3432,16 @@ components: properties: stake_address: $ref: "#/components/schemas/account_history/items/properties/stake_address" - asset_list: - type: array - items: - type: object - properties: - policy_id: - $ref: "#/components/schemas/asset_info/items/properties/policy_id" - asset_name: - $ref: "#/components/schemas/asset_info/items/properties/asset_name" - fingerprint: - $ref: "#/components/schemas/asset_info/items/properties/fingerprint" - decimals: - type: integer - description: Asset decimals - example: 6 - quantity: - type: string - description: Asset quantity owned by account - example: 990000 + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + $ref: "#/components/schemas/asset_addresses/items/properties/quantity" account_history: type: array items: @@ -2992,9 +3473,7 @@ components: type: object properties: tx_hash: - type: string - description: Hash identifier of the transaction - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" block_hash: $ref: "#/components/schemas/blocks/items/properties/hash" block_height: @@ -3061,25 +3540,17 @@ components: type: object properties: bech32: - type: string - description: A Cardano payment/base address (bech32 encoded) where funds were sent or change to be returned - example: addr1q80rc8zj06yzdwwdyqc03rm4l3zv6n89rxuaak0t099n09yssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqad9mkw + $ref: "#/components/schemas/utxo_infos/items/properties/address" cred: type: string description: Payment credential example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 stake_addr: - nullable: true - allOf: - - $ref: "#/components/schemas/account_history/items/properties/stake_address" + $ref: "#/components/schemas/address_info/items/properties/stake_address" tx_hash: - type: string - description: Hash of transaction for UTxO - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: Index of UTxO in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" value: type: string description: Total sum of ADA on the UTxO @@ -3129,23 +3600,7 @@ components: description: Value (json) example: null asset_list: - type: array - nullable: true - description: An array of assets on the UTxO - items: - properties: - policy_id: - $ref: "#/components/schemas/asset_info/items/properties/policy_id" - asset_name: - $ref: "#/components/schemas/asset_info/items/properties/asset_name" - fingerprint: - $ref: "#/components/schemas/asset_info/items/properties/fingerprint" - decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" - quantity: - type: string - description: Quantity of assets on the UTxO - example: 1 + $ref: "#/components/schemas/utxo_infos/items/properties/asset_list" withdrawals: type: array description: Array of withdrawals with-in a transaction @@ -3174,7 +3629,7 @@ components: fingerprint: $ref: "#/components/schemas/asset_info/items/properties/fingerprint" decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" quantity: type: string description: Quantity of minted assets (negative on burn) @@ -3212,7 +3667,7 @@ components: items: properties: script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + $ref: "#/components/schemas/script_info/items/properties/script_hash" script_json: type: object description: JSON representation of the timelock script (null for other script types) @@ -3237,6 +3692,7 @@ components: } plutus_contracts: type: array + nullable: true description: Plutus contracts present in transaction (if any) items: properties: @@ -3246,15 +3702,11 @@ components: example: addr1w999n67e86jn6xal07pzxtrmqynspgx0fwmcmpua4wc6yzsxpljz3 nullable: true script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + $ref: "#/components/schemas/script_info/items/properties/script_hash" bytecode: - type: string - description: CBOR-encoded Plutus script data - example: 5911ea010000332333222332233223322332232323332223233322232333333332222222232333222323333222232323322323332223233322232323322332232323333322222332233223322332233223322223223223232533530333330083333573466e1cd55cea8032400046460a000264646464646666ae68cdc39aab9d5004480008cccc8888cccc16c01000c008004dd71aba15004375c6ae85400cdd71aba15002375a6ae84d5d1280111a8279a982819ab9c491035054310005149926135744a00226ae8940044d55cf280089baa001357426aae79401c8d4124d4c128cd5ce2481035054310004b499263333573466e1d40112002205323333573466e1d40152000205523504a35304b335738921035054310004c49926498cccd5cd19b8735573aa004900011980599191919191919191919191999ab9a3370e6aae754029200023333333333019335027232323333573466e1cd55cea8012400046603e60746ae854008c0b0d5d09aba2500223505935305a3357389201035054310005b49926135573ca00226ea8004d5d0a80519a8138141aba150093335502e75ca05a6ae854020ccd540b9d728169aba1500733502704335742a00c66a04e66aa0a8098eb4d5d0a8029919191999ab9a3370e6aae754009200023350213232323333573466e1cd55cea80124000466a05266a084eb4d5d0a80118239aba135744a00446a0ba6a60bc66ae712401035054310005f49926135573ca00226ea8004d5d0a8011919191999ab9a3370e6aae7540092000233502733504275a6ae854008c11cd5d09aba2500223505d35305e3357389201035054310005f49926135573ca00226ea8004d5d09aba2500223505935305a3357389201035054310005b49926135573ca00226ea8004d5d0a80219a813bae35742a00666a04e66aa0a8eb88004d5d0a801181c9aba135744a00446a0aa6a60ac66ae71241035054310005749926135744a00226ae8940044d5d1280089aba25001135744a00226ae8940044d5d1280089aba25001135573ca00226ea8004d5d0a8011919191999ab9a3370ea00290031180f181d9aba135573ca00646666ae68cdc3a801240084603a608a6ae84d55cf280211999ab9a3370ea00690011180e98181aba135573ca00a46666ae68cdc3a80224000460406eb8d5d09aab9e50062350503530513357389201035054310005249926499264984d55cea80089baa001357426ae8940088d4124d4c128cd5ce249035054310004b49926104a1350483530493357389201035054350004a4984d55cf280089baa001135573a6ea80044dd50009109198008018011000911111111109199999999980080580500480400380300280200180110009109198008018011000891091980080180109000891091980080180109000891091980080180109000909111180200290911118018029091111801002909111180080290008919118011bac0013200135503b2233335573e0024a01c466a01a60086ae84008c00cd5d100101991919191999ab9a3370e6aae75400d200023330073232323333573466e1cd55cea8012400046601a60626ae854008cd404c0b4d5d09aba25002235036353037335738921035054310003849926135573ca00226ea8004d5d0a801999aa805bae500a35742a00466a01eeb8d5d09aba25002235032353033335738921035054310003449926135744a00226aae7940044dd50009110919980080200180110009109198008018011000899aa800bae75a224464460046eac004c8004d540d488c8cccd55cf80112804919a80419aa81898031aab9d5002300535573ca00460086ae8800c0b84d5d08008891001091091198008020018900089119191999ab9a3370ea002900011a80418029aba135573ca00646666ae68cdc3a801240044a01046a0526a605466ae712401035054310002b499264984d55cea80089baa001121223002003112200112001232323333573466e1cd55cea8012400046600c600e6ae854008dd69aba135744a00446a0466a604866ae71241035054310002549926135573ca00226ea80048848cc00400c00880048c8cccd5cd19b8735573aa002900011bae357426aae7940088d407cd4c080cd5ce24810350543100021499261375400224464646666ae68cdc3a800a40084a00e46666ae68cdc3a8012400446a014600c6ae84d55cf280211999ab9a3370ea00690001280511a8111a981199ab9c490103505431000244992649926135573aa00226ea8004484888c00c0104488800844888004480048c8cccd5cd19b8750014800880188cccd5cd19b8750024800080188d4068d4c06ccd5ce249035054310001c499264984d55ce9baa0011220021220012001232323232323333573466e1d4005200c200b23333573466e1d4009200a200d23333573466e1d400d200823300b375c6ae854014dd69aba135744a00a46666ae68cdc3a8022400c46601a6eb8d5d0a8039bae357426ae89401c8cccd5cd19b875005480108cc048c050d5d0a8049bae357426ae8940248cccd5cd19b875006480088c050c054d5d09aab9e500b23333573466e1d401d2000230133016357426aae7940308d407cd4c080cd5ce2481035054310002149926499264992649926135573aa00826aae79400c4d55cf280109aab9e500113754002424444444600e01044244444446600c012010424444444600a010244444440082444444400644244444446600401201044244444446600201201040024646464646666ae68cdc3a800a400446660106eb4d5d0a8021bad35742a0066eb4d5d09aba2500323333573466e1d400920002300a300b357426aae7940188d4040d4c044cd5ce2490350543100012499264984d55cea80189aba25001135573ca00226ea80048488c00800c888488ccc00401401000c80048c8c8cccd5cd19b875001480088c018dd71aba135573ca00646666ae68cdc3a80124000460106eb8d5d09aab9e500423500a35300b3357389201035054310000c499264984d55cea80089baa001212230020032122300100320011122232323333573466e1cd55cea80124000466aa016600c6ae854008c014d5d09aba25002235007353008335738921035054310000949926135573ca00226ea8004498480048004448848cc00400c008448004848c0040088004888848cccc00401401000c00880044880084880048004448c8c00400488cc00cc008008004c8ccc888c8c8cc88cc88ccc888c8c8c8c8cc88c8c8cc88c8cccc8888c8c8c8c8c8c8c8c8ccc888c8ccc888ccc888cccccccc88888888cc88ccccc88888cccc8888cc88cc88cc88ccc888cc88cc88cc88cc88cc88c8c8c8cc88c8c8c8c8c8c8cc88c8c8c8c8c8c8cc888c888c8c94cd4c1240104cc0352401297369676e617475726520646f6573206e6f74206d617463682063726561746f7220696e20646174756d0033223530200022222222222533535032333553068120015027253353079333573466e3c0300041ec1e84d40d4004540d000c841ec41e54008c04540144cc054cc03524012f65787065637465642063726561746f7220746f2067657420616c6c206f66207768617420736865206f72646572656400330153350133335500e305c12001504f350481223335501b2253353070333505006353353502a3235302900122335304c0022350300012502f300e00221001132635300b335738920117696e76616c6964207075626c6963206b657920686173680000c498c05540244cc010c0340080044004004c8d4c08400488888888880254010ccd41354138c1894014c04920c08db7013350133335500e305c12001504f350481223335501b22533530703005002133004335506500d30100020011001001300d5004333504d504e30625005333504d504e533535026301a00321300a300d0011630124830236dc04cc0352401276f6e6c79206d617463686573206f66207061697273206f66206f726465727320616c6c6f77656400533535063350481223335501b225335307030050021330040020011001001300d50041306a162215335350650011306c16221533535067001107222130701623253353502732353024001222001500121333504e223530280022235302a0032232335304e0052335304f004253353077333573466e3c0080041e41e05400c41e081e08cd4c13c01081e094cd4c1dcccd5cd19b8f002001079078150031078153353502e0032153353502f00221335304c0022335304d002233530510022335305200223306d002001207b23353052002207b23306d00200122207b222335304f004207b2225335307c333573466e1c01800c1f81f454cd4c1f0ccd5cd19b8700500207e07d1333573466e1c0100041f81f441f441f441d854cd4d40b8004841d841d8c03140094cd4d40a0c07001484cd54190034c03c0045841b84c0300044d4c068004880084d4c02800480044800480048d4c0680048880088d4c06400488800c8d4c05000488888888880288d4c05400488004894cd4c184004418c4cd5ce001031089119aa8011a82600090009091800801100091a982c0009111002119a82999aa82b245003350533355056489000015054505412233355304b120013500550032353550560012233355304e120013500850062353550590012233353550490012330614800000488cc1880080048cc184005200000133040002001133500400105a22533530590021001105a123350492233353500400322002002001353500200122001122123300100300212001112232001320013550582253353504e00110032213300600230040012353003001223530070022222222222533335302600b21501b21501b21501b2133355305012001500f2353015001225335306353353063333573466e3cd4c0bc00888008d4c0bc010880081941904ccd5cd19b8735302f0022200135302f00422001065064106413501f0031501e00b13350432253353500d002210031001500c2212330010030022001222222222212333333333300100b00a009008007006005004003002200122123300100300220012221233300100400300220012212330010030022001121223002003112200112001122123300100300212001122123300100300212001122123300100300212001121222300300411222002112220011200121222230040052122223003005212222300200521222230010052001221233001003002200121222222230070082212222222330060090082122222223005008122222220041222222200322122222223300200900822122222223300100900820012122300200322212233300100500400320012122300200321223001003200112335001501d501e1220021220012001120011200113002012133500b2233300301300200150162223355300e1200123535501a00122335501d002335530111200123535501d001223355020002333535500d00123300a4800000488cc02c0080048cc028005200000133004002001223355300c1200123535501800122335501b00233353550080012335530101200123535501c00122335501f00235500f001001223335550080150020012335530101200123535501c00122335501f00235500d0010013335550030100020011112223335530041200150153355300c1200123535501800122335501b00235500b0013335530041200122353550190022253353021333553011120013500d33500f22533530230021025100102223535501c001223300a0020050061003133501900400350160013355300c120012353550180012232335501c00330010053200135502322533535019001135500b0032213535501e00222533530263300c00200813355010007001130060030023200135501c221122253353501500110022213300500233355300712001005004001112122230030041122122233002005004112122230010041120011233500722333535004003220020020013535002001220011221233001003002120013200135501422112253353500c0011500e22133500f3004002335530061200100400132001355013221122253353500c00113535006003220012213335350080052200230040023335530071200100500400112212330010030021200122333573466e3c00800404404088cdc000100088911801000919991119a80319aa80480199a80319aa804801000a803a8039a980380091110019a980380091110011a98038009111000889100109109119800802001890008891091980080180108900091110919998008028020018011000900211199ab9a3371000400200800a244004244002400222464600200244660066004004003 + $ref: "#/components/schemas/script_info/items/properties/bytes" size: - type: integer - description: The size of the CBOR serialised script (in bytes) - example: 234895 + $ref: "#/components/schemas/script_info/items/properties/size" valid_contract: type: boolean description: True if the contract is valid or there is no contract @@ -3314,17 +3766,11 @@ components: description: Payment credential example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 stake_addr: - nullable: true - allOf: - - $ref: "#/components/schemas/account_history/items/properties/stake_address" + $ref: "#/components/schemas/address_info/items/properties/stake_address" tx_hash: - type: string - description: Hash of transaction for UTxO - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: Index of UTxO in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" value: type: string description: Total sum of ADA on the UTxO @@ -3339,7 +3785,7 @@ components: items: properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" metadata: type: object nullable: true @@ -3360,7 +3806,7 @@ components: items: properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" num_confirmations: type: integer description: Number of block confirmations @@ -3414,9 +3860,7 @@ components: items: properties: payment_address: - type: string - description: A Cardano payment/base address (bech32 encoded) for transaction's input UTxO - example: addr1qxkfe8s6m8qt5436lec3f0320hrmpppwqgs2gah4360krvyssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqdc3cxp + $ref: "#/components/schemas/utxo_infos/items/properties/address" quantity: type: string description: Asset balance on the payment address @@ -3427,7 +3871,7 @@ components: items: properties: payment_address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" asset_summary: type: array items: @@ -3519,6 +3963,11 @@ components: decimals: type: integer example: 0 + cip68_metadata: + type: object + description: CIP 68 metadata if present for asset + nullable: true + example: {"222": {"fields": [{"map": [{"k": {"bytes": "6e616d65"}, "v": {"bytes": "74657374"}}]}], "constructor": 0}} asset_history: type: array items: @@ -3559,7 +4008,7 @@ components: asset_name: $ref: "#/components/schemas/asset_info/items/properties/asset_name" payment_address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" quantity: $ref: "#/components/schemas/asset_addresses/items/properties/quantity" policy_asset_info: @@ -3599,67 +4048,65 @@ components: total_supply: $ref: "#/components/schemas/asset_info/items/properties/total_supply" decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" - asset_txs: - type: array - description: An array of Tx hashes that included the given asset (latest first) - items: - properties: - tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" - epoch_no: - $ref: "#/components/schemas/blocks/items/properties/epoch_no" - block_height: - $ref: "#/components/schemas/blocks/items/properties/block_height" - block_time: - $ref: "#/components/schemas/blocks/items/properties/block_time" - native_script_list: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + script_info: type: array items: properties: script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + type: string + description: Hash of a script + example: bfa7ffa9b2e164873db6ac6d0528c82e212963bc62e10fd1d81da4af creation_tx_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/creation_tx_hash" + type: string + description: Hash of the script creation transaction + example: 255f061502ad83230351fbcf2d9fade1b5d118d332f92c9861075010a1fe3fbe type: type: string description: Type of the script - enum: ["timelock", "multisig"] - example: timelock - plutus_script_list: + enum: ["plutusV1","plutusV2","timelock","multisig"] + example: plutusV1 + value: + type: object + nullable: true + description: Data in JSON format + example: null + bytes: + type: string + description: Script bytes (cborSeq) + example: 5907f4010000332323232323232323233223232323232332232323232322223232533532533533355300712001323212330012233350052200200200100235001220011233001225335002101710010142325335333573466e3cd400488008d4020880080580544ccd5cd19b873500122001350082200101601510153500122002353500122002222222222200a101413357389201115554784f206e6f7420636f6e73756d6564000133333573466e1cd55cea8012400046644246600200600464646464646464646464646666ae68cdc39aab9d500a480008cccccccccc888888888848cccccccccc00402c02802402001c01801401000c008cd40508c8c8cccd5cd19b8735573aa0049000119910919800801801180f9aba150023019357426ae8940088c98d4cd5ce01581501481409aab9e5001137540026ae854028cd4050054d5d0a804999aa80bbae501635742a010666aa02eeb94058d5d0a80399a80a0109aba15006335014335502402275a6ae854014c8c8c8cccd5cd19b8735573aa00490001199109198008018011919191999ab9a3370e6aae754009200023322123300100300233502575a6ae854008c098d5d09aba2500223263533573805e05c05a05826aae7940044dd50009aba150023232323333573466e1cd55cea8012400046644246600200600466a04aeb4d5d0a80118131aba135744a004464c6a66ae700bc0b80b40b04d55cf280089baa001357426ae8940088c98d4cd5ce01581501481409aab9e5001137540026ae854010cd4051d71aba15003335014335502475c40026ae854008c070d5d09aba2500223263533573804e04c04a04826ae8940044d5d1280089aba25001135744a00226ae8940044d5d1280089aba25001135744a00226aae7940044dd50009aba150023232323333573466e1d400520062321222230040053019357426aae79400c8cccd5cd19b875002480108c848888c008014c06cd5d09aab9e500423333573466e1d400d20022321222230010053015357426aae7940148cccd5cd19b875004480008c848888c00c014dd71aba135573ca00c464c6a66ae7008808408007c0780740704d55cea80089baa001357426ae8940088c98d4cd5ce00d80d00c80c080c89931a99ab9c4910350543500019018135573ca00226ea8004c8004d5405888448894cd40044d400c88004884ccd401488008c010008ccd54c01c4800401401000448c88c008dd6000990009aa80b111999aab9f00125009233500830043574200460066ae880080548c8c8c8cccd5cd19b8735573aa00690001199911091998008020018011919191999ab9a3370e6aae7540092000233221233001003002301735742a00466a01c02c6ae84d5d1280111931a99ab9c01b01a019018135573ca00226ea8004d5d0a801999aa803bae500635742a00466a014eb8d5d09aba2500223263533573802e02c02a02826ae8940044d55cf280089baa0011335500175ceb44488c88c008dd5800990009aa80a11191999aab9f0022500823350073355017300635573aa004600a6aae794008c010d5d100180a09aba100111220021221223300100400312232323333573466e1d4005200023212230020033005357426aae79400c8cccd5cd19b8750024800884880048c98d4cd5ce00980900880800789aab9d500113754002464646666ae68cdc39aab9d5002480008cc8848cc00400c008c014d5d0a8011bad357426ae8940088c98d4cd5ce00800780700689aab9e5001137540024646666ae68cdc39aab9d5001480008dd71aba135573ca004464c6a66ae7003803403002c4dd500089119191999ab9a3370ea00290021091100091999ab9a3370ea00490011190911180180218031aba135573ca00846666ae68cdc3a801a400042444004464c6a66ae7004404003c0380340304d55cea80089baa0012323333573466e1d40052002200523333573466e1d40092000200523263533573801a01801601401226aae74dd5000891001091000919191919191999ab9a3370ea002900610911111100191999ab9a3370ea004900510911111100211999ab9a3370ea00690041199109111111198008048041bae35742a00a6eb4d5d09aba2500523333573466e1d40112006233221222222233002009008375c6ae85401cdd71aba135744a00e46666ae68cdc3a802a400846644244444446600c01201060186ae854024dd71aba135744a01246666ae68cdc3a8032400446424444444600e010601a6ae84d55cf280591999ab9a3370ea00e900011909111111180280418071aba135573ca018464c6a66ae7004c04804404003c03803403002c0284d55cea80209aab9e5003135573ca00426aae7940044dd50009191919191999ab9a3370ea002900111999110911998008028020019bad35742a0086eb4d5d0a8019bad357426ae89400c8cccd5cd19b875002480008c8488c00800cc020d5d09aab9e500623263533573801801601401201026aae75400c4d5d1280089aab9e500113754002464646666ae68cdc3a800a400446424460020066eb8d5d09aab9e500323333573466e1d400920002321223002003375c6ae84d55cf280211931a99ab9c009008007006005135573aa00226ea800444888c8c8cccd5cd19b8735573aa0049000119aa80518031aba150023005357426ae8940088c98d4cd5ce00480400380309aab9e5001137540029309000a490350543100112212330010030021123230010012233003300200200133512233002489209366f09fe40eaaeb17d3cb6b0b61e087d664174c39a48a986f86b2b0ba6e2a7b00480008848cc00400c0088005 + size: + type: integer + description: The size of the CBOR serialised script (in bytes) + example: 2039 + script_list: type: array items: properties: script_hash: - type: string - description: Hash of a script - example: d8480dc869b94b80e81ec91b0abe307279311fe0e7001a9488f61ff8 + $ref: "#/components/schemas/script_info/items/properties/script_hash" creation_tx_hash: - type: string - description: Hash of the script creation transaction - example: fda6c7697009237975ffc30f36666addf4c6e2a2c6f90411a24431b700baaab1 + $ref: "#/components/schemas/script_info/items/properties/creation_tx_hash" + type: + $ref: "#/components/schemas/script_info/items/properties/type" + size: + $ref: "#/components/schemas/script_info/items/properties/size" script_redeemers: type: array items: type: object properties: script_hash: - type: string - description: Hash of Transaction for which details are being shown - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/script_info/items/properties/script_hash" redeemers: type: array items: type: object properties: tx_hash: - type: string - description: Hash of Transaction containing the redeemer - example: fda6c7697009237975ffc30f36666addf4c6e2a2c6f90411a24431b700baaab1 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: The index of the redeemer pointer in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" unit_mem: description: The budget in Memory to run a script example: 520448 @@ -3691,20 +4138,20 @@ components: nullable: true example: 5a595ce795815e81d22a1a522cf3987d546dc5bb016de61b002edd63a5413ec4 datum_value: - type: object - description: The actual data in json format - example: { "bytes": "3c33" } + $ref: "#/components/schemas/script_info/items/properties/value" datum_info: type: array items: type: object properties: - hash: + datum_hash: $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_hash" + creation_tx_hash: + $ref: "#/components/schemas/script_info/items/properties/creation_tx_hash" value: - $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_value" + $ref: "#/components/schemas/script_info/items/properties/value" bytes: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/inline_datum/properties/bytes" + $ref: "#/components/schemas/script_info/items/properties/bytes" headers: {} responses: OK: @@ -3712,7 +4159,7 @@ components: NotFound: description: The server does not recognise the combination of endpoint and parameters provided Unauthorized: - description: The selected server has restricted the endpoint to be only usable via authentication. The authentication supplied was not authorized to access the endpoint + description: Access token is missing or invalid PartialContent: description: The result was truncated BadRequest: @@ -3730,12 +4177,12 @@ tags: - name: Transactions description: Query blockchain transaction details x-tag-expanded: false + - name: Stake Account + description: Query details about specific stake account addresses + x-tag-expanded: false - name: Address description: Query information about specific address(es) x-tag-expanded: false - - name: Account - description: Query details about specific stake account addresses - x-tag-expanded: false - name: Asset description: Query Asset related informations x-tag-expanded: false @@ -3745,4 +4192,5 @@ tags: - name: Script description: Query information about specific scripts (Smart Contracts) x-tag-expanded: false -security: [] +security: + - bearerAuth: [] diff --git a/specs/results/koiosapi-preprod.yaml b/specs/results/koiosapi-preprod.yaml index 6d956f7c..222bbe72 100644 --- a/specs/results/koiosapi-preprod.yaml +++ b/specs/results/koiosapi-preprod.yaml @@ -1,7 +1,7 @@ openapi: 3.0.2 info: title: Koios API - version: 1.0.10 + version: v1.1.0rc description: | Koios is best described as a Decentralized and Elastic RESTful query layer for exploring data on Cardano blockchain to consume within applications/wallets/explorers/etc. This page not only provides an OpenAPI Spec for live implementation, but also ability to execute live demo from client browser against each endpoint with pre-filled examples. @@ -14,11 +14,11 @@ info: Instead of returning entire row, you can elect which rows you would like to fetch from the endpoint by using the `select` parameter with corresponding columns separated by commas. See example below (first is complete information for tip, while second command gives us 3 columns we are interested in):

``` bash - curl "https://api.koios.rest/api/v0/tip" + curl "https://api.koios.rest/api/v1/tip" # [{"hash":"4d44c8a453e677f933c3df42ebcf2fe45987c41268b9cfc9b42ae305e8c3d99a","epoch":317,"abs_slot":51700871,"epoch_slot":120071,"block_height":6806994,"block_time":1643267162}] - curl "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_height" + curl "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_height" # [{"epoch":317,"epoch_slot":120071,"block_height":6806994}] ``` @@ -27,7 +27,7 @@ info: You can filter the returned output based on specific conditions using operators against a column within returned result. Consider an example where you would want to query blocks minted in first 3 minutes of epoch 250 (i.e. epoch_slot was less than 180). To do so your query would look like below:

``` bash - curl "https://api.koios.rest/api/v0/blocks?epoch=eq.250&epoch_slot=lt.180" + curl "https://api.koios.rest/api/v1/blocks?epoch=eq.250&epoch_slot=lt.180" # [{"hash":"8fad2808ac6b37064a0fa69f6fe065807703d5235a57442647bbcdba1c02faf8","epoch":250,"abs_slot":22636942,"epoch_slot":142,"block_height":5385757,"block_time":1614203233,"tx_count":65,"vrf_key":"vrf_vk14y9pjprzlsjvjt66mv5u7w7292sxp3kn4ewhss45ayjga5vurgaqhqknuu","pool":null,"op_cert_counter":2}, # {"hash":"9d33b02badaedc0dedd0d59f3e0411e5fb4ac94217fb5ee86719e8463c570e16","epoch":250,"abs_slot":22636800,"epoch_slot":0,"block_height":5385756,"block_time":1614203091,"tx_count":10,"vrf_key":"vrf_vk1dkfsejw3h2k7tnguwrauqfwnxa7wj3nkp3yw2yw3400c4nlkluwqzwvka6","pool":null,"op_cert_counter":2}] @@ -62,7 +62,7 @@ info: Consider a simple case where I want query `blocks` endpoint for `block_height` column and focus on `content-range` header to monitor the rows we discussed above.

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height" -I | grep -i content-range # content-range: 0-999/* @@ -71,7 +71,7 @@ info: As we can see above, the number of observations returned was 1000 (range being 0-999), but the total size was not queried to avoid wait times. Now, let's modify this default behaviour to query rows beyond the first 999, but this time - also add another clause to limit results by 500. We can do this using `offset=1000` and `limit=500` as below:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height&offset=1000&limit=500" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height&offset=1000&limit=500" -I | grep -i content-range # content-range: 1000-1499/* @@ -80,7 +80,7 @@ info: For GET endpoints, there is also another method to achieve the above, instead of adding parameters to the URL itself, you can specify a `Range` header as below to achieve something similar:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height" -H "Range: 1000-1499" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height" -H "Range: 1000-1499" -I | grep -i content-range # content-range: 1000-1499/* @@ -94,7 +94,7 @@ info: Consider example where you want to check `epoch` and `epoch_slot` for the first 5 blocks created by a particular pool, i.e. you can set order to ascending based on block_height column and add horizontal filter for that pool ID as below:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?pool=eq.pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc&order=block_height.asc&limit=5" + curl -s "https://api.koios.rest/api/v1/blocks?pool=eq.pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc&order=block_height.asc&limit=5" # [{"hash":"610b4c7bbebeeb212bd002885048cc33154ba29f39919d62a3d96de05d315706","epoch":236,"abs_slot":16594295,"epoch_slot":5495,"block_height":5086774,"block_time":1608160586,"tx_count":1,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1}, # {"hash":"d93d1db5275329ab695d30c06a35124038d8d9af64fc2b0aa082b8aa43da4164","epoch":236,"abs_slot":16597729,"epoch_slot":8929,"block_height":5086944,"block_time":1608164020,"tx_count":7,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1}, @@ -109,13 +109,13 @@ info: Below is an example of JSON/CSV output making use of above to print first in JSON (default), and then override response format to CSV.

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_time&limit=3" + curl -s "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_time&limit=3" # [{"epoch":318,"epoch_slot":27867,"block_time":1643606958}, # {"epoch":318,"epoch_slot":27841,"block_time":1643606932}, # {"epoch":318,"epoch_slot":27839,"block_time":1643606930}] - curl -s "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_time&limit=3" -H "Accept: text/csv" + curl -s "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_time&limit=3" -H "Accept: text/csv" # epoch,epoch_slot,block_time # 318,28491,1643607582 @@ -134,6 +134,10 @@ info: Yet, there may be cases where the above restrictions may need exceptions (for example, an explorer or a wallet might need more connections than above - going beyond the Burst Limit). For such cases, it is best to approach the team and we can work towards a solution. + # Authentication + + While Koios public tier remains unauthenticated and allows queries without any authentication, it has low limits to prevent actions against an erroraneous query/loop from a consumer. There is also a Free tier which requires setting up Bearer Auth token that is linked to the owner's wallet account (which can be connected to via [Koios website](https://koios.rest/pricing/Pricing.html) ). + The examples across this API site already [supports authentication](/#auth), for you to use in the queries. # Community projects @@ -142,11 +146,12 @@ info: x-logo: url: "https://api.koios.rest/images/koios.png" servers: - - url: https://api.koios.rest/api/v0 - - url: https://guild.koios.rest/api/v0 - - url: https://preview.koios.rest/api/v0 - - url: https://preprod.koios.rest/api/v0 + - url: https://api.koios.rest/api/v1 + - url: https://guild.koios.rest/api/v1 + - url: https://preview.koios.rest/api/v1 + - url: https://preprod.koios.rest/api/v1 paths: + /tip: #RPC get: tags: @@ -227,6 +232,45 @@ paths: $ref: "#/components/responses/NotFound" summary: Param Update Proposals description: Get all parameter update proposals submitted to the chain starting Shelley era + /reserve_withdrawals: #RPC + get: + tags: + - Network + responses: + "200": + description: Array of withdrawals from reserves against stake accounts + content: + application/json: + schema: + $ref: "#/components/schemas/reserve_withdrawals" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Reserve Withdrawals + description: List of all withdrawals from reserves against stake accounts + /treasury_withdrawals: #RPC + get: + tags: + - Network + responses: + "200": + description: Array of withdrawals from treasury against stake accounts + content: + application/json: + schema: + $ref: "#/components/schemas/reserve_withdrawals" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Treasury Withdrawals + description: List of all withdrawals from treasury against stake accounts + /epoch_info: #RPC get: tags: @@ -294,6 +338,7 @@ paths: summary: Epoch's Block Protocols description: >- Get the information about block protocol distribution in epoch + /blocks: get: tags: @@ -355,28 +400,29 @@ paths: $ref: "#/components/responses/NotFound" summary: Block Transactions description: Get a list of all transactions included in provided blocks - /tx_info: #RPC + + /utxo_info: #RPC post: tags: - Transactions requestBody: - $ref: "#/components/requestBodies/tx_ids" + $ref: "#/components/requestBodies/utxo_refs_with_extended" responses: "200": - description: Array of detailed information about transaction(s) + description: Array of UTXO details content: application/json: schema: - $ref: "#/components/schemas/tx_info" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction Information - description: Get detailed information about transaction(s) - /tx_utxos: #RPC + summary: UTxO Info + description: Get UTxO set for requested UTxO references + /tx_info: #RPC post: tags: - Transactions @@ -384,19 +430,19 @@ paths: $ref: "#/components/requestBodies/tx_ids" responses: "200": - description: Array of inputs and outputs for given transaction(s) + description: Array of detailed information about transaction(s) content: application/json: schema: - $ref: "#/components/schemas/tx_utxos" + $ref: "#/components/schemas/tx_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction UTxOs [DEPRECATED] - description: Get UTxO set (inputs/outputs) of transactions. + summary: Transaction Information + description: Get detailed information about transaction(s) /tx_metadata: #RPC post: tags: @@ -450,7 +496,7 @@ paths: # If using a CLI-generated tx file, please ensure to deserialise (using `xxd -p -r <<< $(jq .cborHex ${tx.signed}) > ${data}`) first before submitting. curl -X POST \ --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/v0/submittx + --data-binary @${data} https://api.koios.rest/api/v1/submittx responses: "202": description: OK @@ -486,8 +532,31 @@ paths: $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction Status (Block Confirmations) + summary: Transaction Status description: Get the number of block confirmations for a given transaction hash list + /tx_utxos: #RPC + post: + tags: + - Transactions + deprecated: true + requestBody: + $ref: "#/components/requestBodies/tx_ids" + responses: + "200": + description: Array of inputs and outputs for given transaction(s) + content: + application/json: + schema: + $ref: "#/components/schemas/tx_utxos" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Transaction UTxOs + description: Get UTxO set (inputs/outputs) of transactions [DEPRECATED - Use /utxo_info instead]. + /address_info: #RPC post: tags: @@ -509,27 +578,27 @@ paths: $ref: "#/components/responses/NotFound" summary: Address Information description: Get address info - balance, associated stake address (if any) and UTxO set for given addresses - /address_txs: #RPC + /address_utxos: #RPC post: tags: - Address requestBody: - $ref: "#/components/requestBodies/address_txs" + $ref: "#/components/requestBodies/payment_addresses_with_extended" responses: "200": - description: Array of transaction hashes + description: Array of address UTXOs content: application/json: schema: - $ref: "#/components/schemas/address_txs" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Address Transactions - description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive) + summary: Address UTXOs + description: Get UTxO set for given addresses /credential_utxos: #RPC post: tags: @@ -542,7 +611,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/credential_utxos" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": @@ -550,28 +619,28 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: UTxOs from payment credentials - description: Get a list of UTxO against input payment credential array including their balances - /address_assets: #RPC + description: Get UTxO details for requested payment credentials + /address_txs: #RPC post: tags: - Address requestBody: - $ref: "#/components/requestBodies/payment_addresses" + $ref: "#/components/requestBodies/address_txs" responses: "200": - description: Array of address-owned assets + description: Array of transaction hashes content: application/json: schema: - $ref: "#/components/schemas/address_assets" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Address Assets - description: Get the list of all the assets (policy, name and quantity) for given addresses + summary: Address Transactions + description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive) /credential_txs: #RPC post: tags: @@ -584,7 +653,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/credential_txs" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": @@ -593,6 +662,28 @@ paths: $ref: "#/components/responses/NotFound" summary: Transactions from payment credentials description: Get the transaction hash list of input payment credential array, optionally filtering after specified block height (inclusive) + /address_assets: #RPC + post: + tags: + - Address + requestBody: + $ref: "#/components/requestBodies/payment_addresses" + responses: + "200": + description: Array of address-owned assets + content: + application/json: + schema: + $ref: "#/components/schemas/address_assets" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Address Assets + description: Get the list of all the assets (policy, name and quantity) for given addresses + /account_list: get: tags: @@ -633,48 +724,70 @@ paths: $ref: "#/components/responses/NotFound" summary: Account Information description: Get the account information for given stake addresses - /account_utxos: #RPC - get: + /account_info_cached: #RPC + post: tags: - Stake Account - parameters: - - $ref: "#/components/parameters/_stake_address" + requestBody: + $ref: "#/components/requestBodies/stake_addresses" responses: "200": - description: Array of account UTxOs associated with stake address + description: Array of account information content: application/json: schema: - $ref: "#/components/schemas/account_utxos" + $ref: "#/components/schemas/account_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Account UTxOs - description: Get a list of all UTxOs for a given stake address (account) - /account_info_cached: #RPC + summary: Account Information (Cached) + description: Get the cached account information for given stake addresses (effective for performance query against registered accounts) + /account_utxos: #RPC post: tags: - Stake Account requestBody: - $ref: "#/components/requestBodies/stake_addresses" + $ref: "#/components/requestBodies/stake_addresses_with_extended" responses: "200": - description: Array of account information + description: Array of account UTxOs associated with given stake addresses content: application/json: schema: - $ref: "#/components/schemas/account_info" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Account Information (Cached) - description: Get the cached account information for given stake addresses, effective for registered accounts + summary: UTxOs for stake addresses (accounts) + description: Get a list of all UTxOs for given stake addresses (account)s + /account_txs: #RPC + get: + tags: + - Stake Account + parameters: + - $ref: "#/components/parameters/_stake_address" + - $ref: "#/components/parameters/_after_block_height" + responses: + "200": + description: Array of Txs associated with stake address (account) + content: + application/json: + schema: + $ref: "#/components/schemas/address_txs" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Account Txs + description: Get a list of all Txs for a given stake address (account) /account_rewards: #RPC post: tags: @@ -783,6 +896,7 @@ paths: $ref: "#/components/responses/NotFound" summary: Account History description: Get the staking history of given stake addresses (accounts) + /asset_list: get: tags: @@ -802,95 +916,89 @@ paths: $ref: "#/components/responses/NotFound" summary: Asset List description: Get the list of all native assets (paginated) - /asset_token_registry: + /policy_asset_list: #RPC get: tags: - Asset + parameters: + - $ref: "#/components/parameters/_asset_policy" responses: "200": - description: Array of token registry information for each asset + description: Array of detailed information of assets under the same policy content: application/json: schema: - $ref: "#/components/schemas/asset_token_registry" + $ref: "#/components/schemas/policy_asset_list" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Token Registry - description: Get a list of assets registered via token registry on github - /asset_addresses: #RPC + summary: Policy Asset List + description: Get the list of asset under the given policy (including balances) + /asset_token_registry: get: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of payment addresses holding the given token (including balances) + description: Array of token registry information for each asset content: application/json: schema: - $ref: "#/components/schemas/asset_addresses" + $ref: "#/components/schemas/asset_token_registry" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Addresses - description: Get the list of all addresses holding a given asset

- `Note - Due to cardano's UTxO design and usage from projects, asset to addresses map can be infinite. Thus, for a small subset of active projects - with millions of transactions, these might end up with timeouts (HTTP code 504) on free layer. Such large-scale projects are free to subscribe to - query layers to have a dedicated cache table for themselves served via Koios.` - /asset_address_list: #RPC - get: + summary: Asset Token Registry + description: Get a list of assets registered via token registry on github + /asset_info: #RPC + post: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" + requestBody: + $ref: "#/components/requestBodies/asset_list" responses: "200": - description: Array of payment addresses holding the given token (including balances) + description: Array of detailed asset information content: application/json: schema: - $ref: "#/components/schemas/asset_addresses" + $ref: "#/components/schemas/asset_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Address List [DEPRECATED] - description: Get the list of all addresses holding a given asset (replaced by asset_addresses) - /asset_nft_address: #RPC - get: + summary: Asset Information (Bulk) + description: Get the information of a list of assets including first minting & token registry metadata + /asset_utxos: #RPC + post: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy_nft" - - $ref: "#/components/parameters/_asset_name_nft" + requestBody: + $ref: "#/components/requestBodies/asset_list_with_extended" responses: "200": - description: Payment addresses currently holding the given NFT + description: Array of UTXOs for given asset list content: application/json: schema: - $ref: "#/components/schemas/asset_nft_address" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: NFT Address - description: Get the address where specified NFT currently reside on. - /asset_info: #RPC + summary: Asset UTXOs + description: Get the UTXO information of a list of assets including + /asset_history: #RPC get: tags: - Asset @@ -899,61 +1007,66 @@ paths: - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed asset information + description: Array of asset mint/burn history content: application/json: schema: - $ref: "#/components/schemas/asset_info" + $ref: "#/components/schemas/asset_history" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Information - description: Get the information of an asset including first minting & token registry metadata - post: + summary: Asset History + description: Get the mint/burn history of an asset + /asset_addresses: #RPC + get: tags: - Asset - requestBody: - $ref: "#/components/requestBodies/asset_list" + parameters: + - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed asset information + description: Array of payment addresses holding the given token (including balances) content: application/json: schema: - $ref: "#/components/schemas/asset_info" + $ref: "#/components/schemas/asset_addresses" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Information (Bulk) - description: Get the information of a list of assets including first minting & token registry metadata - /asset_history: #RPC + summary: Asset Addresses + description: Get the list of all addresses holding a given asset

+ `Note - Due to cardano's UTxO design and usage from projects, asset to addresses map can be infinite. Thus, for a small subset of active projects + with millions of transactions, these might end up with timeouts (HTTP code 504) on free layer. Such large-scale projects are free to subscribe to + query layers to have a dedicated cache table for themselves served via Koios.` + /asset_nft_address: #RPC get: tags: - Asset parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" + - $ref: "#/components/parameters/_asset_policy_nft" + - $ref: "#/components/parameters/_asset_name_nft" responses: "200": - description: Array of asset mint/burn history + description: Payment addresses currently holding the given NFT content: application/json: schema: - $ref: "#/components/schemas/asset_history" + $ref: "#/components/schemas/asset_nft_address" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset History - description: Get the mint/burn history of an asset + summary: NFT Address + description: Get the address where specified NFT currently reside on. /policy_asset_addresses: #RPC get: tags: @@ -999,94 +1112,98 @@ paths: $ref: "#/components/responses/NotFound" summary: Policy Asset Information description: Get the information for all assets under the same policy - /asset_policy_info: #RPC + /asset_summary: #RPC get: tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed information of assets under the same policy + description: Array of asset summary information content: application/json: schema: - $ref: "#/components/schemas/policy_asset_info" + $ref: "#/components/schemas/asset_summary" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Policy Information [DEPRECATED] - description: Get the information for all assets under the same policy (replaced by asset_addresses) - /policy_asset_list: #RPC + summary: Asset Summary + description: Get the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance) + /asset_txs: #RPC get: tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" + - $ref: "#/components/parameters/_after_block_height" + - $ref: "#/components/parameters/_history" responses: "200": - description: Array of detailed information of assets under the same policy + description: An array of Tx hashes that included the given asset (latest first) content: application/json: schema: - $ref: "#/components/schemas/policy_asset_list" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Policy Asset List - description: Get the list of asset under the given policy (including balances) - /asset_summary: #RPC + summary: Asset Transactions + description: Get the list of current or all asset transaction hashes (newest first) + /asset_address_list: #RPC get: tags: - Asset + deprecated: true parameters: - $ref: "#/components/parameters/_asset_policy" - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of asset summary information + description: Array of payment addresses holding the given token (including balances) content: application/json: schema: - $ref: "#/components/schemas/asset_summary" + $ref: "#/components/schemas/asset_addresses" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Summary - description: Get the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance) - /asset_txs: #RPC + summary: Asset Address List + description: Get the list of all addresses holding a given asset [DEPRECATED - replaced by asset_addresses] + /asset_policy_info: #RPC get: + deprecated: true tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" - - $ref: "#/components/parameters/_after_block_height" - - $ref: "#/components/parameters/_history" responses: "200": - description: Array of Tx hashes that included the given asset + description: Array of detailed information of assets under the same policy content: application/json: schema: - $ref: "#/components/schemas/asset_txs" + $ref: "#/components/schemas/policy_asset_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Transactions - description: Get the list of current or all asset transaction hashes (newest first) + summary: Asset Policy Information + description: Get the information for all assets under the same policy (DEPRECATED - replaced by policy_asset_info) + /pool_list: #RPC get: tags: @@ -1105,7 +1222,7 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool List - description: A list of all currently registered/retiring (not retired) pools + description: List of brief info for all pools /pool_info: #RPC post: tags: @@ -1261,6 +1378,48 @@ paths: $ref: "#/components/responses/NotFound" summary: Pool Updates (History) description: Return all pool updates for all pools or only updates for specific pool if specified + /pool_registrations: #RPC + get: + tags: + - Pool + parameters: + - $ref: "#/components/parameters/_epoch_no" + responses: + "200": + description: Array of historical pool updates + content: + application/json: + schema: + $ref: "#/components/schemas/pool_registrations" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Pool Registrations + description: Return all pool registrations initiated in the requested epoch + /pool_retirements: #RPC + get: + tags: + - Pool + parameters: + - $ref: "#/components/parameters/_epoch_no" + responses: + "200": + description: Array of historical pool updates + content: + application/json: + schema: + $ref: "#/components/schemas/pool_registrations" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Pool Retirements + description: Return all pool retirements initiated in the requested epoch /pool_relays: #RPC get: tags: @@ -1279,7 +1438,7 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool Relays - description: A list of registered relays for all currently registered/retiring (not retired) pools + description: A list of registered relays for all pools /pool_metadata: #RPC post: tags: @@ -1300,7 +1459,29 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool Metadata - description: Metadata (on & off-chain) for all currently registered/retiring (not retired) pools + description: Metadata (on & off-chain) for all pools + + /script_info: #RPC + post: + tags: + - Script + requestBody: + $ref: "#/components/requestBodies/script_hashes" + responses: + "200": + description: List of datum information for given datum hashes + content: + application/json: + schema: + $ref: "#/components/schemas/script_info" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Datum Information + description: List of datum information for given datum hashes /native_script_list: #RPC get: tags: @@ -1311,7 +1492,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/native_script_list" + $ref: "#/components/schemas/script_list" "400": $ref: "#/components/responses/BadRequest" "401": @@ -1330,7 +1511,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/plutus_script_list" + $ref: "#/components/schemas/script_list" "400": $ref: "#/components/responses/BadRequest" "401": @@ -1360,6 +1541,28 @@ paths: $ref: "#/components/responses/NotFound" summary: Script Redeemers description: List of all redeemers for a given script hash + /script_utxos: #RPC + get: + tags: + - Script + parameters: + - $ref: "#/components/parameters/_script_hash" + - $ref: "#/components/parameters/_extended" + responses: + "200": + description: List of UTXOs for a given script hash + content: + application/json: + schema: + $ref: "#/components/schemas/utxo_infos" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Script UTXOs + description: List of all UTXOs for a given script hash /datum_info: #RPC post: tags: @@ -1381,6 +1584,43 @@ paths: $ref: "#/components/responses/NotFound" summary: Datum Information description: List of datum information for given datum hashes + /ogmios/?EvaluateTransaction: #ogmios-api + post: + tags: + - Ogmios + x-code-samples: + - lang: "Shell" + source: | + # Assuming ${data} contains EvaluateTransaction payload as documented on Ogmios v6 site. + curl -X POST \ + --header "Content-Type: application/cbor" \ + --data-binary ${data} https://api.koios.rest/api/ogmios/?EvaluateTransaction + responses: + "200": + description: OK + "400": + description: An error occured while submitting transaction. + summary: Evaluate Transaction + description: Evaluate execution units of scripts in a well-formed transaction. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?EvaluateTransaction) for complete spec + /ogmios/?SubmitTransaction: #ogmios-api + post: + tags: + - Ogmios + x-code-samples: + - lang: "Shell" + source: | + # Assuming ${data} contains a CBOR-serialized signed transaction (base16-encoded) as documented on Ogmios v6 site. + curl -X POST \ + --header "Content-Type: application/cbor" \ + --data-binary ${data} https://api.koios.rest/api/ogmios/?SubmitTransaction + responses: + "200": + description: OK + "400": + description: An error occured while querying transaction. + summary: Submit Transaction + description: Submit a signed and serialized transaction to the network. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?SubmitTransaction) for complete spec + components: parameters: select: @@ -1554,6 +1794,16 @@ components: in: query required: false allowEmptyValue: true + _extended: + deprecated: false + name: _extended + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + schema: + type: boolean + example: "false" + in: query + required: false + allowEmptyValue: true _history: deprecated: false name: _history @@ -1661,6 +1911,29 @@ components: _addresses: - addr_test1vzpwq95z3xyum8vqndgdd9mdnmafh3djcxnc6jemlgdmswcve6tkw - addr_test1vpfwv0ezc5g8a4mkku8hhy3y3vp92t7s3ul8g778g5yegsgalc6gc + payment_addresses_with_extended: + content: + application/json: + schema: + required: + - _addresses + type: object + properties: + _addresses: + format: text + type: array + items: + type: string + description: Array of Cardano payment address(es) in bech32 format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _addresses: + - addr_test1vzpwq95z3xyum8vqndgdd9mdnmafh3djcxnc6jemlgdmswcve6tkw + - addr_test1vpfwv0ezc5g8a4mkku8hhy3y3vp92t7s3ul8g778g5yegsgalc6gc + _extended: true address_txs: content: application/json: @@ -1733,6 +2006,32 @@ components: _stake_addresses: - stake_test1urq4rcynzj4uxqc74c852zky7wa6epgmn9r6k3j3gv7502q8jks0l - stake_test1ur4t5nhceyn2amfuj7z74uxmmj8jf9fmgd2egqw8c98ve3cp2g4wx + _first_only: false + _empty: false + + stake_addresses_with_extended: + content: + application/json: + schema: + required: + - _stake_addresses + type: object + properties: + _stake_addresses: + format: text + type: array + items: + type: string + description: Array of Cardano stake address(es) in bech32 format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _stake_addresses: + - stake_test1urq4rcynzj4uxqc74c852zky7wa6epgmn9r6k3j3gv7502q8jks0l + - stake_test1ur4t5nhceyn2amfuj7z74uxmmj8jf9fmgd2egqw8c98ve3cp2g4wx + _extended: true stake_addresses: content: application/json: @@ -1788,10 +2087,15 @@ components: items: type: string description: Array of Cardano payment credential(s) in hex format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call example: _payment_credentials: - b429738bd6cc58b5c7932d001aa2bd05cfea47020a556c8c753d4436 - 82e016828989cd9d809b50d6976d9efa9bc5b2c1a78d4b3bfa1bb83b + _extended: true tx_ids: content: application/json: @@ -1853,6 +2157,22 @@ components: - pool1ext7qrwjzaxcdfhdnkq5mth59ukuu2atcg6tgqpmevpt7ratkta - pool1x4p3cwemsm356vpxnjwuud7w76jz64hyss729zp7xa6wuey6yr9 - pool1ws42l6rawqjv58crs5l32v0eem3qnngpnjfd7epwd4lmjccc5cg + script_hashes: + content: + application/json: + schema: + type: object + properties: + _script_hashes: + format: text + type: array + items: + type: string + description: Array of Cardano script hashes + example: + _script_hashes: + - a8e9f8f34fd631b1d5b9f41a90f4abc0d3935cea7baba0bb34c96f59 + - b4fd6dfe4a643aeec5d75dbb1f27198fc2aabf30bf92ed5470253792 datum_hashes: content: application/json: @@ -1866,10 +2186,30 @@ components: type: string description: Array of Cardano datum hashes example: - _datum_hashes: - - 5571e2c3549f15934a38382d1318707a86751fb70827f4cbd29b104480f1be9b - - 5f7212f546d7e7308ce99b925f05538db19981f4ea3084559c0b28a363245826 - asset_list: + _datum_hashes: + - 5571e2c3549f15934a38382d1318707a86751fb70827f4cbd29b104480f1be9b + - 5f7212f546d7e7308ce99b925f05538db19981f4ea3084559c0b28a363245826 + asset_list: + content: + application/json: + schema: + required: + - _asset_list + type: object + properties: + _asset_list: + format: text + type: array + description: Array of array of policy ID and asset names (hex) + items: + type: array + items: + type: string + example: + _asset_list: + - ['c6e65ba7878b2f8ea0ad39287d3e2fd256dc5c4160fc19bdf4c4d87e','7447454e53'] + - ['777e6b4903dab74963ae581d39875c5dac16c09bb1f511c0af1ddda8','6141414441'] + asset_list_with_extended: content: application/json: schema: @@ -1885,11 +2225,43 @@ components: type: array items: type: string + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call example: _asset_list: - ['c6e65ba7878b2f8ea0ad39287d3e2fd256dc5c4160fc19bdf4c4d87e','7447454e53'] - ['777e6b4903dab74963ae581d39875c5dac16c09bb1f511c0af1ddda8','6141414441'] - securitySchemes: {} + _extended: true + utxo_refs_with_extended: + content: + application/json: + schema: + required: + - _utxo_refs + type: object + properties: + _utxo_refs: + format: text + type: array + items: + type: string + description: Array of Cardano utxo references in the form "hash#index" + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _utxo_refs: + - d10133964da9e443b303917fd0b7644ae3d01c133deff85b4f59416c2d00f530#0 + - 145688d3619e7524510ea64c0ec6363b77a9b8da179ef9bb0273a0940d57d576#0 + _extended: false + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT schemas: tip: type: array @@ -2003,20 +2375,59 @@ components: type: string description: JSON encoded data with details about the parameter update example: {"decentralisation": 0.9} + reserve_withdrawals: + type: array + items: + properties: + epoch_no: + $ref: "#/components/schemas/epoch_info/items/properties/epoch_no" + epoch_slot: + $ref: "#/components/schemas/blocks/items/properties/epoch_slot" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + block_hash: + $ref: "#/components/schemas/blocks/items/properties/hash" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + amount: + $ref: "#/components/schemas/pool_delegators/items/properties/amount" + stake_address: + $ref: "#/components/schemas/account_history/items/properties/stake_address" pool_list: type: array items: properties: pool_id_bech32: - type: string - nullable: true - description: Bech32 representation of pool ID - example: pool1z5uqdk7dzdxaae5633fqfcu2eqzy3a3rgtuvy087fdld7yws0xt + $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" + pool_id_hex: + $ref: "#/components/schemas/pool_info/items/properties/pool_id_hex" + active_epoch_no: + $ref: "#/components/schemas/pool_info/items/properties/active_epoch_no" + margin: + $ref: "#/components/schemas/pool_info/items/properties/margin" + fixed_cost: + $ref: "#/components/schemas/pool_info/items/properties/fixed_cost" + pledge: + $ref: "#/components/schemas/pool_info/items/properties/pledge" + reward_addr: + $ref: "#/components/schemas/pool_info/items/properties/reward_addr" + owners: + $ref: "#/components/schemas/pool_info/items/properties/margin" + relays: + $ref: "#/components/schemas/pool_info/items/properties/margin" ticker: type: string nullable: true description: Pool ticker - example: JAZZ + example: AHL + meta_url: + $ref: "#/components/schemas/pool_info/items/properties/margin" + meta_hash: + $ref: "#/components/schemas/pool_info/items/properties/margin" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/margin" + retiring_epoch: + $ref: "#/components/schemas/pool_info/items/properties/margin" pool_history_info: type: array items: @@ -2088,26 +2499,32 @@ components: $ref: "#/components/schemas/pool_updates/items/properties/active_epoch_no" vrf_key_hash: type: string + nullable: true description: Pool VRF key hash example: 25efdad1bc12944d38e4e3c26c43565bec84973a812737b163b289e87d0d5ed3 margin: type: number + nullable: true description: Margin (decimal format) example: 0.1 fixed_cost: type: string + nullable: true description: Pool fixed cost per epoch example: "500000000" pledge: type: string + nullable: true description: Pool pledge in lovelace example: "64000000000000" reward_addr: type: string + nullable: true description: Pool reward address example: stake1uy6yzwsxxc28lfms0qmpxvyz9a7y770rtcqx9y96m42cttqwvp4m5 owners: type: array + nullable: true items: type: string description: Pool (co)owner address @@ -2270,6 +2687,26 @@ components: type: string description: Latest transaction hash used for delegation by the account example: 368d08fe86804d637649341d3aec4a9baa7dffa6d00f16de2ba9dba814f1c948 + pool_registrations: + type: array + nullable: true + items: + type: object + properties: + pool_id_bech32: + $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + block_hash: + $ref: "#/components/schemas/blocks/items/properties/hash" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + epoch_no: + $ref: "#/components/schemas/epoch_info/items/properties/epoch_no" + epoch_slot: + $ref: "#/components/schemas/blocks/items/properties/epoch_slot" + active_epoch_no: + $ref: "#/components/schemas/pool_updates/items/properties/active_epoch_no" pool_delegators_history: type: array nullable: true @@ -2318,6 +2755,7 @@ components: active_epoch_no: type: integer description: Epoch number in which the update becomes active + nullable: true example: 324 vrf_key_hash: $ref: "#/components/schemas/pool_info/items/properties/vrf_key_hash" @@ -2339,8 +2777,11 @@ components: $ref: "#/components/schemas/pool_info/items/properties/meta_hash" meta_json: $ref: "#/components/schemas/pool_info/items/properties/meta_json" - pool_status: - $ref: "#/components/schemas/pool_info/items/properties/pool_status" + update_type: + type: string + description: Type of update task + enum: ["registration", "deregistration"] + example: registered retiring_epoch: $ref: "#/components/schemas/pool_info/items/properties/retiring_epoch" pool_relays: @@ -2352,6 +2793,8 @@ components: $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" relays: $ref: "#/components/schemas/pool_info/items/properties/relays" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/pool_status" pool_metadata: type: array items: @@ -2365,6 +2808,8 @@ components: $ref: "#/components/schemas/pool_info/items/properties/meta_hash" meta_json: $ref: "#/components/schemas/pool_info/items/properties/meta_json" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/pool_status" epoch_info: type: array items: @@ -2533,8 +2978,8 @@ components: description: The hash of the first block where these parameters are valid example: f9dc2a2fc3a2db09a71af007a740261de585afc9e3022b8e30535592ff4dd9e5 cost_models: - type: string - description: The per language cost models + type: object + description: The per language cost model in JSON example: null nullable: true price_mem: @@ -2724,17 +3169,21 @@ components: properties: block_hash: $ref: "#/components/schemas/blocks/items/properties/hash" - tx_hashes: - type: array - items: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + epoch_no: + $ref: "#/components/schemas/blocks/items/properties/epoch_no" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + block_time: + $ref: "#/components/schemas/blocks/items/properties/block_time" address_info: type: array items: type: object properties: address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" balance: type: string description: Sum of all UTxO values beloning to address @@ -2753,9 +3202,9 @@ components: type: object properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" block_height: $ref: "#/components/schemas/blocks/items/properties/block_height" block_time: @@ -2769,7 +3218,7 @@ components: reference_script: $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/reference_script" asset_list: - $ref: "#/components/schemas/account_assets/items/properties/asset_list" + $ref: "#/components/schemas/utxo_infos/items/properties/asset_list" address_txs: type: array items: @@ -2789,22 +3238,17 @@ components: type: object properties: address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" - asset_list: - $ref: "#/components/schemas/account_assets/items/properties/asset_list" - credential_txs: - $ref: "#/components/schemas/address_txs" - credential_utxos: - type: array - items: - type: object - properties: - tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" - tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" - value: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value" + $ref: "#/components/schemas/utxo_infos/items/properties/address" + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + $ref: "#/components/schemas/asset_addresses/items/properties/quantity" account_list: type: array items: @@ -2825,7 +3269,9 @@ components: enum: ["registered", "not registered"] example: registered delegated_pool: - $ref: "#/components/schemas/pool_list/items/properties/pool_id_bech32" + nullable: true + allOf: + - $ref: "#/components/schemas/pool_list/items/properties/pool_id_bech32" total_balance: type: string description: Total balance of the account including UTxO, rewards and MIRs (in lovelace) @@ -2854,23 +3300,67 @@ components: type: string description: Total treasury MIR value of the account example: "0" - account_utxos: + utxo_infos: type: array items: type: object properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" + type: string + description: Hash identifier of the transaction + example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" + type: integer + description: Index of UTxO in the transaction + example: 0 address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + type: string + description: A Cardano payment/base address (bech32 encoded) + example: addr1qxkfe8s6m8qt5436lec3f0320hrmpppwqgs2gah4360krvyssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqdc3cxp value: $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value" + stake_address: + $ref: "#/components/schemas/address_info/items/properties/stake_address" + payment_cred: + type: string + description: Payment credential + example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 + nullable: true + epoch_no: + $ref: "#/components/schemas/blocks/items/properties/epoch_no" block_height: $ref: "#/components/schemas/blocks/items/properties/block_height" block_time: $ref: "#/components/schemas/blocks/items/properties/block_time" + datum_hash: + $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_hash" + inline_datum: + $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/inline_datum" + reference_script: + $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/reference_script" + asset_list: + type: array + nullable: true + description: An array of assets on the UTxO + items: + properties: + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + type: string + description: Quantity of assets on the UTxO + example: 1 + is_spent: + type: boolean + description: True if the UTXO has been spent + example: true + account_rewards: type: array items: @@ -2915,7 +3405,7 @@ components: enum: ["registration", "delegation", "withdrawal", "deregistration"] example: "registration" tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" epoch_no: $ref: "#/components/schemas/blocks/items/properties/epoch_no" epoch_slot: @@ -2934,7 +3424,7 @@ components: addresses: type: array items: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" account_assets: type: array items: @@ -2942,25 +3432,16 @@ components: properties: stake_address: $ref: "#/components/schemas/account_history/items/properties/stake_address" - asset_list: - type: array - items: - type: object - properties: - policy_id: - $ref: "#/components/schemas/asset_info/items/properties/policy_id" - asset_name: - $ref: "#/components/schemas/asset_info/items/properties/asset_name" - fingerprint: - $ref: "#/components/schemas/asset_info/items/properties/fingerprint" - decimals: - type: integer - description: Asset decimals - example: 6 - quantity: - type: string - description: Asset quantity owned by account - example: 990000 + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + $ref: "#/components/schemas/asset_addresses/items/properties/quantity" account_history: type: array items: @@ -2992,9 +3473,7 @@ components: type: object properties: tx_hash: - type: string - description: Hash identifier of the transaction - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" block_hash: $ref: "#/components/schemas/blocks/items/properties/hash" block_height: @@ -3061,25 +3540,17 @@ components: type: object properties: bech32: - type: string - description: A Cardano payment/base address (bech32 encoded) where funds were sent or change to be returned - example: addr1q80rc8zj06yzdwwdyqc03rm4l3zv6n89rxuaak0t099n09yssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqad9mkw + $ref: "#/components/schemas/utxo_infos/items/properties/address" cred: type: string description: Payment credential example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 stake_addr: - nullable: true - allOf: - - $ref: "#/components/schemas/account_history/items/properties/stake_address" + $ref: "#/components/schemas/address_info/items/properties/stake_address" tx_hash: - type: string - description: Hash of transaction for UTxO - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: Index of UTxO in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" value: type: string description: Total sum of ADA on the UTxO @@ -3129,23 +3600,7 @@ components: description: Value (json) example: null asset_list: - type: array - nullable: true - description: An array of assets on the UTxO - items: - properties: - policy_id: - $ref: "#/components/schemas/asset_info/items/properties/policy_id" - asset_name: - $ref: "#/components/schemas/asset_info/items/properties/asset_name" - fingerprint: - $ref: "#/components/schemas/asset_info/items/properties/fingerprint" - decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" - quantity: - type: string - description: Quantity of assets on the UTxO - example: 1 + $ref: "#/components/schemas/utxo_infos/items/properties/asset_list" withdrawals: type: array description: Array of withdrawals with-in a transaction @@ -3174,7 +3629,7 @@ components: fingerprint: $ref: "#/components/schemas/asset_info/items/properties/fingerprint" decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" quantity: type: string description: Quantity of minted assets (negative on burn) @@ -3212,7 +3667,7 @@ components: items: properties: script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + $ref: "#/components/schemas/script_info/items/properties/script_hash" script_json: type: object description: JSON representation of the timelock script (null for other script types) @@ -3237,6 +3692,7 @@ components: } plutus_contracts: type: array + nullable: true description: Plutus contracts present in transaction (if any) items: properties: @@ -3246,15 +3702,11 @@ components: example: addr1w999n67e86jn6xal07pzxtrmqynspgx0fwmcmpua4wc6yzsxpljz3 nullable: true script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + $ref: "#/components/schemas/script_info/items/properties/script_hash" bytecode: - type: string - description: CBOR-encoded Plutus script data - example: 5911ea010000332333222332233223322332232323332223233322232333333332222222232333222323333222232323322323332223233322232323322332232323333322222332233223322332233223322223223223232533530333330083333573466e1cd55cea8032400046460a000264646464646666ae68cdc39aab9d5004480008cccc8888cccc16c01000c008004dd71aba15004375c6ae85400cdd71aba15002375a6ae84d5d1280111a8279a982819ab9c491035054310005149926135744a00226ae8940044d55cf280089baa001357426aae79401c8d4124d4c128cd5ce2481035054310004b499263333573466e1d40112002205323333573466e1d40152000205523504a35304b335738921035054310004c49926498cccd5cd19b8735573aa004900011980599191919191919191919191999ab9a3370e6aae754029200023333333333019335027232323333573466e1cd55cea8012400046603e60746ae854008c0b0d5d09aba2500223505935305a3357389201035054310005b49926135573ca00226ea8004d5d0a80519a8138141aba150093335502e75ca05a6ae854020ccd540b9d728169aba1500733502704335742a00c66a04e66aa0a8098eb4d5d0a8029919191999ab9a3370e6aae754009200023350213232323333573466e1cd55cea80124000466a05266a084eb4d5d0a80118239aba135744a00446a0ba6a60bc66ae712401035054310005f49926135573ca00226ea8004d5d0a8011919191999ab9a3370e6aae7540092000233502733504275a6ae854008c11cd5d09aba2500223505d35305e3357389201035054310005f49926135573ca00226ea8004d5d09aba2500223505935305a3357389201035054310005b49926135573ca00226ea8004d5d0a80219a813bae35742a00666a04e66aa0a8eb88004d5d0a801181c9aba135744a00446a0aa6a60ac66ae71241035054310005749926135744a00226ae8940044d5d1280089aba25001135744a00226ae8940044d5d1280089aba25001135573ca00226ea8004d5d0a8011919191999ab9a3370ea00290031180f181d9aba135573ca00646666ae68cdc3a801240084603a608a6ae84d55cf280211999ab9a3370ea00690011180e98181aba135573ca00a46666ae68cdc3a80224000460406eb8d5d09aab9e50062350503530513357389201035054310005249926499264984d55cea80089baa001357426ae8940088d4124d4c128cd5ce249035054310004b49926104a1350483530493357389201035054350004a4984d55cf280089baa001135573a6ea80044dd50009109198008018011000911111111109199999999980080580500480400380300280200180110009109198008018011000891091980080180109000891091980080180109000891091980080180109000909111180200290911118018029091111801002909111180080290008919118011bac0013200135503b2233335573e0024a01c466a01a60086ae84008c00cd5d100101991919191999ab9a3370e6aae75400d200023330073232323333573466e1cd55cea8012400046601a60626ae854008cd404c0b4d5d09aba25002235036353037335738921035054310003849926135573ca00226ea8004d5d0a801999aa805bae500a35742a00466a01eeb8d5d09aba25002235032353033335738921035054310003449926135744a00226aae7940044dd50009110919980080200180110009109198008018011000899aa800bae75a224464460046eac004c8004d540d488c8cccd55cf80112804919a80419aa81898031aab9d5002300535573ca00460086ae8800c0b84d5d08008891001091091198008020018900089119191999ab9a3370ea002900011a80418029aba135573ca00646666ae68cdc3a801240044a01046a0526a605466ae712401035054310002b499264984d55cea80089baa001121223002003112200112001232323333573466e1cd55cea8012400046600c600e6ae854008dd69aba135744a00446a0466a604866ae71241035054310002549926135573ca00226ea80048848cc00400c00880048c8cccd5cd19b8735573aa002900011bae357426aae7940088d407cd4c080cd5ce24810350543100021499261375400224464646666ae68cdc3a800a40084a00e46666ae68cdc3a8012400446a014600c6ae84d55cf280211999ab9a3370ea00690001280511a8111a981199ab9c490103505431000244992649926135573aa00226ea8004484888c00c0104488800844888004480048c8cccd5cd19b8750014800880188cccd5cd19b8750024800080188d4068d4c06ccd5ce249035054310001c499264984d55ce9baa0011220021220012001232323232323333573466e1d4005200c200b23333573466e1d4009200a200d23333573466e1d400d200823300b375c6ae854014dd69aba135744a00a46666ae68cdc3a8022400c46601a6eb8d5d0a8039bae357426ae89401c8cccd5cd19b875005480108cc048c050d5d0a8049bae357426ae8940248cccd5cd19b875006480088c050c054d5d09aab9e500b23333573466e1d401d2000230133016357426aae7940308d407cd4c080cd5ce2481035054310002149926499264992649926135573aa00826aae79400c4d55cf280109aab9e500113754002424444444600e01044244444446600c012010424444444600a010244444440082444444400644244444446600401201044244444446600201201040024646464646666ae68cdc3a800a400446660106eb4d5d0a8021bad35742a0066eb4d5d09aba2500323333573466e1d400920002300a300b357426aae7940188d4040d4c044cd5ce2490350543100012499264984d55cea80189aba25001135573ca00226ea80048488c00800c888488ccc00401401000c80048c8c8cccd5cd19b875001480088c018dd71aba135573ca00646666ae68cdc3a80124000460106eb8d5d09aab9e500423500a35300b3357389201035054310000c499264984d55cea80089baa001212230020032122300100320011122232323333573466e1cd55cea80124000466aa016600c6ae854008c014d5d09aba25002235007353008335738921035054310000949926135573ca00226ea8004498480048004448848cc00400c008448004848c0040088004888848cccc00401401000c00880044880084880048004448c8c00400488cc00cc008008004c8ccc888c8c8cc88cc88ccc888c8c8c8c8cc88c8c8cc88c8cccc8888c8c8c8c8c8c8c8c8ccc888c8ccc888ccc888cccccccc88888888cc88ccccc88888cccc8888cc88cc88cc88ccc888cc88cc88cc88cc88cc88c8c8c8cc88c8c8c8c8c8c8cc88c8c8c8c8c8c8cc888c888c8c94cd4c1240104cc0352401297369676e617475726520646f6573206e6f74206d617463682063726561746f7220696e20646174756d0033223530200022222222222533535032333553068120015027253353079333573466e3c0300041ec1e84d40d4004540d000c841ec41e54008c04540144cc054cc03524012f65787065637465642063726561746f7220746f2067657420616c6c206f66207768617420736865206f72646572656400330153350133335500e305c12001504f350481223335501b2253353070333505006353353502a3235302900122335304c0022350300012502f300e00221001132635300b335738920117696e76616c6964207075626c6963206b657920686173680000c498c05540244cc010c0340080044004004c8d4c08400488888888880254010ccd41354138c1894014c04920c08db7013350133335500e305c12001504f350481223335501b22533530703005002133004335506500d30100020011001001300d5004333504d504e30625005333504d504e533535026301a00321300a300d0011630124830236dc04cc0352401276f6e6c79206d617463686573206f66207061697273206f66206f726465727320616c6c6f77656400533535063350481223335501b225335307030050021330040020011001001300d50041306a162215335350650011306c16221533535067001107222130701623253353502732353024001222001500121333504e223530280022235302a0032232335304e0052335304f004253353077333573466e3c0080041e41e05400c41e081e08cd4c13c01081e094cd4c1dcccd5cd19b8f002001079078150031078153353502e0032153353502f00221335304c0022335304d002233530510022335305200223306d002001207b23353052002207b23306d00200122207b222335304f004207b2225335307c333573466e1c01800c1f81f454cd4c1f0ccd5cd19b8700500207e07d1333573466e1c0100041f81f441f441f441d854cd4d40b8004841d841d8c03140094cd4d40a0c07001484cd54190034c03c0045841b84c0300044d4c068004880084d4c02800480044800480048d4c0680048880088d4c06400488800c8d4c05000488888888880288d4c05400488004894cd4c184004418c4cd5ce001031089119aa8011a82600090009091800801100091a982c0009111002119a82999aa82b245003350533355056489000015054505412233355304b120013500550032353550560012233355304e120013500850062353550590012233353550490012330614800000488cc1880080048cc184005200000133040002001133500400105a22533530590021001105a123350492233353500400322002002001353500200122001122123300100300212001112232001320013550582253353504e00110032213300600230040012353003001223530070022222222222533335302600b21501b21501b21501b2133355305012001500f2353015001225335306353353063333573466e3cd4c0bc00888008d4c0bc010880081941904ccd5cd19b8735302f0022200135302f00422001065064106413501f0031501e00b13350432253353500d002210031001500c2212330010030022001222222222212333333333300100b00a009008007006005004003002200122123300100300220012221233300100400300220012212330010030022001121223002003112200112001122123300100300212001122123300100300212001122123300100300212001121222300300411222002112220011200121222230040052122223003005212222300200521222230010052001221233001003002200121222222230070082212222222330060090082122222223005008122222220041222222200322122222223300200900822122222223300100900820012122300200322212233300100500400320012122300200321223001003200112335001501d501e1220021220012001120011200113002012133500b2233300301300200150162223355300e1200123535501a00122335501d002335530111200123535501d001223355020002333535500d00123300a4800000488cc02c0080048cc028005200000133004002001223355300c1200123535501800122335501b00233353550080012335530101200123535501c00122335501f00235500f001001223335550080150020012335530101200123535501c00122335501f00235500d0010013335550030100020011112223335530041200150153355300c1200123535501800122335501b00235500b0013335530041200122353550190022253353021333553011120013500d33500f22533530230021025100102223535501c001223300a0020050061003133501900400350160013355300c120012353550180012232335501c00330010053200135502322533535019001135500b0032213535501e00222533530263300c00200813355010007001130060030023200135501c221122253353501500110022213300500233355300712001005004001112122230030041122122233002005004112122230010041120011233500722333535004003220020020013535002001220011221233001003002120013200135501422112253353500c0011500e22133500f3004002335530061200100400132001355013221122253353500c00113535006003220012213335350080052200230040023335530071200100500400112212330010030021200122333573466e3c00800404404088cdc000100088911801000919991119a80319aa80480199a80319aa804801000a803a8039a980380091110019a980380091110011a98038009111000889100109109119800802001890008891091980080180108900091110919998008028020018011000900211199ab9a3371000400200800a244004244002400222464600200244660066004004003 + $ref: "#/components/schemas/script_info/items/properties/bytes" size: - type: integer - description: The size of the CBOR serialised script (in bytes) - example: 234895 + $ref: "#/components/schemas/script_info/items/properties/size" valid_contract: type: boolean description: True if the contract is valid or there is no contract @@ -3314,17 +3766,11 @@ components: description: Payment credential example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 stake_addr: - nullable: true - allOf: - - $ref: "#/components/schemas/account_history/items/properties/stake_address" + $ref: "#/components/schemas/address_info/items/properties/stake_address" tx_hash: - type: string - description: Hash of transaction for UTxO - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: Index of UTxO in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" value: type: string description: Total sum of ADA on the UTxO @@ -3339,7 +3785,7 @@ components: items: properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" metadata: type: object nullable: true @@ -3360,7 +3806,7 @@ components: items: properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" num_confirmations: type: integer description: Number of block confirmations @@ -3414,9 +3860,7 @@ components: items: properties: payment_address: - type: string - description: A Cardano payment/base address (bech32 encoded) for transaction's input UTxO - example: addr1qxkfe8s6m8qt5436lec3f0320hrmpppwqgs2gah4360krvyssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqdc3cxp + $ref: "#/components/schemas/utxo_infos/items/properties/address" quantity: type: string description: Asset balance on the payment address @@ -3427,7 +3871,7 @@ components: items: properties: payment_address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" asset_summary: type: array items: @@ -3519,6 +3963,11 @@ components: decimals: type: integer example: 0 + cip68_metadata: + type: object + description: CIP 68 metadata if present for asset + nullable: true + example: {"222": {"fields": [{"map": [{"k": {"bytes": "6e616d65"}, "v": {"bytes": "74657374"}}]}], "constructor": 0}} asset_history: type: array items: @@ -3559,7 +4008,7 @@ components: asset_name: $ref: "#/components/schemas/asset_info/items/properties/asset_name" payment_address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" quantity: $ref: "#/components/schemas/asset_addresses/items/properties/quantity" policy_asset_info: @@ -3599,67 +4048,65 @@ components: total_supply: $ref: "#/components/schemas/asset_info/items/properties/total_supply" decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" - asset_txs: - type: array - description: An array of Tx hashes that included the given asset (latest first) - items: - properties: - tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" - epoch_no: - $ref: "#/components/schemas/blocks/items/properties/epoch_no" - block_height: - $ref: "#/components/schemas/blocks/items/properties/block_height" - block_time: - $ref: "#/components/schemas/blocks/items/properties/block_time" - native_script_list: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + script_info: type: array items: properties: script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + type: string + description: Hash of a script + example: bfa7ffa9b2e164873db6ac6d0528c82e212963bc62e10fd1d81da4af creation_tx_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/creation_tx_hash" + type: string + description: Hash of the script creation transaction + example: 255f061502ad83230351fbcf2d9fade1b5d118d332f92c9861075010a1fe3fbe type: type: string description: Type of the script - enum: ["timelock", "multisig"] - example: timelock - plutus_script_list: + enum: ["plutusV1","plutusV2","timelock","multisig"] + example: plutusV1 + value: + type: object + nullable: true + description: Data in JSON format + example: null + bytes: + type: string + description: Script bytes (cborSeq) + example: 5907f4010000332323232323232323233223232323232332232323232322223232533532533533355300712001323212330012233350052200200200100235001220011233001225335002101710010142325335333573466e3cd400488008d4020880080580544ccd5cd19b873500122001350082200101601510153500122002353500122002222222222200a101413357389201115554784f206e6f7420636f6e73756d6564000133333573466e1cd55cea8012400046644246600200600464646464646464646464646666ae68cdc39aab9d500a480008cccccccccc888888888848cccccccccc00402c02802402001c01801401000c008cd40508c8c8cccd5cd19b8735573aa0049000119910919800801801180f9aba150023019357426ae8940088c98d4cd5ce01581501481409aab9e5001137540026ae854028cd4050054d5d0a804999aa80bbae501635742a010666aa02eeb94058d5d0a80399a80a0109aba15006335014335502402275a6ae854014c8c8c8cccd5cd19b8735573aa00490001199109198008018011919191999ab9a3370e6aae754009200023322123300100300233502575a6ae854008c098d5d09aba2500223263533573805e05c05a05826aae7940044dd50009aba150023232323333573466e1cd55cea8012400046644246600200600466a04aeb4d5d0a80118131aba135744a004464c6a66ae700bc0b80b40b04d55cf280089baa001357426ae8940088c98d4cd5ce01581501481409aab9e5001137540026ae854010cd4051d71aba15003335014335502475c40026ae854008c070d5d09aba2500223263533573804e04c04a04826ae8940044d5d1280089aba25001135744a00226ae8940044d5d1280089aba25001135744a00226aae7940044dd50009aba150023232323333573466e1d400520062321222230040053019357426aae79400c8cccd5cd19b875002480108c848888c008014c06cd5d09aab9e500423333573466e1d400d20022321222230010053015357426aae7940148cccd5cd19b875004480008c848888c00c014dd71aba135573ca00c464c6a66ae7008808408007c0780740704d55cea80089baa001357426ae8940088c98d4cd5ce00d80d00c80c080c89931a99ab9c4910350543500019018135573ca00226ea8004c8004d5405888448894cd40044d400c88004884ccd401488008c010008ccd54c01c4800401401000448c88c008dd6000990009aa80b111999aab9f00125009233500830043574200460066ae880080548c8c8c8cccd5cd19b8735573aa00690001199911091998008020018011919191999ab9a3370e6aae7540092000233221233001003002301735742a00466a01c02c6ae84d5d1280111931a99ab9c01b01a019018135573ca00226ea8004d5d0a801999aa803bae500635742a00466a014eb8d5d09aba2500223263533573802e02c02a02826ae8940044d55cf280089baa0011335500175ceb44488c88c008dd5800990009aa80a11191999aab9f0022500823350073355017300635573aa004600a6aae794008c010d5d100180a09aba100111220021221223300100400312232323333573466e1d4005200023212230020033005357426aae79400c8cccd5cd19b8750024800884880048c98d4cd5ce00980900880800789aab9d500113754002464646666ae68cdc39aab9d5002480008cc8848cc00400c008c014d5d0a8011bad357426ae8940088c98d4cd5ce00800780700689aab9e5001137540024646666ae68cdc39aab9d5001480008dd71aba135573ca004464c6a66ae7003803403002c4dd500089119191999ab9a3370ea00290021091100091999ab9a3370ea00490011190911180180218031aba135573ca00846666ae68cdc3a801a400042444004464c6a66ae7004404003c0380340304d55cea80089baa0012323333573466e1d40052002200523333573466e1d40092000200523263533573801a01801601401226aae74dd5000891001091000919191919191999ab9a3370ea002900610911111100191999ab9a3370ea004900510911111100211999ab9a3370ea00690041199109111111198008048041bae35742a00a6eb4d5d09aba2500523333573466e1d40112006233221222222233002009008375c6ae85401cdd71aba135744a00e46666ae68cdc3a802a400846644244444446600c01201060186ae854024dd71aba135744a01246666ae68cdc3a8032400446424444444600e010601a6ae84d55cf280591999ab9a3370ea00e900011909111111180280418071aba135573ca018464c6a66ae7004c04804404003c03803403002c0284d55cea80209aab9e5003135573ca00426aae7940044dd50009191919191999ab9a3370ea002900111999110911998008028020019bad35742a0086eb4d5d0a8019bad357426ae89400c8cccd5cd19b875002480008c8488c00800cc020d5d09aab9e500623263533573801801601401201026aae75400c4d5d1280089aab9e500113754002464646666ae68cdc3a800a400446424460020066eb8d5d09aab9e500323333573466e1d400920002321223002003375c6ae84d55cf280211931a99ab9c009008007006005135573aa00226ea800444888c8c8cccd5cd19b8735573aa0049000119aa80518031aba150023005357426ae8940088c98d4cd5ce00480400380309aab9e5001137540029309000a490350543100112212330010030021123230010012233003300200200133512233002489209366f09fe40eaaeb17d3cb6b0b61e087d664174c39a48a986f86b2b0ba6e2a7b00480008848cc00400c0088005 + size: + type: integer + description: The size of the CBOR serialised script (in bytes) + example: 2039 + script_list: type: array items: properties: script_hash: - type: string - description: Hash of a script - example: d8480dc869b94b80e81ec91b0abe307279311fe0e7001a9488f61ff8 + $ref: "#/components/schemas/script_info/items/properties/script_hash" creation_tx_hash: - type: string - description: Hash of the script creation transaction - example: fda6c7697009237975ffc30f36666addf4c6e2a2c6f90411a24431b700baaab1 + $ref: "#/components/schemas/script_info/items/properties/creation_tx_hash" + type: + $ref: "#/components/schemas/script_info/items/properties/type" + size: + $ref: "#/components/schemas/script_info/items/properties/size" script_redeemers: type: array items: type: object properties: script_hash: - type: string - description: Hash of Transaction for which details are being shown - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/script_info/items/properties/script_hash" redeemers: type: array items: type: object properties: tx_hash: - type: string - description: Hash of Transaction containing the redeemer - example: fda6c7697009237975ffc30f36666addf4c6e2a2c6f90411a24431b700baaab1 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: The index of the redeemer pointer in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" unit_mem: description: The budget in Memory to run a script example: 520448 @@ -3691,20 +4138,20 @@ components: nullable: true example: 5a595ce795815e81d22a1a522cf3987d546dc5bb016de61b002edd63a5413ec4 datum_value: - type: object - description: The actual data in json format - example: { "bytes": "3c33" } + $ref: "#/components/schemas/script_info/items/properties/value" datum_info: type: array items: type: object properties: - hash: + datum_hash: $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_hash" + creation_tx_hash: + $ref: "#/components/schemas/script_info/items/properties/creation_tx_hash" value: - $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_value" + $ref: "#/components/schemas/script_info/items/properties/value" bytes: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/inline_datum/properties/bytes" + $ref: "#/components/schemas/script_info/items/properties/bytes" headers: {} responses: OK: @@ -3712,7 +4159,7 @@ components: NotFound: description: The server does not recognise the combination of endpoint and parameters provided Unauthorized: - description: The selected server has restricted the endpoint to be only usable via authentication. The authentication supplied was not authorized to access the endpoint + description: Access token is missing or invalid PartialContent: description: The result was truncated BadRequest: @@ -3730,12 +4177,12 @@ tags: - name: Transactions description: Query blockchain transaction details x-tag-expanded: false + - name: Stake Account + description: Query details about specific stake account addresses + x-tag-expanded: false - name: Address description: Query information about specific address(es) x-tag-expanded: false - - name: Account - description: Query details about specific stake account addresses - x-tag-expanded: false - name: Asset description: Query Asset related informations x-tag-expanded: false @@ -3745,4 +4192,5 @@ tags: - name: Script description: Query information about specific scripts (Smart Contracts) x-tag-expanded: false -security: [] +security: + - bearerAuth: [] diff --git a/specs/results/koiosapi-preview.yaml b/specs/results/koiosapi-preview.yaml index debc78c1..25db005a 100644 --- a/specs/results/koiosapi-preview.yaml +++ b/specs/results/koiosapi-preview.yaml @@ -1,7 +1,7 @@ openapi: 3.0.2 info: title: Koios API - version: 1.0.10 + version: v1.1.0rc description: | Koios is best described as a Decentralized and Elastic RESTful query layer for exploring data on Cardano blockchain to consume within applications/wallets/explorers/etc. This page not only provides an OpenAPI Spec for live implementation, but also ability to execute live demo from client browser against each endpoint with pre-filled examples. @@ -14,11 +14,11 @@ info: Instead of returning entire row, you can elect which rows you would like to fetch from the endpoint by using the `select` parameter with corresponding columns separated by commas. See example below (first is complete information for tip, while second command gives us 3 columns we are interested in):

``` bash - curl "https://api.koios.rest/api/v0/tip" + curl "https://api.koios.rest/api/v1/tip" # [{"hash":"4d44c8a453e677f933c3df42ebcf2fe45987c41268b9cfc9b42ae305e8c3d99a","epoch":317,"abs_slot":51700871,"epoch_slot":120071,"block_height":6806994,"block_time":1643267162}] - curl "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_height" + curl "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_height" # [{"epoch":317,"epoch_slot":120071,"block_height":6806994}] ``` @@ -27,7 +27,7 @@ info: You can filter the returned output based on specific conditions using operators against a column within returned result. Consider an example where you would want to query blocks minted in first 3 minutes of epoch 250 (i.e. epoch_slot was less than 180). To do so your query would look like below:

``` bash - curl "https://api.koios.rest/api/v0/blocks?epoch=eq.250&epoch_slot=lt.180" + curl "https://api.koios.rest/api/v1/blocks?epoch=eq.250&epoch_slot=lt.180" # [{"hash":"8fad2808ac6b37064a0fa69f6fe065807703d5235a57442647bbcdba1c02faf8","epoch":250,"abs_slot":22636942,"epoch_slot":142,"block_height":5385757,"block_time":1614203233,"tx_count":65,"vrf_key":"vrf_vk14y9pjprzlsjvjt66mv5u7w7292sxp3kn4ewhss45ayjga5vurgaqhqknuu","pool":null,"op_cert_counter":2}, # {"hash":"9d33b02badaedc0dedd0d59f3e0411e5fb4ac94217fb5ee86719e8463c570e16","epoch":250,"abs_slot":22636800,"epoch_slot":0,"block_height":5385756,"block_time":1614203091,"tx_count":10,"vrf_key":"vrf_vk1dkfsejw3h2k7tnguwrauqfwnxa7wj3nkp3yw2yw3400c4nlkluwqzwvka6","pool":null,"op_cert_counter":2}] @@ -62,7 +62,7 @@ info: Consider a simple case where I want query `blocks` endpoint for `block_height` column and focus on `content-range` header to monitor the rows we discussed above.

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height" -I | grep -i content-range # content-range: 0-999/* @@ -71,7 +71,7 @@ info: As we can see above, the number of observations returned was 1000 (range being 0-999), but the total size was not queried to avoid wait times. Now, let's modify this default behaviour to query rows beyond the first 999, but this time - also add another clause to limit results by 500. We can do this using `offset=1000` and `limit=500` as below:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height&offset=1000&limit=500" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height&offset=1000&limit=500" -I | grep -i content-range # content-range: 1000-1499/* @@ -80,7 +80,7 @@ info: For GET endpoints, there is also another method to achieve the above, instead of adding parameters to the URL itself, you can specify a `Range` header as below to achieve something similar:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height" -H "Range: 1000-1499" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height" -H "Range: 1000-1499" -I | grep -i content-range # content-range: 1000-1499/* @@ -94,7 +94,7 @@ info: Consider example where you want to check `epoch` and `epoch_slot` for the first 5 blocks created by a particular pool, i.e. you can set order to ascending based on block_height column and add horizontal filter for that pool ID as below:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?pool=eq.pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc&order=block_height.asc&limit=5" + curl -s "https://api.koios.rest/api/v1/blocks?pool=eq.pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc&order=block_height.asc&limit=5" # [{"hash":"610b4c7bbebeeb212bd002885048cc33154ba29f39919d62a3d96de05d315706","epoch":236,"abs_slot":16594295,"epoch_slot":5495,"block_height":5086774,"block_time":1608160586,"tx_count":1,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1}, # {"hash":"d93d1db5275329ab695d30c06a35124038d8d9af64fc2b0aa082b8aa43da4164","epoch":236,"abs_slot":16597729,"epoch_slot":8929,"block_height":5086944,"block_time":1608164020,"tx_count":7,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1}, @@ -109,13 +109,13 @@ info: Below is an example of JSON/CSV output making use of above to print first in JSON (default), and then override response format to CSV.

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_time&limit=3" + curl -s "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_time&limit=3" # [{"epoch":318,"epoch_slot":27867,"block_time":1643606958}, # {"epoch":318,"epoch_slot":27841,"block_time":1643606932}, # {"epoch":318,"epoch_slot":27839,"block_time":1643606930}] - curl -s "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_time&limit=3" -H "Accept: text/csv" + curl -s "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_time&limit=3" -H "Accept: text/csv" # epoch,epoch_slot,block_time # 318,28491,1643607582 @@ -134,6 +134,10 @@ info: Yet, there may be cases where the above restrictions may need exceptions (for example, an explorer or a wallet might need more connections than above - going beyond the Burst Limit). For such cases, it is best to approach the team and we can work towards a solution. + # Authentication + + While Koios public tier remains unauthenticated and allows queries without any authentication, it has low limits to prevent actions against an erroraneous query/loop from a consumer. There is also a Free tier which requires setting up Bearer Auth token that is linked to the owner's wallet account (which can be connected to via [Koios website](https://koios.rest/pricing/Pricing.html) ). + The examples across this API site already [supports authentication](/#auth), for you to use in the queries. # Community projects @@ -142,11 +146,12 @@ info: x-logo: url: "https://api.koios.rest/images/koios.png" servers: - - url: https://api.koios.rest/api/v0 - - url: https://guild.koios.rest/api/v0 - - url: https://preview.koios.rest/api/v0 - - url: https://preprod.koios.rest/api/v0 + - url: https://api.koios.rest/api/v1 + - url: https://guild.koios.rest/api/v1 + - url: https://preview.koios.rest/api/v1 + - url: https://preprod.koios.rest/api/v1 paths: + /tip: #RPC get: tags: @@ -227,6 +232,45 @@ paths: $ref: "#/components/responses/NotFound" summary: Param Update Proposals description: Get all parameter update proposals submitted to the chain starting Shelley era + /reserve_withdrawals: #RPC + get: + tags: + - Network + responses: + "200": + description: Array of withdrawals from reserves against stake accounts + content: + application/json: + schema: + $ref: "#/components/schemas/reserve_withdrawals" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Reserve Withdrawals + description: List of all withdrawals from reserves against stake accounts + /treasury_withdrawals: #RPC + get: + tags: + - Network + responses: + "200": + description: Array of withdrawals from treasury against stake accounts + content: + application/json: + schema: + $ref: "#/components/schemas/reserve_withdrawals" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Treasury Withdrawals + description: List of all withdrawals from treasury against stake accounts + /epoch_info: #RPC get: tags: @@ -294,6 +338,7 @@ paths: summary: Epoch's Block Protocols description: >- Get the information about block protocol distribution in epoch + /blocks: get: tags: @@ -355,28 +400,29 @@ paths: $ref: "#/components/responses/NotFound" summary: Block Transactions description: Get a list of all transactions included in provided blocks - /tx_info: #RPC + + /utxo_info: #RPC post: tags: - Transactions requestBody: - $ref: "#/components/requestBodies/tx_ids" + $ref: "#/components/requestBodies/utxo_refs_with_extended" responses: "200": - description: Array of detailed information about transaction(s) + description: Array of UTXO details content: application/json: schema: - $ref: "#/components/schemas/tx_info" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction Information - description: Get detailed information about transaction(s) - /tx_utxos: #RPC + summary: UTxO Info + description: Get UTxO set for requested UTxO references + /tx_info: #RPC post: tags: - Transactions @@ -384,19 +430,19 @@ paths: $ref: "#/components/requestBodies/tx_ids" responses: "200": - description: Array of inputs and outputs for given transaction(s) + description: Array of detailed information about transaction(s) content: application/json: schema: - $ref: "#/components/schemas/tx_utxos" + $ref: "#/components/schemas/tx_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction UTxOs [DEPRECATED] - description: Get UTxO set (inputs/outputs) of transactions. + summary: Transaction Information + description: Get detailed information about transaction(s) /tx_metadata: #RPC post: tags: @@ -450,7 +496,7 @@ paths: # If using a CLI-generated tx file, please ensure to deserialise (using `xxd -p -r <<< $(jq .cborHex ${tx.signed}) > ${data}`) first before submitting. curl -X POST \ --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/v0/submittx + --data-binary @${data} https://api.koios.rest/api/v1/submittx responses: "202": description: OK @@ -486,8 +532,31 @@ paths: $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction Status (Block Confirmations) + summary: Transaction Status description: Get the number of block confirmations for a given transaction hash list + /tx_utxos: #RPC + post: + tags: + - Transactions + deprecated: true + requestBody: + $ref: "#/components/requestBodies/tx_ids" + responses: + "200": + description: Array of inputs and outputs for given transaction(s) + content: + application/json: + schema: + $ref: "#/components/schemas/tx_utxos" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Transaction UTxOs + description: Get UTxO set (inputs/outputs) of transactions [DEPRECATED - Use /utxo_info instead]. + /address_info: #RPC post: tags: @@ -509,27 +578,27 @@ paths: $ref: "#/components/responses/NotFound" summary: Address Information description: Get address info - balance, associated stake address (if any) and UTxO set for given addresses - /address_txs: #RPC + /address_utxos: #RPC post: tags: - Address requestBody: - $ref: "#/components/requestBodies/address_txs" + $ref: "#/components/requestBodies/payment_addresses_with_extended" responses: "200": - description: Array of transaction hashes + description: Array of address UTXOs content: application/json: schema: - $ref: "#/components/schemas/address_txs" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Address Transactions - description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive) + summary: Address UTXOs + description: Get UTxO set for given addresses /credential_utxos: #RPC post: tags: @@ -542,7 +611,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/credential_utxos" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": @@ -550,28 +619,28 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: UTxOs from payment credentials - description: Get a list of UTxO against input payment credential array including their balances - /address_assets: #RPC + description: Get UTxO details for requested payment credentials + /address_txs: #RPC post: tags: - Address requestBody: - $ref: "#/components/requestBodies/payment_addresses" + $ref: "#/components/requestBodies/address_txs" responses: "200": - description: Array of address-owned assets + description: Array of transaction hashes content: application/json: schema: - $ref: "#/components/schemas/address_assets" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Address Assets - description: Get the list of all the assets (policy, name and quantity) for given addresses + summary: Address Transactions + description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive) /credential_txs: #RPC post: tags: @@ -584,7 +653,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/credential_txs" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": @@ -593,6 +662,28 @@ paths: $ref: "#/components/responses/NotFound" summary: Transactions from payment credentials description: Get the transaction hash list of input payment credential array, optionally filtering after specified block height (inclusive) + /address_assets: #RPC + post: + tags: + - Address + requestBody: + $ref: "#/components/requestBodies/payment_addresses" + responses: + "200": + description: Array of address-owned assets + content: + application/json: + schema: + $ref: "#/components/schemas/address_assets" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Address Assets + description: Get the list of all the assets (policy, name and quantity) for given addresses + /account_list: get: tags: @@ -633,48 +724,70 @@ paths: $ref: "#/components/responses/NotFound" summary: Account Information description: Get the account information for given stake addresses - /account_utxos: #RPC - get: + /account_info_cached: #RPC + post: tags: - Stake Account - parameters: - - $ref: "#/components/parameters/_stake_address" + requestBody: + $ref: "#/components/requestBodies/stake_addresses" responses: "200": - description: Array of account UTxOs associated with stake address + description: Array of account information content: application/json: schema: - $ref: "#/components/schemas/account_utxos" + $ref: "#/components/schemas/account_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Account UTxOs - description: Get a list of all UTxOs for a given stake address (account) - /account_info_cached: #RPC + summary: Account Information (Cached) + description: Get the cached account information for given stake addresses (effective for performance query against registered accounts) + /account_utxos: #RPC post: tags: - Stake Account requestBody: - $ref: "#/components/requestBodies/stake_addresses" + $ref: "#/components/requestBodies/stake_addresses_with_extended" responses: "200": - description: Array of account information + description: Array of account UTxOs associated with given stake addresses content: application/json: schema: - $ref: "#/components/schemas/account_info" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Account Information (Cached) - description: Get the cached account information for given stake addresses, effective for registered accounts + summary: UTxOs for stake addresses (accounts) + description: Get a list of all UTxOs for given stake addresses (account)s + /account_txs: #RPC + get: + tags: + - Stake Account + parameters: + - $ref: "#/components/parameters/_stake_address" + - $ref: "#/components/parameters/_after_block_height" + responses: + "200": + description: Array of Txs associated with stake address (account) + content: + application/json: + schema: + $ref: "#/components/schemas/address_txs" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Account Txs + description: Get a list of all Txs for a given stake address (account) /account_rewards: #RPC post: tags: @@ -783,6 +896,7 @@ paths: $ref: "#/components/responses/NotFound" summary: Account History description: Get the staking history of given stake addresses (accounts) + /asset_list: get: tags: @@ -802,95 +916,89 @@ paths: $ref: "#/components/responses/NotFound" summary: Asset List description: Get the list of all native assets (paginated) - /asset_token_registry: + /policy_asset_list: #RPC get: tags: - Asset + parameters: + - $ref: "#/components/parameters/_asset_policy" responses: "200": - description: Array of token registry information for each asset + description: Array of detailed information of assets under the same policy content: application/json: schema: - $ref: "#/components/schemas/asset_token_registry" + $ref: "#/components/schemas/policy_asset_list" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Token Registry - description: Get a list of assets registered via token registry on github - /asset_addresses: #RPC + summary: Policy Asset List + description: Get the list of asset under the given policy (including balances) + /asset_token_registry: get: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of payment addresses holding the given token (including balances) + description: Array of token registry information for each asset content: application/json: schema: - $ref: "#/components/schemas/asset_addresses" + $ref: "#/components/schemas/asset_token_registry" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Addresses - description: Get the list of all addresses holding a given asset

- `Note - Due to cardano's UTxO design and usage from projects, asset to addresses map can be infinite. Thus, for a small subset of active projects - with millions of transactions, these might end up with timeouts (HTTP code 504) on free layer. Such large-scale projects are free to subscribe to - query layers to have a dedicated cache table for themselves served via Koios.` - /asset_address_list: #RPC - get: + summary: Asset Token Registry + description: Get a list of assets registered via token registry on github + /asset_info: #RPC + post: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" + requestBody: + $ref: "#/components/requestBodies/asset_list" responses: "200": - description: Array of payment addresses holding the given token (including balances) + description: Array of detailed asset information content: application/json: schema: - $ref: "#/components/schemas/asset_addresses" + $ref: "#/components/schemas/asset_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Address List [DEPRECATED] - description: Get the list of all addresses holding a given asset (replaced by asset_addresses) - /asset_nft_address: #RPC - get: + summary: Asset Information (Bulk) + description: Get the information of a list of assets including first minting & token registry metadata + /asset_utxos: #RPC + post: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy_nft" - - $ref: "#/components/parameters/_asset_name_nft" + requestBody: + $ref: "#/components/requestBodies/asset_list_with_extended" responses: "200": - description: Payment addresses currently holding the given NFT + description: Array of UTXOs for given asset list content: application/json: schema: - $ref: "#/components/schemas/asset_nft_address" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: NFT Address - description: Get the address where specified NFT currently reside on. - /asset_info: #RPC + summary: Asset UTXOs + description: Get the UTXO information of a list of assets including + /asset_history: #RPC get: tags: - Asset @@ -899,61 +1007,66 @@ paths: - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed asset information + description: Array of asset mint/burn history content: application/json: schema: - $ref: "#/components/schemas/asset_info" + $ref: "#/components/schemas/asset_history" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Information - description: Get the information of an asset including first minting & token registry metadata - post: + summary: Asset History + description: Get the mint/burn history of an asset + /asset_addresses: #RPC + get: tags: - Asset - requestBody: - $ref: "#/components/requestBodies/asset_list" + parameters: + - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed asset information + description: Array of payment addresses holding the given token (including balances) content: application/json: schema: - $ref: "#/components/schemas/asset_info" + $ref: "#/components/schemas/asset_addresses" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Information (Bulk) - description: Get the information of a list of assets including first minting & token registry metadata - /asset_history: #RPC + summary: Asset Addresses + description: Get the list of all addresses holding a given asset

+ `Note - Due to cardano's UTxO design and usage from projects, asset to addresses map can be infinite. Thus, for a small subset of active projects + with millions of transactions, these might end up with timeouts (HTTP code 504) on free layer. Such large-scale projects are free to subscribe to + query layers to have a dedicated cache table for themselves served via Koios.` + /asset_nft_address: #RPC get: tags: - Asset parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" + - $ref: "#/components/parameters/_asset_policy_nft" + - $ref: "#/components/parameters/_asset_name_nft" responses: "200": - description: Array of asset mint/burn history + description: Payment addresses currently holding the given NFT content: application/json: schema: - $ref: "#/components/schemas/asset_history" + $ref: "#/components/schemas/asset_nft_address" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset History - description: Get the mint/burn history of an asset + summary: NFT Address + description: Get the address where specified NFT currently reside on. /policy_asset_addresses: #RPC get: tags: @@ -999,94 +1112,98 @@ paths: $ref: "#/components/responses/NotFound" summary: Policy Asset Information description: Get the information for all assets under the same policy - /asset_policy_info: #RPC + /asset_summary: #RPC get: tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed information of assets under the same policy + description: Array of asset summary information content: application/json: schema: - $ref: "#/components/schemas/policy_asset_info" + $ref: "#/components/schemas/asset_summary" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Policy Information [DEPRECATED] - description: Get the information for all assets under the same policy (replaced by asset_addresses) - /policy_asset_list: #RPC + summary: Asset Summary + description: Get the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance) + /asset_txs: #RPC get: tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" + - $ref: "#/components/parameters/_after_block_height" + - $ref: "#/components/parameters/_history" responses: "200": - description: Array of detailed information of assets under the same policy + description: An array of Tx hashes that included the given asset (latest first) content: application/json: schema: - $ref: "#/components/schemas/policy_asset_list" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Policy Asset List - description: Get the list of asset under the given policy (including balances) - /asset_summary: #RPC + summary: Asset Transactions + description: Get the list of current or all asset transaction hashes (newest first) + /asset_address_list: #RPC get: tags: - Asset + deprecated: true parameters: - $ref: "#/components/parameters/_asset_policy" - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of asset summary information + description: Array of payment addresses holding the given token (including balances) content: application/json: schema: - $ref: "#/components/schemas/asset_summary" + $ref: "#/components/schemas/asset_addresses" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Summary - description: Get the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance) - /asset_txs: #RPC + summary: Asset Address List + description: Get the list of all addresses holding a given asset [DEPRECATED - replaced by asset_addresses] + /asset_policy_info: #RPC get: + deprecated: true tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" - - $ref: "#/components/parameters/_after_block_height" - - $ref: "#/components/parameters/_history" responses: "200": - description: Array of Tx hashes that included the given asset + description: Array of detailed information of assets under the same policy content: application/json: schema: - $ref: "#/components/schemas/asset_txs" + $ref: "#/components/schemas/policy_asset_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Transactions - description: Get the list of current or all asset transaction hashes (newest first) + summary: Asset Policy Information + description: Get the information for all assets under the same policy (DEPRECATED - replaced by policy_asset_info) + /pool_list: #RPC get: tags: @@ -1105,7 +1222,7 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool List - description: A list of all currently registered/retiring (not retired) pools + description: List of brief info for all pools /pool_info: #RPC post: tags: @@ -1261,6 +1378,48 @@ paths: $ref: "#/components/responses/NotFound" summary: Pool Updates (History) description: Return all pool updates for all pools or only updates for specific pool if specified + /pool_registrations: #RPC + get: + tags: + - Pool + parameters: + - $ref: "#/components/parameters/_epoch_no" + responses: + "200": + description: Array of historical pool updates + content: + application/json: + schema: + $ref: "#/components/schemas/pool_registrations" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Pool Registrations + description: Return all pool registrations initiated in the requested epoch + /pool_retirements: #RPC + get: + tags: + - Pool + parameters: + - $ref: "#/components/parameters/_epoch_no" + responses: + "200": + description: Array of historical pool updates + content: + application/json: + schema: + $ref: "#/components/schemas/pool_registrations" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Pool Retirements + description: Return all pool retirements initiated in the requested epoch /pool_relays: #RPC get: tags: @@ -1279,7 +1438,7 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool Relays - description: A list of registered relays for all currently registered/retiring (not retired) pools + description: A list of registered relays for all pools /pool_metadata: #RPC post: tags: @@ -1300,7 +1459,29 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool Metadata - description: Metadata (on & off-chain) for all currently registered/retiring (not retired) pools + description: Metadata (on & off-chain) for all pools + + /script_info: #RPC + post: + tags: + - Script + requestBody: + $ref: "#/components/requestBodies/script_hashes" + responses: + "200": + description: List of datum information for given datum hashes + content: + application/json: + schema: + $ref: "#/components/schemas/script_info" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Datum Information + description: List of datum information for given datum hashes /native_script_list: #RPC get: tags: @@ -1311,7 +1492,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/native_script_list" + $ref: "#/components/schemas/script_list" "400": $ref: "#/components/responses/BadRequest" "401": @@ -1330,7 +1511,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/plutus_script_list" + $ref: "#/components/schemas/script_list" "400": $ref: "#/components/responses/BadRequest" "401": @@ -1360,6 +1541,28 @@ paths: $ref: "#/components/responses/NotFound" summary: Script Redeemers description: List of all redeemers for a given script hash + /script_utxos: #RPC + get: + tags: + - Script + parameters: + - $ref: "#/components/parameters/_script_hash" + - $ref: "#/components/parameters/_extended" + responses: + "200": + description: List of UTXOs for a given script hash + content: + application/json: + schema: + $ref: "#/components/schemas/utxo_infos" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Script UTXOs + description: List of all UTXOs for a given script hash /datum_info: #RPC post: tags: @@ -1381,6 +1584,43 @@ paths: $ref: "#/components/responses/NotFound" summary: Datum Information description: List of datum information for given datum hashes + /ogmios/?EvaluateTransaction: #ogmios-api + post: + tags: + - Ogmios + x-code-samples: + - lang: "Shell" + source: | + # Assuming ${data} contains EvaluateTransaction payload as documented on Ogmios v6 site. + curl -X POST \ + --header "Content-Type: application/cbor" \ + --data-binary ${data} https://api.koios.rest/api/ogmios/?EvaluateTransaction + responses: + "200": + description: OK + "400": + description: An error occured while submitting transaction. + summary: Evaluate Transaction + description: Evaluate execution units of scripts in a well-formed transaction. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?EvaluateTransaction) for complete spec + /ogmios/?SubmitTransaction: #ogmios-api + post: + tags: + - Ogmios + x-code-samples: + - lang: "Shell" + source: | + # Assuming ${data} contains a CBOR-serialized signed transaction (base16-encoded) as documented on Ogmios v6 site. + curl -X POST \ + --header "Content-Type: application/cbor" \ + --data-binary ${data} https://api.koios.rest/api/ogmios/?SubmitTransaction + responses: + "200": + description: OK + "400": + description: An error occured while querying transaction. + summary: Submit Transaction + description: Submit a signed and serialized transaction to the network. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?SubmitTransaction) for complete spec + components: parameters: select: @@ -1554,6 +1794,16 @@ components: in: query required: false allowEmptyValue: true + _extended: + deprecated: false + name: _extended + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + schema: + type: boolean + example: "false" + in: query + required: false + allowEmptyValue: true _history: deprecated: false name: _history @@ -1661,6 +1911,29 @@ components: _addresses: - addr_test1vpfwv0ezc5g8a4mkku8hhy3y3vp92t7s3ul8g778g5yegsgalc6gc - addr_test1vqneq3v0dqh3x3muv6ee3lt8e5729xymnxuavx6tndcjc2cv24ef9 + payment_addresses_with_extended: + content: + application/json: + schema: + required: + - _addresses + type: object + properties: + _addresses: + format: text + type: array + items: + type: string + description: Array of Cardano payment address(es) in bech32 format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _addresses: + - addr_test1vpfwv0ezc5g8a4mkku8hhy3y3vp92t7s3ul8g778g5yegsgalc6gc + - addr_test1vqneq3v0dqh3x3muv6ee3lt8e5729xymnxuavx6tndcjc2cv24ef9 + _extended: true address_txs: content: application/json: @@ -1733,6 +2006,32 @@ components: _stake_addresses: - stake_test1urqntq4wexjylnrdnp97qq79qkxxvrsa9lcnwr7ckjd6w0cr04y4p - stake_test1up6wqzrw2h9vvjy5zfkjn0dwtymy5r29zyhf8fyhm6fat9c2am5hl + _first_only: false + _empty: false + + stake_addresses_with_extended: + content: + application/json: + schema: + required: + - _stake_addresses + type: object + properties: + _stake_addresses: + format: text + type: array + items: + type: string + description: Array of Cardano stake address(es) in bech32 format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _stake_addresses: + - stake_test1urqntq4wexjylnrdnp97qq79qkxxvrsa9lcnwr7ckjd6w0cr04y4p + - stake_test1up6wqzrw2h9vvjy5zfkjn0dwtymy5r29zyhf8fyhm6fat9c2am5hl + _extended: true stake_addresses: content: application/json: @@ -1788,10 +2087,15 @@ components: items: type: string description: Array of Cardano payment credential(s) in hex format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call example: _payment_credentials: - 33c378cee41b2e15ac848f7f6f1d2f78155ab12d93b713de898d855f - 52e63f22c5107ed776b70f7b92248b02552fd08f3e747bc745099441 + _extended: true tx_ids: content: application/json: @@ -1853,6 +2157,22 @@ components: - pool1p90428kec03mjdya3k4gv5d20w7lmed7ca0snknef5j977l3y8l - pool1wwh3k3ldzujdvgxllfwlnnkxyheafkacqlufnvpr77n5q72f9hw - pool1p835jxsj8py5n34lrgk6fvpgpxxvh585qm8dzvp7ups37vdet5a + script_hashes: + content: + application/json: + schema: + type: object + properties: + _script_hashes: + format: text + type: array + items: + type: string + description: Array of Cardano script hashes + example: + _script_hashes: + - c6d963e8892916ab8753d3c342037cd122123c4dd783a07af21f8dac + - c0c671fba483641a71bb92d3a8b7c52c90bf1c01e2b83116ad7d4536 datum_hashes: content: application/json: @@ -1866,10 +2186,30 @@ components: type: string description: Array of Cardano datum hashes example: - _datum_hashes: - - 6181b3dc623cd8812caf027a3507e9b3095388a7cf3db65983e1fddd3a84c88c - - f8ae55ff89e1f5366f23e16bcaf2073252337b96031a02d79e41d653b5f0a978 - asset_list: + _datum_hashes: + - 6181b3dc623cd8812caf027a3507e9b3095388a7cf3db65983e1fddd3a84c88c + - f8ae55ff89e1f5366f23e16bcaf2073252337b96031a02d79e41d653b5f0a978 + asset_list: + content: + application/json: + schema: + required: + - _asset_list + type: object + properties: + _asset_list: + format: text + type: array + description: Array of array of policy ID and asset names (hex) + items: + type: array + items: + type: string + example: + _asset_list: + - ['065270479316f1d92e00f7f9f095ebeaac9d009c878dc35ce36d3404','433374'] + - ['189e2c53985411addb8df0f3e09f70e343da69f06746c408aba672a8','15fc257714a51769e192761d674db2ee2e80137428e522f9b914debb5f785301'] + asset_list_with_extended: content: application/json: schema: @@ -1885,11 +2225,43 @@ components: type: array items: type: string + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call example: _asset_list: - ['065270479316f1d92e00f7f9f095ebeaac9d009c878dc35ce36d3404','433374'] - ['189e2c53985411addb8df0f3e09f70e343da69f06746c408aba672a8','15fc257714a51769e192761d674db2ee2e80137428e522f9b914debb5f785301'] - securitySchemes: {} + _extended: true + utxo_refs_with_extended: + content: + application/json: + schema: + required: + - _utxo_refs + type: object + properties: + _utxo_refs: + format: text + type: array + items: + type: string + description: Array of Cardano utxo references in the form "hash#index" + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _utxo_refs: + - 206f6da5b0b0de45605a95f5ce7e172be9674550f7dde3838c45cbf24bab8b00#0 + - f1592b29b79ae85d753913dd25644c60925a4a0683979faa33832fead4b4bd9c#0 + _extended: false + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT schemas: tip: type: array @@ -2003,20 +2375,59 @@ components: type: string description: JSON encoded data with details about the parameter update example: {"decentralisation": 0.9} + reserve_withdrawals: + type: array + items: + properties: + epoch_no: + $ref: "#/components/schemas/epoch_info/items/properties/epoch_no" + epoch_slot: + $ref: "#/components/schemas/blocks/items/properties/epoch_slot" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + block_hash: + $ref: "#/components/schemas/blocks/items/properties/hash" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + amount: + $ref: "#/components/schemas/pool_delegators/items/properties/amount" + stake_address: + $ref: "#/components/schemas/account_history/items/properties/stake_address" pool_list: type: array items: properties: pool_id_bech32: - type: string - nullable: true - description: Bech32 representation of pool ID - example: pool1z5uqdk7dzdxaae5633fqfcu2eqzy3a3rgtuvy087fdld7yws0xt + $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" + pool_id_hex: + $ref: "#/components/schemas/pool_info/items/properties/pool_id_hex" + active_epoch_no: + $ref: "#/components/schemas/pool_info/items/properties/active_epoch_no" + margin: + $ref: "#/components/schemas/pool_info/items/properties/margin" + fixed_cost: + $ref: "#/components/schemas/pool_info/items/properties/fixed_cost" + pledge: + $ref: "#/components/schemas/pool_info/items/properties/pledge" + reward_addr: + $ref: "#/components/schemas/pool_info/items/properties/reward_addr" + owners: + $ref: "#/components/schemas/pool_info/items/properties/margin" + relays: + $ref: "#/components/schemas/pool_info/items/properties/margin" ticker: type: string nullable: true description: Pool ticker - example: JAZZ + example: AHL + meta_url: + $ref: "#/components/schemas/pool_info/items/properties/margin" + meta_hash: + $ref: "#/components/schemas/pool_info/items/properties/margin" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/margin" + retiring_epoch: + $ref: "#/components/schemas/pool_info/items/properties/margin" pool_history_info: type: array items: @@ -2088,26 +2499,32 @@ components: $ref: "#/components/schemas/pool_updates/items/properties/active_epoch_no" vrf_key_hash: type: string + nullable: true description: Pool VRF key hash example: 25efdad1bc12944d38e4e3c26c43565bec84973a812737b163b289e87d0d5ed3 margin: type: number + nullable: true description: Margin (decimal format) example: 0.1 fixed_cost: type: string + nullable: true description: Pool fixed cost per epoch example: "500000000" pledge: type: string + nullable: true description: Pool pledge in lovelace example: "64000000000000" reward_addr: type: string + nullable: true description: Pool reward address example: stake1uy6yzwsxxc28lfms0qmpxvyz9a7y770rtcqx9y96m42cttqwvp4m5 owners: type: array + nullable: true items: type: string description: Pool (co)owner address @@ -2270,6 +2687,26 @@ components: type: string description: Latest transaction hash used for delegation by the account example: 368d08fe86804d637649341d3aec4a9baa7dffa6d00f16de2ba9dba814f1c948 + pool_registrations: + type: array + nullable: true + items: + type: object + properties: + pool_id_bech32: + $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + block_hash: + $ref: "#/components/schemas/blocks/items/properties/hash" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + epoch_no: + $ref: "#/components/schemas/epoch_info/items/properties/epoch_no" + epoch_slot: + $ref: "#/components/schemas/blocks/items/properties/epoch_slot" + active_epoch_no: + $ref: "#/components/schemas/pool_updates/items/properties/active_epoch_no" pool_delegators_history: type: array nullable: true @@ -2318,6 +2755,7 @@ components: active_epoch_no: type: integer description: Epoch number in which the update becomes active + nullable: true example: 324 vrf_key_hash: $ref: "#/components/schemas/pool_info/items/properties/vrf_key_hash" @@ -2339,8 +2777,11 @@ components: $ref: "#/components/schemas/pool_info/items/properties/meta_hash" meta_json: $ref: "#/components/schemas/pool_info/items/properties/meta_json" - pool_status: - $ref: "#/components/schemas/pool_info/items/properties/pool_status" + update_type: + type: string + description: Type of update task + enum: ["registration", "deregistration"] + example: registered retiring_epoch: $ref: "#/components/schemas/pool_info/items/properties/retiring_epoch" pool_relays: @@ -2352,6 +2793,8 @@ components: $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" relays: $ref: "#/components/schemas/pool_info/items/properties/relays" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/pool_status" pool_metadata: type: array items: @@ -2365,6 +2808,8 @@ components: $ref: "#/components/schemas/pool_info/items/properties/meta_hash" meta_json: $ref: "#/components/schemas/pool_info/items/properties/meta_json" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/pool_status" epoch_info: type: array items: @@ -2533,8 +2978,8 @@ components: description: The hash of the first block where these parameters are valid example: f9dc2a2fc3a2db09a71af007a740261de585afc9e3022b8e30535592ff4dd9e5 cost_models: - type: string - description: The per language cost models + type: object + description: The per language cost model in JSON example: null nullable: true price_mem: @@ -2724,17 +3169,21 @@ components: properties: block_hash: $ref: "#/components/schemas/blocks/items/properties/hash" - tx_hashes: - type: array - items: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + epoch_no: + $ref: "#/components/schemas/blocks/items/properties/epoch_no" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + block_time: + $ref: "#/components/schemas/blocks/items/properties/block_time" address_info: type: array items: type: object properties: address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" balance: type: string description: Sum of all UTxO values beloning to address @@ -2753,9 +3202,9 @@ components: type: object properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" block_height: $ref: "#/components/schemas/blocks/items/properties/block_height" block_time: @@ -2769,7 +3218,7 @@ components: reference_script: $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/reference_script" asset_list: - $ref: "#/components/schemas/account_assets/items/properties/asset_list" + $ref: "#/components/schemas/utxo_infos/items/properties/asset_list" address_txs: type: array items: @@ -2789,22 +3238,17 @@ components: type: object properties: address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" - asset_list: - $ref: "#/components/schemas/account_assets/items/properties/asset_list" - credential_txs: - $ref: "#/components/schemas/address_txs" - credential_utxos: - type: array - items: - type: object - properties: - tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" - tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" - value: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value" + $ref: "#/components/schemas/utxo_infos/items/properties/address" + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + $ref: "#/components/schemas/asset_addresses/items/properties/quantity" account_list: type: array items: @@ -2825,7 +3269,9 @@ components: enum: ["registered", "not registered"] example: registered delegated_pool: - $ref: "#/components/schemas/pool_list/items/properties/pool_id_bech32" + nullable: true + allOf: + - $ref: "#/components/schemas/pool_list/items/properties/pool_id_bech32" total_balance: type: string description: Total balance of the account including UTxO, rewards and MIRs (in lovelace) @@ -2854,23 +3300,67 @@ components: type: string description: Total treasury MIR value of the account example: "0" - account_utxos: + utxo_infos: type: array items: type: object properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" + type: string + description: Hash identifier of the transaction + example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" + type: integer + description: Index of UTxO in the transaction + example: 0 address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + type: string + description: A Cardano payment/base address (bech32 encoded) + example: addr1qxkfe8s6m8qt5436lec3f0320hrmpppwqgs2gah4360krvyssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqdc3cxp value: $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value" + stake_address: + $ref: "#/components/schemas/address_info/items/properties/stake_address" + payment_cred: + type: string + description: Payment credential + example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 + nullable: true + epoch_no: + $ref: "#/components/schemas/blocks/items/properties/epoch_no" block_height: $ref: "#/components/schemas/blocks/items/properties/block_height" block_time: $ref: "#/components/schemas/blocks/items/properties/block_time" + datum_hash: + $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_hash" + inline_datum: + $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/inline_datum" + reference_script: + $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/reference_script" + asset_list: + type: array + nullable: true + description: An array of assets on the UTxO + items: + properties: + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + type: string + description: Quantity of assets on the UTxO + example: 1 + is_spent: + type: boolean + description: True if the UTXO has been spent + example: true + account_rewards: type: array items: @@ -2915,7 +3405,7 @@ components: enum: ["registration", "delegation", "withdrawal", "deregistration"] example: "registration" tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" epoch_no: $ref: "#/components/schemas/blocks/items/properties/epoch_no" epoch_slot: @@ -2934,7 +3424,7 @@ components: addresses: type: array items: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" account_assets: type: array items: @@ -2942,25 +3432,16 @@ components: properties: stake_address: $ref: "#/components/schemas/account_history/items/properties/stake_address" - asset_list: - type: array - items: - type: object - properties: - policy_id: - $ref: "#/components/schemas/asset_info/items/properties/policy_id" - asset_name: - $ref: "#/components/schemas/asset_info/items/properties/asset_name" - fingerprint: - $ref: "#/components/schemas/asset_info/items/properties/fingerprint" - decimals: - type: integer - description: Asset decimals - example: 6 - quantity: - type: string - description: Asset quantity owned by account - example: 990000 + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + $ref: "#/components/schemas/asset_addresses/items/properties/quantity" account_history: type: array items: @@ -2992,9 +3473,7 @@ components: type: object properties: tx_hash: - type: string - description: Hash identifier of the transaction - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" block_hash: $ref: "#/components/schemas/blocks/items/properties/hash" block_height: @@ -3061,25 +3540,17 @@ components: type: object properties: bech32: - type: string - description: A Cardano payment/base address (bech32 encoded) where funds were sent or change to be returned - example: addr1q80rc8zj06yzdwwdyqc03rm4l3zv6n89rxuaak0t099n09yssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqad9mkw + $ref: "#/components/schemas/utxo_infos/items/properties/address" cred: type: string description: Payment credential example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 stake_addr: - nullable: true - allOf: - - $ref: "#/components/schemas/account_history/items/properties/stake_address" + $ref: "#/components/schemas/address_info/items/properties/stake_address" tx_hash: - type: string - description: Hash of transaction for UTxO - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: Index of UTxO in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" value: type: string description: Total sum of ADA on the UTxO @@ -3129,23 +3600,7 @@ components: description: Value (json) example: null asset_list: - type: array - nullable: true - description: An array of assets on the UTxO - items: - properties: - policy_id: - $ref: "#/components/schemas/asset_info/items/properties/policy_id" - asset_name: - $ref: "#/components/schemas/asset_info/items/properties/asset_name" - fingerprint: - $ref: "#/components/schemas/asset_info/items/properties/fingerprint" - decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" - quantity: - type: string - description: Quantity of assets on the UTxO - example: 1 + $ref: "#/components/schemas/utxo_infos/items/properties/asset_list" withdrawals: type: array description: Array of withdrawals with-in a transaction @@ -3174,7 +3629,7 @@ components: fingerprint: $ref: "#/components/schemas/asset_info/items/properties/fingerprint" decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" quantity: type: string description: Quantity of minted assets (negative on burn) @@ -3212,7 +3667,7 @@ components: items: properties: script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + $ref: "#/components/schemas/script_info/items/properties/script_hash" script_json: type: object description: JSON representation of the timelock script (null for other script types) @@ -3237,6 +3692,7 @@ components: } plutus_contracts: type: array + nullable: true description: Plutus contracts present in transaction (if any) items: properties: @@ -3246,15 +3702,11 @@ components: example: addr1w999n67e86jn6xal07pzxtrmqynspgx0fwmcmpua4wc6yzsxpljz3 nullable: true script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + $ref: "#/components/schemas/script_info/items/properties/script_hash" bytecode: - type: string - description: CBOR-encoded Plutus script data - example: 5911ea010000332333222332233223322332232323332223233322232333333332222222232333222323333222232323322323332223233322232323322332232323333322222332233223322332233223322223223223232533530333330083333573466e1cd55cea8032400046460a000264646464646666ae68cdc39aab9d5004480008cccc8888cccc16c01000c008004dd71aba15004375c6ae85400cdd71aba15002375a6ae84d5d1280111a8279a982819ab9c491035054310005149926135744a00226ae8940044d55cf280089baa001357426aae79401c8d4124d4c128cd5ce2481035054310004b499263333573466e1d40112002205323333573466e1d40152000205523504a35304b335738921035054310004c49926498cccd5cd19b8735573aa004900011980599191919191919191919191999ab9a3370e6aae754029200023333333333019335027232323333573466e1cd55cea8012400046603e60746ae854008c0b0d5d09aba2500223505935305a3357389201035054310005b49926135573ca00226ea8004d5d0a80519a8138141aba150093335502e75ca05a6ae854020ccd540b9d728169aba1500733502704335742a00c66a04e66aa0a8098eb4d5d0a8029919191999ab9a3370e6aae754009200023350213232323333573466e1cd55cea80124000466a05266a084eb4d5d0a80118239aba135744a00446a0ba6a60bc66ae712401035054310005f49926135573ca00226ea8004d5d0a8011919191999ab9a3370e6aae7540092000233502733504275a6ae854008c11cd5d09aba2500223505d35305e3357389201035054310005f49926135573ca00226ea8004d5d09aba2500223505935305a3357389201035054310005b49926135573ca00226ea8004d5d0a80219a813bae35742a00666a04e66aa0a8eb88004d5d0a801181c9aba135744a00446a0aa6a60ac66ae71241035054310005749926135744a00226ae8940044d5d1280089aba25001135744a00226ae8940044d5d1280089aba25001135573ca00226ea8004d5d0a8011919191999ab9a3370ea00290031180f181d9aba135573ca00646666ae68cdc3a801240084603a608a6ae84d55cf280211999ab9a3370ea00690011180e98181aba135573ca00a46666ae68cdc3a80224000460406eb8d5d09aab9e50062350503530513357389201035054310005249926499264984d55cea80089baa001357426ae8940088d4124d4c128cd5ce249035054310004b49926104a1350483530493357389201035054350004a4984d55cf280089baa001135573a6ea80044dd50009109198008018011000911111111109199999999980080580500480400380300280200180110009109198008018011000891091980080180109000891091980080180109000891091980080180109000909111180200290911118018029091111801002909111180080290008919118011bac0013200135503b2233335573e0024a01c466a01a60086ae84008c00cd5d100101991919191999ab9a3370e6aae75400d200023330073232323333573466e1cd55cea8012400046601a60626ae854008cd404c0b4d5d09aba25002235036353037335738921035054310003849926135573ca00226ea8004d5d0a801999aa805bae500a35742a00466a01eeb8d5d09aba25002235032353033335738921035054310003449926135744a00226aae7940044dd50009110919980080200180110009109198008018011000899aa800bae75a224464460046eac004c8004d540d488c8cccd55cf80112804919a80419aa81898031aab9d5002300535573ca00460086ae8800c0b84d5d08008891001091091198008020018900089119191999ab9a3370ea002900011a80418029aba135573ca00646666ae68cdc3a801240044a01046a0526a605466ae712401035054310002b499264984d55cea80089baa001121223002003112200112001232323333573466e1cd55cea8012400046600c600e6ae854008dd69aba135744a00446a0466a604866ae71241035054310002549926135573ca00226ea80048848cc00400c00880048c8cccd5cd19b8735573aa002900011bae357426aae7940088d407cd4c080cd5ce24810350543100021499261375400224464646666ae68cdc3a800a40084a00e46666ae68cdc3a8012400446a014600c6ae84d55cf280211999ab9a3370ea00690001280511a8111a981199ab9c490103505431000244992649926135573aa00226ea8004484888c00c0104488800844888004480048c8cccd5cd19b8750014800880188cccd5cd19b8750024800080188d4068d4c06ccd5ce249035054310001c499264984d55ce9baa0011220021220012001232323232323333573466e1d4005200c200b23333573466e1d4009200a200d23333573466e1d400d200823300b375c6ae854014dd69aba135744a00a46666ae68cdc3a8022400c46601a6eb8d5d0a8039bae357426ae89401c8cccd5cd19b875005480108cc048c050d5d0a8049bae357426ae8940248cccd5cd19b875006480088c050c054d5d09aab9e500b23333573466e1d401d2000230133016357426aae7940308d407cd4c080cd5ce2481035054310002149926499264992649926135573aa00826aae79400c4d55cf280109aab9e500113754002424444444600e01044244444446600c012010424444444600a010244444440082444444400644244444446600401201044244444446600201201040024646464646666ae68cdc3a800a400446660106eb4d5d0a8021bad35742a0066eb4d5d09aba2500323333573466e1d400920002300a300b357426aae7940188d4040d4c044cd5ce2490350543100012499264984d55cea80189aba25001135573ca00226ea80048488c00800c888488ccc00401401000c80048c8c8cccd5cd19b875001480088c018dd71aba135573ca00646666ae68cdc3a80124000460106eb8d5d09aab9e500423500a35300b3357389201035054310000c499264984d55cea80089baa001212230020032122300100320011122232323333573466e1cd55cea80124000466aa016600c6ae854008c014d5d09aba25002235007353008335738921035054310000949926135573ca00226ea8004498480048004448848cc00400c008448004848c0040088004888848cccc00401401000c00880044880084880048004448c8c00400488cc00cc008008004c8ccc888c8c8cc88cc88ccc888c8c8c8c8cc88c8c8cc88c8cccc8888c8c8c8c8c8c8c8c8ccc888c8ccc888ccc888cccccccc88888888cc88ccccc88888cccc8888cc88cc88cc88ccc888cc88cc88cc88cc88cc88c8c8c8cc88c8c8c8c8c8c8cc88c8c8c8c8c8c8cc888c888c8c94cd4c1240104cc0352401297369676e617475726520646f6573206e6f74206d617463682063726561746f7220696e20646174756d0033223530200022222222222533535032333553068120015027253353079333573466e3c0300041ec1e84d40d4004540d000c841ec41e54008c04540144cc054cc03524012f65787065637465642063726561746f7220746f2067657420616c6c206f66207768617420736865206f72646572656400330153350133335500e305c12001504f350481223335501b2253353070333505006353353502a3235302900122335304c0022350300012502f300e00221001132635300b335738920117696e76616c6964207075626c6963206b657920686173680000c498c05540244cc010c0340080044004004c8d4c08400488888888880254010ccd41354138c1894014c04920c08db7013350133335500e305c12001504f350481223335501b22533530703005002133004335506500d30100020011001001300d5004333504d504e30625005333504d504e533535026301a00321300a300d0011630124830236dc04cc0352401276f6e6c79206d617463686573206f66207061697273206f66206f726465727320616c6c6f77656400533535063350481223335501b225335307030050021330040020011001001300d50041306a162215335350650011306c16221533535067001107222130701623253353502732353024001222001500121333504e223530280022235302a0032232335304e0052335304f004253353077333573466e3c0080041e41e05400c41e081e08cd4c13c01081e094cd4c1dcccd5cd19b8f002001079078150031078153353502e0032153353502f00221335304c0022335304d002233530510022335305200223306d002001207b23353052002207b23306d00200122207b222335304f004207b2225335307c333573466e1c01800c1f81f454cd4c1f0ccd5cd19b8700500207e07d1333573466e1c0100041f81f441f441f441d854cd4d40b8004841d841d8c03140094cd4d40a0c07001484cd54190034c03c0045841b84c0300044d4c068004880084d4c02800480044800480048d4c0680048880088d4c06400488800c8d4c05000488888888880288d4c05400488004894cd4c184004418c4cd5ce001031089119aa8011a82600090009091800801100091a982c0009111002119a82999aa82b245003350533355056489000015054505412233355304b120013500550032353550560012233355304e120013500850062353550590012233353550490012330614800000488cc1880080048cc184005200000133040002001133500400105a22533530590021001105a123350492233353500400322002002001353500200122001122123300100300212001112232001320013550582253353504e00110032213300600230040012353003001223530070022222222222533335302600b21501b21501b21501b2133355305012001500f2353015001225335306353353063333573466e3cd4c0bc00888008d4c0bc010880081941904ccd5cd19b8735302f0022200135302f00422001065064106413501f0031501e00b13350432253353500d002210031001500c2212330010030022001222222222212333333333300100b00a009008007006005004003002200122123300100300220012221233300100400300220012212330010030022001121223002003112200112001122123300100300212001122123300100300212001122123300100300212001121222300300411222002112220011200121222230040052122223003005212222300200521222230010052001221233001003002200121222222230070082212222222330060090082122222223005008122222220041222222200322122222223300200900822122222223300100900820012122300200322212233300100500400320012122300200321223001003200112335001501d501e1220021220012001120011200113002012133500b2233300301300200150162223355300e1200123535501a00122335501d002335530111200123535501d001223355020002333535500d00123300a4800000488cc02c0080048cc028005200000133004002001223355300c1200123535501800122335501b00233353550080012335530101200123535501c00122335501f00235500f001001223335550080150020012335530101200123535501c00122335501f00235500d0010013335550030100020011112223335530041200150153355300c1200123535501800122335501b00235500b0013335530041200122353550190022253353021333553011120013500d33500f22533530230021025100102223535501c001223300a0020050061003133501900400350160013355300c120012353550180012232335501c00330010053200135502322533535019001135500b0032213535501e00222533530263300c00200813355010007001130060030023200135501c221122253353501500110022213300500233355300712001005004001112122230030041122122233002005004112122230010041120011233500722333535004003220020020013535002001220011221233001003002120013200135501422112253353500c0011500e22133500f3004002335530061200100400132001355013221122253353500c00113535006003220012213335350080052200230040023335530071200100500400112212330010030021200122333573466e3c00800404404088cdc000100088911801000919991119a80319aa80480199a80319aa804801000a803a8039a980380091110019a980380091110011a98038009111000889100109109119800802001890008891091980080180108900091110919998008028020018011000900211199ab9a3371000400200800a244004244002400222464600200244660066004004003 + $ref: "#/components/schemas/script_info/items/properties/bytes" size: - type: integer - description: The size of the CBOR serialised script (in bytes) - example: 234895 + $ref: "#/components/schemas/script_info/items/properties/size" valid_contract: type: boolean description: True if the contract is valid or there is no contract @@ -3314,17 +3766,11 @@ components: description: Payment credential example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 stake_addr: - nullable: true - allOf: - - $ref: "#/components/schemas/account_history/items/properties/stake_address" + $ref: "#/components/schemas/address_info/items/properties/stake_address" tx_hash: - type: string - description: Hash of transaction for UTxO - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: Index of UTxO in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" value: type: string description: Total sum of ADA on the UTxO @@ -3339,7 +3785,7 @@ components: items: properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" metadata: type: object nullable: true @@ -3360,7 +3806,7 @@ components: items: properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" num_confirmations: type: integer description: Number of block confirmations @@ -3414,9 +3860,7 @@ components: items: properties: payment_address: - type: string - description: A Cardano payment/base address (bech32 encoded) for transaction's input UTxO - example: addr1qxkfe8s6m8qt5436lec3f0320hrmpppwqgs2gah4360krvyssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqdc3cxp + $ref: "#/components/schemas/utxo_infos/items/properties/address" quantity: type: string description: Asset balance on the payment address @@ -3427,7 +3871,7 @@ components: items: properties: payment_address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" asset_summary: type: array items: @@ -3519,6 +3963,11 @@ components: decimals: type: integer example: 0 + cip68_metadata: + type: object + description: CIP 68 metadata if present for asset + nullable: true + example: {"222": {"fields": [{"map": [{"k": {"bytes": "6e616d65"}, "v": {"bytes": "74657374"}}]}], "constructor": 0}} asset_history: type: array items: @@ -3559,7 +4008,7 @@ components: asset_name: $ref: "#/components/schemas/asset_info/items/properties/asset_name" payment_address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" quantity: $ref: "#/components/schemas/asset_addresses/items/properties/quantity" policy_asset_info: @@ -3599,67 +4048,65 @@ components: total_supply: $ref: "#/components/schemas/asset_info/items/properties/total_supply" decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" - asset_txs: - type: array - description: An array of Tx hashes that included the given asset (latest first) - items: - properties: - tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" - epoch_no: - $ref: "#/components/schemas/blocks/items/properties/epoch_no" - block_height: - $ref: "#/components/schemas/blocks/items/properties/block_height" - block_time: - $ref: "#/components/schemas/blocks/items/properties/block_time" - native_script_list: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + script_info: type: array items: properties: script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + type: string + description: Hash of a script + example: bfa7ffa9b2e164873db6ac6d0528c82e212963bc62e10fd1d81da4af creation_tx_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/creation_tx_hash" + type: string + description: Hash of the script creation transaction + example: 255f061502ad83230351fbcf2d9fade1b5d118d332f92c9861075010a1fe3fbe type: type: string description: Type of the script - enum: ["timelock", "multisig"] - example: timelock - plutus_script_list: + enum: ["plutusV1","plutusV2","timelock","multisig"] + example: plutusV1 + value: + type: object + nullable: true + description: Data in JSON format + example: null + bytes: + type: string + description: Script bytes (cborSeq) + example: 5907f4010000332323232323232323233223232323232332232323232322223232533532533533355300712001323212330012233350052200200200100235001220011233001225335002101710010142325335333573466e3cd400488008d4020880080580544ccd5cd19b873500122001350082200101601510153500122002353500122002222222222200a101413357389201115554784f206e6f7420636f6e73756d6564000133333573466e1cd55cea8012400046644246600200600464646464646464646464646666ae68cdc39aab9d500a480008cccccccccc888888888848cccccccccc00402c02802402001c01801401000c008cd40508c8c8cccd5cd19b8735573aa0049000119910919800801801180f9aba150023019357426ae8940088c98d4cd5ce01581501481409aab9e5001137540026ae854028cd4050054d5d0a804999aa80bbae501635742a010666aa02eeb94058d5d0a80399a80a0109aba15006335014335502402275a6ae854014c8c8c8cccd5cd19b8735573aa00490001199109198008018011919191999ab9a3370e6aae754009200023322123300100300233502575a6ae854008c098d5d09aba2500223263533573805e05c05a05826aae7940044dd50009aba150023232323333573466e1cd55cea8012400046644246600200600466a04aeb4d5d0a80118131aba135744a004464c6a66ae700bc0b80b40b04d55cf280089baa001357426ae8940088c98d4cd5ce01581501481409aab9e5001137540026ae854010cd4051d71aba15003335014335502475c40026ae854008c070d5d09aba2500223263533573804e04c04a04826ae8940044d5d1280089aba25001135744a00226ae8940044d5d1280089aba25001135744a00226aae7940044dd50009aba150023232323333573466e1d400520062321222230040053019357426aae79400c8cccd5cd19b875002480108c848888c008014c06cd5d09aab9e500423333573466e1d400d20022321222230010053015357426aae7940148cccd5cd19b875004480008c848888c00c014dd71aba135573ca00c464c6a66ae7008808408007c0780740704d55cea80089baa001357426ae8940088c98d4cd5ce00d80d00c80c080c89931a99ab9c4910350543500019018135573ca00226ea8004c8004d5405888448894cd40044d400c88004884ccd401488008c010008ccd54c01c4800401401000448c88c008dd6000990009aa80b111999aab9f00125009233500830043574200460066ae880080548c8c8c8cccd5cd19b8735573aa00690001199911091998008020018011919191999ab9a3370e6aae7540092000233221233001003002301735742a00466a01c02c6ae84d5d1280111931a99ab9c01b01a019018135573ca00226ea8004d5d0a801999aa803bae500635742a00466a014eb8d5d09aba2500223263533573802e02c02a02826ae8940044d55cf280089baa0011335500175ceb44488c88c008dd5800990009aa80a11191999aab9f0022500823350073355017300635573aa004600a6aae794008c010d5d100180a09aba100111220021221223300100400312232323333573466e1d4005200023212230020033005357426aae79400c8cccd5cd19b8750024800884880048c98d4cd5ce00980900880800789aab9d500113754002464646666ae68cdc39aab9d5002480008cc8848cc00400c008c014d5d0a8011bad357426ae8940088c98d4cd5ce00800780700689aab9e5001137540024646666ae68cdc39aab9d5001480008dd71aba135573ca004464c6a66ae7003803403002c4dd500089119191999ab9a3370ea00290021091100091999ab9a3370ea00490011190911180180218031aba135573ca00846666ae68cdc3a801a400042444004464c6a66ae7004404003c0380340304d55cea80089baa0012323333573466e1d40052002200523333573466e1d40092000200523263533573801a01801601401226aae74dd5000891001091000919191919191999ab9a3370ea002900610911111100191999ab9a3370ea004900510911111100211999ab9a3370ea00690041199109111111198008048041bae35742a00a6eb4d5d09aba2500523333573466e1d40112006233221222222233002009008375c6ae85401cdd71aba135744a00e46666ae68cdc3a802a400846644244444446600c01201060186ae854024dd71aba135744a01246666ae68cdc3a8032400446424444444600e010601a6ae84d55cf280591999ab9a3370ea00e900011909111111180280418071aba135573ca018464c6a66ae7004c04804404003c03803403002c0284d55cea80209aab9e5003135573ca00426aae7940044dd50009191919191999ab9a3370ea002900111999110911998008028020019bad35742a0086eb4d5d0a8019bad357426ae89400c8cccd5cd19b875002480008c8488c00800cc020d5d09aab9e500623263533573801801601401201026aae75400c4d5d1280089aab9e500113754002464646666ae68cdc3a800a400446424460020066eb8d5d09aab9e500323333573466e1d400920002321223002003375c6ae84d55cf280211931a99ab9c009008007006005135573aa00226ea800444888c8c8cccd5cd19b8735573aa0049000119aa80518031aba150023005357426ae8940088c98d4cd5ce00480400380309aab9e5001137540029309000a490350543100112212330010030021123230010012233003300200200133512233002489209366f09fe40eaaeb17d3cb6b0b61e087d664174c39a48a986f86b2b0ba6e2a7b00480008848cc00400c0088005 + size: + type: integer + description: The size of the CBOR serialised script (in bytes) + example: 2039 + script_list: type: array items: properties: script_hash: - type: string - description: Hash of a script - example: d8480dc869b94b80e81ec91b0abe307279311fe0e7001a9488f61ff8 + $ref: "#/components/schemas/script_info/items/properties/script_hash" creation_tx_hash: - type: string - description: Hash of the script creation transaction - example: fda6c7697009237975ffc30f36666addf4c6e2a2c6f90411a24431b700baaab1 + $ref: "#/components/schemas/script_info/items/properties/creation_tx_hash" + type: + $ref: "#/components/schemas/script_info/items/properties/type" + size: + $ref: "#/components/schemas/script_info/items/properties/size" script_redeemers: type: array items: type: object properties: script_hash: - type: string - description: Hash of Transaction for which details are being shown - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/script_info/items/properties/script_hash" redeemers: type: array items: type: object properties: tx_hash: - type: string - description: Hash of Transaction containing the redeemer - example: fda6c7697009237975ffc30f36666addf4c6e2a2c6f90411a24431b700baaab1 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: The index of the redeemer pointer in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" unit_mem: description: The budget in Memory to run a script example: 520448 @@ -3691,20 +4138,20 @@ components: nullable: true example: 5a595ce795815e81d22a1a522cf3987d546dc5bb016de61b002edd63a5413ec4 datum_value: - type: object - description: The actual data in json format - example: { "bytes": "3c33" } + $ref: "#/components/schemas/script_info/items/properties/value" datum_info: type: array items: type: object properties: - hash: + datum_hash: $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_hash" + creation_tx_hash: + $ref: "#/components/schemas/script_info/items/properties/creation_tx_hash" value: - $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_value" + $ref: "#/components/schemas/script_info/items/properties/value" bytes: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/inline_datum/properties/bytes" + $ref: "#/components/schemas/script_info/items/properties/bytes" headers: {} responses: OK: @@ -3712,7 +4159,7 @@ components: NotFound: description: The server does not recognise the combination of endpoint and parameters provided Unauthorized: - description: The selected server has restricted the endpoint to be only usable via authentication. The authentication supplied was not authorized to access the endpoint + description: Access token is missing or invalid PartialContent: description: The result was truncated BadRequest: @@ -3730,12 +4177,12 @@ tags: - name: Transactions description: Query blockchain transaction details x-tag-expanded: false + - name: Stake Account + description: Query details about specific stake account addresses + x-tag-expanded: false - name: Address description: Query information about specific address(es) x-tag-expanded: false - - name: Account - description: Query details about specific stake account addresses - x-tag-expanded: false - name: Asset description: Query Asset related informations x-tag-expanded: false @@ -3745,4 +4192,5 @@ tags: - name: Script description: Query information about specific scripts (Smart Contracts) x-tag-expanded: false -security: [] +security: + - bearerAuth: [] diff --git a/specs/templates/1-api-info.yaml b/specs/templates/1-api-info.yaml index 656eaf17..da7e3265 100644 --- a/specs/templates/1-api-info.yaml +++ b/specs/templates/1-api-info.yaml @@ -1,6 +1,6 @@ info: title: Koios API - version: 1.0.10 + version: v1.1.0rc description: | Koios is best described as a Decentralized and Elastic RESTful query layer for exploring data on Cardano blockchain to consume within applications/wallets/explorers/etc. This page not only provides an OpenAPI Spec for live implementation, but also ability to execute live demo from client browser against each endpoint with pre-filled examples. @@ -13,11 +13,11 @@ info: Instead of returning entire row, you can elect which rows you would like to fetch from the endpoint by using the `select` parameter with corresponding columns separated by commas. See example below (first is complete information for tip, while second command gives us 3 columns we are interested in):

``` bash - curl "https://api.koios.rest/api/v0/tip" + curl "https://api.koios.rest/api/v1/tip" # [{"hash":"4d44c8a453e677f933c3df42ebcf2fe45987c41268b9cfc9b42ae305e8c3d99a","epoch":317,"abs_slot":51700871,"epoch_slot":120071,"block_height":6806994,"block_time":1643267162}] - curl "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_height" + curl "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_height" # [{"epoch":317,"epoch_slot":120071,"block_height":6806994}] ``` @@ -26,7 +26,7 @@ info: You can filter the returned output based on specific conditions using operators against a column within returned result. Consider an example where you would want to query blocks minted in first 3 minutes of epoch 250 (i.e. epoch_slot was less than 180). To do so your query would look like below:

``` bash - curl "https://api.koios.rest/api/v0/blocks?epoch=eq.250&epoch_slot=lt.180" + curl "https://api.koios.rest/api/v1/blocks?epoch=eq.250&epoch_slot=lt.180" # [{"hash":"8fad2808ac6b37064a0fa69f6fe065807703d5235a57442647bbcdba1c02faf8","epoch":250,"abs_slot":22636942,"epoch_slot":142,"block_height":5385757,"block_time":1614203233,"tx_count":65,"vrf_key":"vrf_vk14y9pjprzlsjvjt66mv5u7w7292sxp3kn4ewhss45ayjga5vurgaqhqknuu","pool":null,"op_cert_counter":2}, # {"hash":"9d33b02badaedc0dedd0d59f3e0411e5fb4ac94217fb5ee86719e8463c570e16","epoch":250,"abs_slot":22636800,"epoch_slot":0,"block_height":5385756,"block_time":1614203091,"tx_count":10,"vrf_key":"vrf_vk1dkfsejw3h2k7tnguwrauqfwnxa7wj3nkp3yw2yw3400c4nlkluwqzwvka6","pool":null,"op_cert_counter":2}] @@ -61,7 +61,7 @@ info: Consider a simple case where I want query `blocks` endpoint for `block_height` column and focus on `content-range` header to monitor the rows we discussed above.

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height" -I | grep -i content-range # content-range: 0-999/* @@ -70,7 +70,7 @@ info: As we can see above, the number of observations returned was 1000 (range being 0-999), but the total size was not queried to avoid wait times. Now, let's modify this default behaviour to query rows beyond the first 999, but this time - also add another clause to limit results by 500. We can do this using `offset=1000` and `limit=500` as below:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height&offset=1000&limit=500" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height&offset=1000&limit=500" -I | grep -i content-range # content-range: 1000-1499/* @@ -79,7 +79,7 @@ info: For GET endpoints, there is also another method to achieve the above, instead of adding parameters to the URL itself, you can specify a `Range` header as below to achieve something similar:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=block_height" -H "Range: 1000-1499" -I | grep -i content-range + curl -s "https://api.koios.rest/api/v1/blocks?select=block_height" -H "Range: 1000-1499" -I | grep -i content-range # content-range: 1000-1499/* @@ -93,7 +93,7 @@ info: Consider example where you want to check `epoch` and `epoch_slot` for the first 5 blocks created by a particular pool, i.e. you can set order to ascending based on block_height column and add horizontal filter for that pool ID as below:

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?pool=eq.pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc&order=block_height.asc&limit=5" + curl -s "https://api.koios.rest/api/v1/blocks?pool=eq.pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc&order=block_height.asc&limit=5" # [{"hash":"610b4c7bbebeeb212bd002885048cc33154ba29f39919d62a3d96de05d315706","epoch":236,"abs_slot":16594295,"epoch_slot":5495,"block_height":5086774,"block_time":1608160586,"tx_count":1,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1}, # {"hash":"d93d1db5275329ab695d30c06a35124038d8d9af64fc2b0aa082b8aa43da4164","epoch":236,"abs_slot":16597729,"epoch_slot":8929,"block_height":5086944,"block_time":1608164020,"tx_count":7,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1}, @@ -108,13 +108,13 @@ info: Below is an example of JSON/CSV output making use of above to print first in JSON (default), and then override response format to CSV.

``` bash - curl -s "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_time&limit=3" + curl -s "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_time&limit=3" # [{"epoch":318,"epoch_slot":27867,"block_time":1643606958}, # {"epoch":318,"epoch_slot":27841,"block_time":1643606932}, # {"epoch":318,"epoch_slot":27839,"block_time":1643606930}] - curl -s "https://api.koios.rest/api/v0/blocks?select=epoch,epoch_slot,block_time&limit=3" -H "Accept: text/csv" + curl -s "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_time&limit=3" -H "Accept: text/csv" # epoch,epoch_slot,block_time # 318,28491,1643607582 @@ -133,6 +133,10 @@ info: Yet, there may be cases where the above restrictions may need exceptions (for example, an explorer or a wallet might need more connections than above - going beyond the Burst Limit). For such cases, it is best to approach the team and we can work towards a solution. + # Authentication + + While Koios public tier remains unauthenticated and allows queries without any authentication, it has low limits to prevent actions against an erroraneous query/loop from a consumer. There is also a Free tier which requires setting up Bearer Auth token that is linked to the owner's wallet account (which can be connected to via [Koios website](https://koios.rest/pricing/Pricing.html) ). + The examples across this API site already [supports authentication](/#auth), for you to use in the queries. # Community projects diff --git a/specs/templates/2-api-params.yaml b/specs/templates/2-api-params.yaml index 40dac816..5c1a3d7d 100644 --- a/specs/templates/2-api-params.yaml +++ b/specs/templates/2-api-params.yaml @@ -170,6 +170,16 @@ parameters: in: query required: false allowEmptyValue: true + _extended: + deprecated: false + name: _extended + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + schema: + type: boolean + example: "false" + in: query + required: false + allowEmptyValue: true _history: deprecated: false name: _history diff --git a/specs/templates/3-api-requestBodies.yaml b/specs/templates/3-api-requestBodies.yaml index 0b69563f..4ef376b5 100644 --- a/specs/templates/3-api-requestBodies.yaml +++ b/specs/templates/3-api-requestBodies.yaml @@ -35,6 +35,29 @@ requestBodies: _addresses: - ##payment_addresses1_rb## - ##payment_addresses2_rb## + payment_addresses_with_extended: + content: + application/json: + schema: + required: + - _addresses + type: object + properties: + _addresses: + format: text + type: array + items: + type: string + description: Array of Cardano payment address(es) in bech32 format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _addresses: + - ##payment_addresses1_rb## + - ##payment_addresses2_rb## + _extended: true address_txs: content: application/json: @@ -107,6 +130,32 @@ requestBodies: _stake_addresses: - ##stake_addresses1_rb## - ##stake_addresses2_rb## + _first_only: false + _empty: false + + stake_addresses_with_extended: + content: + application/json: + schema: + required: + - _stake_addresses + type: object + properties: + _stake_addresses: + format: text + type: array + items: + type: string + description: Array of Cardano stake address(es) in bech32 format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _stake_addresses: + - ##stake_addresses1_rb## + - ##stake_addresses2_rb## + _extended: true stake_addresses: content: application/json: @@ -162,10 +211,15 @@ requestBodies: items: type: string description: Array of Cardano payment credential(s) in hex format + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call example: _payment_credentials: - ##credential_txs_payment_credentials1_rb## - ##credential_txs_payment_credentials2_rb## + _extended: true tx_ids: content: application/json: @@ -227,6 +281,22 @@ requestBodies: - ##pool_ids_pool_bech32_ids1_rb## - ##pool_ids_pool_bech32_ids2_rb## - ##pool_ids_pool_bech32_ids3_rb## + script_hashes: + content: + application/json: + schema: + type: object + properties: + _script_hashes: + format: text + type: array + items: + type: string + description: Array of Cardano script hashes + example: + _script_hashes: + - ##script_hashes1_rb## + - ##script_hashes2_rb## datum_hashes: content: application/json: @@ -263,3 +333,51 @@ requestBodies: _asset_list: - ##asset1_rb## - ##asset2_rb## + asset_list_with_extended: + content: + application/json: + schema: + required: + - _asset_list + type: object + properties: + _asset_list: + format: text + type: array + description: Array of array of policy ID and asset names (hex) + items: + type: array + items: + type: string + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _asset_list: + - ##asset1_rb## + - ##asset2_rb## + _extended: true + utxo_refs_with_extended: + content: + application/json: + schema: + required: + - _utxo_refs + type: object + properties: + _utxo_refs: + format: text + type: array + items: + type: string + description: Array of Cardano utxo references in the form "hash#index" + _extended: + format: boolean + type: boolean + description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call + example: + _utxo_refs: + - ##utxo_ref1_rb## + - ##utxo_ref2_rb## + _extended: false diff --git a/specs/templates/4-api-schemas.yaml b/specs/templates/4-api-schemas.yaml index 09703f3a..942a0582 100644 --- a/specs/templates/4-api-schemas.yaml +++ b/specs/templates/4-api-schemas.yaml @@ -111,20 +111,59 @@ schemas: type: string description: JSON encoded data with details about the parameter update example: {"decentralisation": 0.9} + reserve_withdrawals: + type: array + items: + properties: + epoch_no: + $ref: "#/components/schemas/epoch_info/items/properties/epoch_no" + epoch_slot: + $ref: "#/components/schemas/blocks/items/properties/epoch_slot" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + block_hash: + $ref: "#/components/schemas/blocks/items/properties/hash" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + amount: + $ref: "#/components/schemas/pool_delegators/items/properties/amount" + stake_address: + $ref: "#/components/schemas/account_history/items/properties/stake_address" pool_list: type: array items: properties: pool_id_bech32: - type: string - nullable: true - description: Bech32 representation of pool ID - example: pool1z5uqdk7dzdxaae5633fqfcu2eqzy3a3rgtuvy087fdld7yws0xt + $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" + pool_id_hex: + $ref: "#/components/schemas/pool_info/items/properties/pool_id_hex" + active_epoch_no: + $ref: "#/components/schemas/pool_info/items/properties/active_epoch_no" + margin: + $ref: "#/components/schemas/pool_info/items/properties/margin" + fixed_cost: + $ref: "#/components/schemas/pool_info/items/properties/fixed_cost" + pledge: + $ref: "#/components/schemas/pool_info/items/properties/pledge" + reward_addr: + $ref: "#/components/schemas/pool_info/items/properties/reward_addr" + owners: + $ref: "#/components/schemas/pool_info/items/properties/margin" + relays: + $ref: "#/components/schemas/pool_info/items/properties/margin" ticker: type: string nullable: true description: Pool ticker - example: JAZZ + example: AHL + meta_url: + $ref: "#/components/schemas/pool_info/items/properties/margin" + meta_hash: + $ref: "#/components/schemas/pool_info/items/properties/margin" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/margin" + retiring_epoch: + $ref: "#/components/schemas/pool_info/items/properties/margin" pool_history_info: type: array items: @@ -196,26 +235,32 @@ schemas: $ref: "#/components/schemas/pool_updates/items/properties/active_epoch_no" vrf_key_hash: type: string + nullable: true description: Pool VRF key hash example: 25efdad1bc12944d38e4e3c26c43565bec84973a812737b163b289e87d0d5ed3 margin: type: number + nullable: true description: Margin (decimal format) example: 0.1 fixed_cost: type: string + nullable: true description: Pool fixed cost per epoch example: "500000000" pledge: type: string + nullable: true description: Pool pledge in lovelace example: "64000000000000" reward_addr: type: string + nullable: true description: Pool reward address example: stake1uy6yzwsxxc28lfms0qmpxvyz9a7y770rtcqx9y96m42cttqwvp4m5 owners: type: array + nullable: true items: type: string description: Pool (co)owner address @@ -378,6 +423,26 @@ schemas: type: string description: Latest transaction hash used for delegation by the account example: 368d08fe86804d637649341d3aec4a9baa7dffa6d00f16de2ba9dba814f1c948 + pool_registrations: + type: array + nullable: true + items: + type: object + properties: + pool_id_bech32: + $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + block_hash: + $ref: "#/components/schemas/blocks/items/properties/hash" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + epoch_no: + $ref: "#/components/schemas/epoch_info/items/properties/epoch_no" + epoch_slot: + $ref: "#/components/schemas/blocks/items/properties/epoch_slot" + active_epoch_no: + $ref: "#/components/schemas/pool_updates/items/properties/active_epoch_no" pool_delegators_history: type: array nullable: true @@ -426,6 +491,7 @@ schemas: active_epoch_no: type: integer description: Epoch number in which the update becomes active + nullable: true example: 324 vrf_key_hash: $ref: "#/components/schemas/pool_info/items/properties/vrf_key_hash" @@ -447,8 +513,11 @@ schemas: $ref: "#/components/schemas/pool_info/items/properties/meta_hash" meta_json: $ref: "#/components/schemas/pool_info/items/properties/meta_json" - pool_status: - $ref: "#/components/schemas/pool_info/items/properties/pool_status" + update_type: + type: string + description: Type of update task + enum: ["registration", "deregistration"] + example: registered retiring_epoch: $ref: "#/components/schemas/pool_info/items/properties/retiring_epoch" pool_relays: @@ -460,6 +529,8 @@ schemas: $ref: "#/components/schemas/pool_info/items/properties/pool_id_bech32" relays: $ref: "#/components/schemas/pool_info/items/properties/relays" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/pool_status" pool_metadata: type: array items: @@ -473,6 +544,8 @@ schemas: $ref: "#/components/schemas/pool_info/items/properties/meta_hash" meta_json: $ref: "#/components/schemas/pool_info/items/properties/meta_json" + pool_status: + $ref: "#/components/schemas/pool_info/items/properties/pool_status" epoch_info: type: array items: @@ -641,8 +714,8 @@ schemas: description: The hash of the first block where these parameters are valid example: f9dc2a2fc3a2db09a71af007a740261de585afc9e3022b8e30535592ff4dd9e5 cost_models: - type: string - description: The per language cost models + type: object + description: The per language cost model in JSON example: null nullable: true price_mem: @@ -832,17 +905,21 @@ schemas: properties: block_hash: $ref: "#/components/schemas/blocks/items/properties/hash" - tx_hashes: - type: array - items: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + tx_hash: + $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + epoch_no: + $ref: "#/components/schemas/blocks/items/properties/epoch_no" + block_height: + $ref: "#/components/schemas/blocks/items/properties/block_height" + block_time: + $ref: "#/components/schemas/blocks/items/properties/block_time" address_info: type: array items: type: object properties: address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" balance: type: string description: Sum of all UTxO values beloning to address @@ -861,9 +938,9 @@ schemas: type: object properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" block_height: $ref: "#/components/schemas/blocks/items/properties/block_height" block_time: @@ -877,7 +954,7 @@ schemas: reference_script: $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/reference_script" asset_list: - $ref: "#/components/schemas/account_assets/items/properties/asset_list" + $ref: "#/components/schemas/utxo_infos/items/properties/asset_list" address_txs: type: array items: @@ -897,22 +974,17 @@ schemas: type: object properties: address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" - asset_list: - $ref: "#/components/schemas/account_assets/items/properties/asset_list" - credential_txs: - $ref: "#/components/schemas/address_txs" - credential_utxos: - type: array - items: - type: object - properties: - tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" - tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" - value: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value" + $ref: "#/components/schemas/utxo_infos/items/properties/address" + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + $ref: "#/components/schemas/asset_addresses/items/properties/quantity" account_list: type: array items: @@ -933,7 +1005,9 @@ schemas: enum: ["registered", "not registered"] example: registered delegated_pool: - $ref: "#/components/schemas/pool_list/items/properties/pool_id_bech32" + nullable: true + allOf: + - $ref: "#/components/schemas/pool_list/items/properties/pool_id_bech32" total_balance: type: string description: Total balance of the account including UTxO, rewards and MIRs (in lovelace) @@ -962,23 +1036,67 @@ schemas: type: string description: Total treasury MIR value of the account example: "0" - account_utxos: + utxo_infos: type: array items: type: object properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash" + type: string + description: Hash identifier of the transaction + example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e tx_index: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index" + type: integer + description: Index of UTxO in the transaction + example: 0 address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + type: string + description: A Cardano payment/base address (bech32 encoded) + example: addr1qxkfe8s6m8qt5436lec3f0320hrmpppwqgs2gah4360krvyssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqdc3cxp value: $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value" + stake_address: + $ref: "#/components/schemas/address_info/items/properties/stake_address" + payment_cred: + type: string + description: Payment credential + example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 + nullable: true + epoch_no: + $ref: "#/components/schemas/blocks/items/properties/epoch_no" block_height: $ref: "#/components/schemas/blocks/items/properties/block_height" block_time: $ref: "#/components/schemas/blocks/items/properties/block_time" + datum_hash: + $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_hash" + inline_datum: + $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/inline_datum" + reference_script: + $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/reference_script" + asset_list: + type: array + nullable: true + description: An array of assets on the UTxO + items: + properties: + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + type: string + description: Quantity of assets on the UTxO + example: 1 + is_spent: + type: boolean + description: True if the UTXO has been spent + example: true + account_rewards: type: array items: @@ -1023,7 +1141,7 @@ schemas: enum: ["registration", "delegation", "withdrawal", "deregistration"] example: "registration" tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" epoch_no: $ref: "#/components/schemas/blocks/items/properties/epoch_no" epoch_slot: @@ -1042,7 +1160,7 @@ schemas: addresses: type: array items: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" account_assets: type: array items: @@ -1050,25 +1168,16 @@ schemas: properties: stake_address: $ref: "#/components/schemas/account_history/items/properties/stake_address" - asset_list: - type: array - items: - type: object - properties: - policy_id: - $ref: "#/components/schemas/asset_info/items/properties/policy_id" - asset_name: - $ref: "#/components/schemas/asset_info/items/properties/asset_name" - fingerprint: - $ref: "#/components/schemas/asset_info/items/properties/fingerprint" - decimals: - type: integer - description: Asset decimals - example: 6 - quantity: - type: string - description: Asset quantity owned by account - example: 990000 + policy_id: + $ref: "#/components/schemas/asset_info/items/properties/policy_id" + asset_name: + $ref: "#/components/schemas/asset_info/items/properties/asset_name" + fingerprint: + $ref: "#/components/schemas/asset_info/items/properties/fingerprint" + decimals: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + quantity: + $ref: "#/components/schemas/asset_addresses/items/properties/quantity" account_history: type: array items: @@ -1100,9 +1209,7 @@ schemas: type: object properties: tx_hash: - type: string - description: Hash identifier of the transaction - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" block_hash: $ref: "#/components/schemas/blocks/items/properties/hash" block_height: @@ -1169,25 +1276,17 @@ schemas: type: object properties: bech32: - type: string - description: A Cardano payment/base address (bech32 encoded) where funds were sent or change to be returned - example: addr1q80rc8zj06yzdwwdyqc03rm4l3zv6n89rxuaak0t099n09yssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqad9mkw + $ref: "#/components/schemas/utxo_infos/items/properties/address" cred: type: string description: Payment credential example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 stake_addr: - nullable: true - allOf: - - $ref: "#/components/schemas/account_history/items/properties/stake_address" + $ref: "#/components/schemas/address_info/items/properties/stake_address" tx_hash: - type: string - description: Hash of transaction for UTxO - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: Index of UTxO in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" value: type: string description: Total sum of ADA on the UTxO @@ -1237,23 +1336,7 @@ schemas: description: Value (json) example: null asset_list: - type: array - nullable: true - description: An array of assets on the UTxO - items: - properties: - policy_id: - $ref: "#/components/schemas/asset_info/items/properties/policy_id" - asset_name: - $ref: "#/components/schemas/asset_info/items/properties/asset_name" - fingerprint: - $ref: "#/components/schemas/asset_info/items/properties/fingerprint" - decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" - quantity: - type: string - description: Quantity of assets on the UTxO - example: 1 + $ref: "#/components/schemas/utxo_infos/items/properties/asset_list" withdrawals: type: array description: Array of withdrawals with-in a transaction @@ -1282,7 +1365,7 @@ schemas: fingerprint: $ref: "#/components/schemas/asset_info/items/properties/fingerprint" decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" quantity: type: string description: Quantity of minted assets (negative on burn) @@ -1320,7 +1403,7 @@ schemas: items: properties: script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + $ref: "#/components/schemas/script_info/items/properties/script_hash" script_json: type: object description: JSON representation of the timelock script (null for other script types) @@ -1345,6 +1428,7 @@ schemas: } plutus_contracts: type: array + nullable: true description: Plutus contracts present in transaction (if any) items: properties: @@ -1354,15 +1438,11 @@ schemas: example: addr1w999n67e86jn6xal07pzxtrmqynspgx0fwmcmpua4wc6yzsxpljz3 nullable: true script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + $ref: "#/components/schemas/script_info/items/properties/script_hash" bytecode: - type: string - description: CBOR-encoded Plutus script data - example: 5911ea010000332333222332233223322332232323332223233322232333333332222222232333222323333222232323322323332223233322232323322332232323333322222332233223322332233223322223223223232533530333330083333573466e1cd55cea8032400046460a000264646464646666ae68cdc39aab9d5004480008cccc8888cccc16c01000c008004dd71aba15004375c6ae85400cdd71aba15002375a6ae84d5d1280111a8279a982819ab9c491035054310005149926135744a00226ae8940044d55cf280089baa001357426aae79401c8d4124d4c128cd5ce2481035054310004b499263333573466e1d40112002205323333573466e1d40152000205523504a35304b335738921035054310004c49926498cccd5cd19b8735573aa004900011980599191919191919191919191999ab9a3370e6aae754029200023333333333019335027232323333573466e1cd55cea8012400046603e60746ae854008c0b0d5d09aba2500223505935305a3357389201035054310005b49926135573ca00226ea8004d5d0a80519a8138141aba150093335502e75ca05a6ae854020ccd540b9d728169aba1500733502704335742a00c66a04e66aa0a8098eb4d5d0a8029919191999ab9a3370e6aae754009200023350213232323333573466e1cd55cea80124000466a05266a084eb4d5d0a80118239aba135744a00446a0ba6a60bc66ae712401035054310005f49926135573ca00226ea8004d5d0a8011919191999ab9a3370e6aae7540092000233502733504275a6ae854008c11cd5d09aba2500223505d35305e3357389201035054310005f49926135573ca00226ea8004d5d09aba2500223505935305a3357389201035054310005b49926135573ca00226ea8004d5d0a80219a813bae35742a00666a04e66aa0a8eb88004d5d0a801181c9aba135744a00446a0aa6a60ac66ae71241035054310005749926135744a00226ae8940044d5d1280089aba25001135744a00226ae8940044d5d1280089aba25001135573ca00226ea8004d5d0a8011919191999ab9a3370ea00290031180f181d9aba135573ca00646666ae68cdc3a801240084603a608a6ae84d55cf280211999ab9a3370ea00690011180e98181aba135573ca00a46666ae68cdc3a80224000460406eb8d5d09aab9e50062350503530513357389201035054310005249926499264984d55cea80089baa001357426ae8940088d4124d4c128cd5ce249035054310004b49926104a1350483530493357389201035054350004a4984d55cf280089baa001135573a6ea80044dd50009109198008018011000911111111109199999999980080580500480400380300280200180110009109198008018011000891091980080180109000891091980080180109000891091980080180109000909111180200290911118018029091111801002909111180080290008919118011bac0013200135503b2233335573e0024a01c466a01a60086ae84008c00cd5d100101991919191999ab9a3370e6aae75400d200023330073232323333573466e1cd55cea8012400046601a60626ae854008cd404c0b4d5d09aba25002235036353037335738921035054310003849926135573ca00226ea8004d5d0a801999aa805bae500a35742a00466a01eeb8d5d09aba25002235032353033335738921035054310003449926135744a00226aae7940044dd50009110919980080200180110009109198008018011000899aa800bae75a224464460046eac004c8004d540d488c8cccd55cf80112804919a80419aa81898031aab9d5002300535573ca00460086ae8800c0b84d5d08008891001091091198008020018900089119191999ab9a3370ea002900011a80418029aba135573ca00646666ae68cdc3a801240044a01046a0526a605466ae712401035054310002b499264984d55cea80089baa001121223002003112200112001232323333573466e1cd55cea8012400046600c600e6ae854008dd69aba135744a00446a0466a604866ae71241035054310002549926135573ca00226ea80048848cc00400c00880048c8cccd5cd19b8735573aa002900011bae357426aae7940088d407cd4c080cd5ce24810350543100021499261375400224464646666ae68cdc3a800a40084a00e46666ae68cdc3a8012400446a014600c6ae84d55cf280211999ab9a3370ea00690001280511a8111a981199ab9c490103505431000244992649926135573aa00226ea8004484888c00c0104488800844888004480048c8cccd5cd19b8750014800880188cccd5cd19b8750024800080188d4068d4c06ccd5ce249035054310001c499264984d55ce9baa0011220021220012001232323232323333573466e1d4005200c200b23333573466e1d4009200a200d23333573466e1d400d200823300b375c6ae854014dd69aba135744a00a46666ae68cdc3a8022400c46601a6eb8d5d0a8039bae357426ae89401c8cccd5cd19b875005480108cc048c050d5d0a8049bae357426ae8940248cccd5cd19b875006480088c050c054d5d09aab9e500b23333573466e1d401d2000230133016357426aae7940308d407cd4c080cd5ce2481035054310002149926499264992649926135573aa00826aae79400c4d55cf280109aab9e500113754002424444444600e01044244444446600c012010424444444600a010244444440082444444400644244444446600401201044244444446600201201040024646464646666ae68cdc3a800a400446660106eb4d5d0a8021bad35742a0066eb4d5d09aba2500323333573466e1d400920002300a300b357426aae7940188d4040d4c044cd5ce2490350543100012499264984d55cea80189aba25001135573ca00226ea80048488c00800c888488ccc00401401000c80048c8c8cccd5cd19b875001480088c018dd71aba135573ca00646666ae68cdc3a80124000460106eb8d5d09aab9e500423500a35300b3357389201035054310000c499264984d55cea80089baa001212230020032122300100320011122232323333573466e1cd55cea80124000466aa016600c6ae854008c014d5d09aba25002235007353008335738921035054310000949926135573ca00226ea8004498480048004448848cc00400c008448004848c0040088004888848cccc00401401000c00880044880084880048004448c8c00400488cc00cc008008004c8ccc888c8c8cc88cc88ccc888c8c8c8c8cc88c8c8cc88c8cccc8888c8c8c8c8c8c8c8c8ccc888c8ccc888ccc888cccccccc88888888cc88ccccc88888cccc8888cc88cc88cc88ccc888cc88cc88cc88cc88cc88c8c8c8cc88c8c8c8c8c8c8cc88c8c8c8c8c8c8cc888c888c8c94cd4c1240104cc0352401297369676e617475726520646f6573206e6f74206d617463682063726561746f7220696e20646174756d0033223530200022222222222533535032333553068120015027253353079333573466e3c0300041ec1e84d40d4004540d000c841ec41e54008c04540144cc054cc03524012f65787065637465642063726561746f7220746f2067657420616c6c206f66207768617420736865206f72646572656400330153350133335500e305c12001504f350481223335501b2253353070333505006353353502a3235302900122335304c0022350300012502f300e00221001132635300b335738920117696e76616c6964207075626c6963206b657920686173680000c498c05540244cc010c0340080044004004c8d4c08400488888888880254010ccd41354138c1894014c04920c08db7013350133335500e305c12001504f350481223335501b22533530703005002133004335506500d30100020011001001300d5004333504d504e30625005333504d504e533535026301a00321300a300d0011630124830236dc04cc0352401276f6e6c79206d617463686573206f66207061697273206f66206f726465727320616c6c6f77656400533535063350481223335501b225335307030050021330040020011001001300d50041306a162215335350650011306c16221533535067001107222130701623253353502732353024001222001500121333504e223530280022235302a0032232335304e0052335304f004253353077333573466e3c0080041e41e05400c41e081e08cd4c13c01081e094cd4c1dcccd5cd19b8f002001079078150031078153353502e0032153353502f00221335304c0022335304d002233530510022335305200223306d002001207b23353052002207b23306d00200122207b222335304f004207b2225335307c333573466e1c01800c1f81f454cd4c1f0ccd5cd19b8700500207e07d1333573466e1c0100041f81f441f441f441d854cd4d40b8004841d841d8c03140094cd4d40a0c07001484cd54190034c03c0045841b84c0300044d4c068004880084d4c02800480044800480048d4c0680048880088d4c06400488800c8d4c05000488888888880288d4c05400488004894cd4c184004418c4cd5ce001031089119aa8011a82600090009091800801100091a982c0009111002119a82999aa82b245003350533355056489000015054505412233355304b120013500550032353550560012233355304e120013500850062353550590012233353550490012330614800000488cc1880080048cc184005200000133040002001133500400105a22533530590021001105a123350492233353500400322002002001353500200122001122123300100300212001112232001320013550582253353504e00110032213300600230040012353003001223530070022222222222533335302600b21501b21501b21501b2133355305012001500f2353015001225335306353353063333573466e3cd4c0bc00888008d4c0bc010880081941904ccd5cd19b8735302f0022200135302f00422001065064106413501f0031501e00b13350432253353500d002210031001500c2212330010030022001222222222212333333333300100b00a009008007006005004003002200122123300100300220012221233300100400300220012212330010030022001121223002003112200112001122123300100300212001122123300100300212001122123300100300212001121222300300411222002112220011200121222230040052122223003005212222300200521222230010052001221233001003002200121222222230070082212222222330060090082122222223005008122222220041222222200322122222223300200900822122222223300100900820012122300200322212233300100500400320012122300200321223001003200112335001501d501e1220021220012001120011200113002012133500b2233300301300200150162223355300e1200123535501a00122335501d002335530111200123535501d001223355020002333535500d00123300a4800000488cc02c0080048cc028005200000133004002001223355300c1200123535501800122335501b00233353550080012335530101200123535501c00122335501f00235500f001001223335550080150020012335530101200123535501c00122335501f00235500d0010013335550030100020011112223335530041200150153355300c1200123535501800122335501b00235500b0013335530041200122353550190022253353021333553011120013500d33500f22533530230021025100102223535501c001223300a0020050061003133501900400350160013355300c120012353550180012232335501c00330010053200135502322533535019001135500b0032213535501e00222533530263300c00200813355010007001130060030023200135501c221122253353501500110022213300500233355300712001005004001112122230030041122122233002005004112122230010041120011233500722333535004003220020020013535002001220011221233001003002120013200135501422112253353500c0011500e22133500f3004002335530061200100400132001355013221122253353500c00113535006003220012213335350080052200230040023335530071200100500400112212330010030021200122333573466e3c00800404404088cdc000100088911801000919991119a80319aa80480199a80319aa804801000a803a8039a980380091110019a980380091110011a98038009111000889100109109119800802001890008891091980080180108900091110919998008028020018011000900211199ab9a3371000400200800a244004244002400222464600200244660066004004003 + $ref: "#/components/schemas/script_info/items/properties/bytes" size: - type: integer - description: The size of the CBOR serialised script (in bytes) - example: 234895 + $ref: "#/components/schemas/script_info/items/properties/size" valid_contract: type: boolean description: True if the contract is valid or there is no contract @@ -1422,17 +1502,11 @@ schemas: description: Payment credential example: de3c1c527e8826b9cd2030f88f75fc44cd4ce519b9ded9eb794b3794 stake_addr: - nullable: true - allOf: - - $ref: "#/components/schemas/account_history/items/properties/stake_address" + $ref: "#/components/schemas/address_info/items/properties/stake_address" tx_hash: - type: string - description: Hash of transaction for UTxO - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: Index of UTxO in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" value: type: string description: Total sum of ADA on the UTxO @@ -1447,7 +1521,7 @@ schemas: items: properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" metadata: type: object nullable: true @@ -1468,7 +1542,7 @@ schemas: items: properties: tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" num_confirmations: type: integer description: Number of block confirmations @@ -1522,9 +1596,7 @@ schemas: items: properties: payment_address: - type: string - description: A Cardano payment/base address (bech32 encoded) for transaction's input UTxO - example: addr1qxkfe8s6m8qt5436lec3f0320hrmpppwqgs2gah4360krvyssntpwjcz303mx3h4avg7p29l3zd8u3jyglmewds9ezrqdc3cxp + $ref: "#/components/schemas/utxo_infos/items/properties/address" quantity: type: string description: Asset balance on the payment address @@ -1535,7 +1607,7 @@ schemas: items: properties: payment_address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" asset_summary: type: array items: @@ -1627,6 +1699,11 @@ schemas: decimals: type: integer example: 0 + cip68_metadata: + type: object + description: CIP 68 metadata if present for asset + nullable: true + example: {"222": {"fields": [{"map": [{"k": {"bytes": "6e616d65"}, "v": {"bytes": "74657374"}}]}], "constructor": 0}} asset_history: type: array items: @@ -1667,7 +1744,7 @@ schemas: asset_name: $ref: "#/components/schemas/asset_info/items/properties/asset_name" payment_address: - $ref: "#/components/schemas/asset_addresses/items/properties/payment_address" + $ref: "#/components/schemas/utxo_infos/items/properties/address" quantity: $ref: "#/components/schemas/asset_addresses/items/properties/quantity" policy_asset_info: @@ -1707,67 +1784,65 @@ schemas: total_supply: $ref: "#/components/schemas/asset_info/items/properties/total_supply" decimals: - $ref: "#/components/schemas/account_assets/items/properties/asset_list/items/properties/decimals" - asset_txs: - type: array - description: An array of Tx hashes that included the given asset (latest first) - items: - properties: - tx_hash: - $ref: "#/components/schemas/tx_info/items/properties/tx_hash" - epoch_no: - $ref: "#/components/schemas/blocks/items/properties/epoch_no" - block_height: - $ref: "#/components/schemas/blocks/items/properties/block_height" - block_time: - $ref: "#/components/schemas/blocks/items/properties/block_time" - native_script_list: + $ref: "#/components/schemas/asset_info/items/properties/token_registry_metadata/properties/decimals" + script_info: type: array items: properties: script_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/script_hash" + type: string + description: Hash of a script + example: bfa7ffa9b2e164873db6ac6d0528c82e212963bc62e10fd1d81da4af creation_tx_hash: - $ref: "#/components/schemas/plutus_script_list/items/properties/creation_tx_hash" + type: string + description: Hash of the script creation transaction + example: 255f061502ad83230351fbcf2d9fade1b5d118d332f92c9861075010a1fe3fbe type: type: string description: Type of the script - enum: ["timelock", "multisig"] - example: timelock - plutus_script_list: + enum: ["plutusV1","plutusV2","timelock","multisig"] + example: plutusV1 + value: + type: object + nullable: true + description: Data in JSON format + example: null + bytes: + type: string + description: Script bytes (cborSeq) + example: 5907f4010000332323232323232323233223232323232332232323232322223232533532533533355300712001323212330012233350052200200200100235001220011233001225335002101710010142325335333573466e3cd400488008d4020880080580544ccd5cd19b873500122001350082200101601510153500122002353500122002222222222200a101413357389201115554784f206e6f7420636f6e73756d6564000133333573466e1cd55cea8012400046644246600200600464646464646464646464646666ae68cdc39aab9d500a480008cccccccccc888888888848cccccccccc00402c02802402001c01801401000c008cd40508c8c8cccd5cd19b8735573aa0049000119910919800801801180f9aba150023019357426ae8940088c98d4cd5ce01581501481409aab9e5001137540026ae854028cd4050054d5d0a804999aa80bbae501635742a010666aa02eeb94058d5d0a80399a80a0109aba15006335014335502402275a6ae854014c8c8c8cccd5cd19b8735573aa00490001199109198008018011919191999ab9a3370e6aae754009200023322123300100300233502575a6ae854008c098d5d09aba2500223263533573805e05c05a05826aae7940044dd50009aba150023232323333573466e1cd55cea8012400046644246600200600466a04aeb4d5d0a80118131aba135744a004464c6a66ae700bc0b80b40b04d55cf280089baa001357426ae8940088c98d4cd5ce01581501481409aab9e5001137540026ae854010cd4051d71aba15003335014335502475c40026ae854008c070d5d09aba2500223263533573804e04c04a04826ae8940044d5d1280089aba25001135744a00226ae8940044d5d1280089aba25001135744a00226aae7940044dd50009aba150023232323333573466e1d400520062321222230040053019357426aae79400c8cccd5cd19b875002480108c848888c008014c06cd5d09aab9e500423333573466e1d400d20022321222230010053015357426aae7940148cccd5cd19b875004480008c848888c00c014dd71aba135573ca00c464c6a66ae7008808408007c0780740704d55cea80089baa001357426ae8940088c98d4cd5ce00d80d00c80c080c89931a99ab9c4910350543500019018135573ca00226ea8004c8004d5405888448894cd40044d400c88004884ccd401488008c010008ccd54c01c4800401401000448c88c008dd6000990009aa80b111999aab9f00125009233500830043574200460066ae880080548c8c8c8cccd5cd19b8735573aa00690001199911091998008020018011919191999ab9a3370e6aae7540092000233221233001003002301735742a00466a01c02c6ae84d5d1280111931a99ab9c01b01a019018135573ca00226ea8004d5d0a801999aa803bae500635742a00466a014eb8d5d09aba2500223263533573802e02c02a02826ae8940044d55cf280089baa0011335500175ceb44488c88c008dd5800990009aa80a11191999aab9f0022500823350073355017300635573aa004600a6aae794008c010d5d100180a09aba100111220021221223300100400312232323333573466e1d4005200023212230020033005357426aae79400c8cccd5cd19b8750024800884880048c98d4cd5ce00980900880800789aab9d500113754002464646666ae68cdc39aab9d5002480008cc8848cc00400c008c014d5d0a8011bad357426ae8940088c98d4cd5ce00800780700689aab9e5001137540024646666ae68cdc39aab9d5001480008dd71aba135573ca004464c6a66ae7003803403002c4dd500089119191999ab9a3370ea00290021091100091999ab9a3370ea00490011190911180180218031aba135573ca00846666ae68cdc3a801a400042444004464c6a66ae7004404003c0380340304d55cea80089baa0012323333573466e1d40052002200523333573466e1d40092000200523263533573801a01801601401226aae74dd5000891001091000919191919191999ab9a3370ea002900610911111100191999ab9a3370ea004900510911111100211999ab9a3370ea00690041199109111111198008048041bae35742a00a6eb4d5d09aba2500523333573466e1d40112006233221222222233002009008375c6ae85401cdd71aba135744a00e46666ae68cdc3a802a400846644244444446600c01201060186ae854024dd71aba135744a01246666ae68cdc3a8032400446424444444600e010601a6ae84d55cf280591999ab9a3370ea00e900011909111111180280418071aba135573ca018464c6a66ae7004c04804404003c03803403002c0284d55cea80209aab9e5003135573ca00426aae7940044dd50009191919191999ab9a3370ea002900111999110911998008028020019bad35742a0086eb4d5d0a8019bad357426ae89400c8cccd5cd19b875002480008c8488c00800cc020d5d09aab9e500623263533573801801601401201026aae75400c4d5d1280089aab9e500113754002464646666ae68cdc3a800a400446424460020066eb8d5d09aab9e500323333573466e1d400920002321223002003375c6ae84d55cf280211931a99ab9c009008007006005135573aa00226ea800444888c8c8cccd5cd19b8735573aa0049000119aa80518031aba150023005357426ae8940088c98d4cd5ce00480400380309aab9e5001137540029309000a490350543100112212330010030021123230010012233003300200200133512233002489209366f09fe40eaaeb17d3cb6b0b61e087d664174c39a48a986f86b2b0ba6e2a7b00480008848cc00400c0088005 + size: + type: integer + description: The size of the CBOR serialised script (in bytes) + example: 2039 + script_list: type: array items: properties: script_hash: - type: string - description: Hash of a script - example: d8480dc869b94b80e81ec91b0abe307279311fe0e7001a9488f61ff8 + $ref: "#/components/schemas/script_info/items/properties/script_hash" creation_tx_hash: - type: string - description: Hash of the script creation transaction - example: fda6c7697009237975ffc30f36666addf4c6e2a2c6f90411a24431b700baaab1 + $ref: "#/components/schemas/script_info/items/properties/creation_tx_hash" + type: + $ref: "#/components/schemas/script_info/items/properties/type" + size: + $ref: "#/components/schemas/script_info/items/properties/size" script_redeemers: type: array items: type: object properties: script_hash: - type: string - description: Hash of Transaction for which details are being shown - example: f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e + $ref: "#/components/schemas/script_info/items/properties/script_hash" redeemers: type: array items: type: object properties: tx_hash: - type: string - description: Hash of Transaction containing the redeemer - example: fda6c7697009237975ffc30f36666addf4c6e2a2c6f90411a24431b700baaab1 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_hash" tx_index: - type: integer - description: The index of the redeemer pointer in the transaction - example: 0 + $ref: "#/components/schemas/utxo_infos/items/properties/tx_index" unit_mem: description: The budget in Memory to run a script example: 520448 @@ -1799,17 +1874,17 @@ schemas: nullable: true example: 5a595ce795815e81d22a1a522cf3987d546dc5bb016de61b002edd63a5413ec4 datum_value: - type: object - description: The actual data in json format - example: { "bytes": "3c33" } + $ref: "#/components/schemas/script_info/items/properties/value" datum_info: type: array items: type: object properties: - hash: + datum_hash: $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_hash" + creation_tx_hash: + $ref: "#/components/schemas/script_info/items/properties/creation_tx_hash" value: - $ref: "#/components/schemas/script_redeemers/items/properties/redeemers/items/properties/datum_value" + $ref: "#/components/schemas/script_info/items/properties/value" bytes: - $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/inline_datum/properties/bytes" + $ref: "#/components/schemas/script_info/items/properties/bytes" diff --git a/specs/templates/api-main.yaml b/specs/templates/api-main.yaml index c411c04d..86168694 100644 --- a/specs/templates/api-main.yaml +++ b/specs/templates/api-main.yaml @@ -1,11 +1,12 @@ openapi: 3.0.2 #!info!# servers: - - url: https://api.koios.rest/api/v0 - - url: https://guild.koios.rest/api/v0 - - url: https://preview.koios.rest/api/v0 - - url: https://preprod.koios.rest/api/v0 + - url: https://api.koios.rest/api/v1 + - url: https://guild.koios.rest/api/v1 + - url: https://preview.koios.rest/api/v1 + - url: https://preprod.koios.rest/api/v1 paths: + /tip: #RPC get: tags: @@ -86,6 +87,45 @@ paths: $ref: "#/components/responses/NotFound" summary: Param Update Proposals description: Get all parameter update proposals submitted to the chain starting Shelley era + /reserve_withdrawals: #RPC + get: + tags: + - Network + responses: + "200": + description: Array of withdrawals from reserves against stake accounts + content: + application/json: + schema: + $ref: "#/components/schemas/reserve_withdrawals" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Reserve Withdrawals + description: List of all withdrawals from reserves against stake accounts + /treasury_withdrawals: #RPC + get: + tags: + - Network + responses: + "200": + description: Array of withdrawals from treasury against stake accounts + content: + application/json: + schema: + $ref: "#/components/schemas/reserve_withdrawals" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Treasury Withdrawals + description: List of all withdrawals from treasury against stake accounts + /epoch_info: #RPC get: tags: @@ -153,6 +193,7 @@ paths: summary: Epoch's Block Protocols description: >- Get the information about block protocol distribution in epoch + /blocks: get: tags: @@ -214,28 +255,29 @@ paths: $ref: "#/components/responses/NotFound" summary: Block Transactions description: Get a list of all transactions included in provided blocks - /tx_info: #RPC + + /utxo_info: #RPC post: tags: - Transactions requestBody: - $ref: "#/components/requestBodies/tx_ids" + $ref: "#/components/requestBodies/utxo_refs_with_extended" responses: "200": - description: Array of detailed information about transaction(s) + description: Array of UTXO details content: application/json: schema: - $ref: "#/components/schemas/tx_info" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction Information - description: Get detailed information about transaction(s) - /tx_utxos: #RPC + summary: UTxO Info + description: Get UTxO set for requested UTxO references + /tx_info: #RPC post: tags: - Transactions @@ -243,19 +285,19 @@ paths: $ref: "#/components/requestBodies/tx_ids" responses: "200": - description: Array of inputs and outputs for given transaction(s) + description: Array of detailed information about transaction(s) content: application/json: schema: - $ref: "#/components/schemas/tx_utxos" + $ref: "#/components/schemas/tx_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction UTxOs [DEPRECATED] - description: Get UTxO set (inputs/outputs) of transactions. + summary: Transaction Information + description: Get detailed information about transaction(s) /tx_metadata: #RPC post: tags: @@ -309,7 +351,7 @@ paths: # If using a CLI-generated tx file, please ensure to deserialise (using `xxd -p -r <<< $(jq .cborHex ${tx.signed}) > ${data}`) first before submitting. curl -X POST \ --header "Content-Type: application/cbor" \ - --data-binary ${data} https://api.koios.rest/api/v0/submittx + --data-binary @${data} https://api.koios.rest/api/v1/submittx responses: "202": description: OK @@ -345,8 +387,31 @@ paths: $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Transaction Status (Block Confirmations) + summary: Transaction Status description: Get the number of block confirmations for a given transaction hash list + /tx_utxos: #RPC + post: + tags: + - Transactions + deprecated: true + requestBody: + $ref: "#/components/requestBodies/tx_ids" + responses: + "200": + description: Array of inputs and outputs for given transaction(s) + content: + application/json: + schema: + $ref: "#/components/schemas/tx_utxos" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Transaction UTxOs + description: Get UTxO set (inputs/outputs) of transactions [DEPRECATED - Use /utxo_info instead]. + /address_info: #RPC post: tags: @@ -368,27 +433,27 @@ paths: $ref: "#/components/responses/NotFound" summary: Address Information description: Get address info - balance, associated stake address (if any) and UTxO set for given addresses - /address_txs: #RPC + /address_utxos: #RPC post: tags: - Address requestBody: - $ref: "#/components/requestBodies/address_txs" + $ref: "#/components/requestBodies/payment_addresses_with_extended" responses: "200": - description: Array of transaction hashes + description: Array of address UTXOs content: application/json: schema: - $ref: "#/components/schemas/address_txs" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Address Transactions - description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive) + summary: Address UTXOs + description: Get UTxO set for given addresses /credential_utxos: #RPC post: tags: @@ -401,7 +466,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/credential_utxos" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": @@ -409,28 +474,28 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: UTxOs from payment credentials - description: Get a list of UTxO against input payment credential array including their balances - /address_assets: #RPC + description: Get UTxO details for requested payment credentials + /address_txs: #RPC post: tags: - Address requestBody: - $ref: "#/components/requestBodies/payment_addresses" + $ref: "#/components/requestBodies/address_txs" responses: "200": - description: Array of address-owned assets + description: Array of transaction hashes content: application/json: schema: - $ref: "#/components/schemas/address_assets" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Address Assets - description: Get the list of all the assets (policy, name and quantity) for given addresses + summary: Address Transactions + description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive) /credential_txs: #RPC post: tags: @@ -443,7 +508,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/credential_txs" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": @@ -452,6 +517,28 @@ paths: $ref: "#/components/responses/NotFound" summary: Transactions from payment credentials description: Get the transaction hash list of input payment credential array, optionally filtering after specified block height (inclusive) + /address_assets: #RPC + post: + tags: + - Address + requestBody: + $ref: "#/components/requestBodies/payment_addresses" + responses: + "200": + description: Array of address-owned assets + content: + application/json: + schema: + $ref: "#/components/schemas/address_assets" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Address Assets + description: Get the list of all the assets (policy, name and quantity) for given addresses + /account_list: get: tags: @@ -492,48 +579,70 @@ paths: $ref: "#/components/responses/NotFound" summary: Account Information description: Get the account information for given stake addresses - /account_utxos: #RPC - get: + /account_info_cached: #RPC + post: tags: - Stake Account - parameters: - - $ref: "#/components/parameters/_stake_address" + requestBody: + $ref: "#/components/requestBodies/stake_addresses" responses: "200": - description: Array of account UTxOs associated with stake address + description: Array of account information content: application/json: schema: - $ref: "#/components/schemas/account_utxos" + $ref: "#/components/schemas/account_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Account UTxOs - description: Get a list of all UTxOs for a given stake address (account) - /account_info_cached: #RPC + summary: Account Information (Cached) + description: Get the cached account information for given stake addresses (effective for performance query against registered accounts) + /account_utxos: #RPC post: tags: - Stake Account requestBody: - $ref: "#/components/requestBodies/stake_addresses" + $ref: "#/components/requestBodies/stake_addresses_with_extended" responses: "200": - description: Array of account information + description: Array of account UTxOs associated with given stake addresses content: application/json: schema: - $ref: "#/components/schemas/account_info" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Account Information (Cached) - description: Get the cached account information for given stake addresses, effective for registered accounts + summary: UTxOs for stake addresses (accounts) + description: Get a list of all UTxOs for given stake addresses (account)s + /account_txs: #RPC + get: + tags: + - Stake Account + parameters: + - $ref: "#/components/parameters/_stake_address" + - $ref: "#/components/parameters/_after_block_height" + responses: + "200": + description: Array of Txs associated with stake address (account) + content: + application/json: + schema: + $ref: "#/components/schemas/address_txs" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Account Txs + description: Get a list of all Txs for a given stake address (account) /account_rewards: #RPC post: tags: @@ -642,6 +751,7 @@ paths: $ref: "#/components/responses/NotFound" summary: Account History description: Get the staking history of given stake addresses (accounts) + /asset_list: get: tags: @@ -661,95 +771,89 @@ paths: $ref: "#/components/responses/NotFound" summary: Asset List description: Get the list of all native assets (paginated) - /asset_token_registry: + /policy_asset_list: #RPC get: tags: - Asset + parameters: + - $ref: "#/components/parameters/_asset_policy" responses: "200": - description: Array of token registry information for each asset + description: Array of detailed information of assets under the same policy content: application/json: schema: - $ref: "#/components/schemas/asset_token_registry" + $ref: "#/components/schemas/policy_asset_list" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Token Registry - description: Get a list of assets registered via token registry on github - /asset_addresses: #RPC + summary: Policy Asset List + description: Get the list of asset under the given policy (including balances) + /asset_token_registry: get: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of payment addresses holding the given token (including balances) + description: Array of token registry information for each asset content: application/json: schema: - $ref: "#/components/schemas/asset_addresses" + $ref: "#/components/schemas/asset_token_registry" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Addresses - description: Get the list of all addresses holding a given asset

- `Note - Due to cardano's UTxO design and usage from projects, asset to addresses map can be infinite. Thus, for a small subset of active projects - with millions of transactions, these might end up with timeouts (HTTP code 504) on free layer. Such large-scale projects are free to subscribe to - query layers to have a dedicated cache table for themselves served via Koios.` - /asset_address_list: #RPC - get: + summary: Asset Token Registry + description: Get a list of assets registered via token registry on github + /asset_info: #RPC + post: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" + requestBody: + $ref: "#/components/requestBodies/asset_list" responses: "200": - description: Array of payment addresses holding the given token (including balances) + description: Array of detailed asset information content: application/json: schema: - $ref: "#/components/schemas/asset_addresses" + $ref: "#/components/schemas/asset_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Address List [DEPRECATED] - description: Get the list of all addresses holding a given asset (replaced by asset_addresses) - /asset_nft_address: #RPC - get: + summary: Asset Information (Bulk) + description: Get the information of a list of assets including first minting & token registry metadata + /asset_utxos: #RPC + post: tags: - Asset - parameters: - - $ref: "#/components/parameters/_asset_policy_nft" - - $ref: "#/components/parameters/_asset_name_nft" + requestBody: + $ref: "#/components/requestBodies/asset_list_with_extended" responses: "200": - description: Payment addresses currently holding the given NFT + description: Array of UTXOs for given asset list content: application/json: schema: - $ref: "#/components/schemas/asset_nft_address" + $ref: "#/components/schemas/utxo_infos" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: NFT Address - description: Get the address where specified NFT currently reside on. - /asset_info: #RPC + summary: Asset UTXOs + description: Get the UTXO information of a list of assets including + /asset_history: #RPC get: tags: - Asset @@ -758,61 +862,66 @@ paths: - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed asset information + description: Array of asset mint/burn history content: application/json: schema: - $ref: "#/components/schemas/asset_info" + $ref: "#/components/schemas/asset_history" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Information - description: Get the information of an asset including first minting & token registry metadata - post: + summary: Asset History + description: Get the mint/burn history of an asset + /asset_addresses: #RPC + get: tags: - Asset - requestBody: - $ref: "#/components/requestBodies/asset_list" + parameters: + - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed asset information + description: Array of payment addresses holding the given token (including balances) content: application/json: schema: - $ref: "#/components/schemas/asset_info" + $ref: "#/components/schemas/asset_addresses" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Information (Bulk) - description: Get the information of a list of assets including first minting & token registry metadata - /asset_history: #RPC + summary: Asset Addresses + description: Get the list of all addresses holding a given asset

+ `Note - Due to cardano's UTxO design and usage from projects, asset to addresses map can be infinite. Thus, for a small subset of active projects + with millions of transactions, these might end up with timeouts (HTTP code 504) on free layer. Such large-scale projects are free to subscribe to + query layers to have a dedicated cache table for themselves served via Koios.` + /asset_nft_address: #RPC get: tags: - Asset parameters: - - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" + - $ref: "#/components/parameters/_asset_policy_nft" + - $ref: "#/components/parameters/_asset_name_nft" responses: "200": - description: Array of asset mint/burn history + description: Payment addresses currently holding the given NFT content: application/json: schema: - $ref: "#/components/schemas/asset_history" + $ref: "#/components/schemas/asset_nft_address" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset History - description: Get the mint/burn history of an asset + summary: NFT Address + description: Get the address where specified NFT currently reside on. /policy_asset_addresses: #RPC get: tags: @@ -858,94 +967,98 @@ paths: $ref: "#/components/responses/NotFound" summary: Policy Asset Information description: Get the information for all assets under the same policy - /asset_policy_info: #RPC + /asset_summary: #RPC get: tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of detailed information of assets under the same policy + description: Array of asset summary information content: application/json: schema: - $ref: "#/components/schemas/policy_asset_info" + $ref: "#/components/schemas/asset_summary" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Policy Information [DEPRECATED] - description: Get the information for all assets under the same policy (replaced by asset_addresses) - /policy_asset_list: #RPC + summary: Asset Summary + description: Get the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance) + /asset_txs: #RPC get: tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" + - $ref: "#/components/parameters/_asset_name" + - $ref: "#/components/parameters/_after_block_height" + - $ref: "#/components/parameters/_history" responses: "200": - description: Array of detailed information of assets under the same policy + description: An array of Tx hashes that included the given asset (latest first) content: application/json: schema: - $ref: "#/components/schemas/policy_asset_list" + $ref: "#/components/schemas/address_txs" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Policy Asset List - description: Get the list of asset under the given policy (including balances) - /asset_summary: #RPC + summary: Asset Transactions + description: Get the list of current or all asset transaction hashes (newest first) + /asset_address_list: #RPC get: tags: - Asset + deprecated: true parameters: - $ref: "#/components/parameters/_asset_policy" - $ref: "#/components/parameters/_asset_name" responses: "200": - description: Array of asset summary information + description: Array of payment addresses holding the given token (including balances) content: application/json: schema: - $ref: "#/components/schemas/asset_summary" + $ref: "#/components/schemas/asset_addresses" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Summary - description: Get the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance) - /asset_txs: #RPC + summary: Asset Address List + description: Get the list of all addresses holding a given asset [DEPRECATED - replaced by asset_addresses] + /asset_policy_info: #RPC get: + deprecated: true tags: - Asset parameters: - $ref: "#/components/parameters/_asset_policy" - - $ref: "#/components/parameters/_asset_name" - - $ref: "#/components/parameters/_after_block_height" - - $ref: "#/components/parameters/_history" responses: "200": - description: Array of Tx hashes that included the given asset + description: Array of detailed information of assets under the same policy content: application/json: schema: - $ref: "#/components/schemas/asset_txs" + $ref: "#/components/schemas/policy_asset_info" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" - summary: Asset Transactions - description: Get the list of current or all asset transaction hashes (newest first) + summary: Asset Policy Information + description: Get the information for all assets under the same policy (DEPRECATED - replaced by policy_asset_info) + /pool_list: #RPC get: tags: @@ -964,7 +1077,7 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool List - description: A list of all currently registered/retiring (not retired) pools + description: List of brief info for all pools /pool_info: #RPC post: tags: @@ -1120,6 +1233,48 @@ paths: $ref: "#/components/responses/NotFound" summary: Pool Updates (History) description: Return all pool updates for all pools or only updates for specific pool if specified + /pool_registrations: #RPC + get: + tags: + - Pool + parameters: + - $ref: "#/components/parameters/_epoch_no" + responses: + "200": + description: Array of historical pool updates + content: + application/json: + schema: + $ref: "#/components/schemas/pool_registrations" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Pool Registrations + description: Return all pool registrations initiated in the requested epoch + /pool_retirements: #RPC + get: + tags: + - Pool + parameters: + - $ref: "#/components/parameters/_epoch_no" + responses: + "200": + description: Array of historical pool updates + content: + application/json: + schema: + $ref: "#/components/schemas/pool_registrations" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Pool Retirements + description: Return all pool retirements initiated in the requested epoch /pool_relays: #RPC get: tags: @@ -1138,7 +1293,7 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool Relays - description: A list of registered relays for all currently registered/retiring (not retired) pools + description: A list of registered relays for all pools /pool_metadata: #RPC post: tags: @@ -1159,7 +1314,29 @@ paths: "404": $ref: "#/components/responses/NotFound" summary: Pool Metadata - description: Metadata (on & off-chain) for all currently registered/retiring (not retired) pools + description: Metadata (on & off-chain) for all pools + + /script_info: #RPC + post: + tags: + - Script + requestBody: + $ref: "#/components/requestBodies/script_hashes" + responses: + "200": + description: List of datum information for given datum hashes + content: + application/json: + schema: + $ref: "#/components/schemas/script_info" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Datum Information + description: List of datum information for given datum hashes /native_script_list: #RPC get: tags: @@ -1170,7 +1347,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/native_script_list" + $ref: "#/components/schemas/script_list" "400": $ref: "#/components/responses/BadRequest" "401": @@ -1189,7 +1366,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/plutus_script_list" + $ref: "#/components/schemas/script_list" "400": $ref: "#/components/responses/BadRequest" "401": @@ -1219,6 +1396,28 @@ paths: $ref: "#/components/responses/NotFound" summary: Script Redeemers description: List of all redeemers for a given script hash + /script_utxos: #RPC + get: + tags: + - Script + parameters: + - $ref: "#/components/parameters/_script_hash" + - $ref: "#/components/parameters/_extended" + responses: + "200": + description: List of UTXOs for a given script hash + content: + application/json: + schema: + $ref: "#/components/schemas/utxo_infos" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "404": + $ref: "#/components/responses/NotFound" + summary: Script UTXOs + description: List of all UTXOs for a given script hash /datum_info: #RPC post: tags: @@ -1240,10 +1439,51 @@ paths: $ref: "#/components/responses/NotFound" summary: Datum Information description: List of datum information for given datum hashes + /ogmios/?EvaluateTransaction: #ogmios-api + post: + tags: + - Ogmios + x-code-samples: + - lang: "Shell" + source: | + # Assuming ${data} contains EvaluateTransaction payload as documented on Ogmios v6 site. + curl -X POST \ + --header "Content-Type: application/cbor" \ + --data-binary ${data} https://api.koios.rest/api/ogmios/?EvaluateTransaction + responses: + "200": + description: OK + "400": + description: An error occured while submitting transaction. + summary: Evaluate Transaction + description: Evaluate execution units of scripts in a well-formed transaction. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?EvaluateTransaction) for complete spec + /ogmios/?SubmitTransaction: #ogmios-api + post: + tags: + - Ogmios + x-code-samples: + - lang: "Shell" + source: | + # Assuming ${data} contains a CBOR-serialized signed transaction (base16-encoded) as documented on Ogmios v6 site. + curl -X POST \ + --header "Content-Type: application/cbor" \ + --data-binary ${data} https://api.koios.rest/api/ogmios/?SubmitTransaction + responses: + "200": + description: OK + "400": + description: An error occured while querying transaction. + summary: Submit Transaction + description: Submit a signed and serialized transaction to the network. Please refer to Ogmios documentation [here](https://ogmios.dev/api/#operation-publish-/?SubmitTransaction) for complete spec + components: #!params!# #!requestBodies!# - securitySchemes: {} + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT #!schemas!# headers: {} responses: @@ -1252,7 +1492,7 @@ components: NotFound: description: The server does not recognise the combination of endpoint and parameters provided Unauthorized: - description: The selected server has restricted the endpoint to be only usable via authentication. The authentication supplied was not authorized to access the endpoint + description: Access token is missing or invalid PartialContent: description: The result was truncated BadRequest: @@ -1270,12 +1510,12 @@ tags: - name: Transactions description: Query blockchain transaction details x-tag-expanded: false + - name: Stake Account + description: Query details about specific stake account addresses + x-tag-expanded: false - name: Address description: Query information about specific address(es) x-tag-expanded: false - - name: Account - description: Query details about specific stake account addresses - x-tag-expanded: false - name: Asset description: Query Asset related informations x-tag-expanded: false @@ -1285,4 +1525,5 @@ tags: - name: Script description: Query information about specific scripts (Smart Contracts) x-tag-expanded: false -security: [] +security: + - bearerAuth: [] diff --git a/specs/templates/example-map.json b/specs/templates/example-map.json index 07393754..1d63245c 100644 --- a/specs/templates/example-map.json +++ b/specs/templates/example-map.json @@ -8,7 +8,7 @@ }, "_epoch_no": { "m": "320", - "g": "1950", + "g": "6219", "pv": "12", "pp": "31" }, @@ -80,14 +80,14 @@ }, "_script_hash": { "m": "d8480dc869b94b80e81ec91b0abe307279311fe0e7001a9488f61ff8", - "g": "160301a01ee86d8e46cbe3aef1e3bf69bfa28c65d5be2dde56a37af8", + "g": "1392eec7d575292ae1523da65ff1b4b021886e917c8c43de54aa7cbd", "pv": "f758cf422ca0cbed7d9d6fad1eb5a3c70537d62e661ad450dd2a3810", "pp": "590555d7b5760e98ae2bdd29b356247776251dfab0a207bfce98a485" } }, "requestBodies": { "epoch_no": { - "m": "350", + "m": "409", "g": "1500", "pv": "11", "pp": "30" @@ -99,7 +99,7 @@ "pp": "['c6e65ba7878b2f8ea0ad39287d3e2fd256dc5c4160fc19bdf4c4d87e','7447454e53']" }, "asset2": { - "m": "['1d7f33bd23d85e1a25d87d86fac4f199c3197a2f7afeb662a0f34e1e','776f726c646d6f62696c65746f6b656e']", + "m": "['f0ff48bbb7bbe9d59a40f1ce90e9e9d0ff5002ec48f232b49ca0fb9a','6b6f696f732e72657374']", "g": "['313534a537bc476c86ff7c57ec511bd7f24a9d15654091b24e9c606e','41484c636f696e']", "pv": "['189e2c53985411addb8df0f3e09f70e343da69f06746c408aba672a8','15fc257714a51769e192761d674db2ee2e80137428e522f9b914debb5f785301']", "pp": "['777e6b4903dab74963ae581d39875c5dac16c09bb1f511c0af1ddda8','6141414441']" @@ -182,6 +182,18 @@ "pv": "f1592b29b79ae85d753913dd25644c60925a4a0683979faa33832fead4b4bd9c", "pp": "d10133964da9e443b303917fd0b7644ae3d01c133deff85b4f59416c2d00f530" }, + "utxo_ref1": { + "m": "f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e#0", + "g": "f82e568d42604fd71424d193c86ec00c97aead2b8f018e81c3139d9e3770c735#0", + "pv": "206f6da5b0b0de45605a95f5ce7e172be9674550f7dde3838c45cbf24bab8b00#0", + "pp": "d10133964da9e443b303917fd0b7644ae3d01c133deff85b4f59416c2d00f530#0" + }, + "utxo_ref2": { + "m": "0b8ba3bed976fa4913f19adc9f6dd9063138db5b4dd29cecde369456b5155e94#0", + "g": "88ae22495123c7ee37a0bbe865243757185a302ed5359d1eae9347030628290a#0", + "pv": "f1592b29b79ae85d753913dd25644c60925a4a0683979faa33832fead4b4bd9c#0", + "pp": "145688d3619e7524510ea64c0ec6363b77a9b8da179ef9bb0273a0940d57d576#0" + }, "pool_ids_pool_bech32_ids1": { "m": "pool100wj94uzf54vup2hdzk0afng4dhjaqggt7j434mtgm8v2gfvfgp", "g": "pool19st4a2vvu78tjtyywjte2eml3kx6ynersgd2nyw0y4jvyhlfu0u", @@ -200,6 +212,18 @@ "pv": "pool1p835jxsj8py5n34lrgk6fvpgpxxvh585qm8dzvp7ups37vdet5a", "pp": "pool1ws42l6rawqjv58crs5l32v0eem3qnngpnjfd7epwd4lmjccc5cg" }, + "script_hashes1": { + "m": "bd2119ee2bfb8c8d7c427e8af3c35d537534281e09e23013bca5b138", + "g": "a08a267e92456ba48e157dd7e77bdd35aba0fc50fe625a10a6a7fc5e", + "pv": "c6d963e8892916ab8753d3c342037cd122123c4dd783a07af21f8dac", + "pp": "a8e9f8f34fd631b1d5b9f41a90f4abc0d3935cea7baba0bb34c96f59" + }, + "script_hashes2": { + "m": "c0c671fba483641a71bb92d3a8b7c52c90bf1c01e2b83116ad7d4536", + "g": "1f3a4aa08cfa0e47fff200578f0d4847b6890b7093a765773feb35de", + "pv": "c0c671fba483641a71bb92d3a8b7c52c90bf1c01e2b83116ad7d4536", + "pp": "b4fd6dfe4a643aeec5d75dbb1f27198fc2aabf30bf92ed5470253792" + }, "datum_hashes1": { "m": "818ee3db3bbbd04f9f2ce21778cac3ac605802a4fcb00c8b3a58ee2dafc17d46", "g": "964af1ff2a66ce472d34ac39b47f356b6d971d62c794a89ec12825d5de30f3aa", diff --git a/tests/conftest.py b/tests/conftest.py index be41cf8f..092a801e 100755 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -5,10 +5,10 @@ def pytest_addoption(parser): parser.addoption( - "--local-url", action="store", default="http://127.0.0.1:8053/api/v0" + "--local-url", action="store", default="http://127.0.0.1:8053/api/v1" ) parser.addoption( - "--compare-url", action="store", default="https://guild.koios.rest/api/v0" + "--compare-url", action="store", default="https://guild.koios.rest/api/v1" ) parser.addoption( "--api-schema-file", diff --git a/tests/setup-tests.sh b/tests/setup-tests.sh index 1262ac58..6bd86044 100755 --- a/tests/setup-tests.sh +++ b/tests/setup-tests.sh @@ -13,13 +13,13 @@ cat <<-EOF To run the endpoint validation tests, use the below: schemathesis --pre-run not_empty_response run --request-timeout 5000 https://guild.koios.rest/koiosapi.yaml --hypothesis-phases=explicit \\ - --hypothesis-verbosity quiet -b http://127.0.0.1:8053/api/v0 -c all --validate-schema=true -H "Content-Type: application/json" + --hypothesis-verbosity quiet -b http://127.0.0.1:8053/api/v1 -c all --validate-schema=true -H "Content-Type: application/json" - where http://127.0.0.1:8053/api/v0 is the URL of instance you want to test, and guild.koios.rest is the target enviornment for testing. + where http://127.0.0.1:8053/api/v1 is the URL of instance you want to test, and guild.koios.rest is the target enviornment for testing. To run the data validations tests, use the below: - pytest --local-url http://127.0.0.1:8053/api/v0 --compare-url https://guild.koios.rest/api/v0 --api-schema-file ../specs/results/koiosapi-guild.yaml -x -v + pytest --local-url http://127.0.0.1:8053/api/v1 --compare-url https://guild.koios.rest/api/v1 --api-schema-file ../specs/results/koiosapi-guild.yaml -x -v Arguments: local-run : URL of instance you want to test"