koios

package module
v3.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 30, 2024 License: Apache-2.0 Imports: 21 Imported by: 3

README

Koios Go

Koios API Client Library for Go

Koios API is Elastic Cardano Query Layer!

A consistent query layer for developers to build upon Cardano, with multiple, redundant endpoints that allow for easy scalability.

Koios API Client Library for Go

PkgGoDev

go get github.com/cardano-community/koios-go-client/v3
...
import (
  "github.com/cardano-community/koios-go-client/v3" // imports as package "koios"
)
...

There is CLI Application to interact with Koios API from Command-line see:

koios cli repository for souce and installing instruction of koios cli

Build Status

linux macos windows

Koios API Endpoint Tests

mainnet guild preview preprod

Development Status

GitHub last commit codecov codeql misspell Go Report Card



Usage

See Godoc PkgGoDev

Additionally you can find all usecases by looking source of koio-cli Command-line application koios-cli which utilizes entire API of this library.

NOTE

Library normalizes some of the API responses and constructs Typed response for each end point. If you wish to work with *http.Response directly you can do so by using api client GET,POST, HEAD methods.

Basic usage

package main

import (
	"context"
	"fmt"
	"log"

	koios "github.com/cardano-community/koios-go-client/v3"
)

func main() {
  // Call to koios.New without options is same as calling it with default opts.
  // See godoc for available configuration options.
  // api, err := koios.New(
  // 	koios.Host(koios.MainnetHost),
  // 	koios.APIVersion(koios.DefaultAPIVersion),
  // 	koios.Port(koios.DefaultPort),
  // 	koios.Schema(koios.DefaultSchema),
  // 	koios.HttpClient(koios.DefaultHttpClient),
  // ).
  api, err := koios.New()
  if err != nil {
    log.Fatal(err)
  }

  res, err := api.GetTip(context.Background(), nil)
  if err != nil {
	  log.Fatal(err)
  }
  fmt.Println("status: ", res.Status)
  fmt.Println("statu_code: ", res.StatusCode)

  fmt.Println("abs_slot: ", res.Data.AbsSlot)
  fmt.Println("block_no: ", res.Data.BlockNo)
  fmt.Println("block_time: ", res.Data.BlockTime)
  fmt.Println("epoch: ", res.Data.Epoch)
  fmt.Println("epoch_slot: ", res.Data.EpochSlot)
  fmt.Println("hash: ", res.Data.Hash)
}

Concurrency using goroutines

This library is thread-safe so you can freerly use same api client instance passing it to your goroutines.

Following example uses goroutines to query chain tip from different endpoints.

func main() {
  api, _ := koios.New(
    // limit client request 1 per second even though
    // this example will send requests in goroutines.
    koios.RateLimit(1),
  )
  ctx := context.Background()
  var wg sync.WaitGroup
  servers := []string{
    koios.GuildHost,
    koios.PreviewHost,
    koios.TestnetHost,
    koios.MainnetHost,
    koios.PreProdHost,
    koios.MainnetHost,
    koios.MainnetHostEU,
  }

  // Thanks to rate limit option requests will be made
  // once in a second.
  for _, host := range servers {
    wg.Add(1)
    go func(ctx context.Context, host string) {
      defer wg.Done()
      // switching host by creating light clone of client
      // with new options
      client, err := api.WithOptions(koios.Host(host))
      res, _ := client.GET(ctx, "/tip", nil)
      defer res.Body.Close()
      body, _ := io.ReadAll(res.Body)
      fmt.Println("Host: ", host)
      fmt.Println("Response: ", string(body))
    }(ctx, host)
  }

  wg.Wait()
}

Math on ada, assets and tokens).

Library uses decimal.Decimal data type to represent lovelace and coin values.
Which provides arbitrary-precision fixed-point decimal numbers in go.

For decimal package API see

Contributing

We would love for you to contribute to Koios API Client Library for Go and help make it even better than it is today! As a contributor, here are the guidelines we would like you to follow:

Code of Conduct

Help us keep Koios API Client Library for Go open and inclusive. Please read and follow our Code of Conduct


Got a Question or Problem?

Do not open issues for general support questions as we want to keep GitHub issues for bug reports and feature requests. You've got much better chances of getting your question answered on Koios Telegram Group


Issues and Bugs

If you find a bug in the source code, you can help us by submitting an issue to our GitHub Repository. Even better, you can submit a Pull Request with a fix.


Feature Requests

You can request a new feature by submitting an issue to our GitHub Repository. If you would like to implement a new feature, please submit an issue with a proposal for your work first, to be sure that we can use it. Please consider what kind of change it is:

  • For a Major Feature, first open an issue and outline your proposal so that it can be discussed. This will also allow us to better coordinate our efforts, prevent duplication of work, and help you to craft the change so that it is successfully accepted into the project.
  • Small Features can be crafted and directly submitted as a Pull Request.

Submission Guidelines

Submitting an Issue

Before you submit an issue, please search the issue tracker, maybe an issue for your problem already exists and the discussion might inform you of workarounds readily available.

You can file new issues by filling out our new issue form.


Submitting a Pull Request (PR)

Before you submit your Pull Request (PR) consider the following guidelines:

  1. Search GitHub for an open or closed PR that relates to your submission. You don't want to duplicate effort.

  2. Fork the cardano-community/koios-go-client repo.

  3. Setup you local repository

    git@github.com:<your-github-username>/koios-go-client.git
    cd koios-go-client
    git remote add upstream git@github.com:cardano-community/koios-go-client.git
    
  4. Make your changes in a new git branch and ensure that you always start from up to date main branch. Repeat this step every time you are about to start woking on new PR.

    e.g. Start new change work to update readme:

    # if you are not in main branch e.g. still on previous work branch
    git checkout main
    git pull --ff upstream main
    git checkout -b update-readme main
    
  5. Create your patch, including appropriate test cases.

  6. Follow our Coding Rules.

  7. If changes are in source code except documentations then run the full test suite, as described in the developer documentation, and ensure that all tests pass.

  8. Commit your changes using a descriptive commit message that follows our commit message conventions. Adherence to these conventions is necessary because release notes are automatically generated from these messages.

    git add -A
    git commit --signoff
    # or in short
    git commit -sm"docs(markdown): update readme examples"
    
  9. Push your branch to GitHub:

    git push -u origin update-readme
    
  10. In GitHub, send a pull request to main branch.

  • If we suggest changes then:
    • Make the required updates.

    • Re-run the test suites to ensure tests are still passing.

    • Rebase your branch and force push to your GitHub repository (this will update your Pull Request):

      git fetch --all
      git rebase upstream main
      git push -uf origin update-readme
      

That's it! Thank you for your contribution!


After your pull request is merged

After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:

  • Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:

    git push origin --delete update-readme
    
  • Check out the main branch:

    git checkout main -f
    
  • Delete the local branch:

    git branch -D update-readme
    
  • Update your master with the latest upstream version:

    git pull --ff upstream main
    

Coding Rules

To ensure consistency throughout the source code, keep these rules in mind as you are working:

  • All features or bug fixes must be tested by one or more specs (unit-tests).
  • All public API methods must be documented.

Commit Message Guidelines

Conventional Commits

We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history. Commit messages should be well formatted, and to make that "standardized", we are using Conventional Commits. Our release workflow uses these rules to generate changelogs.


Commit Message Format

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

When maintainers are merging PR merge commit should be edited:

<type>(<scope>): <subject> (#pr)
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The header is mandatory and the scope of the header is optional.

Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.

The footer should contain a closing reference to an issue if any.

Samples:

docs(markdown): update readme examples

fix(endpoint): update Tip endpoint to latest specs.

description of your change.
refactor(client): change Client GET function signature

change order of client GET method arguments.

BREAKING CHANGE: Clien.Get signature has changed

Revert

If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.


Type

Must be one of the following:

  • build: Changes that affect the build system or external dependencies (example scopes: goreleaser, taskfile)
  • chore: Other changes that don't modify src or test files.
  • ci: Changes to our CI configuration files and scripts.
  • dep: Changes related to dependecies e.g. go.mod
  • docs: Documentation only changes (example scopes: markdown, godoc)
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • revert: Reverts a previous commit
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests

Scope

The following is the list of supported scopes:

scope description
client API client related changes
endpoint Changes related to api endpoints
godoc Go documentation
markdown Markdown files

Subject

The subject contains a succinct description of the change:

  • use the imperative, present tense: "change" not "changed" nor "changes"
  • don't capitalize the first letter
  • no dot (.) at the end
Body

Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.

The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit Closes.

Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.

A detailed explanation can be found in this [document][commit-message-format].


Development Documentation

Setup your machine

Prerequisites:

Setup local env

task setup

Lint your code

task lint

Test your change

task test

View code coverage report from in browser (results from task test)

task cover

Credits

GitHub contributors

Original author.
koios-go-client was moved under Cardano Community from howijd/koios-rest-go-client

Koios Go banner design.
Koios Go banner was designed by Egon Elbre egonelbre.com

Documentation

Overview

Package koios provides api client library to interact with Koios API endpoints and Cardano Blockchain. Sub package ./cmd/koios-rest provides cli application. 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.

Index

Constants

View Source
const (
	MainnetHost              = "api.koios.rest"
	MainnetHostEU            = "eu-api.koios.rest"
	GuildHost                = "guild.koios.rest"
	PreviewHost              = "preview.koios.rest"
	PreProdHost              = "preprod.koios.rest"
	DefaultAPIVersion        = "v0"
	DefaultPort       uint16 = 443
	DefaultScheme            = "https"
	LibraryVersion           = "v0"
	DefaultRateLimit  int    = 10 // https://api.koios.rest/#overview--limits
	DefaultOrigin            = "https://github.com/cardano-community/koios-go-client"
	PageSize          uint   = 1000
)

MainnetHost : is primay and default api host. GuildnetHost : is Guild network host. PreviewHost : is Preview network host. PreProdHost : is Pre Production network host. DefaultAPIVersion : is openapi spec version e.g. /v0. DefaultPort : default port used by api client. DefaultSchema : default schema used by api client. LibraryVersion : koios go library version. DefaultRateLimit : is default rate limit used by api client. DefaultOrigin : is default origin header used by api client.

Variables

View Source
var (
	ErrURLValuesLenght          = errors.New("if presenent then only single url.Values should be provided")
	ErrHTTPClientTimeoutSetting = errors.New("http.Client.Timeout should never be 0 in production")
	ErrHTTPClientChange         = errors.New("http.Client can only be set as option to koios.New")
	ErrOriginSet                = errors.New("origin can only be set as option to koios.New")
	ErrRateLimitRange           = errors.New("rate limit must be between 1-255 requests per sec")
	ErrResponseIsNotJSON        = errors.New("got non json response")
	ErrNoTxHash                 = errors.New("missing transaxtion hash(es)")
	ErrNoDatumHash              = errors.New("missing datum hash(es)")
	ErrNoAddress                = errors.New("missing address")
	ErrNoPoolID                 = errors.New("missing pool id")
	ErrResponse                 = errors.New("response error")
	ErrSchema                   = errors.New("scheme must be http or https")
	ErrReqOptsAlreadyUsed       = errors.New("request options can only be used once")
	ErrUnexpectedResponseField  = errors.New("unexpected response field")
	ErrUTxOInputAlreadyUsed     = errors.New("UTxO already used")
	ErrNoData                   = errors.New("no data")

	// ZeroLovelace is alias decimal.Zero.
	ZeroLovelace = decimal.Zero.Copy() //nolint: gochecknoglobals
	// ZeroCoin is alias decimal.Zero.
	ZeroCoin = decimal.Zero.Copy() //nolint: gochecknoglobals
)

Predefined errors used by the library.

Functions

func ReadAndUnmarshalResponse

func ReadAndUnmarshalResponse(rsp *http.Response, res *Response, dest any) error

ReadAndUnmarshalResponse is helper to unmarchal json responses.

func ReadResponseBody

func ReadResponseBody(rsp *http.Response) (body []byte, err error)

ReadResponseBody is reading http.Response aand closing it after read.

Types

type AccountAddresses

type AccountAddresses struct {
	StakeAddress Address   `json:"stake_address"`
	Addresses    []Address `json:"addresses"`
}

type AccountAddressesResponse

type AccountAddressesResponse struct {
	Response
	Data *AccountAddresses `json:"data"`
}

AccountAddressesResponse represents response from `/account_addresses` endpoint.

type AccountAssets

type AccountAssets struct {
	StakeAddress Address `json:"stake_address"`
	Assets       []Asset `json:"asset_list"`
}

type AccountAssetsResponse

type AccountAssetsResponse struct {
	Response
	Data *AccountAssets `json:"data"`
}

AccountAssetsResponse represents response from `/account_assets` endpoint.

type AccountHistory

type AccountHistory struct {
	StakeAddress Address               `json:"stake_address"`
	History      []AccountHistoryEntry `json:"history"`
}

AccountHistoryEntry history entry list item.

type AccountHistoryEntry

type AccountHistoryEntry struct {
	PoolID      PoolID          `json:"pool_id"`
	EpochNo     EpochNo         `json:"epoch_no"`
	ActiveStake decimal.Decimal `json:"active_stake"`
}

type AccountHistoryResponse

type AccountHistoryResponse struct {
	Response
	Data *AccountHistory `json:"data"`
}

AccountHistoryResponse represents response from `/account_history` endpoint.

type AccountInfo

type AccountInfo struct {
	Status           string          `json:"status"`
	DelegatedPool    *PoolID         `json:"delegated_pool"`
	StakeAddress     Address         `json:"stake_address"`
	TotalBalance     decimal.Decimal `json:"total_balance"`
	UTxO             decimal.Decimal `json:"utxo"`
	Rewards          decimal.Decimal `json:"rewards"`
	Withdrawals      decimal.Decimal `json:"withdrawals"`
	RewardsAvailable decimal.Decimal `json:"rewards_available"`
	Reserves         decimal.Decimal `json:"reserves"`
	Treasury         decimal.Decimal `json:"treasury"`
}

AccountInfo data returned by `/account_info`.

type AccountInfoResponse

type AccountInfoResponse struct {
	Response
	Data *AccountInfo `json:"data"`
}

AccountInfoResponse represents response from `/account_info` endpoint.

type AccountListResponse

type AccountListResponse struct {
	Response
	Data []Address `json:"data"`
}

AccountListResponse represents response from `/account_list` endpoint.

type AccountRewards

type AccountRewards struct {
	PoolID         PoolID          `json:"pool_id"`
	EarnedEpoch    EpochNo         `json:"earned_epoch"`
	SpendableEpoch EpochNo         `json:"spendable_epoch"`
	Amount         decimal.Decimal `json:"amount"`
	Type           string          `json:"type"`
}

type AccountRewardsInfo

type AccountRewardsInfo struct {
	StakeAddress Address          `json:"stake_address"`
	Rewards      []AccountRewards `json:"rewards"`
}

AccountRewardsInfo data returned by `/account_rewards`.

type AccountRewardsResponse

type AccountRewardsResponse struct {
	Response
	Data *AccountRewardsInfo `json:"data"`
}

AccountRewardsResponse represents response from `/account_rewards` endpoint.

type AccountUpdate

type AccountUpdate struct {
	ActionType   string    `json:"action_type"`
	TxHash       TxHash    `json:"tx_hash"`
	EpochNo      EpochNo   `json:"epoch_no"`
	EpochSlot    Slot      `json:"epoch_slot"`
	AbsoluteSlot Slot      `json:"absolute_slot"`
	BlockTime    Timestamp `json:"block_time"`
}

AccountAction data entry for `/account_updates`.

type AccountUpdates

type AccountUpdates struct {
	StakeAddress Address         `json:"stake_address"`
	Updates      []AccountUpdate `json:"updates"`
}

type AccountUpdatesResponse

type AccountUpdatesResponse struct {
	Response
	Data *AccountUpdates `json:"data"`
}

AccountUpdatesResponse represents response from `/account_rewards` endpoint.

type AccountsAddressesResponse

type AccountsAddressesResponse struct {
	Response
	Data []AccountAddresses `json:"data"`
}

type AccountsAssetsResponse

type AccountsAssetsResponse struct {
	Response
	Data []AccountAssets `json:"data"`
}

type AccountsHistoryResponse

type AccountsHistoryResponse struct {
	Response
	Data []AccountHistory `json:"data"`
}

type AccountsInfoResponse

type AccountsInfoResponse struct {
	Response
	Data []AccountInfo `json:"data"`
}

type AccountsRewardsResponse

type AccountsRewardsResponse struct {
	Response
	Data []AccountRewardsInfo `json:"data"`
}

type AccountsUpdatesResponse

type AccountsUpdatesResponse struct {
	Response
	Data []AccountUpdates `json:"data"`
}

type Address

type Address string

Address defines type for _address.

func (Address) Bytes

func (a Address) Bytes() []byte

Bytes returns address bytes.

func (Address) String

func (a Address) String() string

String returns StakeAddress as string.

func (Address) Valid

func (a Address) Valid() (bool, error)

Valid validates address and returns false and error if address is invalid otherwise it returns true, nil.

type AddressAsset

type AddressAsset struct {
	AssetName      AssetName       `json:"asset_name"`
	AssetNameASCII string          `json:"asset_name_ascii"`
	Balance        decimal.Decimal `json:"balance"`
}

type AddressAssets

type AddressAssets struct {
	Address   Address `json:"address"`
	AssetList []Asset `json:"asset_list"`
}

type AddressAssetsResponse

type AddressAssetsResponse struct {
	Response
	Data *AddressAssets `json:"data"`
}

AddressAssetsResponse represents response from `/address_info` endpoint.

type AddressInfo

type AddressInfo struct {
	// Balance ADA Lovelace balance of address
	Balance decimal.Decimal `json:"balance"`

	Address Address `json:"address"`

	// StakeAddress associated with address
	StakeAddress Address `json:"stake_address,omitempty"`

	ScriptAddress bool `json:"script_address"`

	UTxOs []UTxO `json:"utxo_set"`
}

AddressInfo esponse for `/address_info`.

type AddressInfoResponse

type AddressInfoResponse struct {
	Response
	Data *AddressInfo `json:"data"`
}

AddressInfoResponse represents response from `/address_info` endpoint.

type AddressTx

type AddressTx struct {
	TxHash      TxHash    `json:"tx_hash"`
	EpochNo     EpochNo   `json:"epoch_no"`
	BlockTime   Timestamp `json:"block_time"`
	BlockHeight uint64    `json:"block_height"`
}

type AddressTxsResponse

type AddressTxsResponse struct {
	Response
	Data []AddressTx `json:"data"`
}

AddressTxsResponse represents response from `/address_txs` endpoint.

type AddressesAssetsResponse

type AddressesAssetsResponse struct {
	Response
	Data []AddressAssets `json:"data"`
}

type AddressesInfoResponse

type AddressesInfoResponse struct {
	Response
	Data []AddressInfo `json:"data"`
}

type Asset

type Asset struct {
	// Asset Name (hex).
	AssetName AssetName `json:"asset_name,omitempty"`

	Fingerprint AssetFingerprint `json:"fingerprint,omitempty"`

	// Asset Policy ID (hex).
	PolicyID PolicyID `json:"policy_id"`

	// Quantity
	// Input: asset balance on the selected input transaction.
	// Output: sum of assets for output UTxO.
	// Mint: sum of minted assets (negative on burn).
	Quantity decimal.Decimal `json:"quantity,omitempty"`
}

Asset represents Cardano Asset.

type AssetAddressListResponse

type AssetAddressListResponse struct {
	Response
	Data []AssetHolder `json:"data"`
}

AssetAddressListResponse represents response from `/asset_address_list` endpoint.

type AssetFingerprint

type AssetFingerprint string

AssetFingerprint defines type for asset_fingerprint. The CIP14 fingerprint of the asset, This specification defines a user-facing asset fingerprint as a bech32-encoded blake2b-160 digest of the concatenation of the policy id and the asset name.

func (AssetFingerprint) String

func (v AssetFingerprint) String() string

String returns AssetFingerprint as string.

type AssetHistory

type AssetHistory struct {
	Asset
	MintingTXs []AssetMintTX `json:"minting_txs"`
}

AssetHistory holds given asset mint/burn tx's.

type AssetHistoryResponse

type AssetHistoryResponse struct {
	Response
	Data *AssetHistory `json:"data"`
}

AssetHistoryResponse represents response from `/asset_history` endpoint.

type AssetHolder

type AssetHolder struct {
	PaymentAddress Address         `json:"payment_address"`
	Quantity       decimal.Decimal `json:"quantity"`
}

AssetHolder payment addresses holding the given token (including balance).

type AssetInfo

type AssetInfo struct {
	// Asset Name (hex).
	AssetName AssetName `json:"asset_name"`

	// Asset Name (ASCII)
	AssetNameASCII string `json:"asset_name_ascii"`

	// The CIP14 fingerprint of the asset
	Fingerprint AssetFingerprint `json:"fingerprint"`

	// MintingTxMetadata minting Tx JSON payload if it can be decoded as JSON
	// MintingTxMetadata *TxInfoMetadata `json:"minting_tx_metadata"`
	MintingTxMetadata *json.RawMessage `json:"minting_tx_metadata,omitempty"`

	// Asset metadata registered on the Cardano Token Registry
	TokenRegistryMetadata *TokenRegistryMetadata `json:"token_registry_metadata,omitempty"`

	// Asset Policy ID (hex).
	PolicyID PolicyID `json:"policy_id,omitempty"`

	// TotalSupply of Asset
	TotalSupply decimal.Decimal `json:"total_supply"`

	// CreationTime of Asset
	CreationTime Timestamp `json:"creation_time"`

	// MintCnt count of mint transactions
	MintCnt int `json:"mint_cnt"`

	// BurnCnt count of burn transactions
	BurnCnt int `json:"burn_cnt"`

	// MintingTxHash mint tx
	MintingTxHash TxHash `json:"minting_tx_hash"`
}

AssetInfo info about the asset.

type AssetInfoResponse

type AssetInfoResponse struct {
	Data *AssetInfo `json:"data"`
	Response
}

AssetInfoResponse represents response from `/asset_info` endpoint.

type AssetListResponse

type AssetListResponse struct {
	Response
	Data []Asset `json:"data"`
}

AssetListResponse represents response from `/asset_list` endpoint.

type AssetMintTX

type AssetMintTX struct {
	TxHash    TxHash          `json:"tx_hash"`
	Quantity  decimal.Decimal `json:"quantity"`
	BlockTime Timestamp       `json:"block_time"`
	Metadata  TxMetadata      `json:"metadata,omitempty"`
}

AssetMintTX holds specific mint tx hash and amount.

type AssetName

type AssetName string

AssetName defines type for _asset_name.

func (AssetName) String

func (v AssetName) String() string

String returns AssetName as string.

type AssetPolicyInfoResponse

type AssetPolicyInfoResponse struct {
	Response
	Data []AssetInfo `json:"data"`
}

AssetPolicyInfoResponse represents response from `/asset_policy_info` endpoint.

type AssetSummary

type AssetSummary struct {
	Asset

	// Total number of registered wallets holding the given asset
	StakedWallets uint64 `json:"staked_wallets"`

	// Total number of transactions including the given asset
	TotalTransactions uint64 `json:"total_transactions"`

	// Total number of payment addresses (not belonging
	// to registered wallets) holding the given asset
	UnstakedAddresses uint64 `json:"unstaked_addresses"`
}

AssetSummary aggregated asset summary.

type AssetSummaryResponse

type AssetSummaryResponse struct {
	Response
	Data []AssetSummary `json:"data"`
}

AssetSummaryResponse represents response from `/asset_summary` endpoint.

type AssetTxsResponse

type AssetTxsResponse struct {
	Response
	Data []AddressTx `json:"data"`
}

AssetTxsResponse represents response from `/asset_txs` endpoint.

type Block

type Block struct {
	// Hash block hash
	Hash BlockHash `json:"hash"`

	// EpochNo number.
	EpochNo EpochNo `json:"epoch_no"`

	// AbsSlot is overall slot number (slots from genesis block of chain).
	AbsSlot Slot `json:"abs_slot"`

	// EpochSlot slot number within epoch.
	EpochSlot Slot `json:"epoch_slot"`

	// Height is block number on chain where transaction was included.
	Height int `json:"block_height"`

	// Size of block.
	Size int `json:"block_size"`

	// Time of the block.
	Time Timestamp `json:"block_time"`

	// TxCount transactions count in block.
	TxCount int `json:"tx_count"`

	// VrfKey is pool VRF key.
	VrfKey string `json:"vrf_key"`

	// OpCert latest ool operational certificate hash
	OpCert string `json:"op_cert,omitempty"`

	// Pool ID.
	Pool string `json:"pool"`

	// OpCertCounter is pool latest operational certificate counter value.
	OpCertCounter int `json:"op_cert_counter"`

	// ParentHash parent block hash
	ParentHash BlockHash `json:"parent_hash,omitempty"`

	// ChildHash child block hash
	ChildHash BlockHash `json:"child_hash,omitempty"`

	// ProtoMajor is protocol major version
	ProtoMajor int `json:"proto_major,omitempty"`
	// ProtoMinor is protocol minor version
	ProtoMinor int `json:"proto_minor,omitempty"`

	// TotalOutput output of the block (in lovelace)
	TotalOutput decimal.Decimal `json:"total_output,omitempty"`

	// TotalOutput Total fees of the block (in lovelace)
	TotalFees decimal.Decimal `json:"total_fees,omitempty"`

	// Confirmations is number of confirmations for the block
	Confirmations int `json:"num_confirmations"`
}

Block defines model for block.

func (*Block) UnmarshalJSON

func (block *Block) UnmarshalJSON(b []byte) error

handle api json tags Block.epoch and Block.epoch_no. SEE: https://github.com/cardano-community/koios-artifacts/issues/102

type BlockHash

type BlockHash string

BlockHash defines type for _block_hash.

func (BlockHash) String

func (v BlockHash) String() string

String returns BlockHash as string.

type BlockInfoResponse

type BlockInfoResponse struct {
	Response
	Data Block `json:"data"`
}

BlockInfoResponse represents response from `/block_info` endpoint.

type BlockNo

type BlockNo int

type BlockProtocol

type BlockProtocol struct {
	// The protocol major version
	ProtoMajor int `json:"proto_major"`

	// The protocol minor version
	ProtoMinor int `json:"proto_minor"`

	Blocks int `json:"blocks"`
}

type BlockTxs

type BlockTxs struct {
	BlockHash BlockHash `json:"block_hash"`
	TxHashes  []TxHash  `json:"tx_hashes"`
}

type BlockTxsResponse

type BlockTxsResponse struct {
	Response
	Data BlockTxs `json:"data"`
}

type BlocksInfoResponse

type BlocksInfoResponse struct {
	Response
	Data []Block `json:"data"`
}

BlockInfoResponse represents response from `/block_info` endpoint.

type BlocksResponse

type BlocksResponse struct {
	Response
	Data []Block `json:"data"`
}

BlocksResponse represents response from `/blocks` endpoint.

type BlocksTxsResponse

type BlocksTxsResponse struct {
	Response
	Data []BlockTxs `json:"data"`
}

type Certificate

type Certificate struct {
	// Index of the certificate
	Index int `json:"index"`

	// Info is A JSON object containing information from the certificate.
	Info map[string]json.RawMessage `json:"info"`

	// Type of certificate could be:
	// delegation, stake_registration, stake_deregistraion, pool_update,
	// pool_retire, param_proposal, reserve_MIR, treasury_MIR).
	Type string `json:"type"`
}

Certificate information.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is api client instance.

func New

func New(opts ...Option) (*Client, error)

New creates thread-safe API client you can freerly pass this client to multiple go routines.

Call to New without options is same as call with default options. e.g. api, err := koios.New(

koios.Host(koios.MainnetHost),
koios.APIVersion(koios.DefaultAPIVersion),
koios.Port(koios.DefaultPort),
koios.Schema(koios.DefaultSchema),
koios.HttpClient(koios.DefaultHttpClient),

).

func (*Client) BaseURL

func (c *Client) BaseURL() string

BaseURL returns currently used base url e.g. https://api.koios.rest/api/v0

func (*Client) GET

func (c *Client) GET(
	ctx context.Context,
	path string,
	opts *RequestOptions,
) (*http.Response, error)

GET sends api http GET request to provided relative path with query params and returns an HTTP response. When using GET method you are expected to handle the response according to net/http.Do documentation. e.g. Caller should close resp.Body when done reading from it.

func (*Client) GetAccountAddresses

func (c *Client) GetAccountAddresses(
	ctx context.Context,
	acc Address,
	epoch *EpochNo,
	opts *RequestOptions,
) (res *AccountAddressesResponse, err error)

GetAccountAddresses retruns all addresses associated with an account.

func (*Client) GetAccountAssets

func (c *Client) GetAccountAssets(
	ctx context.Context,
	acc Address,
	opts *RequestOptions,
) (res *AccountAssetsResponse, err error)

GetAccountAssets retruns all the native asset balance of an account.

func (*Client) GetAccountHistory

func (c *Client) GetAccountHistory(
	ctx context.Context,
	acc Address,
	epoch *EpochNo,
	opts *RequestOptions,
) (res *AccountHistoryResponse, err error)

GetAccountHistory retruns the staking history of an account.

func (*Client) GetAccountInfo

func (c *Client) GetAccountInfo(
	ctx context.Context,
	acc Address,
	cached bool,
	opts *RequestOptions,
) (res *AccountInfoResponse, err error)

GetAccountInfo returns the account info of any (payment or staking) address.

func (*Client) GetAccountRewards

func (c *Client) GetAccountRewards(
	ctx context.Context,
	acc Address,
	epoch *EpochNo,
	opts *RequestOptions,
) (res *AccountRewardsResponse, err error)

GetAccountRewards retruns the full rewards history (including MIR) for a stake address, or certain epoch if specified.

func (*Client) GetAccountUpdates

func (c *Client) GetAccountUpdates(
	ctx context.Context,
	acc Address,
	epoch *EpochNo,
	opts *RequestOptions,
) (res *AccountUpdatesResponse, err error)

func (*Client) GetAccounts

func (c *Client) GetAccounts(
	ctx context.Context,
	opts *RequestOptions,
) (res *AccountListResponse, err error)

GetAccountList returns a list of all accounts.

func (*Client) GetAccountsAddresses

func (c *Client) GetAccountsAddresses(
	ctx context.Context,
	accs []Address,
	opts *RequestOptions,
) (res *AccountsAddressesResponse, err error)

func (*Client) GetAccountsAssets

func (c *Client) GetAccountsAssets(
	ctx context.Context,
	accs []Address,
	opts *RequestOptions,
) (res *AccountsAssetsResponse, err error)

func (*Client) GetAccountsHistory

func (c *Client) GetAccountsHistory(
	ctx context.Context,
	accs []Address,
	opts *RequestOptions,
) (res *AccountsHistoryResponse, err error)

func (*Client) GetAccountsInfo

func (c *Client) GetAccountsInfo(
	ctx context.Context,
	accs []Address,
	cached bool,
	opts *RequestOptions,
) (res *AccountsInfoResponse, err error)

func (*Client) GetAccountsRewards

func (c *Client) GetAccountsRewards(
	ctx context.Context,
	accs []Address,
	epoch *EpochNo,
	opts *RequestOptions,
) (res *AccountsRewardsResponse, err error)

func (*Client) GetAccountsUpdates

func (c *Client) GetAccountsUpdates(
	ctx context.Context,
	accs []Address,
	opts *RequestOptions,
) (res *AccountsUpdatesResponse, err error)

func (*Client) GetAddressAssets

func (c *Client) GetAddressAssets(
	ctx context.Context,
	addr Address,
	opts *RequestOptions,
) (res *AddressAssetsResponse, err error)

GetAddressAssets returns the list of all the assets (policy, name and quantity) for a given address.

func (*Client) GetAddressInfo

func (c *Client) GetAddressInfo(
	ctx context.Context,
	addr Address,
	opts *RequestOptions,
) (res *AddressInfoResponse, err error)

GetAddressInfo returns address info - balance, associated stake address (if any) and UTxO set.

func (*Client) GetAddressTxs

func (c *Client) GetAddressTxs(
	ctx context.Context,
	addrs []Address,
	h uint64,
	opts *RequestOptions,
) (*AddressTxsResponse, error)

func (*Client) GetAddressesAssets

func (c *Client) GetAddressesAssets(
	ctx context.Context,
	addrs []Address,
	opts *RequestOptions,
) (*AddressesAssetsResponse, error)

func (*Client) GetAddressesInfo

func (c *Client) GetAddressesInfo(
	ctx context.Context,
	addr []Address,
	opts *RequestOptions,
) (res *AddressesInfoResponse, err error)

func (*Client) GetAssetAddresses

func (c *Client) GetAssetAddresses(
	ctx context.Context,
	policy PolicyID,
	assetName AssetName,
	opts *RequestOptions,
) (res *AssetAddressListResponse, err error)

GetAssetAddressList returns the list of all addresses holding a given asset.

func (*Client) GetAssetHistory

func (c *Client) GetAssetHistory(
	ctx context.Context,
	policy PolicyID,
	name AssetName,
	opts *RequestOptions,
) (res *AssetHistoryResponse, err error)

GetAssetHistory returns mint/burn history of an asset.

func (*Client) GetAssetInfo

func (c *Client) GetAssetInfo(
	ctx context.Context,
	policy PolicyID,
	name AssetName,
	opts *RequestOptions,
) (res *AssetInfoResponse, err error)

GetAssetInfo returns the information of an asset including first minting & token registry metadata.

func (*Client) GetAssetPolicyInfo

func (c *Client) GetAssetPolicyInfo(
	ctx context.Context,
	policy PolicyID,
	opts *RequestOptions,
) (res *AssetPolicyInfoResponse, err error)

GetAssetPolicyInfo returns information for all assets under the same policy.

func (*Client) GetAssetSummary

func (c *Client) GetAssetSummary(
	ctx context.Context,
	policy PolicyID,
	name AssetName,
	opts *RequestOptions,
) (res *AssetSummaryResponse, err error)

GetAssetSummary returns the summary of an asset (total transactions exclude minting/total wallets include only wallets with asset balance).

func (*Client) GetAssetTxs

func (c *Client) GetAssetTxs(
	ctx context.Context,
	policy PolicyID,
	name AssetName,
	afterBlockHeight int,
	history bool,
	opts *RequestOptions,
) (res *AssetTxsResponse, err error)

GetAssetTxs returns the list of all asset transaction hashes (newest first).

func (*Client) GetAssets

func (c *Client) GetAssets(
	ctx context.Context,
	opts *RequestOptions,
) (res *AssetListResponse, err error)

GetAssetList returns the list of all native assets (paginated).

func (*Client) GetBlockInfo

func (c *Client) GetBlockInfo(
	ctx context.Context,
	hash BlockHash,
	opts *RequestOptions,
) (res *BlockInfoResponse, err error)

GetBlockInfo returns detailed information about a specific block.

func (*Client) GetBlockInfos

func (c *Client) GetBlockInfos(
	ctx context.Context,
	hashes []BlockHash,
	opts *RequestOptions,
) (res *BlocksInfoResponse, err error)

GetBlocksInfo returns detailed information about a set of blocks.

func (*Client) GetBlockTxs

func (c *Client) GetBlockTxs(
	ctx context.Context,
	hash BlockHash,
	opts *RequestOptions,
) (res *BlockTxsResponse, err error)

GetBlocksTxs returns a list of all transactions included in a blocks.

func (*Client) GetBlocks

func (c *Client) GetBlocks(
	ctx context.Context,
	opts *RequestOptions,
) (res *BlocksResponse, err error)

GetBlocks returns summarised details about all blocks (paginated - latest first).

func (*Client) GetBlocksTxs

func (c *Client) GetBlocksTxs(
	ctx context.Context,
	hashes []BlockHash,
	opts *RequestOptions,
) (res *BlocksTxsResponse, err error)

GetBlocksTxs returns a list of all transactions included in a blocks.

func (*Client) GetCredentialTxs

func (c *Client) GetCredentialTxs(
	ctx context.Context,
	creds []PaymentCredential,
	h uint64,
	opts *RequestOptions,
) (res *CredentialTxsResponse, err error)

func (*Client) GetDatumInfo

func (c *Client) GetDatumInfo(
	ctx context.Context,
	hash DatumHash,
	opts *RequestOptions,
) (res *DatumInfoResponse, err error)

GetTxStatus returns status of transaction.

func (*Client) GetDatumInfos

func (c *Client) GetDatumInfos(
	ctx context.Context,
	hashes []DatumHash,
	opts *RequestOptions,
) (*DatumInfosResponse, error)

GetTxsStatuses returns status of transaction(s).

func (*Client) GetEpochBlockProtocols

func (c *Client) GetEpochBlockProtocols(
	ctx context.Context,
	epoch *EpochNo,
	opts *RequestOptions,
) (res *EpochBlockProtocolsResponse, err error)

GetEpochBlockProtocols returns the information about block protocol distribution in epoch.

func (*Client) GetEpochInfo

func (c *Client) GetEpochInfo(
	ctx context.Context,
	epoch *EpochNo,
	opts *RequestOptions,
) (res *EpochInfoResponse, err error)

GetEpochInfo returns the epoch information, all epochs if no epoch specified.

func (*Client) GetEpochParams

func (c *Client) GetEpochParams(
	ctx context.Context,
	epoch *EpochNo,
	opts *RequestOptions,
) (res *EpochParamsResponse, err error)

GetEpochParams returns the protocol parameters for specific epoch, and information about all epochs if no epoch specified.

func (*Client) GetGenesis

func (c *Client) GetGenesis(
	ctx context.Context,
	opts *RequestOptions,
) (*GenesisResponse, error)

GetGenesis returns the Genesis parameters used to start specific era on chain.

func (*Client) GetNativeScripts

func (c *Client) GetNativeScripts(
	ctx context.Context,
	opts *RequestOptions,
) (res *NativeScriptListResponse, err error)

GetNativeScriptList returns list of all existing native script hashes along with their creation transaction hashes.

func (*Client) GetPlutusScripts

func (c *Client) GetPlutusScripts(
	ctx context.Context,
	opts *RequestOptions,
) (res *PlutusScriptListResponse, err error)

GetPlutusScriptList returns all existing Plutus script hashes along with their creation transaction hashes.

func (*Client) GetPoolBlocks

func (c *Client) GetPoolBlocks(
	ctx context.Context,
	pid PoolID,
	epoch *EpochNo,
	opts *RequestOptions,
) (res *PoolBlocksResponse, err error)

GetPoolBlocks returns information about blocks minted by a given pool in current epoch (or _epoch_no if provided).

func (*Client) GetPoolDelegators

func (c *Client) GetPoolDelegators(
	ctx context.Context,
	pid PoolID,
	opts *RequestOptions,
) (res *PoolDelegatorsResponse, err error)

GetPoolDelegators returns information about delegators by a given pool and optional epoch (current if omitted).

func (*Client) GetPoolDelegatorsHistory

func (c *Client) GetPoolDelegatorsHistory(
	ctx context.Context,
	pid PoolID,
	epoch *EpochNo,
	opts *RequestOptions,
) (res *PoolDelegatorsHistoryResponse, err error)

func (*Client) GetPoolHistory

func (c *Client) GetPoolHistory(
	ctx context.Context,
	pid PoolID,
	epoch *EpochNo,
	opts *RequestOptions,
) (res *PoolHistoryResponse, err error)

GetPoolHistory returns 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).

func (*Client) GetPoolInfo

func (c *Client) GetPoolInfo(
	ctx context.Context,
	pid PoolID,
	opts *RequestOptions,
) (res *PoolInfoResponse, err error)

GetPoolInfo returns current pool status and details for a specified pool.

func (*Client) GetPoolInfos

func (c *Client) GetPoolInfos(
	ctx context.Context,
	pids []PoolID,
	opts *RequestOptions,
) (res *PoolInfosResponse, err error)

GetPoolInfos returns current pool statuses and details for a specified list of pool ids.

func (*Client) GetPoolMetadata

func (c *Client) GetPoolMetadata(
	ctx context.Context,
	pids []PoolID,
	opts *RequestOptions,
) (res *PoolMetadataResponse, err error)

GetPoolMetadata returns Metadata(on & off-chain) for all currently registered/retiring (not retired) pools.

func (*Client) GetPoolRelays

func (c *Client) GetPoolRelays(
	ctx context.Context,
	opts *RequestOptions,
) (res *PoolRelaysResponse, err error)

GetPoolRelays returns a list of registered relays for all currently registered/retiring (not retired) pools.

func (*Client) GetPoolSnapshot

func (c *Client) GetPoolSnapshot(
	ctx context.Context,
	pid PoolID,
	opts *RequestOptions,
) (res *PoolSnapshotResponse, err error)

func (*Client) GetPoolUpdates

func (c *Client) GetPoolUpdates(
	ctx context.Context,
	pid *PoolID,
	opts *RequestOptions,
) (res *PoolUpdatesResponse, err error)

GetPoolUpdates returns all pool updates for all pools or only updates for specific pool if specified.

func (*Client) GetPools

func (c *Client) GetPools(
	ctx context.Context,
	opts *RequestOptions,
) (res *PoolListResponse, err error)

GetPoolList returns the list of all currently registered/retiring (not retired) pools.

func (*Client) GetScriptRedeemers

func (c *Client) GetScriptRedeemers(
	ctx context.Context,
	sh ScriptHash,
	opts *RequestOptions,
) (res *ScriptRedeemersResponse, err error)

GetScriptRedeemers returns a list of all redeemers for a given script hash.

func (*Client) GetTip

func (c *Client) GetTip(
	ctx context.Context,
	opts *RequestOptions,
) (res *TipResponse, err error)

GetTip returns the tip info about the latest block seen by chain.

func (*Client) GetTotals

func (c *Client) GetTotals(
	ctx context.Context,
	epoch *EpochNo,
	opts *RequestOptions,
) (*TotalsResponse, error)

GetTotals returns the circulating utxo, treasury, rewards, supply and reserves in lovelace for specified epoch, all epochs if empty.

func (*Client) GetTxInfo

func (c *Client) GetTxInfo(
	ctx context.Context,
	hash TxHash,
	opts *RequestOptions,
) (res *TxInfoResponse, err error)

GetTxInfo returns detailed information about transaction.

func (*Client) GetTxMetaLabels

func (c *Client) GetTxMetaLabels(
	ctx context.Context,
	opts *RequestOptions,
) (*TxMetaLabelsResponse, error)

GetTxMetaLabels retruns a list of all transaction metalabels.

func (*Client) GetTxMetadata

func (c *Client) GetTxMetadata(
	ctx context.Context,
	hash TxHash,
	opts *RequestOptions,
) (res *TxMetadataResponse, err error)

GetTxMetadata returns metadata information (if any) for given transaction.

func (*Client) GetTxStatus

func (c *Client) GetTxStatus(
	ctx context.Context,
	hash TxHash,
	opts *RequestOptions,
) (res *TxStatusResponse, err error)

GetTxStatus returns status of transaction.

func (*Client) GetTxUTxOs

func (c *Client) GetTxUTxOs(
	ctx context.Context,
	hash TxHash,
	opts *RequestOptions,
) (res *TxUTxOsResponse, err error)

GetTxUTxOs returns UTxO set (inputs/outputs) of transaction.

func (*Client) GetTxsInfo

func (c *Client) GetTxsInfo(
	ctx context.Context,
	txs []TxHash,
	opts *RequestOptions,
) (*TxsInfosResponse, error)

GetTxsInfo returns detailed information about transaction(s).

func (*Client) GetTxsMetadata

func (c *Client) GetTxsMetadata(
	ctx context.Context,
	txs []TxHash,
	opts *RequestOptions,
) (*TxsMetadataResponse, error)

GetTxsMetadata returns metadata for requested transaction(s).

func (*Client) GetTxsStatuses

func (c *Client) GetTxsStatuses(
	ctx context.Context,
	txs []TxHash,
	opts *RequestOptions,
) (*TxsStatusesResponse, error)

GetTxsStatuses returns status of transaction(s).

func (*Client) GetTxsUTxOs

func (c *Client) GetTxsUTxOs(
	ctx context.Context,
	txs []TxHash,
	opts *RequestOptions,
) (*TxsUTxOsResponse, error)

GetTxsUTxOs returns UTxO set (inputs/outputs) of transactions.

func (*Client) HEAD

func (c *Client) HEAD(
	ctx context.Context,
	path string,
	opts *RequestOptions,
) (*http.Response, error)

HEAD sends api http HEAD request to provided relative path with query params and returns an HTTP response.

func (*Client) NewRequestOptions

func (c *Client) NewRequestOptions() *RequestOptions

func (*Client) POST

func (c *Client) POST(
	ctx context.Context,
	path string,
	body io.Reader,
	opts *RequestOptions,
) (*http.Response, error)

POST sends api http POST request to provided relative path with query params and returns an HTTP response. When using POST method you are expected to handle the response according to net/http.Do documentation. e.g. Caller should close resp.Body when done reading from it.

func (*Client) ServerURL

func (c *Client) ServerURL() *url.URL

ServerURL returns currently used server url e.g. https://api.koios.rest/

func (*Client) SubmitSignedTx

func (c *Client) SubmitSignedTx(
	ctx context.Context,
	stx TxBodyJSON,
	opts *RequestOptions,
) (*SubmitSignedTxResponse, error)

SubmitSignedTx Submit an transaction to the network.

func (*Client) WithOptions

func (c *Client) WithOptions(opts ...Option) (*Client, error)

WithOptions returns new light clone of client with modified options applied.

type CredentialTxsResponse

type CredentialTxsResponse struct {
	Response
	Data []AddressTx `json:"data"`
}

CredentialTxsResponse represents response from `/credential_txs` endpoint.

type DatumHash

type DatumHash string

func (DatumHash) String

func (v DatumHash) String() string

String returns DatumHash as string.

type DatumInfo

type DatumInfo struct {
	Hash  DatumHash        `json:"hash"`
	Bytes string           `json:"bytes"`
	Value *json.RawMessage `json:"value"`
}

DatumInfo datum information for given datum hash

type DatumInfoResponse

type DatumInfoResponse struct {
	Response
	Data *DatumInfo `json:"data"`
}

type DatumInfosResponse

type DatumInfosResponse struct {
	Response
	Data []DatumInfo `json:"data"`
}

DatumInfosResponse represents response from `/datum_info` endpoint.

type EUTxO

type EUTxO struct {
	/// TxHash is hash of transaction.
	TxHash TxHash `json:"tx_hash,omitempty"`

	// Inputs An array with details about inputs used in a transaction.
	Inputs []UTxO `json:"inputs" cbor:"0,keyasint"`
	// Outputs An array with details about outputs from the transaction.
	Outputs []UTxO `json:"outputs" cbor:"1,keyasint"`
}

UTxO model holds inputs and outputs for given UTxO.

type EpochBlockProtocolsResponse

type EpochBlockProtocolsResponse struct {
	Response
	Data []BlockProtocol `json:"data"`
}

type EpochInfo

type EpochInfo struct {
	// Epoch number
	EpochNo EpochNo `json:"epoch_no"`

	// OutSum total output value across all transactions in epoch.
	OutSum decimal.Decimal `json:"out_sum"`

	// Number of blocks created in epoch
	BlkCount int `json:"blk_count"`

	// Total fees incurred by transactions in epoch
	Fees decimal.Decimal `json:"fees"`

	// Timestamp for first block created in epoch
	FirstBlockTime Timestamp `json:"first_block_time"`

	// Timestamp for last block created in epoch
	LastBlockTime Timestamp `json:"last_block_time"`

	// Number of transactions submitted in epoch
	TxCount int `json:"tx_count"`

	// EndTime of epoch
	EndTime Timestamp `json:"end_time"`

	// StartTime of epoch
	StartTime Timestamp `json:"start_time"`

	// ActiveStake Total active stake in epoch stake snapshot
	// (null for pre-Shelley epochs)
	ActiveStake decimal.Decimal `json:"active_stake,omitempty"`

	// TotalRewards earned in epoch (null for pre-Shelley epochs)
	TotalRewards decimal.Decimal `json:"total_rewards,omitempty"`

	// AvgBlkReward Average block reward for epoch (null for pre-Shelley epochs)
	AvgBlkReward decimal.Decimal `json:"avg_blk_reward,omitempty"`
}

EpochInfo defines model for epoch_info.

type EpochInfoResponse

type EpochInfoResponse struct {
	Response
	Data []EpochInfo `json:"data"`
}

EpochInfoResponse response of /epoch_info.

type EpochNo

type EpochNo int

EpochNo defines type for _epoch_no.

func (EpochNo) String

func (v EpochNo) String() string

String returns EpochNo as string.

type EpochParams

type EpochParams struct {
	// The hash of the first block where these parameters are valid
	BlockHash BlockHash `json:"block_hash"`

	// The cost per UTxO word
	CoinsPerUtxoSize decimal.Decimal `json:"coins_per_utxo_size"`

	// The percentage of the tx fee which must be provided as collateral
	// when including non-native scripts
	CollateralPercent int `json:"collateral_percent"`

	// The per language cost models
	CostModels string `json:"cost_models"`

	// The decentralisation parameter (1 fully centralised, 0 fully decentralised)
	Decentralisation float64 `json:"decentralisation"`

	// The hash of 32-byte string of extra random-ness added into
	// the protocol's entropy pool
	ExtraEntropy string `json:"extra_entropy"`

	// Epoch number
	EpochNo EpochNo `json:"epoch_no"`

	// The pledge influence on pool rewards
	Influence float64 `json:"influence"`

	// The amount (in lovelace) required for a deposit to register a stake address
	KeyDeposit decimal.Decimal `json:"key_deposit"`

	// The maximum block header size (in bytes)
	MaxBhSize int `json:"max_bh_size"`

	// The maximum number of execution memory allowed to be used in a single block
	MaxBlockExMem float32 `json:"max_block_ex_mem"`

	// The maximum number of execution steps allowed to be used in a single block
	MaxBlockExSteps float32 `json:"max_block_ex_steps"`

	// The maximum block size (in bytes)
	MaxBlockSize int `json:"max_block_size"`

	// The maximum number of collateral inputs allowed in a transaction
	MaxCollateralInputs int `json:"max_collateral_inputs"`

	// The maximum number of epochs in the future that a pool retirement
	// is allowed to be scheduled for
	MaxEpoch int `json:"max_epoch"`

	// The maximum number of execution memory allowed to be used in a single transaction
	MaxTxExMem float32 `json:"max_tx_ex_mem"`

	// The maximum number of execution steps allowed to be used in a single transaction
	MaxTxExSteps float32 `json:"max_tx_ex_steps"`

	// The maximum transaction size (in bytes)
	MaxTxSize int `json:"max_tx_size"`

	// The maximum Val size
	MaxValSize float64 `json:"max_val_size"`

	// The 'a' parameter to calculate the minimum transaction fee
	MinFeeA decimal.Decimal `json:"min_fee_a"`

	// The 'b' parameter to calculate the minimum transaction fee
	MinFeeB decimal.Decimal `json:"min_fee_b"`

	// The minimum pool cost
	MinPoolCost decimal.Decimal `json:"min_pool_cost"`

	// The minimum value of a UTxO entry
	MinUtxoValue decimal.Decimal `json:"min_utxo_value"`

	// The monetary expansion rate
	MonetaryExpandRate float64 `json:"monetary_expand_rate"`

	// The nonce value for this epoch
	Nonce string `json:"nonce"`

	// The optimal number of stake pools
	OptimalPoolCount int `json:"optimal_pool_count"`

	// The amount (in lovelace) required for a deposit to register a stake pool
	PoolDeposit decimal.Decimal `json:"pool_deposit"`

	// The per word cost of script memory usage
	PriceMem decimal.Decimal `json:"price_mem"`

	// The cost of script execution step usage
	PriceStep decimal.Decimal `json:"price_step"`

	// The protocol major version
	ProtocolMajor int `json:"protocol_major"`

	// The protocol minor version
	ProtocolMinor int `json:"protocol_minor"`

	// The treasury growth rate
	TreasuryGrowthRate float64 `json:"treasury_growth_rate"`
}

EpochParams defines model for epoch_params.

type EpochParamsResponse

type EpochParamsResponse struct {
	Response
	Data []EpochParams `json:"data"`
}

EpochParamsResponse response of /epoch_params.

type ErrorCode

type ErrorCode string

func ErrorCodeFromInt

func ErrorCodeFromInt(code int) ErrorCode

func (ErrorCode) Int

func (c ErrorCode) Int() int

Int returns error code as integer if strconv.Atoi is able to parse it, otherwise it returns 0.

func (ErrorCode) String

func (c ErrorCode) String() string

String returns error code as string.

type Genesis

type Genesis struct {
	// Active Slot Co-Efficient (f) - determines the _probability_ of number of
	// slots in epoch that are expected to have blocks
	// (so mainnet, this would be: 432000 * 0.05 = 21600 estimated blocks).
	ActiveSlotCoeff decimal.Decimal `json:"activeslotcoeff"`

	// A JSON dump of Alonzo Genesis.
	AlonzoGenesis json.RawMessage `json:"alonzogenesis"`

	// Number of slots in an epoch.
	EpochLength decimal.Decimal `json:"epochlength"`

	// Number of KES key evolutions that will automatically occur before a KES
	// (hot) key is expired. This parameter is for security of a pool,
	// in case an operator had access to his hot(online) machine compromised.
	MaxKesRevolutions decimal.Decimal `json:"maxkesrevolutions"`

	// Maximum smallest units (lovelaces) supply for the blockchain.
	MaxLovelaceSupply decimal.Decimal `json:"maxlovelacesupply"`

	// Network ID used at various CLI identification to distinguish between
	// Mainnet and other networks.
	NetworkID string `json:"networkid"`

	// Unique network identifier for chain.
	NetworkMagic decimal.Decimal `json:"networkmagic"`

	// A unit (k) used to divide epochs to determine stability window
	// (used in security checks like ensuring atleast 1 block was
	// created in 3*k/f period, or to finalize next epoch's nonce
	// at 4*k/f slots before end of epoch).
	SecurityParam decimal.Decimal `json:"securityparam"`

	// Duration of a single slot (in seconds).
	SlotLength decimal.Decimal `json:"slotlength"`

	// Number of slots that represent a single KES period
	// (a unit used for validation of KES key evolutions).
	SlotsPerKesPeriod decimal.Decimal `json:"slotsperkesperiod"`

	// Timestamp for first block (genesis) on chain.
	SystemStart Timestamp `json:"systemstart"`

	// Number of BFT members that need to approve
	// (via vote) a Protocol Update Proposal.
	UpdateQuorum decimal.Decimal `json:"updatequorum"`
}

Genesis defines model for genesis.

func (*Genesis) AlonzoGenesisMap

func (g *Genesis) AlonzoGenesisMap() (map[string]any, error)

type GenesisResponse

type GenesisResponse struct {
	Response
	Data Genesis `json:"data"`
}

GenesisResponse response of /genesis.

type NativeScript

type NativeScript struct {
	// Hash of the script creation transaction
	CreationTxHash TxHash `json:"creation_tx_hash"`

	// Hash of a script
	ScriptHash string `json:"script_hash"`
	Type       string `json:"type"`
	Script     struct {
		Type    string            `json:"type"`
		Scripts []json.RawMessage `json:"scripts"`
	} `json:"script"`
}

NativeScript item of native script list.

type NativeScriptListResponse

type NativeScriptListResponse struct {
	Response
	Data []NativeScript `json:"data"`
}

NativeScriptListResponse represents response from `/native_script_list` endpoint.

type Option

type Option struct {
	// contains filtered or unexported fields
}

Option is callback function to apply configurations options of API Client.

func APIVersion

func APIVersion(version string) Option

APIVersion returns option to apply change of the baseurl api version https://api.koios.rest/api/<version>/

func CollectRequestsStats

func CollectRequestsStats(enabled bool) Option

CollectRequestsStats when enabled uses httptrace is used to collect detailed timing information about the request.

func HTTPClient

func HTTPClient(client *http.Client) Option

HTTPClient enables to set htt.Client to be used for requests.

func Host

func Host(host string) Option

Host returns option apply func which can be used to change the baseurl hostname https://<host>/api/v0/

func Origin

func Origin(origin string) Option

Origin sets Origin header for outgoing api requests. Recomoended is to set it to URL or FQDN of your project using this library.

In case you appliation goes rouge this could help to keep api.koios.rest service stable and up and running while temporary limiting requests it accepts from your application.

It's not required, but considered as good practice so that Cardano Community can provide HA services for Cardano ecosystem.

func Port

func Port(port uint16) Option

Port returns option apply func which can be used to change the baseurl port https://api.koios.rest:<port>/api/v0/

func RateLimit

func RateLimit(reqps int) Option

RateLimit sets requests per second this client is allowed to create and effectievely rate limits outgoing requests. Let's respect usage of the community provided resources.

func Scheme

func Scheme(scheme string) Option

Scheme returns option apply func which can be used to change the baseurl scheme <scheme>://api.koios.rest/api/v0/.

type PaymentAddr

type PaymentAddr struct {
	// Bech32 is Cardano payment/base address (bech32 encoded)
	// for transaction's or change to be returned.
	Bech32 Address `json:"bech32"`

	// Payment credential.
	Cred PaymentCredential `json:"cred"`
}

PaymentAddr info.

type PaymentCredential

type PaymentCredential string

PaymentCredential type def.

func (PaymentCredential) String

func (v PaymentCredential) String() string

String returns PaymentCredential as string.

type PlutusContract

type PlutusContract struct {
	Address       Address    `json:"address"`
	ScriptHash    ScriptHash `json:"script_hash"`
	ByteCode      string     `json:"bytecode"`
	Size          int        `json:"size"`
	ValidContract bool       `json:"valid_contract"`
}

type PlutusScriptListItem

type PlutusScriptListItem struct {
	// Hash of the script creation transaction
	CreationTxHash TxHash `json:"creation_tx_hash"`

	// Hash of a script
	ScriptHash string `json:"script_hash"`
}

PlutusScriptListItem item of plutus script list.

type PlutusScriptListResponse

type PlutusScriptListResponse struct {
	Response
	Data []PlutusScriptListItem `json:"data"`
}

PlutusScriptListResponse represents response from `/plutus_script_list` endpoint.

type PolicyID

type PolicyID string

PolicyID type def.

func (PolicyID) String

func (v PolicyID) String() string

String returns PolicyID as string.

type PoolBlockInfo

type PoolBlockInfo struct {
	// Slot is overall slot number (slots from genesis block of chain).
	AbsSlot Slot `json:"abs_slot"`

	// Hash block hash
	BlockHash BlockHash `json:"block_hash"`

	// BlockHeight ogf the block
	BlockHeight uint64 `json:"block_height"`

	// Time time of the block.
	BlockTime Timestamp `json:"block_time"`

	// Epoch number.
	EpochNo EpochNo `json:"epoch_no"`

	// EpochSlot slot number within epoch.
	EpochSlot Slot `json:"epoch_slot"`
}

PoolBlockInfo block info.

type PoolBlocksResponse

type PoolBlocksResponse struct {
	Response
	Data []PoolBlockInfo `json:"data"`
}

PoolBlocksResponse represents response from `/pool_blocks` endpoint.

type PoolDelegator

type PoolDelegator struct {
	StakeAddress           Address         `json:"stake_address"`
	Amount                 decimal.Decimal `json:"amount"`
	ActiveEpochNo          EpochNo         `json:"active_epoch_no"`
	LatestDelegationTxHash TxHash          `json:"latest_delegation_tx_hash"`
}

PoolDelegator info.

type PoolDelegatorHistory

type PoolDelegatorHistory struct {
	StakeAddress Address         `json:"stake_address"`
	Amount       decimal.Decimal `json:"amount"`
	EpochNo      EpochNo         `json:"epoch_no"`
}

type PoolDelegatorsHistoryResponse

type PoolDelegatorsHistoryResponse struct {
	Response
	Data []PoolDelegatorHistory `json:"data"`
}

type PoolDelegatorsResponse

type PoolDelegatorsResponse struct {
	Response
	Data []PoolDelegator `json:"data"`
}

PoolDelegatorsResponse represents response from `/pool_delegators` endpoint.

type PoolHistory

type PoolHistory struct {
	// Epoch number.
	EpochNo EpochNo `json:"epoch_no"`
	// ActiveStake Pool active stake.
	ActiveStake    decimal.Decimal `json:"active_stake"`
	ActiveStakePCT float64         `json:"active_stake_pct"`
	SaturationPCT  float64         `json:"saturation_pct"`
	BlockCNT       int             `json:"block_cnt"`
	DelegatorCNT   int             `json:"delegator_cnt"`
	Margin         float64         `json:"margin"`
	FixedCost      decimal.Decimal `json:"fixed_cost"`
	PoolFees       decimal.Decimal `json:"pool_fees"`
	DelegRewards   decimal.Decimal `json:"deleg_rewards"`
	EpochROS       decimal.Decimal `json:"epoch_ros"`
}

PoolHistory entry.

type PoolHistoryResponse

type PoolHistoryResponse struct {
	Response
	Data []PoolHistory `json:"data"`
}

PoolHistoryResponse represents response from `/pool_history` endpoint.

type PoolID

type PoolID string

PoolID type def.

func (PoolID) String

func (v PoolID) String() string

String returns PoolID as string.

type PoolInfo

type PoolInfo struct {
	// ActiveEpochNo Block number on chain where transaction was included.
	ActiveEpoch EpochNo `json:"active_epoch_no"`

	// ActiveStake Pool active stake.
	ActiveStake decimal.Decimal `json:"active_stake"`

	// Total pool blocks on chain
	BlockCount uint64 `json:"block_count"`

	// FixedCost Pool fixed cost per epoch
	FixedCost decimal.Decimal `json:"fixed_cost"`

	// LiveDelegators Pool live delegator count
	LiveDelegators uint64 `json:"live_delegators"`

	// LiveSaturation Pool live saturation (decimal format)
	LiveSaturation float32 `json:"live_saturation"`

	// LiveStake Pool live stake
	LiveStake decimal.Decimal `json:"live_stake"`

	// LivePledge Pool live pledge
	LivePledge decimal.Decimal `json:"live_pledge"`

	// Margin (decimal format)
	Margin float32 `json:"margin"`

	// MetaHash Pool metadata hash
	MetaHash string `json:"meta_hash"`

	// MetaJson pool meta json
	MetaJSON PoolMetaJSON `json:"meta_json"`

	// MetaUrl Pool metadata URL
	MetaURL string `json:"meta_url"`

	// OpCert Pool latest operational certificate hash
	OpCert string `json:"op_cert"`

	// OpCertCounter Pool latest operational certificate counter value
	OpCertCounter int `json:"op_cert_counter"`

	// Owners of the pool
	Owners []Address `json:"owners"`

	// Pledge pledge in lovelace
	Pledge decimal.Decimal `json:"pledge"`

	// ID (bech32 format)
	PoolID PoolID `json:"pool_id_bech32"`

	// IDHex Pool ID (Hex format)
	PoolIdHex string `json:"pool_id_hex"`

	// Pool status (registered | retiring | retired)
	PoolStatus string `json:"pool_status"`

	// Announced retiring epoch (nullable)
	RetiringEpoch *EpochNo `json:"retiring_epoch"`

	// Pool reward address
	RewardAddr Address `json:"reward_addr"`

	// Pool VRF key hash
	VrfKeyHash string `json:"vrf_key_hash"`

	// Relays of the pool
	Relays []Relay `json:"relays"`

	Sigma float64 `json:"sigma"`
}

PoolInfo defines model for pool_info.

type PoolInfoResponse

type PoolInfoResponse struct {
	Response
	Data *PoolInfo `json:"data"`
}

PoolInfoResponse represents response from `/pool_info` endpoint. when requesting info about single pool.

type PoolInfosResponse

type PoolInfosResponse struct {
	Response
	Data []PoolInfo `json:"data"`
}

PoolInfosResponse represents response from `/pool_info` endpoint.

type PoolListItem

type PoolListItem struct {
	// PoolID Bech32 representation of pool ID.
	PoolID PoolID `json:"pool_id_bech32"`

	// Ticker of Pool.
	Ticker string `json:"ticker,omitempty"`
}

PoolListItem defines model for pool list item.

type PoolListResponse

type PoolListResponse struct {
	Response
	Data []PoolListItem `json:"data"`
}

PoolListResponse represents response from `/pool_list` endpoint.

type PoolMetaJSON

type PoolMetaJSON struct {
	// Pool description
	Description *string `json:"description"`

	// Pool homepage URL
	Homepage *string `json:"homepage"`

	// Pool name
	Name *string `json:"name"`

	// Pool ticker
	Ticker *string `json:"ticker"`
}

PoolMetaJSON pool meadata json.

type PoolMetadata

type PoolMetadata struct {
	// ID (bech32 format)
	PoolID PoolID `json:"pool_id_bech32"`
	// MetaUrl Pool metadata URL
	MetaURL string `json:"meta_url"`

	// MetaHash Pool metadata hash
	MetaHash string `json:"meta_hash"`

	// MetaJson pool meta json
	MetaJSON *PoolMetaJSON `json:"meta_json,omitempty"`
}

PoolMetadata metadata list item.

type PoolMetadataResponse

type PoolMetadataResponse struct {
	Response
	Data []PoolMetadata `json:"data"`
}

PoolMetadataResponse represents response from `/pool_metadata` endpoint.

type PoolRelays

type PoolRelays struct {
	PoolID PoolID `json:"pool_id_bech32"`
	// Relays of the pool.
	Relays []Relay `json:"relays"`
}

PoolRelays list item.

type PoolRelaysResponse

type PoolRelaysResponse struct {
	Response
	Data []PoolRelays `json:"data"`
}

PoolRelaysResponse represents response from `/pool_relays` endpoint.

type PoolSnapshot

type PoolSnapshot struct {
	Snapshot    string          `json:"snapshot"`
	EpochNo     EpochNo         `json:"epoch_no"`
	Nonce       string          `json:"nonce"`
	PoolStake   decimal.Decimal `json:"pool_stake"`
	ActiveStake decimal.Decimal `json:"active_stake"`
}

type PoolSnapshotResponse

type PoolSnapshotResponse struct {
	Response
	Data []PoolSnapshot `json:"data"`
}

type PoolUpdateInfo

type PoolUpdateInfo struct {
	// TxHash update transaction
	TxHash TxHash `json:"tx_hash"`

	// Time time of the block.
	BlockTime Timestamp `json:"block_time"`

	// ID (bech32 format)
	PoolID PoolID `json:"pool_id_bech32"`

	// IDHex Pool ID (Hex format)
	PoolIDHex string `json:"pool_id_hex"`

	// ActiveEpochNo Block number on chain where transaction was included.
	ActiveEpoch EpochNo `json:"active_epoch_no"`

	// FixedCost Pool fixed cost per epoch
	FixedCost decimal.Decimal `json:"fixed_cost"`

	// Margin (decimal format)
	Margin float32 `json:"margin"`

	// MetaHash Pool metadata hash
	MetaHash string `json:"meta_hash"`

	// MetaUrl Pool metadata URL
	MetaURL string `json:"meta_url"`

	// Owners of the pool.
	Owners []Address `json:"owners"`

	// Pledge pledge in lovelace.
	Pledge decimal.Decimal `json:"pledge"`

	// Pool status (registered | retiring | retired).
	PoolStatus string `json:"pool_status"`

	// Announced retiring epoch (nullable).
	RetiringEpoch *EpochNo `json:"retiring_epoch.omitempty"`

	// Pool reward address.
	RewardAddr Address `json:"reward_addr"`

	// Pool VRF key hash.
	VrfKeyHash string `json:"vrf_key_hash"`

	// Relays of the pool.
	Relays []Relay `json:"relays"`
}

PoolUpdateInfo response item from `/pool_updates`.

type PoolUpdatesResponse

type PoolUpdatesResponse struct {
	Response
	Data []PoolUpdateInfo `json:"data"`
}

PoolUpdatesResponse represents response from `/pool_updates` endpoint.

type Relay

type Relay struct {
	// DNS name of the relay (nullable)
	DNS string `json:"dns"`

	// IPv4 address of the relay (nullable)
	Ipv4 string `json:"ipv4,"`

	// IPv6 address of the relay (nullable)
	Ipv6 string `json:"ipv6,"`

	// Port number of the relay (nullable)
	Port uint16 `json:"port"`

	// DNS service name of the relay (nullable)
	Srv string `json:"srv"`
}

Relay defines model for pool relay.

type RequestOptions

type RequestOptions struct {
	// contains filtered or unexported fields
}

RequestOptions for the request.

func (*RequestOptions) Clone

func (ro *RequestOptions) Clone() *RequestOptions

Clone the request options for using it with other request.

func (*RequestOptions) HeaderAdd

func (ro *RequestOptions) HeaderAdd(key, val string)

HeadersAdd adds the value to request headers by key. It appends to any existing values associated with key.

func (*RequestOptions) HeaderApply

func (ro *RequestOptions) HeaderApply(h http.Header)

HeadersApply sets all values from provided header.

func (*RequestOptions) HeaderSet

func (ro *RequestOptions) HeaderSet(key, val string)

HeadersSet sets the key to value in request headers. It replaces any existing values.

func (*RequestOptions) QueryAdd

func (ro *RequestOptions) QueryAdd(key, val string)

QueryAdd adds the value to request query by key. It appends to any existing values associated with key.

func (*RequestOptions) QueryApply

func (ro *RequestOptions) QueryApply(h url.Values)

QueryApply sets all values from provided query.

func (*RequestOptions) QuerySet

func (ro *RequestOptions) QuerySet(key, val string)

QuerySet sets the key to value in request query. It replaces any existing values.

func (*RequestOptions) SetCurrentPage

func (ro *RequestOptions) SetCurrentPage(page uint)

SetCurrentPage modifies range header of the request to satisfy current page requested.

func (*RequestOptions) SetPageSize

func (ro *RequestOptions) SetPageSize(size uint)

SetPageSize for request modifies range header to satisfy requested page size.

type RequestStats

type RequestStats struct {
	// ReqStartedAt time when request was started.
	ReqStartedAt time.Time `json:"req_started_at,omitempty"`

	// DNSLookupDur DNS lookup duration.
	DNSLookupDur time.Duration `json:"req_dns_lookup_dur,omitempty"`

	// TLSHSDur time it took to perform TLS handshake.
	TLSHSDur time.Duration `json:"tls_hs_dur,omitempty"`

	// ESTCXNDur time it took to establish connection.
	ESTCXNDur time.Duration `json:"est_cxn_dur,omitempty"`

	// TTFB time it took to get the first byte of the response
	// after connextion was established.
	TTFB time.Duration `json:"ttfb,omitempty"`

	// ReqDur total time it took to peform the request.
	ReqDur time.Duration `json:"req_dur,omitempty"`

	// ReqDurStr String representation of ReqDur.
	ReqDurStr string `json:"req_dur_str,omitempty"`
}

RequestStats represent collected request stats if collecting request stats is enabled.

type Response

type Response struct {
	// RequestURL is full request url.
	RequestURL string `json:"request_url"`

	// RequestMethod is HTTP method used for request.
	RequestMethod string `json:"request_method"`

	// StatusCode of the HTTP response.
	StatusCode int `json:"status_code"`

	// Status of the HTTP response header if present.
	Status string `json:"status"`

	// Date response header.
	Date string `json:"date,omitempty"`

	// ContentLocation response header if present.
	ContentLocation string `json:"content_location,omitempty"`

	// ContentRange response header if present.
	ContentRange string `json:"content_range,omitempty"`

	// Error response body if present.
	Error *ResponseError `json:"error,omitempty"`

	// Stats of the request if stats are enabled.
	Stats *RequestStats `json:"stats,omitempty"`
}

Response wraps API responses.

type ResponseError

type ResponseError struct {

	// Hint of the error reported by server.
	Hint string `json:"hint,omitempty"`

	// Details of the error reported by server.
	Details string `json:"details,omitempty"`

	// Code is error code reported by server.
	Code ErrorCode `json:"code,omitempty"`

	// Message is error message reported by server.
	Message string `json:"message,omitempty"`
	// contains filtered or unexported fields
}

ResponseError represents api error messages.

func (*ResponseError) Error

func (e *ResponseError) Error() string

Error return underlying error string.

func (*ResponseError) Unwrap

func (e *ResponseError) Unwrap() error

Error return underlying error string.

type ScriptHash

type ScriptHash string

ScriptHash defines type for _script_hash.

func (ScriptHash) String

func (v ScriptHash) String() string

String returns ScriptHash as string.

type ScriptRedeemer

type ScriptRedeemer struct {
	// The Hash of the Plutus Data
	DatumHash string `json:"datum_hash"`

	// The actual data in json format
	DatumValue map[string]any `json:"datum_value"`

	// The budget in fees to run a script - the fees depend on the
	// ExUnits and the current prices.
	Fee decimal.Decimal `json:"fee,omitempty"`

	// What kind pf validation this redeemer is used for,
	// it can be one of 'spend', 'mint', 'cert', 'reward'.
	Purpose string `json:"purpose"`

	// TxHash of Transaction containing the redeemer.
	TxHash TxHash `json:"tx_hash"`

	// TxIndex The index of the redeemer pointer in the transaction.
	TxIndex uint32 `json:"tx_index"`

	// The budget in Memory to run a script.
	UnitMem int `json:"unit_mem"`

	// The budget in Cpu steps to run a script.
	UnitSteps int `json:"unit_steps"`
}

ScriptRedeemer model.

type ScriptRedeemers

type ScriptRedeemers struct {
	// Hash of Transaction for which details are being shown
	ScriptHash ScriptHash `json:"script_hash"`

	// Redeemers list
	Redeemers []ScriptRedeemer `json:"redeemers"`
}

ScriptRedeemers defines model for script_redeemers.

type ScriptRedeemersResponse

type ScriptRedeemersResponse struct {
	Response
	Data *ScriptRedeemers `json:"data"`
}

ScriptRedeemersResponse represents response from `/script_redeemers` endpoint.

type Slot

type Slot int

type SubmitSignedTxResponse

type SubmitSignedTxResponse struct {
	Response
	Data TxHash `json:"data"`
}

SubmitSignedTxResponse represents response from `/submittx` endpoint.

type TX

type TX struct {
	EUTxO
	TxInfo
}

type Timestamp

type Timestamp struct {
	time.Time
}

Timestamp extends time to work with unix timestamps and fix time format anomalies when Unmarshaling and Marshaling Koios API times.

func (Timestamp) MarshalJSON

func (t Timestamp) MarshalJSON() ([]byte, error)

MarshalJSON turns our time.Time back into an int.

func (*Timestamp) UnmarshalJSON

func (t *Timestamp) UnmarshalJSON(b []byte) error

type Tip

type Tip struct {
	// Absolute Slot number (slots not divided into epochs)
	AbsSlot Slot `json:"abs_slot"`

	// Block Height number on chain
	BlockNo BlockNo `json:"block_no"`

	// Timestamp for when the block was created
	BlockTime Timestamp `json:"block_time"`

	// EpochNo number
	EpochNo EpochNo `json:"epoch_no"`

	// Slot number within Epoch
	EpochSlot Slot `json:"epoch_slot"`

	// Block Hash in hex
	Hash BlockHash `json:"hash"`
}

Tip defines model for tip.

type TipResponse

type TipResponse struct {
	Response
	Data Tip `json:"data"`
}

TipResponse response of /tip.

type TokenRegistryMetadata

type TokenRegistryMetadata struct {
	Decimals    int    `json:"decimals"`
	Description string `json:"description"`

	// A PNG image file as a byte string
	Name   string `json:"name"`
	Ticker string `json:"ticker"`
	URL    string `json:"url"`
}

TokenRegistryMetadata metadata registered on the Cardano Token Registry.

type Totals

type Totals struct {

	// Circulating UTxOs for given epoch (in lovelaces).
	Circulation decimal.Decimal `json:"circulation"`

	// Epoch number.
	EpochNo EpochNo `json:"epoch_no"`

	// Total Reserves yet to be unlocked on chain.
	Reserves decimal.Decimal `json:"reserves"`

	// Rewards accumulated as of given epoch (in lovelaces).
	Reward decimal.Decimal `json:"reward"`

	// Total Active Supply (sum of treasury funds, rewards,
	// UTxOs, deposits and fees) for given epoch (in lovelaces).
	Supply decimal.Decimal `json:"supply"`

	// Funds in treasury for given epoch (in lovelaces).
	Treasury decimal.Decimal `json:"treasury"`
}

Totals defines model for totals.

type TotalsResponse

type TotalsResponse struct {
	Response
	Data []Totals `json:"data"`
}

TotalsResponse represents response from `/totals` endpoint.

type TxBodyJSON

type TxBodyJSON struct {
	Type        string `json:"type"`
	Description string `json:"description"`
	CborHex     string `json:"cborHex"`
}

TxBodyJSON used to Unmarshal built transactions.

type TxHash

type TxHash string

TxHash defines type for tx_hash.

func (TxHash) String

func (v TxHash) String() string

String returns TxHash as string.

type TxInfo

type TxInfo struct {
	// BlockHash is hash of the block in which transaction was included.
	BlockHash BlockHash `json:"block_hash"`

	// BlockHeight is block number on chain where transaction was included.
	BlockHeight int `json:"block_height"`

	// Epoch number.
	EpochNo EpochNo `json:"epoch_no"`

	// EpochSlot is slot number within epoch.
	EpochSlot Slot `json:"epoch_slot"`

	// AbsoluteSlot is overall slot number (slots from genesis block of chain).
	AbsoluteSlot Slot `json:"absolute_slot"`

	// TxTimestamp is timestamp when block containing transaction was created.
	TxTimestamp Timestamp `json:"tx_timestamp"`

	// TxBlockIndex is index of transaction within block.
	TxBlockIndex int `json:"tx_block_index"`

	// TxSize is transaction size in bytes.
	TxSize int `json:"tx_size"`

	// TotalOutput is total sum of all transaction outputs (in lovelaces).
	TotalOutput decimal.Decimal `json:"total_output"`

	// Fee is total transaction fee (in lovelaces).
	Fee decimal.Decimal `json:"fee" cbor:"2,keyasint"`

	// Deposit is total deposits included in transaction (for example,
	// if it is registering a pool/key).
	Deposit decimal.Decimal `json:"deposit"`

	// InvalidAfter is slot number after which transaction cannot be validated.
	InvalidAfter Timestamp `json:"invalid_after,omitempty" cbor:"3,keyasint,omitempty"`

	// InvalidBefore is slot number before which transaction cannot be validated.
	// (if supplied, else 0)
	InvalidBefore Timestamp `json:"invalid_before,omitempty" cbor:"8,keyasint,omitempty"`

	// CollateralInputs An array of collateral inputs needed when dealing with smart contracts.
	CollateralInputs []UTxO `json:"collateral_inputs,omitempty"`

	// CollateralOutput
	CollateralOutput *UTxO `json:"collateral_output,omitempty"`

	// CollateralInputs An array of collateral inputs needed when dealing with smart contracts.
	ReferenceInputs []UTxO `json:"reference_inputs,omitempty"`

	// AssetsMinted An array of minted assets with-in a transaction (if any).
	AssetsMinted []Asset `json:"assets_minted,omitempty"`

	// Metadata present with-in a transaction (if any)
	Metadata TxMetadata `json:"metadata,omitempty"`

	// Array of withdrawals with-in a transaction (if any)
	Withdrawals []TxsWithdrawal `json:"withdrawals,omitempty"`

	// Certificates present with-in a transaction (if any)
	Certificates []Certificate `json:"certificates,omitempty"`

	NativeScripts   []NativeScript   `json:"native_scripts,omitempty"`
	PlutusContracts []PlutusContract `json:"plutus_contracts,omitempty"`
}

TxInfo transaction info.

type TxInfoResponse

type TxInfoResponse struct {
	Response
	Data TX `json:"data"`
}

TxInfoResponse represents response from `/tx_info` endpoint. when requesting info about single transaction.

type TxMetaLabelsResponse

type TxMetaLabelsResponse struct {
	Response
	Data []TxMetalabel `json:"data"`
}

TxMetaLabelsResponse represents response from `/tx_metalabels` endpoint.

type TxMetadata

type TxMetadata map[string]json.RawMessage

TxMetadata transaction metadata lookup res for `/tx_metadata` endpoint.

func (*TxMetadata) UnmarshalJSON

func (m *TxMetadata) UnmarshalJSON(b []byte) error

type TxMetadataOf

type TxMetadataOf struct {
	TxHash   TxHash     `json:"tx_hash"`
	Metadata TxMetadata `json:"metadata,omitempty"`
}

func (*TxMetadataOf) UnmarshalJSON

func (m *TxMetadataOf) UnmarshalJSON(b []byte) error

type TxMetadataResponse

type TxMetadataResponse struct {
	Response
	Data *TxMetadataOf `json:"data"`
}

TxMetadataResponse represents response from `/tx_metadata` endpoint.

type TxMetalabel

type TxMetalabel struct {
	// A distinct known metalabel
	Key string `json:"key"`
}

TxMetalabel

type TxStatus

type TxStatus struct {
	TxHash        TxHash `json:"tx_hash"`
	Confirmations uint64 `json:"num_confirmations"`
}

TxStatus is tx_status enpoint response.

type TxStatusResponse

type TxStatusResponse struct {
	Response
	Data *TxStatus `json:"data"`
}

TxStatusResponse represents response from `/tx_status` endpoint.

type TxUTxOsResponse

type TxUTxOsResponse struct {
	Response
	Data *EUTxO `json:"data"`
}

TxUTxOsResponse represents response from `/tx_utxos` endpoint.

type TxsInfosResponse

type TxsInfosResponse struct {
	Response
	Data []TX `json:"data"`
}

TxsInfosResponse represents response from `/tx_info` endpoint.

type TxsMetadataResponse

type TxsMetadataResponse struct {
	Response
	Data []TxMetadataOf `json:"data"`
}

TxsMetadataResponse represents response from `/tx_metadata` endpoint.

type TxsStatusesResponse

type TxsStatusesResponse struct {
	Response
	Data []TxStatus `json:"data"`
}

TxsStatusesResponse represents response from `/tx_status` endpoint.

type TxsUTxOsResponse

type TxsUTxOsResponse struct {
	Response
	Data []EUTxO `json:"data"`
}

TxsUTxOsResponse represents response from `/tx_utxos` endpoint.

type TxsWithdrawal

type TxsWithdrawal struct {
	// Amount is withdrawal amount in lovelaces.
	Amount decimal.Decimal `json:"amount,omitempty"`
	// StakeAddress fo withdrawal.
	StakeAddress Address `json:"stake_addr,omitempty"`
}

TxsWithdrawal withdrawal record in transaction.

type UTxO

type UTxO struct {
	// Hash of this transaction.
	TxHash TxHash `json:"tx_hash"`

	// Index of output UTxO.
	TxIndex int `json:"tx_index"`

	// where funds were sent or change to be returned.
	PaymentAddr *PaymentAddr `json:"payment_addr,omitempty"`

	// StakeAddress for transaction's output UTxO.
	StakeAddress *Address `json:"stake_addr,omitempty"`

	// Total sum on the output address.
	Value decimal.Decimal `json:"value"`

	DatumHash       DatumHash `json:"datum_hash,omitempty"`
	InlineDatum     any       `json:"inline_datum,omitempty"`
	ReferenceScript any       `json:"reference_script,omitempty"`
	// An array of assets to be included in output UTxO.
	AssetList []Asset `json:"asset_list,omitempty"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL