| License | Apache-2.0 |
|---|---|
| Safe Haskell | None |
| Language | GHC2021 |
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
- data Call
- callName :: Call -> Text
- data Access
- = Read
- | Submission
- data Method
- data Body
- data Request (a :: Access) = Request {
- requestCall :: Call
- requestMethod :: Method
- requestPath :: Text
- requestQuery :: [(Text, Text)]
- requestBody :: Body
- requestOrder :: Maybe Text
- tipRequest :: Request 'Read
- addressUtxosRequest :: [Addr] -> Request 'Read
- assetUtxosRequest :: [(PolicyID, AssetName)] -> Request 'Read
- assetTxsRequest :: PolicyID -> AssetName -> Request 'Read
- txInfoRequest :: [TxId] -> Request 'Read
- txCborRequest :: [TxId] -> Request 'Read
- epochParamsRequest :: EpochNo -> Request 'Read
- cliProtocolParamsRequest :: Request 'Read
- submitTxRequest :: ByteString -> Request 'Submission
- txStatusRequest :: [TxId] -> Request 'Read
- accountInfoRequest :: AccountAddress -> Request 'Read
- referenceScriptUtxosRequest :: [ScriptHash] -> Request 'Read
- utxoInfoRequest :: [TxIn] -> Request 'Read
- assetInfoRequest :: (PolicyID, AssetName) -> Request 'Read
- data Tip = Tip {
- tipSlot :: SlotNo
- tipBlockHash :: ByteString
- tipBlockHeight :: Word64
- tipEpoch :: EpochNo
- tipBlockTime :: Word64
- data AssetTx = AssetTx {
- assetTxId :: TxId
- assetTxBlockHeight :: Word64
- assetTxEpoch :: EpochNo
- data TxInfo = TxInfo {
- txInfoId :: TxId
- txInfoBlockHeight :: Word64
- txInfoInputs :: [(TxIn, TxOut ConwayEra)]
- txInfoReferenceInputs :: [(TxIn, TxOut ConwayEra)]
- txInfoOutputs :: [(TxIn, TxOut ConwayEra)]
- txInfoValid :: Bool
- data TxCbor = TxCbor {
- txCborId :: TxId
- txCborBytes :: ByteString
- txCborTx :: ConwayTx
- txCborValid :: Bool
- data TxStatus = TxStatus {
- txStatusId :: TxId
- txStatusConfirmations :: Maybe Word64
- data AccountStatus = AccountStatus {
- accountStakeAddress :: Text
- accountStatus :: Text
- data UtxoInfo = UtxoInfo {
- utxoInfoReference :: TxIn
- utxoInfoSpent :: Bool
- data AssetInfo = AssetInfo {
- assetInfoMintingTx :: TxId
- assetInfoSupply :: Integer
- data DecodeFailure = DecodeFailure {
- decodePosition :: Text
- decodeReason :: Text
- parseBody :: ByteString -> Either DecodeFailure Value
- decodeTip :: Value -> Either DecodeFailure [Tip]
- decodeUtxos :: Value -> Either DecodeFailure [(TxIn, TxOut ConwayEra)]
- decodeAssetTxs :: Value -> Either DecodeFailure [AssetTx]
- decodeTxInfos :: Value -> Either DecodeFailure [TxInfo]
- decodeTxCbors :: Value -> Either DecodeFailure [TxCbor]
- decodeEpochParams :: Value -> Either DecodeFailure [PParams ConwayEra]
- decodeCliProtocolParams :: Value -> Either DecodeFailure (PParams ConwayEra)
- decodeSubmitted :: ByteString -> Either DecodeFailure TxId
- decodeTxStatuses :: Value -> Either DecodeFailure [TxStatus]
- decodeAccountStatuses :: Value -> Either DecodeFailure [AccountStatus]
- decodeReferenceScriptUtxos :: Value -> Either DecodeFailure [(ScriptHash, TxIn)]
- decodeUtxoInfos :: Value -> Either DecodeFailure [UtxoInfo]
- decodeAssetInfos :: Value -> Either DecodeFailure [AssetInfo]
- renderAddress :: Addr -> Text
- parseAddress :: Text -> Either Text Addr
- renderRewardAccount :: AccountAddress -> Text
- parseRewardAccount :: Text -> Either Text AccountAddress
- txIdHex :: TxId -> Text
- policyHex :: PolicyID -> Text
- assetNameHex :: AssetName -> Text
Calls
The Koios calls this client makes.
Constructors
Instances
| Bounded Call Source # | |
Defined in Singular.Provider.Koios.Wire | |
| Enum Call Source # | |
| Show Call Source # | |
Defined in Singular.Provider.Koios.Wire | |
| Eq Call Source # | |
Defined in Singular.Provider.Koios.Wire | |
| Ord Call Source # | |
Defined in Singular.Provider.Koios.Wire | |
Requests
HTTP method of a request.
Instances
| Show Method Source # | |
Defined in Singular.Provider.Koios.Wire | |
| Eq Method Source # | |
Defined in Singular.Provider.Koios.Wire | |
| Ord Method Source # | |
Request body.
Constructors
| NoBody | |
| JsonBody Value | A JSON document |
| CborBody ByteString | Raw CBOR bytes, as |
Instances
| Show Body Source # | |
Defined in Singular.Provider.Koios.Wire | |
| Eq Body Source # | |
Defined in Singular.Provider.Koios.Wire | |
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
| Show (Request a) Source # | |
Defined in Singular.Provider.Koios.Wire | |
| Eq (Request a) Source # | |
Defined in Singular.Provider.Koios.Wire | |
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
The chain tip.
Constructors
| Tip | |
Fields
| |
Instances
| Show Tip Source # | |
Defined in Singular.Provider.Koios.Wire | |
| Eq Tip Source # | |
Defined in Singular.Provider.Koios.Wire | |
One transaction that included an asset.
Constructors
| AssetTx | |
Fields
| |
Instances
| Show AssetTx Source # | |
Defined in Singular.Provider.Koios.Wire | |
| Eq AssetTx Source # | |
Defined in Singular.Provider.Koios.Wire | |
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
| Show TxInfo Source # | |
Defined in Singular.Provider.Koios.Wire | |
| Eq TxInfo Source # | |
Defined in Singular.Provider.Koios.Wire | |
One transaction's raw bytes, decoded as a Conway transaction whose id is the one Koios named.
Constructors
| TxCbor | |
Fields
| |
Instances
| Show TxCbor Source # | |
Defined in Singular.Provider.Koios.Wire | |
| Eq TxCbor Source # | |
Defined in Singular.Provider.Koios.Wire | |
One transaction's confirmations, or Nothing when not yet seen.
Constructors
| TxStatus | |
Fields
| |
Instances
| Show TxStatus Source # | |
Defined in Singular.Provider.Koios.Wire | |
| Eq TxStatus Source # | |
Defined in Singular.Provider.Koios.Wire | |
data AccountStatus Source #
One stake address's registration status, as Koios states it.
Constructors
| AccountStatus | |
Fields
| |
Instances
| Show AccountStatus Source # | |
Defined in Singular.Provider.Koios.Wire Methods showsPrec :: Int -> AccountStatus -> ShowS Source # show :: AccountStatus -> String Source # showList :: [AccountStatus] -> ShowS Source # | |
| Eq AccountStatus Source # | |
Defined in Singular.Provider.Koios.Wire Methods (==) :: AccountStatus -> AccountStatus -> Bool Source # (/=) :: AccountStatus -> AccountStatus -> Bool Source # | |
One named output and whether Koios reports it spent.
Constructors
| UtxoInfo | |
Fields
| |
Instances
| Show UtxoInfo Source # | |
Defined in Singular.Provider.Koios.Wire | |
| Eq UtxoInfo Source # | |
Defined in Singular.Provider.Koios.Wire | |
One asset's latest minting transaction and its current total supply,
as asset_info states them.
Constructors
| AssetInfo | |
Fields
| |
Instances
| Show AssetInfo Source # | |
Defined in Singular.Provider.Koios.Wire | |
| Eq AssetInfo Source # | |
Defined in Singular.Provider.Koios.Wire | |
Decoders
data DecodeFailure Source #
An answer that does not decode, with the position that failed.
Constructors
| DecodeFailure | |
Fields
| |
Instances
| Show DecodeFailure Source # | |
Defined in Singular.Provider.Koios.Wire Methods showsPrec :: Int -> DecodeFailure -> ShowS Source # show :: DecodeFailure -> String Source # showList :: [DecodeFailure] -> ShowS Source # | |
| Eq DecodeFailure Source # | |
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.
assetNameHex :: AssetName -> Text Source #
Hex of an asset name.