singular-registry
LicenseApache-2.0
Safe HaskellNone
LanguageGHC2021

Singular.Provider.Koios.Wire

Description

One request description per Koios call, and one decoder per answer, from Koios JSON into Conway ledger types. Nothing here performs a request: a transport carries the description and returns the raw answer, and Singular.Provider.Koios.Client pages and decodes it with these functions. A recorded answer and a live one therefore pass through the same code.

A request is indexed by its access: every call reads, except submitTxRequest, which is the only Submission. A component that must never submit, such as the fixture recorder, accepts only Request 'Read.

A decoder that fails names the position that failed, as a JSON path into the answer. Outputs keep everything the ledger keeps: the address, the value with every policy and asset name, an inline datum's bytes or else a datum hash, and a reference script's bytes, checked against the script hash Koios names. A native reference script is refused by name: Koios gives no bytes for it, only a summary. Koios reports a datum_hash for an inline datum too; the inline datum wins. Transaction bytes are decoded as a Conway transaction and checked against the transaction id Koios names.

A transaction's validity — false for a transaction recorded as a phase-2 failure, whose collateral alone was spent — is read from the transaction itself where its bytes are decoded, from Koios's valid_contract otherwise, and never used to drop a transaction.

Requests name addresses and stake addresses in bech32, so they cover Shelley addresses; Koios names Byron addresses in base58, which this module does not render.

Synopsis

Calls

data Call Source #

The Koios calls this client makes.

Instances

Instances details
Bounded Call Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

minBound :: Call Source #

maxBound :: Call Source #

Enum Call Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

succ :: Call -> Call Source #

pred :: Call -> Call Source #

toEnum :: Int -> Call Source #

fromEnum :: Call -> Int Source #

enumFrom :: Call -> [Call] Source #

enumFromThen :: Call -> Call -> [Call] Source #

enumFromTo :: Call -> Call -> [Call] Source #

enumFromThenTo :: Call -> Call -> Call -> [Call] Source #

Show Call Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

showsPrec :: Int -> Call -> ShowS Source #

show :: Call -> String Source #

showList :: [Call] -> ShowS Source #

Eq Call Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

(==) :: Call -> Call -> Bool Source #

(/=) :: Call -> Call -> Bool Source #

Ord Call Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

compare :: Call -> Call -> Ordering Source #

(<) :: Call -> Call -> Bool Source #

(<=) :: Call -> Call -> Bool Source #

(>) :: Call -> Call -> Bool Source #

(>=) :: Call -> Call -> Bool Source #

max :: Call -> Call -> Call Source #

min :: Call -> Call -> Call Source #

callName :: Call -> Text Source #

The Koios endpoint name of a call, as in its path.

Requests

data Access Source #

Whether a request reads or submits.

Constructors

Read 
Submission 

data Method Source #

HTTP method of a request.

Constructors

Get 
Post 

Instances

Instances details
Show Method Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

showsPrec :: Int -> Method -> ShowS Source #

show :: Method -> String Source #

showList :: [Method] -> ShowS Source #

Eq Method Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

(==) :: Method -> Method -> Bool Source #

(/=) :: Method -> Method -> Bool Source #

Ord Method Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

compare :: Method -> Method -> Ordering Source #

(<) :: Method -> Method -> Bool Source #

(<=) :: Method -> Method -> Bool Source #

(>) :: Method -> Method -> Bool Source #

(>=) :: Method -> Method -> Bool Source #

max :: Method -> Method -> Method Source #

min :: Method -> Method -> Method Source #

data Body Source #

Request body.

Constructors

NoBody 
JsonBody Value

A JSON document

CborBody ByteString

Raw CBOR bytes, as submittx takes them

Instances

Instances details
Show Body Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

showsPrec :: Int -> Body -> ShowS Source #

show :: Body -> String Source #

showList :: [Body] -> ShowS Source #

Eq Body Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

(==) :: Body -> Body -> Bool Source #

(/=) :: Body -> Body -> Bool Source #

data Request (a :: Access) Source #

One Koios request, before paging. A paged request names the order its rows are read in; the client adds offset and limit.

Constructors

Request 

Fields

Instances

Instances details
Show (Request a) Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

showsPrec :: Int -> Request a -> ShowS Source #

show :: Request a -> String Source #

showList :: [Request a] -> ShowS Source #

Eq (Request a) Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

(==) :: Request a -> Request a -> Bool Source #

(/=) :: Request a -> Request a -> Bool Source #

tipRequest :: Request 'Read Source #

tip: the chain tip.

addressUtxosRequest :: [Addr] -> Request 'Read Source #

address_utxos, extended, ordered by output reference.

assetUtxosRequest :: [(PolicyID, AssetName)] -> Request 'Read Source #

asset_utxos, extended, ordered by output reference.

assetTxsRequest :: PolicyID -> AssetName -> Request 'Read Source #

asset_txs with history: every transaction that included the asset. Koios lists them newest first; pages are read by block height then transaction id only so that pages are stable. That order is not the order in which the asset was passed on: Koios gives no index within a block, and a transaction that included the asset need not have spent it.

txInfoRequest :: [TxId] -> Request 'Read Source #

tx_info with inputs, assets, scripts and bytecode. Without _assets Koios answers every asset list empty.

txCborRequest :: [TxId] -> Request 'Read Source #

tx_cbor: the raw transactions.

epochParamsRequest :: EpochNo -> Request 'Read Source #

epoch_params of one epoch.

cliProtocolParamsRequest :: Request 'Read Source #

cli_protocol_params: the current protocol parameters in the node's own JSON form.

submitTxRequest :: ByteString -> Request 'Submission Source #

submittx: submit a signed transaction's CBOR.

txStatusRequest :: [TxId] -> Request 'Read Source #

tx_status: confirmations of transactions.

accountInfoRequest :: AccountAddress -> Request 'Read Source #

account_info of one stake address.

referenceScriptUtxosRequest :: [ScriptHash] -> Request 'Read Source #

reference_script_utxos: every unspent output whose reference script is one of the hashes, ordered by output reference. Koios names each row's hash; a consumer computes it from the output instead.

utxoInfoRequest :: [TxIn] -> Request 'Read Source #

utxo_info: whether each named output is spent.

assetInfoRequest :: (PolicyID, AssetName) -> Request 'Read Source #

asset_info of one asset: its latest minting transaction and supply.

Decoded facts

data Tip Source #

The chain tip.

Constructors

Tip 

Fields

Instances

Instances details
Show Tip Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

showsPrec :: Int -> Tip -> ShowS Source #

show :: Tip -> String Source #

showList :: [Tip] -> ShowS Source #

Eq Tip Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

(==) :: Tip -> Tip -> Bool Source #

(/=) :: Tip -> Tip -> Bool Source #

data AssetTx Source #

One transaction that included an asset.

Constructors

AssetTx 

Fields

Instances

Instances details
Show AssetTx Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

showsPrec :: Int -> AssetTx -> ShowS Source #

show :: AssetTx -> String Source #

showList :: [AssetTx] -> ShowS Source #

Eq AssetTx Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

(==) :: AssetTx -> AssetTx -> Bool Source #

(/=) :: AssetTx -> AssetTx -> Bool Source #

data TxInfo Source #

One transaction's resolved outputs: the outputs it spent, the outputs it referenced and the outputs it created, each with its output reference, and whether it is valid.

Constructors

TxInfo 

Fields

Instances

Instances details
Show TxInfo Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

showsPrec :: Int -> TxInfo -> ShowS Source #

show :: TxInfo -> String Source #

showList :: [TxInfo] -> ShowS Source #

Eq TxInfo Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

(==) :: TxInfo -> TxInfo -> Bool Source #

(/=) :: TxInfo -> TxInfo -> Bool Source #

data TxCbor Source #

One transaction's raw bytes, decoded as a Conway transaction whose id is the one Koios named.

Constructors

TxCbor 

Fields

Instances

Instances details
Show TxCbor Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

showsPrec :: Int -> TxCbor -> ShowS Source #

show :: TxCbor -> String Source #

showList :: [TxCbor] -> ShowS Source #

Eq TxCbor Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

(==) :: TxCbor -> TxCbor -> Bool Source #

(/=) :: TxCbor -> TxCbor -> Bool Source #

data TxStatus Source #

One transaction's confirmations, or Nothing when not yet seen.

Constructors

TxStatus 

Fields

Instances

Instances details
Show TxStatus Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

showsPrec :: Int -> TxStatus -> ShowS Source #

show :: TxStatus -> String Source #

showList :: [TxStatus] -> ShowS Source #

Eq TxStatus Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

(==) :: TxStatus -> TxStatus -> Bool Source #

(/=) :: TxStatus -> TxStatus -> Bool Source #

data AccountStatus Source #

One stake address's registration status, as Koios states it.

Constructors

AccountStatus 

Fields

Instances

Instances details
Show AccountStatus Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

showsPrec :: Int -> AccountStatus -> ShowS Source #

show :: AccountStatus -> String Source #

showList :: [AccountStatus] -> ShowS Source #

Eq AccountStatus Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

(==) :: AccountStatus -> AccountStatus -> Bool Source #

(/=) :: AccountStatus -> AccountStatus -> Bool Source #

data UtxoInfo Source #

One named output and whether Koios reports it spent.

Constructors

UtxoInfo 

Fields

Instances

Instances details
Show UtxoInfo Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

showsPrec :: Int -> UtxoInfo -> ShowS Source #

show :: UtxoInfo -> String Source #

showList :: [UtxoInfo] -> ShowS Source #

Eq UtxoInfo Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

(==) :: UtxoInfo -> UtxoInfo -> Bool Source #

(/=) :: UtxoInfo -> UtxoInfo -> Bool Source #

data AssetInfo Source #

One asset's latest minting transaction and its current total supply, as asset_info states them.

Constructors

AssetInfo 

Fields

Instances

Instances details
Show AssetInfo Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

showsPrec :: Int -> AssetInfo -> ShowS Source #

show :: AssetInfo -> String Source #

showList :: [AssetInfo] -> ShowS Source #

Eq AssetInfo Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

(==) :: AssetInfo -> AssetInfo -> Bool Source #

(/=) :: AssetInfo -> AssetInfo -> Bool Source #

Decoders

data DecodeFailure Source #

An answer that does not decode, with the position that failed.

Constructors

DecodeFailure 

Fields

Instances

Instances details
Show DecodeFailure Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

showsPrec :: Int -> DecodeFailure -> ShowS Source #

show :: DecodeFailure -> String Source #

showList :: [DecodeFailure] -> ShowS Source #

Eq DecodeFailure Source # 
Instance details

Defined in Singular.Provider.Koios.Wire

Methods

(==) :: DecodeFailure -> DecodeFailure -> Bool Source #

(/=) :: DecodeFailure -> DecodeFailure -> Bool Source #

parseBody :: ByteString -> Either DecodeFailure Value Source #

Parse an answer body as one JSON document. A body that is not one, such as a body cut off mid-array, fails with the parser's reason.

decodeTip :: Value -> Either DecodeFailure [Tip] Source #

Decode a tip answer: empty when Koios returned no row. Koios API 1.4.2, cardano-community/koios-artifacts revision 2e2eb57933e1e2528de5ca36ee961759841cf389, specsresultskoiosapi-preprod.yaml: #componentsschemastipitemspropertiesblock_time refers to #componentsschemasblocksitemspropertiesblock_time, UNIX seconds. Missing, fractional, negative or overflowing raw seconds refuse by name.

decodeUtxos :: Value -> Either DecodeFailure [(TxIn, TxOut ConwayEra)] Source #

Decode the rows of an address_utxos or asset_utxos page.

decodeAssetTxs :: Value -> Either DecodeFailure [AssetTx] Source #

Decode the rows of an asset_txs page.

decodeTxInfos :: Value -> Either DecodeFailure [TxInfo] Source #

Decode a tx_info answer. The same pinned schema's #componentsschemastx_infoitemspropertiesblock_height refers to #componentsschemasblocksitemspropertiesblock_height, a block height.

decodeTxCbors :: Value -> Either DecodeFailure [TxCbor] Source #

Decode a tx_cbor answer, each transaction checked against its id.

decodeEpochParams :: Value -> Either DecodeFailure [PParams ConwayEra] Source #

Decode an epoch_params answer: empty when Koios returned no row.

decodeCliProtocolParams :: Value -> Either DecodeFailure (PParams ConwayEra) Source #

Decode a cli_protocol_params answer with the ledger's own reader.

decodeSubmitted :: ByteString -> Either DecodeFailure TxId Source #

Decode the transaction id a submittx accepted: a JSON string, or the bare hex text.

decodeTxStatuses :: Value -> Either DecodeFailure [TxStatus] Source #

Decode a tx_status answer.

decodeAccountStatuses :: Value -> Either DecodeFailure [AccountStatus] Source #

Decode an account_info answer.

decodeReferenceScriptUtxos :: Value -> Either DecodeFailure [(ScriptHash, TxIn)] Source #

Decode a reference_script_utxos page: each row's hash and reference.

decodeUtxoInfos :: Value -> Either DecodeFailure [UtxoInfo] Source #

Decode a utxo_info answer.

decodeAssetInfos :: Value -> Either DecodeFailure [AssetInfo] Source #

Decode an asset_info answer.

Renderings

renderAddress :: Addr -> Text Source #

The bech32 rendering of a Shelley address.

parseAddress :: Text -> Either Text Addr Source #

Parse a bech32 address.

renderRewardAccount :: AccountAddress -> Text Source #

The bech32 stake address of a reward account.

parseRewardAccount :: Text -> Either Text AccountAddress Source #

Parse a bech32 stake address.

txIdHex :: TxId -> Text Source #

Hex of a transaction id.

policyHex :: PolicyID -> Text Source #

Hex of a policy id.

assetNameHex :: AssetName -> Text Source #

Hex of an asset name.