Socket
Socket
Sign inDemoInstall

@adabox/koios-ts-client

Package Overview
Dependencies
6
Maintainers
1
Versions
8
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@adabox/koios-ts-client

Cardano REST Client library which allows interacting with The Cardano Blockchain.


Version published
Maintainers
1
Weekly downloads
1

Weekly downloads

Readme

Source

Preview Preprod Mainnet CodeQL Coverage License Version

Koios

Koios TypeScript Client

Koios Typescript Client is a REST Client library which allows interacting with Koios Server Instances. Koios TypeScript Client Library is based on Koios Elastic Query Layer for Cardano Node by Cardano Community Guild Operators.
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.
Resource and maintenance requirements for Cardano blockchain components (e.g. cardano-node, cardano-db-sync) are ever-growing. Along with that, every builder needs to identify how to query complex information from the chain.

Table of contents

Prerequisites

This project requires NodeJS (version 16 or later) and NPM. Node and NPM are really easy to install. To make sure you have them available on your machine, try running the following command.

$ npm -v ; node -v
9.6.3
v16.5.0

Features

  • Synchronous REST messaging
  • Pagination (Limit and Offset)
  • Horizontal Filtering
  • Vertical Filtering
  • Sorting Supported
  • Rate Control (soon)
  • Inner Retry Mechanism upon Timeouts
Supported REST Services
ServiceEndpointDescription
NetworkChain TipGet the tip info about the latest block seen by chain
Genesis InfoGet the Genesis parameters used to start specific era on chain
Get historical tokenomic statsGet the circulating utxo, treasury, rewards, supply and reserves in lovelace for specified epoch, all epochs if empty
Param Update ProposalsGet all parameter update proposals submitted to the chain starting Shelley era
EpochEpoch InformationGet the epoch information, all epochs if no epoch specified
Epoch's Protocol ParametersGet the protocol parameters for specific epoch, returns information about all epochs if no epoch specified
Epoch's Block ProtocolsGet the information about block protocol distribution in epoch
BlockBlock ListGet summarised details about all blocks (paginated - latest first)
Block InformationGet detailed information about a specific block
Block TransactionsGet a list of all transactions included in a provided block
TransactionsTransaction InformationGet detailed information about transaction(s)
Transaction UTxOsGet UTxO set (inputs/outputs) of transactions.
Transaction MetadataGet metadata information (if any) for given transaction(s)
Transaction Metadata LabelsGet a list of all transaction metalabels
Submit TransactionSubmit an already serialized transaction to the network.
Transaction Status (Block Confirmations)Get the number of block confirmations for a given transaction hash list
AddressAddress InformationGet address info - balance, associated stake address (if any) and UTxO set
Address TransactionsGet the transaction hash list of input address array, optionally filtering after specified block height (inclusive)
Address AssetsGet the list of all the assets (policy, name and quantity) for a given address
Transactions from payment credentialsGet the transaction hash list of input payment credential array, optionally filtering after specified block height (inclusive)
Stake AccountAccount ListGet a list of all accounts
Account InformationGet the account info of any (payment or staking) address
Account UTxOsGet a list of all UTxOs for a given stake address (account)
Account Information (Cached)Get the cached account information for given stake addresses (accounts)
Account RewardsGet the full rewards history (including MIR) for a stake address, or certain epoch if specified
Account UpdatesGet the account updates (registration, deregistration, delegation and withdrawals)
Account AddressesGet all addresses associated with an account
Account AssetsGet the native asset balance of an account
Account HistoryGet the staking history of an account
AssetAsset ListGet the list of all native assets (paginated)
Asset AddressesGet the list of all addresses holding a given asset
NFT AddressGet the address where specified NFT currently reside on
Asset InformationGet the information of an asset including first minting & token registry metadata
Asset Information (Bulk)Get the information of a list of assets including first minting & token registry metadata
Asset HistoryGet the mint/burn history of an asset
Policy Asset Address ListGet the list of addresses with quantity for each asset on the given policy.
Policy Asset InformationGet the information for all assets under the same policy
Policy Asset ListGet the list of asset under the given policy (including balances)
Asset SummaryGet the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance)
Asset TransactionsGet the list of all asset transaction hashes (newest first)
PoolPool ListA list of all currently registered/retiring (not retired) pools
Pool InformationCurrent pool statuses and details for a specified list of pool ids
Pool Stake SnapshotReturns Mark, Set and Go stake snapshots for the selected pool, useful for leaderlog calculation
Pool Delegators ListReturn information about live delegators for a given pool.
Pool Delegators HistoryReturn information about active delegators (incl. history) for a given pool and epoch number - current epoch if not provided.
Pool BlocksReturn information about blocks minted by a given pool in current epoch (or _epoch_no if provided)
Pool Stake, Block and Reward HistoryReturn information about pool stake, block and reward history in a given epoch _epoch_no (or all epochs that pool existed for, in descending order if no _epoch_no was provided)
Pool Updates (History)Return all pool updates for all pools or only updates for specific pool if specified
Pool RelaysA list of registered relays for all currently registered/retiring (not retired) pools
Pool MetadataMetadata (on & off-chain) for all currently registered/retiring (not retired) pools
ScriptNative Script ListList of all existing native script hashes along with their creation transaction hashes
Plutus Script ListList of all existing Plutus script hashes along with their creation transaction hashes
Script RedeemersList of all redeemers for a given script hash
Datum InformationList of datum information for given datum hashes

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Installation

BEFORE YOU INSTALL: please read the prerequisites

Start with cloning this repo on your local machine:

$ git clone https://github.com/adabox-aio/koios-typescript-client.git
$ cd koios-typescript-client

To install and set up the library, run:

$ npm i @adabox/koios-ts-client

Usage

Import

import {BackendFactory} from "@adabox/koios-ts-client"

Get Koios Backend Service

  • Mainnet
const koiosBackendService = BackendFactory.getKoiosMainnetService()
  • Preview
const koiosBackendService = BackendFactory.getKoiosPreviewService()
  • Preprod
const koiosBackendService = BackendFactory.getKoiosPreprodService()

Get Koios Backend Services

const koiosNetworkService = koiosBackendService.getNetworkService()
const koiosEpochService = koiosBackendService.getEpochService()
const koiosBlockService = koiosBackendService.getBlockService()
const koiosTransactionsService = koiosBackendService.getTransactionsService()
const koiosAddressService = koiosBackendService.getAddressService()
const koiosAssetService = koiosBackendService.getAssetService()
const koiosPoolService = koiosBackendService.getPoolService()
const koiosScriptService = koiosBackendService.getScriptService()
const koiosAccountService = koiosBackendService.getAccountService()

Advanced Query Example (Preview)

Querying a Descending Order of All Address Transactions since Block No. #42248 to Block No. #69447 (inclusive), Limited to Maximum of 10 Results.

const addresses = [
    'addr_test1qrvaadv0h7atv366u6966u4rft2svjlf5uajy8lkpsgdrc24rnskuetxz2u3m5ac22s3njvftxcl2fc8k8kjr088ge0qz98xmv',
]
const options = Options.builder()
    .option(Limit.of(10))
    .option(Offset.of(0))
    .option(Order.by("block_height", SortType.DESC))
    .option(Filter.of("block_height", FilterType.GTE, "42248"))
    .option(Filter.of("block_height", FilterType.LTE, "69447")).build();

const result = await koiosAddressService.getAddressTransactions(addresses, undefined, options)
console.log(result)

Error Handling

Koios TypeScript Client throws 2 types of errors,KoiosHttpError and KoiosTimeoutError. Each of these errors is extended from the built-in Error class, allowing you to properly catch it and handle it in your code.

import {KoiosHttpError, KoiosTimeoutError} from "@adabox/koios-ts-client";

try {
  const result = await koiosTransactionsService.getTransactionInformation(["abc"])
} catch (error) {
  if (error instanceof KoiosHttpError || error instanceof KoiosTimeoutError) {
    console.log(error) // Koios Error
  } else {
      throw error // rethrow other errors
  }
}

Supported Environment Variables

VariableTypeDescriptionDefault
KOIOS_MAX_RETRIESintegerSets the max retry count upon request timeout5
KOIOS_READ_TIMEOUT_SECintegerSets the default read timeout for new connections (seconds)300

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

  1. Fork it!
  2. Create your feature branch: git checkout -b my-new-feature
  3. Add your changes: git add .
  4. Commit your changes: git commit -am 'Add some feature'
  5. Push to the branch: git push origin my-new-feature
  6. Submit a pull request :sunglasses:

Discord Discord | Twitter Twitter

Keywords

FAQs

Last updated on 03 Sep 2023

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc