| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Cardano.API
Contents
- Cryptographic key interface
- Payment addresses
- Byron addresses
- Shelley addresses
- Stake addresses
- Building transactions
- Signing transactions
- Fee calculation
- Transaction metadata
- Registering stake address and delegating
- Registering stake pools
- Scripts
- Serialisation
- Errors
- Node interaction
- Node operation
- Genesis file
- Special transactions
Description
This module provides a library interface for interacting with Cardano as a user of the system.
It is intended to be the complete API covering everything but without exposing constructors that reveal any lower level types.
In the interest of simplicity it glosses over some details of the system. Most simple tools should be able to work just using this interface, however you can go deeper and expose the types from the underlying libraries using Cardano.Api.Byron or Cardano.Api.Shelley.
Synopsis
- class HasTypeProxy t where
- data AsType t
- proxyToAsType :: Proxy t -> AsType t
- class (Eq (VerificationKey keyrole), Show (VerificationKey keyrole), SerialiseAsRawBytes (Hash keyrole), HasTextEnvelope (VerificationKey keyrole), HasTextEnvelope (SigningKey keyrole)) => Key keyrole
- getVerificationKey :: Key keyrole => SigningKey keyrole -> VerificationKey keyrole
- verificationKeyHash :: Key keyrole => VerificationKey keyrole -> Hash keyrole
- castVerificationKey :: CastVerificationKeyRole keyroleA keyroleB => VerificationKey keyroleA -> VerificationKey keyroleB
- castSigningKey :: CastSigningKeyRole keyroleA keyroleB => SigningKey keyroleA -> SigningKey keyroleB
- generateSigningKey :: Key keyrole => AsType keyrole -> IO (SigningKey keyrole)
- deterministicSigningKey :: Key keyrole => AsType keyrole -> Seed -> SigningKey keyrole
- deterministicSigningKeySeedSize :: Key keyrole => AsType keyrole -> Word
- data family Hash keyrole :: Type
- castHash :: CastHash keyroleA keyroleB => Hash keyroleA -> Hash keyroleB
- data Address era
- data NetworkId
- makeByronAddress :: NetworkId -> VerificationKey ByronKey -> Address era
- data ByronKey
- makeShelleyAddress :: NetworkId -> PaymentCredential -> StakeAddressReference -> Address Shelley
- data PaymentCredential
- data StakeAddressReference
- data PaymentKey
- data PaymentExtendedKey
- data StakeAddress
- data StakeCredential
- makeStakeAddress :: NetworkId -> StakeCredential -> StakeAddress
- data StakeKey
- data StakeExtendedKey
- data TxBody era
- data TxId
- getTxId :: TxBody era -> TxId
- data TxIn = TxIn TxId TxIx
- data TxOut era = TxOut (Address era) Lovelace
- newtype TxIx = TxIx Word
- type TTL = SlotNo
- type TxFee = Lovelace
- newtype Lovelace = Lovelace Integer
- makeByronTransaction :: [TxIn] -> [TxOut Byron] -> Either ByronTxBodyConversionError (TxBody Byron)
- makeShelleyTransaction :: TxExtraContent -> TTL -> TxFee -> [TxIn] -> [TxOut anyera] -> TxBody Shelley
- data SlotNo
- data TxExtraContent
- txExtraContentEmpty :: TxExtraContent
- data Certificate
- data Tx era
- getTxBody :: Tx era -> TxBody era
- getTxWitnesses :: Tx era -> [Witness era]
- signByronTransaction :: NetworkId -> TxBody Byron -> [SigningKey ByronKey] -> Tx Byron
- signShelleyTransaction :: TxBody Shelley -> [ShelleyWitnessSigningKey] -> Tx Shelley
- makeSignedTransaction :: [Witness era] -> TxBody era -> Tx era
- data Witness era
- makeByronKeyWitness :: NetworkId -> TxBody Byron -> SigningKey ByronKey -> Witness Byron
- data ShelleyWitnessSigningKey
- makeShelleyKeyWitness :: TxBody Shelley -> ShelleyWitnessSigningKey -> Witness Shelley
- makeShelleyBootstrapWitness :: WitnessNetworkIdOrByronAddress -> TxBody Shelley -> SigningKey ByronKey -> Witness Shelley
- makeShelleyScriptWitness :: Script -> Witness Shelley
- transactionFee :: Natural -> Natural -> Tx Shelley -> Lovelace
- estimateTransactionFee :: NetworkId -> Natural -> Natural -> Tx Shelley -> Int -> Int -> Int -> Int -> Lovelace
- data TxMetadata where
- pattern TxMetadata :: Map Word64 TxMetadataValue -> TxMetadata
- data TxMetadataValue
- makeTransactionMetadata :: Map Word64 TxMetadataValue -> TxMetadata
- makeStakeAddressRegistrationCertificate :: StakeCredential -> Certificate
- makeStakeAddressDeregistrationCertificate :: StakeCredential -> Certificate
- makeStakeAddressDelegationCertificate :: StakeCredential -> PoolId -> Certificate
- makeStakePoolRegistrationCertificate :: StakePoolParameters -> Certificate
- makeStakePoolRetirementCertificate :: PoolId -> EpochNo -> Certificate
- data StakePoolParameters
- data StakePoolRelay
- data StakePoolMetadataReference
- data StakePoolMetadata
- validateAndHashStakePoolMetadata :: ByteString -> Either StakePoolMetadataValidationError (StakePoolMetadata, Hash StakePoolMetadata)
- data StakePoolMetadataValidationError
- data Script
- scriptHash :: Script -> Hash Script
- data MultiSigScript
- makeMultiSigScript :: MultiSigScript -> Script
- class HasTypeProxy a => SerialiseAsCBOR a
- class Typeable a => ToCBOR a
- class Typeable a => FromCBOR a
- serialiseToCBOR :: SerialiseAsCBOR a => a -> ByteString
- deserialiseFromCBOR :: SerialiseAsCBOR a => AsType a -> ByteString -> Either DecoderError a
- class ToJSON a
- class FromJSON a
- serialiseToJSON :: ToJSON a => a -> ByteString
- deserialiseFromJSON :: FromJSON a => AsType a -> ByteString -> Either JsonDecodeError a
- class (HasTypeProxy a, SerialiseAsRawBytes a) => SerialiseAsBech32 a
- serialiseToBech32 :: SerialiseAsBech32 a => a -> Text
- deserialiseFromBech32 :: SerialiseAsBech32 a => AsType a -> Text -> Either Bech32DecodeError a
- deserialiseAnyOfFromBech32 :: forall b. [FromSomeType SerialiseAsBech32 b] -> Text -> Either Bech32DecodeError b
- data Bech32DecodeError
- class HasTypeProxy addr => SerialiseAddress addr
- serialiseAddress :: SerialiseAddress addr => addr -> Text
- deserialiseAddress :: SerialiseAddress addr => AsType addr -> Text -> Maybe addr
- class HasTypeProxy a => SerialiseAsRawBytes a
- serialiseToRawBytes :: SerialiseAsRawBytes a => a -> ByteString
- deserialiseFromRawBytes :: SerialiseAsRawBytes a => AsType a -> ByteString -> Maybe a
- serialiseToRawBytesHex :: SerialiseAsRawBytes a => a -> ByteString
- deserialiseFromRawBytesHex :: SerialiseAsRawBytes a => AsType a -> ByteString -> Maybe a
- class SerialiseAsCBOR a => HasTextEnvelope a
- type TextEnvelope = TextView
- type TextEnvelopeType = TextViewType
- type TextEnvelopeDescr = TextViewDescription
- type TextEnvelopeError = TextViewError
- serialiseToTextEnvelope :: forall a. HasTextEnvelope a => Maybe TextEnvelopeDescr -> a -> TextEnvelope
- deserialiseFromTextEnvelope :: HasTextEnvelope a => AsType a -> TextEnvelope -> Either TextEnvelopeError a
- readFileTextEnvelope :: HasTextEnvelope a => AsType a -> FilePath -> IO (Either (FileError TextEnvelopeError) a)
- writeFileTextEnvelope :: HasTextEnvelope a => FilePath -> Maybe TextEnvelopeDescr -> a -> IO (Either (FileError ()) ())
- readTextEnvelopeFromFile :: FilePath -> IO (Either (FileError TextEnvelopeError) TextEnvelope)
- readTextEnvelopeOfTypeFromFile :: TextEnvelopeType -> FilePath -> IO (Either (FileError TextEnvelopeError) TextEnvelope)
- data FromSomeType (c :: Type -> Constraint) b
- deserialiseFromTextEnvelopeAnyOf :: [FromSomeType HasTextEnvelope b] -> TextEnvelope -> Either TextEnvelopeError b
- readFileTextEnvelopeAnyOf :: [FromSomeType HasTextEnvelope b] -> FilePath -> IO (Either (FileError TextEnvelopeError) b)
- class Show e => Error e
- throwErrorAsException :: Error e => e -> IO a
- data FileError e
- connectToLocalNode :: forall mode block. (ShowProxy block, ShowProxy (ApplyTxErr block), ShowProxy (Query block), ShowProxy (GenTx block), ShowQuery (Query block)) => LocalNodeConnectInfo mode block -> LocalNodeClientProtocols block -> IO ()
- data LocalNodeConnectInfo mode block
- localNodeSocketPath :: LocalNodeConnectInfo mode block -> FilePath
- localNodeNetworkId :: LocalNodeConnectInfo mode block -> NetworkId
- localNodeConsensusMode :: LocalNodeConnectInfo mode block -> NodeConsensusMode mode block
- data NodeConsensusMode mode block
- data LocalNodeClientProtocols block
- localChainSyncClient :: LocalNodeClientProtocols block -> Maybe (ChainSyncClient block (Point block) (Tip block) IO ())
- localTxSubmissionClient :: LocalNodeClientProtocols block -> Maybe (LocalTxSubmissionClient (GenTx block) (ApplyTxErr block) IO ())
- localStateQueryClient :: LocalNodeClientProtocols block -> Maybe (LocalStateQueryClient block (Point block) (Query block) IO ())
- nullLocalNodeClientProtocols :: LocalNodeClientProtocols block
- data ChainSyncClient header point tip (m :: Type -> Type) a
- runChainSyncClient :: ChainSyncClient header point tip m a -> m (ClientStIdle header point tip m a)
- data LocalTxSubmissionClient tx reject (m :: Type -> Type) a
- runLocalTxSubmissionClient :: LocalTxSubmissionClient tx reject m a -> m (LocalTxClientStIdle tx reject m a)
- submitTxToNodeLocal :: forall mode block. (ShowProxy block, ShowProxy (ApplyTxErr block), ShowProxy (Query block), ShowProxy (GenTx block), ShowQuery (Query block)) => LocalNodeConnectInfo mode block -> GenTx block -> IO (SubmitResult (ApplyTxErr block))
- data LocalStateQueryClient block point (query :: Type -> Type) (m :: Type -> Type) a
- runLocalStateQueryClient :: LocalStateQueryClient block point query m a -> m (ClientStIdle block point query m a)
- queryNodeLocalState :: forall mode block result. (ShowProxy block, ShowProxy (ApplyTxErr block), ShowProxy (Query block), ShowProxy (GenTx block), ShowQuery (Query block)) => LocalNodeConnectInfo mode block -> (Point block, Query block result) -> IO (Either AcquireFailure result)
- data OperationalCertificate
- data OperationalCertificateIssueCounter
- data OperationalCertIssueError
- issueOperationalCertificate :: VerificationKey KesKey -> Either (SigningKey StakePoolKey) (SigningKey GenesisDelegateExtendedKey) -> KESPeriod -> OperationalCertificateIssueCounter -> Either OperationalCertIssueError (OperationalCertificate, OperationalCertificateIssueCounter)
- data GenesisKey
- data GenesisExtendedKey
- data GenesisDelegateKey
- data GenesisDelegateExtendedKey
- data GenesisUTxOKey
- genesisUTxOPseudoTxIn :: NetworkId -> Hash GenesisUTxOKey -> TxIn
- makeMIRCertificate :: MIRPot -> [(StakeCredential, Lovelace)] -> Certificate
- makeGenesisKeyDelegationCertificate :: Hash GenesisKey -> Hash GenesisDelegateKey -> Hash VrfKey -> Certificate
- data NetworkMagic
- makeShelleyUpdateProposal :: ProtocolParametersUpdate -> [Hash GenesisKey] -> EpochNo -> UpdateProposal
Documentation
class HasTypeProxy t where Source #
Associated Types
A family of singleton types used in this API to indicate which type to use where it would otherwise be ambiguous or merely unclear.
Values of this type are passed to
Methods
proxyToAsType :: Proxy t -> AsType t Source #
Instances
Cryptographic key interface
class (Eq (VerificationKey keyrole), Show (VerificationKey keyrole), SerialiseAsRawBytes (Hash keyrole), HasTextEnvelope (VerificationKey keyrole), HasTextEnvelope (SigningKey keyrole)) => Key keyrole Source #
An interface for cryptographic keys used for signatures with a SigningKey
and a VerificationKey key.
This interface does not provide actual signing or verifying functions since this API is concerned with the management of keys: generating and serialising.
Minimal complete definition
getVerificationKey, deterministicSigningKey, deterministicSigningKeySeedSize, verificationKeyHash
Instances
getVerificationKey :: Key keyrole => SigningKey keyrole -> VerificationKey keyrole Source #
Get the corresponding verification key from a signing key.
verificationKeyHash :: Key keyrole => VerificationKey keyrole -> Hash keyrole Source #
castVerificationKey :: CastVerificationKeyRole keyroleA keyroleB => VerificationKey keyroleA -> VerificationKey keyroleB Source #
Change the role of a VerificationKey, if the representation permits.
castSigningKey :: CastSigningKeyRole keyroleA keyroleB => SigningKey keyroleA -> SigningKey keyroleB Source #
Change the role of a SigningKey, if the representation permits.
Generating keys
generateSigningKey :: Key keyrole => AsType keyrole -> IO (SigningKey keyrole) Source #
Generate a SigningKey using a seed from operating system entropy.
deterministicSigningKey :: Key keyrole => AsType keyrole -> Seed -> SigningKey keyrole Source #
Generate a SigningKey deterministically, given a Seed. The
required size of the seed is given by deterministicSigningKeySeedSize.
Hashes
In Cardano most keys are identified by their hash, and hashes are used in many other places.
data family Hash keyrole :: Type Source #
Instances
Payment addresses
Constructing and inspecting normal payment addresses
Instances
Byron addresses
Byron-era payment keys. Used for Byron addresses and witnessing transactions that spend from these addresses.
These use Ed25519 but with a 32byte "chaincode" used in HD derivation.
The inclusion of the chaincode is a design mistake but one that cannot
be corrected for the Byron era. The Shelley era PaymentKeys do not include
a chaincode. It is safe to use a zero or random chaincode for new Byron keys.
This is a type level tag, used with other interfaces like Key.
Instances
Shelley addresses
makeShelleyAddress :: NetworkId -> PaymentCredential -> StakeAddressReference -> Address Shelley Source #
data PaymentCredential Source #
Instances
| Eq PaymentCredential Source # | |
Defined in Cardano.Api.Typed Methods (==) :: PaymentCredential -> PaymentCredential -> Bool # (/=) :: PaymentCredential -> PaymentCredential -> Bool # | |
| Show PaymentCredential Source # | |
Defined in Cardano.Api.Typed Methods showsPrec :: Int -> PaymentCredential -> ShowS # show :: PaymentCredential -> String # showList :: [PaymentCredential] -> ShowS # | |
data StakeAddressReference Source #
Instances
| Eq StakeAddressReference Source # | |
Defined in Cardano.Api.Typed Methods (==) :: StakeAddressReference -> StakeAddressReference -> Bool # (/=) :: StakeAddressReference -> StakeAddressReference -> Bool # | |
| Show StakeAddressReference Source # | |
Defined in Cardano.Api.Typed Methods showsPrec :: Int -> StakeAddressReference -> ShowS # show :: StakeAddressReference -> String # showList :: [StakeAddressReference] -> ShowS # | |
data PaymentKey Source #
Shelley-era payment keys. Used for Shelley payment addresses and witnessing transactions that spend from these addresses.
This is a type level tag, used with other interfaces like Key.
Instances
data PaymentExtendedKey Source #
Shelley-era payment keys using extended ed25519 cryptographic keys.
They can be used for Shelley payment addresses and witnessing transactions that spend from these addresses.
These extended keys are used by HD wallets. So this type provides interoperability with HD wallets. The ITN CLI also supported this key type.
The extended verification keys can be converted (via castVerificationKey)
to ordinary keys (i.e. VerificationKey PaymentKey) but this is not the
case for the signing keys. The signing keys can be used to witness
transactions directly, with verification via their non-extended verification
key (VerificationKey PaymentKey).
This is a type level tag, used with other interfaces like Key.
Instances
Stake addresses
Constructing and inspecting stake addresses
data StakeAddress Source #
Instances
data StakeCredential Source #
Instances
| Eq StakeCredential Source # | |
Defined in Cardano.Api.Typed Methods (==) :: StakeCredential -> StakeCredential -> Bool # (/=) :: StakeCredential -> StakeCredential -> Bool # | |
| Show StakeCredential Source # | |
Defined in Cardano.Api.Typed Methods showsPrec :: Int -> StakeCredential -> ShowS # show :: StakeCredential -> String # showList :: [StakeCredential] -> ShowS # | |
Instances
data StakeExtendedKey Source #
Shelley-era stake keys using extended ed25519 cryptographic keys.
They can be used for Shelley stake addresses and witnessing transactions that use stake addresses.
These extended keys are used by HD wallets. So this type provides interoperability with HD wallets. The ITN CLI also supported this key type.
The extended verification keys can be converted (via castVerificationKey)
to ordinary keys (i.e. VerificationKey StakeKey) but this is not the
case for the signing keys. The signing keys can be used to witness
transactions directly, with verification via their non-extended verification
key (VerificationKey StakeKey).
This is a type level tag, used with other interfaces like Key.
Instances
Building transactions
Constructing and inspecting transactions
Instances
Instances
| Eq TxId Source # | |
| Ord TxId Source # | |
| Show TxId Source # | |
| IsString TxId Source # | |
Defined in Cardano.Api.Typed Methods fromString :: String -> TxId # | |
| SerialiseAsRawBytes TxId Source # | |
Defined in Cardano.Api.Typed Methods serialiseToRawBytes :: TxId -> ByteString Source # deserialiseFromRawBytes :: AsType TxId -> ByteString -> Maybe TxId Source # | |
| HasTypeProxy TxId Source # | |
| data AsType TxId Source # | |
Defined in Cardano.Api.Typed | |
Instances
| Enum Lovelace Source # | |
Defined in Cardano.Api.Typed | |
| Eq Lovelace Source # | |
| Ord Lovelace Source # | |
Defined in Cardano.Api.Typed | |
| Show Lovelace Source # | |
makeByronTransaction :: [TxIn] -> [TxOut Byron] -> Either ByronTxBodyConversionError (TxBody Byron) Source #
makeShelleyTransaction :: TxExtraContent -> TTL -> TxFee -> [TxIn] -> [TxOut anyera] -> TxBody Shelley Source #
The 0-based index for the Ourboros time slot.
Instances
| Bounded SlotNo | |
| Enum SlotNo | |
Defined in Cardano.Slotting.Slot | |
| Eq SlotNo | |
| Num SlotNo | |
| Ord SlotNo | |
| Show SlotNo | |
| Generic SlotNo | |
| NFData SlotNo | |
Defined in Cardano.Slotting.Slot | |
| ToJSON SlotNo | |
| FromJSON SlotNo | |
| ToCBOR SlotNo | |
| FromCBOR SlotNo | |
| NoThunks SlotNo | |
| Serialise SlotNo | |
| Condense SlotNo | |
| HasField "ttl" (TxBody era) SlotNo | |
Defined in Shelley.Spec.Ledger.TxBody | |
| Embed (StakeCreds era) (Map (Credential 'Staking era) SlotNo) | |
Defined in Shelley.Spec.Ledger.TxBody Methods toBase :: StakeCreds era -> Map (Credential 'Staking era) SlotNo Source # fromBase :: Map (Credential 'Staking era) SlotNo -> StakeCreds era Source # | |
| HasExp (StakeCreds era) (Map (Credential 'Staking era) SlotNo) | |
Defined in Shelley.Spec.Ledger.TxBody Methods toExp :: StakeCreds era -> Exp (Map (Credential 'Staking era) SlotNo) Source # | |
| type Rep SlotNo | |
Defined in Cardano.Slotting.Slot | |
data TxExtraContent Source #
data Certificate Source #
Instances
Signing transactions
Creating transaction witnesses one by one, or all in one go.
Instances
getTxWitnesses :: Tx era -> [Witness era] Source #
Signing in one go
Incremental signing and separate witnesses
Instances
makeShelleyBootstrapWitness :: WitnessNetworkIdOrByronAddress -> TxBody Shelley -> SigningKey ByronKey -> Witness Shelley Source #
Fee calculation
For a concrete fully-constructed transaction, determine the minimum fee that it needs to pay.
This function is simple, but if you are doing input selection then you probably want to consider estimateTransactionFee.
estimateTransactionFee Source #
Arguments
| :: NetworkId | |
| -> Natural | The fixed tx fee |
| -> Natural | The tx fee per byte |
| -> Tx Shelley | |
| -> Int | The number of extra UTxO transaction inputs |
| -> Int | The number of extra transaction outputs |
| -> Int | The number of extra Shelley key witnesses |
| -> Int | The number of extra Byron key witnesses |
| -> Lovelace |
This can estimate what the transaction fee will be, based on a starting base transaction, plus the numbers of the additional components of the transaction that may be added.
So for example with wallet coin selection, the base transaction should contain all the things not subject to coin selection (such as script inputs, metadata, withdrawals, certs etc)
Transaction metadata
Embedding additional structured data within transactions.
data TxMetadata where Source #
Bundled Patterns
| pattern TxMetadata :: Map Word64 TxMetadataValue -> TxMetadata |
Instances
data TxMetadataValue Source #
Instances
| Eq TxMetadataValue Source # | |
Defined in Cardano.Api.Typed Methods (==) :: TxMetadataValue -> TxMetadataValue -> Bool # (/=) :: TxMetadataValue -> TxMetadataValue -> Bool # | |
| Ord TxMetadataValue Source # | |
Defined in Cardano.Api.Typed Methods compare :: TxMetadataValue -> TxMetadataValue -> Ordering # (<) :: TxMetadataValue -> TxMetadataValue -> Bool # (<=) :: TxMetadataValue -> TxMetadataValue -> Bool # (>) :: TxMetadataValue -> TxMetadataValue -> Bool # (>=) :: TxMetadataValue -> TxMetadataValue -> Bool # max :: TxMetadataValue -> TxMetadataValue -> TxMetadataValue # min :: TxMetadataValue -> TxMetadataValue -> TxMetadataValue # | |
| Show TxMetadataValue Source # | |
Defined in Cardano.Api.Typed Methods showsPrec :: Int -> TxMetadataValue -> ShowS # show :: TxMetadataValue -> String # showList :: [TxMetadataValue] -> ShowS # | |
Registering stake address and delegating
Certificates that are embedded in transactions for registering and unregistering stake address, and for setting the stake pool delegation choice for a stake address.
Registering stake pools
Certificates that are embedded in transactions for registering and retiring stake pools. This includes updating the stake pool parameters.
data StakePoolParameters Source #
Instances
| Eq StakePoolParameters Source # | |
Defined in Cardano.Api.Typed Methods (==) :: StakePoolParameters -> StakePoolParameters -> Bool # (/=) :: StakePoolParameters -> StakePoolParameters -> Bool # | |
| Show StakePoolParameters Source # | |
Defined in Cardano.Api.Typed Methods showsPrec :: Int -> StakePoolParameters -> ShowS # show :: StakePoolParameters -> String # showList :: [StakePoolParameters] -> ShowS # | |
data StakePoolRelay Source #
Instances
| Eq StakePoolRelay Source # | |
Defined in Cardano.Api.Typed Methods (==) :: StakePoolRelay -> StakePoolRelay -> Bool # (/=) :: StakePoolRelay -> StakePoolRelay -> Bool # | |
| Show StakePoolRelay Source # | |
Defined in Cardano.Api.Typed Methods showsPrec :: Int -> StakePoolRelay -> ShowS # show :: StakePoolRelay -> String # showList :: [StakePoolRelay] -> ShowS # | |
data StakePoolMetadataReference Source #
Instances
| Eq StakePoolMetadataReference Source # | |
Defined in Cardano.Api.Typed Methods (==) :: StakePoolMetadataReference -> StakePoolMetadataReference -> Bool # (/=) :: StakePoolMetadataReference -> StakePoolMetadataReference -> Bool # | |
| Show StakePoolMetadataReference Source # | |
Defined in Cardano.Api.Typed Methods showsPrec :: Int -> StakePoolMetadataReference -> ShowS # show :: StakePoolMetadataReference -> String # showList :: [StakePoolMetadataReference] -> ShowS # | |
Stake pool off-chain metadata
data StakePoolMetadata Source #
A representation of the required fields for off-chain stake pool metadata.
Instances
validateAndHashStakePoolMetadata :: ByteString -> Either StakePoolMetadataValidationError (StakePoolMetadata, Hash StakePoolMetadata) Source #
Decode and validate the provided JSON-encoded bytes as StakePoolMetadata.
Return the decoded metadata and the hash of the original bytes.
data StakePoolMetadataValidationError Source #
A stake pool metadata validation error.
Instances
| Show StakePoolMetadataValidationError Source # | |
Defined in Cardano.Api.Typed Methods showsPrec :: Int -> StakePoolMetadataValidationError -> ShowS # | |
| Error StakePoolMetadataValidationError Source # | |
Defined in Cardano.Api.Typed Methods displayError :: StakePoolMetadataValidationError -> String Source # | |
Scripts
Both PaymentCredentials and StakeCredentials can use scripts.
Shelley supports multi-signatures via scripts.
Instances
| Eq Script Source # | |
| Ord Script Source # | |
| Show Script Source # | |
| ToCBOR Script Source # | |
| HasTextEnvelope Script Source # | |
Defined in Cardano.Api.Typed Methods textEnvelopeType :: AsType Script -> TextEnvelopeType Source # textEnvelopeDefaultDescr :: Script -> TextEnvelopeDescr Source # | |
| SerialiseAsCBOR Script Source # | |
Defined in Cardano.Api.Typed Methods serialiseToCBOR :: Script -> ByteString Source # deserialiseFromCBOR :: AsType Script -> ByteString -> Either DecoderError Script Source # | |
| HasTypeProxy Script Source # | |
| Eq (Hash Script) Source # | |
| Ord (Hash Script) Source # | |
Defined in Cardano.Api.Typed | |
| Show (Hash Script) Source # | |
| SerialiseAsRawBytes (Hash Script) Source # | |
Defined in Cardano.Api.Typed Methods serialiseToRawBytes :: Hash Script -> ByteString Source # deserialiseFromRawBytes :: AsType (Hash Script) -> ByteString -> Maybe (Hash Script) Source # | |
| newtype Hash Script Source # | |
Defined in Cardano.Api.Typed | |
| data AsType Script Source # | |
Defined in Cardano.Api.Typed | |
Script addresses
Making addresses from scripts.
Multi-signature scripts
Making multi-signature scripts.
data MultiSigScript Source #
Instances
| Eq MultiSigScript Source # | |
Defined in Cardano.Api.Typed Methods (==) :: MultiSigScript -> MultiSigScript -> Bool # (/=) :: MultiSigScript -> MultiSigScript -> Bool # | |
| Show MultiSigScript Source # | |
Defined in Cardano.Api.Typed Methods showsPrec :: Int -> MultiSigScript -> ShowS # show :: MultiSigScript -> String # showList :: [MultiSigScript] -> ShowS # | |
| ToJSON MultiSigScript Source # | |
Defined in Cardano.Api.Typed Methods toJSON :: MultiSigScript -> Value Source # toEncoding :: MultiSigScript -> Encoding Source # toJSONList :: [MultiSigScript] -> Value Source # toEncodingList :: [MultiSigScript] -> Encoding Source # | |
| FromJSON MultiSigScript Source # | |
Defined in Cardano.Api.Typed Methods parseJSON :: Value -> Parser MultiSigScript Source # parseJSONList :: Value -> Parser [MultiSigScript] Source # | |
Serialisation
Support for serialising data in JSON, CBOR and text files.
CBOR
class HasTypeProxy a => SerialiseAsCBOR a Source #
Instances
class Typeable a => ToCBOR a Source #
Minimal complete definition
Instances
class Typeable a => FromCBOR a Source #
Minimal complete definition
Instances
serialiseToCBOR :: SerialiseAsCBOR a => a -> ByteString Source #
deserialiseFromCBOR :: SerialiseAsCBOR a => AsType a -> ByteString -> Either DecoderError a Source #
JSON
A type that can be converted to JSON.
Instances in general must specify toJSON and should (but don't need
to) specify toEncoding.
An example type and instance:
-- Allow ourselves to writeTextliterals. {-# LANGUAGE OverloadedStrings #-} data Coord = Coord { x :: Double, y :: Double } instanceToJSONCoord wheretoJSON(Coord x y) =object["x".=x, "y".=y]toEncoding(Coord x y) =pairs("x".=x<>"y".=y)
Instead of manually writing your ToJSON instance, there are two options
to do it automatically:
- Data.Aeson.TH provides Template Haskell functions which will derive an instance at compile time. The generated instance is optimized for your type so it will probably be more efficient than the following option.
- The compiler can provide a default generic implementation for
toJSON.
To use the second, simply add a deriving clause to your
datatype and declare a GenericToJSON instance. If you require nothing other than
defaultOptions, it is sufficient to write (and this is the only
alternative where the default toJSON implementation is sufficient):
{-# LANGUAGE DeriveGeneric #-}
import GHC.Generics
data Coord = Coord { x :: Double, y :: Double } deriving Generic
instance ToJSON Coord where
toEncoding = genericToEncoding defaultOptions
If on the other hand you wish to customize the generic decoding, you have to implement both methods:
customOptions =defaultOptions{fieldLabelModifier=maptoUpper} instanceToJSONCoord wheretoJSON=genericToJSONcustomOptionstoEncoding=genericToEncodingcustomOptions
Previous versions of this library only had the toJSON method. Adding
toEncoding had two reasons:
- toEncoding is more efficient for the common case that the output of
toJSONis directly serialized to aByteString. Further, expressing either method in terms of the other would be non-optimal. - The choice of defaults allows a smooth transition for existing users:
Existing instances that do not define
toEncodingstill compile and have the correct semantics. This is ensured by making the default implementation oftoEncodingusetoJSON. This produces correct results, but since it performs an intermediate conversion to aValue, it will be less efficient than directly emitting anEncoding. (this also means that specifying nothing more thaninstance ToJSON Coordwould be sufficient as a generically decoding instance, but there probably exists no good reason to not specifytoEncodingin new instances.)
Instances
A type that can be converted from JSON, with the possibility of failure.
In many cases, you can get the compiler to generate parsing code for you (see below). To begin, let's cover writing an instance by hand.
There are various reasons a conversion could fail. For example, an
Object could be missing a required key, an Array could be of
the wrong size, or a value could be of an incompatible type.
The basic ways to signal a failed conversion are as follows:
failyields a custom error message: it is the recommended way of reporting a failure;empty(ormzero) is uninformative: use it when the error is meant to be caught by some(;<|>)typeMismatchcan be used to report a failure when the encountered value is not of the expected JSON type;unexpectedis an appropriate alternative when more than one type may be expected, or to keep the expected type implicit.
prependFailure (or modifyFailure) add more information to a parser's
error messages.
An example type and instance using typeMismatch and prependFailure:
-- Allow ourselves to writeTextliterals. {-# LANGUAGE OverloadedStrings #-} data Coord = Coord { x :: Double, y :: Double } instanceFromJSONCoord whereparseJSON(Objectv) = Coord<$>v.:"x"<*>v.:"y" -- We do not expect a non-Objectvalue here. -- We could useemptyto fail, buttypeMismatch-- gives a much more informative error message.parseJSONinvalid =prependFailure"parsing Coord failed, " (typeMismatch"Object" invalid)
For this common case of only being concerned with a single
type of JSON value, the functions withObject, withScientific, etc.
are provided. Their use is to be preferred when possible, since
they are more terse. Using withObject, we can rewrite the above instance
(assuming the same language extension and data type) as:
instanceFromJSONCoord whereparseJSON=withObject"Coord" $ \v -> Coord<$>v.:"x"<*>v.:"y"
Instead of manually writing your FromJSON instance, there are two options
to do it automatically:
- Data.Aeson.TH provides Template Haskell functions which will derive an instance at compile time. The generated instance is optimized for your type so it will probably be more efficient than the following option.
- The compiler can provide a default generic implementation for
parseJSON.
To use the second, simply add a deriving clause to your
datatype and declare a GenericFromJSON instance for your datatype without giving
a definition for parseJSON.
For example, the previous example can be simplified to just:
{-# LANGUAGE DeriveGeneric #-}
import GHC.Generics
data Coord = Coord { x :: Double, y :: Double } deriving Generic
instance FromJSON Coord
The default implementation will be equivalent to
parseJSON = ; if you need different
options, you can customize the generic decoding by defining:genericParseJSON defaultOptions
customOptions =defaultOptions{fieldLabelModifier=maptoUpper} instanceFromJSONCoord whereparseJSON=genericParseJSONcustomOptions
Instances
serialiseToJSON :: ToJSON a => a -> ByteString Source #
deserialiseFromJSON :: FromJSON a => AsType a -> ByteString -> Either JsonDecodeError a Source #
Bech32
class (HasTypeProxy a, SerialiseAsRawBytes a) => SerialiseAsBech32 a Source #
Minimal complete definition
bech32PrefixFor, bech32PrefixesPermitted
Instances
serialiseToBech32 :: SerialiseAsBech32 a => a -> Text Source #
deserialiseFromBech32 :: SerialiseAsBech32 a => AsType a -> Text -> Either Bech32DecodeError a Source #
deserialiseAnyOfFromBech32 :: forall b. [FromSomeType SerialiseAsBech32 b] -> Text -> Either Bech32DecodeError b Source #
data Bech32DecodeError Source #
Bech32 decoding error.
Instances
| Eq Bech32DecodeError Source # | |
Defined in Cardano.Api.Typed Methods (==) :: Bech32DecodeError -> Bech32DecodeError -> Bool # (/=) :: Bech32DecodeError -> Bech32DecodeError -> Bool # | |
| Show Bech32DecodeError Source # | |
Defined in Cardano.Api.Typed Methods showsPrec :: Int -> Bech32DecodeError -> ShowS # show :: Bech32DecodeError -> String # showList :: [Bech32DecodeError] -> ShowS # | |
| Error Bech32DecodeError Source # | |
Defined in Cardano.Api.Typed Methods | |
Addresses
Address serialisation is (sadly) special
class HasTypeProxy addr => SerialiseAddress addr Source #
Address serialisation uses different serialisation formats for different kinds of addresses, so it needs its own class.
In particular, Byron addresses are typically formatted in base 58, while Shelley addresses (payment and stake) are formatted using Bech32.
Minimal complete definition
Instances
| SerialiseAddress StakeAddress Source # | |
Defined in Cardano.Api.Typed Methods serialiseAddress :: StakeAddress -> Text Source # deserialiseAddress :: AsType StakeAddress -> Text -> Maybe StakeAddress Source # | |
| SerialiseAddress (Address Shelley) Source # | |
| SerialiseAddress (Address Byron) Source # | |
serialiseAddress :: SerialiseAddress addr => addr -> Text Source #
deserialiseAddress :: SerialiseAddress addr => AsType addr -> Text -> Maybe addr Source #
Raw binary
Some types have a natural raw binary format.
class HasTypeProxy a => SerialiseAsRawBytes a Source #
Minimal complete definition
Instances
serialiseToRawBytes :: SerialiseAsRawBytes a => a -> ByteString Source #
deserialiseFromRawBytes :: SerialiseAsRawBytes a => AsType a -> ByteString -> Maybe a Source #
serialiseToRawBytesHex :: SerialiseAsRawBytes a => a -> ByteString Source #
deserialiseFromRawBytesHex :: SerialiseAsRawBytes a => AsType a -> ByteString -> Maybe a Source #
Text envelope
Support for a envelope file format with text headers and a hex-encoded binary payload.
class SerialiseAsCBOR a => HasTextEnvelope a Source #
Minimal complete definition
Instances
type TextEnvelope = TextView Source #
type TextEnvelopeType = TextViewType Source #
type TextEnvelopeError = TextViewError Source #
serialiseToTextEnvelope :: forall a. HasTextEnvelope a => Maybe TextEnvelopeDescr -> a -> TextEnvelope Source #
deserialiseFromTextEnvelope :: HasTextEnvelope a => AsType a -> TextEnvelope -> Either TextEnvelopeError a Source #
readFileTextEnvelope :: HasTextEnvelope a => AsType a -> FilePath -> IO (Either (FileError TextEnvelopeError) a) Source #
writeFileTextEnvelope :: HasTextEnvelope a => FilePath -> Maybe TextEnvelopeDescr -> a -> IO (Either (FileError ()) ()) Source #
readTextEnvelopeFromFile :: FilePath -> IO (Either (FileError TextEnvelopeError) TextEnvelope) Source #
readTextEnvelopeOfTypeFromFile :: TextEnvelopeType -> FilePath -> IO (Either (FileError TextEnvelopeError) TextEnvelope) Source #
Reading one of several key types
data FromSomeType (c :: Type -> Constraint) b Source #
deserialiseFromTextEnvelopeAnyOf :: [FromSomeType HasTextEnvelope b] -> TextEnvelope -> Either TextEnvelopeError b Source #
readFileTextEnvelopeAnyOf :: [FromSomeType HasTextEnvelope b] -> FilePath -> IO (Either (FileError TextEnvelopeError) b) Source #
Errors
class Show e => Error e Source #
Minimal complete definition
Instances
| Error () Source # | |
Defined in Cardano.Api.Typed Methods displayError :: () -> String Source # | |
| Error TextViewError Source # | |
Defined in Cardano.Api.Typed Methods displayError :: TextViewError -> String Source # | |
| Error Bech32DecodeError Source # | |
Defined in Cardano.Api.Typed Methods | |
| Error OperationalCertIssueError Source # | |
Defined in Cardano.Api.Typed Methods displayError :: OperationalCertIssueError -> String Source # | |
| Error StakePoolMetadataValidationError Source # | |
Defined in Cardano.Api.Typed Methods displayError :: StakePoolMetadataValidationError -> String Source # | |
| Error TxMetadataJsonSchemaError Source # | |
Defined in Cardano.Api.MetaData Methods displayError :: TxMetadataJsonSchemaError -> String Source # | |
| Error TxMetadataJsonError Source # | |
Defined in Cardano.Api.MetaData Methods | |
| Error TxMetadataRangeError Source # | |
Defined in Cardano.Api.MetaData Methods | |
| Error e => Error (FileError e) Source # | |
Defined in Cardano.Api.Typed Methods displayError :: FileError e -> String Source # | |
throwErrorAsException :: Error e => e -> IO a Source #
The preferred approach is to use Except or ExceptT, but you can if
necessary use IO exceptions.
Node interaction
Operations that involve talking to a local Cardano node.
Queries
Submitting transactions
Low level protocol interaction with a Cardano node
connectToLocalNode :: forall mode block. (ShowProxy block, ShowProxy (ApplyTxErr block), ShowProxy (Query block), ShowProxy (GenTx block), ShowQuery (Query block)) => LocalNodeConnectInfo mode block -> LocalNodeClientProtocols block -> IO () Source #
Establish a connection to a node and execute the given set of protocol handlers.
data LocalNodeConnectInfo mode block Source #
localNodeSocketPath :: LocalNodeConnectInfo mode block -> FilePath Source #
localNodeNetworkId :: LocalNodeConnectInfo mode block -> NetworkId Source #
localNodeConsensusMode :: LocalNodeConnectInfo mode block -> NodeConsensusMode mode block Source #
data NodeConsensusMode mode block Source #
data LocalNodeClientProtocols block Source #
localChainSyncClient :: LocalNodeClientProtocols block -> Maybe (ChainSyncClient block (Point block) (Tip block) IO ()) Source #
localTxSubmissionClient :: LocalNodeClientProtocols block -> Maybe (LocalTxSubmissionClient (GenTx block) (ApplyTxErr block) IO ()) Source #
localStateQueryClient :: LocalNodeClientProtocols block -> Maybe (LocalStateQueryClient block (Point block) (Query block) IO ()) Source #
Chain sync protocol
data ChainSyncClient header point tip (m :: Type -> Type) a #
runChainSyncClient :: ChainSyncClient header point tip m a -> m (ClientStIdle header point tip m a) #
Local tx submission
data LocalTxSubmissionClient tx reject (m :: Type -> Type) a #
runLocalTxSubmissionClient :: LocalTxSubmissionClient tx reject m a -> m (LocalTxClientStIdle tx reject m a) #
submitTxToNodeLocal :: forall mode block. (ShowProxy block, ShowProxy (ApplyTxErr block), ShowProxy (Query block), ShowProxy (GenTx block), ShowQuery (Query block)) => LocalNodeConnectInfo mode block -> GenTx block -> IO (SubmitResult (ApplyTxErr block)) Source #
Local state query
runLocalStateQueryClient :: LocalStateQueryClient block point query m a -> m (ClientStIdle block point query m a) #
queryNodeLocalState :: forall mode block result. (ShowProxy block, ShowProxy (ApplyTxErr block), ShowProxy (Query block), ShowProxy (GenTx block), ShowQuery (Query block)) => LocalNodeConnectInfo mode block -> (Point block, Query block result) -> IO (Either AcquireFailure result) Source #
Establish a connection to a node and execute a single query using the local state query protocol.
Node operation
Support for the steps needed to operate a node
Operational certificates
data OperationalCertificate Source #
Instances
data OperationalCertificateIssueCounter Source #
Instances
| Eq OperationalCertificateIssueCounter Source # | |
Defined in Cardano.Api.Typed | |
| Show OperationalCertificateIssueCounter Source # | |
Defined in Cardano.Api.Typed Methods showsPrec :: Int -> OperationalCertificateIssueCounter -> ShowS # | |
| ToCBOR OperationalCertificateIssueCounter Source # | |
Defined in Cardano.Api.Typed Methods toCBOR :: OperationalCertificateIssueCounter -> Encoding Source # encodedSizeExpr :: (forall t. ToCBOR t => Proxy t -> Size) -> Proxy OperationalCertificateIssueCounter -> Size Source # encodedListSizeExpr :: (forall t. ToCBOR t => Proxy t -> Size) -> Proxy [OperationalCertificateIssueCounter] -> Size Source # | |
| FromCBOR OperationalCertificateIssueCounter Source # | |
Defined in Cardano.Api.Typed | |
| HasTextEnvelope OperationalCertificateIssueCounter Source # | |
| SerialiseAsCBOR OperationalCertificateIssueCounter Source # | |
| HasTypeProxy OperationalCertificateIssueCounter Source # | |
Defined in Cardano.Api.Typed Associated Types | |
| data AsType OperationalCertificateIssueCounter Source # | |
data OperationalCertIssueError Source #
Instances
| Show OperationalCertIssueError Source # | |
Defined in Cardano.Api.Typed Methods showsPrec :: Int -> OperationalCertIssueError -> ShowS # show :: OperationalCertIssueError -> String # showList :: [OperationalCertIssueError] -> ShowS # | |
| Error OperationalCertIssueError Source # | |
Defined in Cardano.Api.Typed Methods displayError :: OperationalCertIssueError -> String Source # | |
issueOperationalCertificate :: VerificationKey KesKey -> Either (SigningKey StakePoolKey) (SigningKey GenesisDelegateExtendedKey) -> KESPeriod -> OperationalCertificateIssueCounter -> Either OperationalCertIssueError (OperationalCertificate, OperationalCertificateIssueCounter) Source #
Genesis file
Types and functions needed to inspect or create a genesis file.
data GenesisKey Source #
Instances
data GenesisExtendedKey Source #
Shelley-era genesis keys using extended ed25519 cryptographic keys.
These serve the same role as normal genesis keys, but are here to support legacy Byron genesis keys which used extended keys.
The extended verification keys can be converted (via castVerificationKey)
to ordinary keys (i.e. VerificationKey GenesisKey) but this is not the
case for the signing keys. The signing keys can be used to witness
transactions directly, with verification via their non-extended verification
key (VerificationKey GenesisKey).
This is a type level tag, used with other interfaces like Key.
Instances
data GenesisDelegateKey Source #
Instances
data GenesisDelegateExtendedKey Source #
Shelley-era genesis keys using extended ed25519 cryptographic keys.
These serve the same role as normal genesis keys, but are here to support legacy Byron genesis keys which used extended keys.
The extended verification keys can be converted (via castVerificationKey)
to ordinary keys (i.e. VerificationKey GenesisKey) but this is not the
case for the signing keys. The signing keys can be used to witness
transactions directly, with verification via their non-extended verification
key (VerificationKey GenesisKey).
This is a type level tag, used with other interfaces like Key.
Instances
data GenesisUTxOKey Source #
Instances
genesisUTxOPseudoTxIn :: NetworkId -> Hash GenesisUTxOKey -> TxIn Source #
Compute the TxIn of the initial UTxO pseudo-transaction corresponding
to the given address in the genesis initial funds.
The Shelley initial UTxO is constructed from the sgInitialFunds which
is not a full UTxO but just a map from addresses to coin values.
This gets turned into a UTxO by making a pseudo-transaction for each address,
with the 0th output being the coin value. So to spend from the initial UTxO
we need this same TxIn to use as an input to the spending transaction.
Special transactions
There are various additional things that can be embedded in a transaction for special operations.
makeMIRCertificate :: MIRPot -> [(StakeCredential, Lovelace)] -> Certificate Source #
makeGenesisKeyDelegationCertificate :: Hash GenesisKey -> Hash GenesisDelegateKey -> Hash VrfKey -> Certificate Source #
data NetworkMagic #
Instances
| Eq NetworkMagic | |
Defined in Ouroboros.Network.Magic | |
| Show NetworkMagic | |
Defined in Ouroboros.Network.Magic Methods showsPrec :: Int -> NetworkMagic -> ShowS # show :: NetworkMagic -> String # showList :: [NetworkMagic] -> ShowS # | |
| Generic NetworkMagic | |
Defined in Ouroboros.Network.Magic Associated Types type Rep NetworkMagic :: Type -> Type # | |
| NoThunks NetworkMagic | |
Defined in Ouroboros.Network.Magic | |
| type Rep NetworkMagic | |
Defined in Ouroboros.Network.Magic type Rep NetworkMagic = D1 ('MetaData "NetworkMagic" "Ouroboros.Network.Magic" "ouroboros-network-0.1.0.0-DgIBwCUrGXaLitNwqCfIcM" 'True) (C1 ('MetaCons "NetworkMagic" 'PrefixI 'True) (S1 ('MetaSel ('Just "unNetworkMagic") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word32))) | |