diff --git a/CHANGELOG.md b/CHANGELOG.md index c083e85..51a2257 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Revision history for `maestro-sdk` +## [1.7.0](https://github.com/maestro-org/haskell-sdk/compare/v1.5.0..v1.6.0) -- 2024-08-17 + +* Updated to newer `era-summaries` and `protocol-parameters` endpoint from earlier `era-history` and `protocol-params` respectively. +* `AssetInfo` type which corresponds to `/assets/:asset` is updated with more response fields. + ## [1.6.0](https://github.com/maestro-org/haskell-sdk/compare/v1.5.0..v1.6.0) -- 2024-04-09 Added: diff --git a/maestro-sdk.cabal b/maestro-sdk.cabal index 7de8f0c..7f3a3a1 100644 --- a/maestro-sdk.cabal +++ b/maestro-sdk.cabal @@ -1,27 +1,27 @@ -cabal-version: 3.0 -name: maestro-sdk -version: 1.6.0 -synopsis: Maestro Blockchain Indexer SDK +cabal-version: 3.0 +name: maestro-sdk +version: 1.7.0 +synopsis: Maestro Blockchain Indexer SDK description: Maestro provides blockchain indexers, APIs and event management systems for the Cardano blockchain. -license: Apache-2.0 -license-file: LICENSE -author: support@gomaestro.org -maintainer: support@gomaestro.org -copyright: (c) 2023 Maestro Blockchain Inc -build-type: Simple -category: Blockchain, Cardano, SDK, API, REST -extra-doc-files: CHANGELOG.md +license: Apache-2.0 +license-file: LICENSE +author: support@gomaestro.org +maintainer: support@gomaestro.org +copyright: (c) 2023 Maestro Blockchain Inc +build-type: Simple +category: Blockchain, Cardano, SDK, API, REST +extra-doc-files: CHANGELOG.md extra-source-files: README.md -tested-with: GHC ==8.10.7 || ==9.2.8 || ==9.6.2 +tested-with: ghc ==8.10.7 || ==9.2.8 || ==9.6.2 source-repository head - type: git + type: git location: https://github.com/maestro-org/haskell-sdk common common - ghc-options: -Wall + ghc-options: -Wall default-extensions: DataKinds DeriveGeneric @@ -44,7 +44,7 @@ common common TypeOperators library - import: common + import: common exposed-modules: Maestro.API.V1 Maestro.API.V1.Accounts @@ -88,41 +88,41 @@ library Maestro.Types.V1.Transactions build-depends: - , aeson ^>=2.1 - , base ^>=4.14.3.0 || ^>=4.16.4.0 || ^>=4.18.0.0 - , bytestring >=0.10 && <0.11 || ^>=0.11 - , containers ^>=0.6 - , data-default-class ^>=0.1 - , deriving-aeson ^>=0.2 - , http-api-data >=0.5 && <0.6 || ^>=0.6 - , http-client ^>=0.7 - , http-client-tls ^>=0.3 - , http-types ^>=0.12 - , retry ^>=0.9 - , servant >=0.19 && <0.20 || ^>=0.20 - , servant-client >=0.19 && <0.20 || ^>=0.20 - , servant-client-core >=0.19 && <0.20 || ^>=0.20 - , text ^>=1.2 || ^>=2.0 - , time ^>=1.9 || >=1.11 && <1.12 || ^>=1.12 + aeson >=2.1 && <2.3, + base >=4.9 && <5, + bytestring >=0.10 && <0.12, + containers ^>=0.6, + data-default-class ^>=0.1, + deriving-aeson ^>=0.2, + http-api-data >=0.5 && <0.7, + http-client ^>=0.7, + http-client-tls ^>=0.3, + http-types ^>=0.12, + retry ^>=0.9, + servant >=0.19 && <0.21, + servant-client >=0.19 && <0.21, + servant-client-core >=0.19 && <0.21, + text >=1.2 && <3.0, + time >=1.9 && <1.13, - hs-source-dirs: src + hs-source-dirs: src default-language: Haskell2010 test-suite maestro-sdk-tests - import: common - default-language: Haskell2010 - type: exitcode-stdio-1.0 - hs-source-dirs: test - main-is: Driver.hs - other-modules: Maestro.Test.Backoff + import: common + default-language: Haskell2010 + type: exitcode-stdio-1.0 + hs-source-dirs: test + main-is: Driver.hs + other-modules: Maestro.Test.Backoff build-depends: - , base ^>=4.14.3.0 || ^>=4.16.4.0 || ^>=4.18.0.0 - , containers ^>=0.6.5.1 - , hspec ^>=2.11.4 - , maestro-sdk - , tasty ^>=1.4.3 - , tasty-hspec ^>=1.2.0.4 - , text ^>=1.2.4.1 || ^>=2.0.2 - , time ^>=1.9.3 || ^>=1.11.1.1 || ^>=1.12.2 + base, + containers, + hspec >=2.11 && <2.12, + maestro-sdk, + tasty >=1.4 && <1.6, + tasty-hspec >=1.2 && <1.3, + text, + time, build-tool-depends: tasty-discover:tasty-discover diff --git a/src/Maestro/API/V1/General.hs b/src/Maestro/API/V1/General.hs index 3fdc570..d09af29 100644 --- a/src/Maestro/API/V1/General.hs +++ b/src/Maestro/API/V1/General.hs @@ -13,11 +13,11 @@ data GeneralAPI route = :> Get '[JSON] TimestampedSystemStart , eraHistory :: route - :- "era-history" + :- "era-summaries" :> Get '[JSON] TimestampedEraSummaries , protocolParams :: route - :- "protocol-params" + :- "protocol-parameters" :> Get '[JSON] TimestampedProtocolParameters , chainTip :: route diff --git a/src/Maestro/Types/V1/Assets.hs b/src/Maestro/Types/V1/Assets.hs index 42cc1ff..2699bee 100644 --- a/src/Maestro/Types/V1/Assets.hs +++ b/src/Maestro/Types/V1/Assets.hs @@ -5,6 +5,7 @@ module Maestro.Types.V1.Assets ( TimestampedAssetInfo (..), ) where +import Data.Aeson (Value) import Data.Text (Text) import Data.Word (Word64) import Deriving.Aeson @@ -28,9 +29,41 @@ data TokenRegistryMetadata = TokenRegistryMetadata deriving stock (Eq, Show, Generic) deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "tokenRegistryMetadata", CamelToSnake]] TokenRegistryMetadata +data Cip68AssetType = CIP68ATReferenceNft | CIP68ATUserNft | CIP68ATUserFt + deriving stock (Eq, Show, Generic, Enum, Bounded) + deriving (FromJSON, ToJSON) via CustomJSON '[ConstructorTagModifier '[StripPrefix "CIP68AT", CamelToSnake]] Cip68AssetType + +data Cip68Metadata = Cip68Metadata + { cip68MetadataExtra :: !(Maybe Text) + -- ^ Custom user defined Plutus data CBOR bytes. + , cip68MetadataMetadata :: !Value + -- ^ Asset CIP-68 metadata. + , cip68MetadataPurpose :: !Cip68AssetType + -- ^ Purpose. + , cip68MetadataVersion :: !Word64 + -- ^ CIP-68 version. + } + deriving stock (Eq, Show, Generic) + deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "cip68Metadata", CamelToSnake]] Cip68Metadata + +-- | Asset information corresponding to popular standards. +data AssetStandards = AssetStandards + { assetStandardsCip25Metadata :: !(Maybe Value) + -- ^ CIP-25 metadata for a specific asset. + , assetStandardsCip68Metadata :: !(Maybe Cip68Metadata) + } + deriving stock (Eq, Show, Generic) + deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "assetStandards", CamelToSnake]] AssetStandards + -- | Information about a specific Cardano native-asset. data AssetInfo = AssetInfo - { assetInfoTokenRegistryMetadata :: !(Maybe TokenRegistryMetadata) + { assetInfoAssetName :: !TokenName + -- ^ Hex encoding of the asset name. + , assetInfoAssetStandards :: !AssetStandards + -- ^ Asset information corresponding to popular standards. + , assetInfoLatestMintTxMetadata :: !(Maybe Value) + -- ^ Metadata of the most recent transaction which minted or burned the asset. + , assetInfoTokenRegistryMetadata :: !(Maybe TokenRegistryMetadata) -- ^ See `TokenRegistryMetadata`. } deriving stock (Eq, Show, Generic) diff --git a/src/Maestro/Types/V1/General.hs b/src/Maestro/Types/V1/General.hs index 81eb385..da10205 100644 --- a/src/Maestro/Types/V1/General.hs +++ b/src/Maestro/Types/V1/General.hs @@ -3,14 +3,19 @@ module Maestro.Types.V1.General ( -- * Types for @/system-start@ endpoint TimestampedSystemStart (..) - -- * Types for @/era-history@ endpoint + -- * Types for @/era-summaries@ endpoint , TimestampedEraSummaries (..) , EraSummary (..) , EraParameters (..) , EraBound (..) - -- * Types for @/protocol-params@ endpoint + , EraBoundTime (..) + , EpochSlotLength (..) + -- * Types for @/protocol-parameters@ endpoint + , AsAda (..) + , AsLovelace (..) + , AsBytes (..) , ProtocolVersion (..) - , MemoryStepsWith (..) + , MemoryCpuWith (..) , CostModel (..) , CostModels (..) , MaestroRational (..) @@ -26,7 +31,7 @@ module Maestro.Types.V1.General import Control.Monad (unless, when) import Data.Aeson (FromJSON (parseJSON), toEncoding, toJSON, withText) -import Data.Map.Strict (Map) +import Data.Int (Int64) import Data.Ratio (denominator, numerator, (%)) import Data.Text (Text) import qualified Data.Text as Txt @@ -59,7 +64,7 @@ instance IsTimestamped TimestampedSystemStart where getTimestamp = timestampedSystemStartLastUpdated ------------------------------------------------------------------ --- Types for @/era-history@ endpoint +-- Types for @/era-summaries@ endpoint ------------------------------------------------------------------ -- | Network era summaries. @@ -89,11 +94,16 @@ data EraSummary = EraSummary deriving stock (Eq, Show, Generic) deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "eraSummary", LowerFirst]] EraSummary +newtype EpochSlotLength = EpochSlotLength + { epochSlotLengthMilliseconds :: NominalDiffTime } + deriving stock (Eq, Show, Generic) + deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "epochSlotLength", LowerFirst]] EpochSlotLength + -- | Parameters for a network era which can vary between hardforks. data EraParameters = EraParameters { eraParametersEpochLength :: !EpochSize -- ^ Number of slots in an epoch. - , eraParametersSlotLength :: !NominalDiffTime + , eraParametersSlotLength :: !EpochSlotLength -- ^ How long a slot lasts. , eraParametersSafeZone :: !(Maybe Word64) -- ^ Number of slots from the tip of the ledger in which a hardfork will not happen. @@ -101,22 +111,53 @@ data EraParameters = EraParameters deriving stock (Eq, Show, Generic) deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "eraParameters", CamelToSnake]] EraParameters +newtype EraBoundTime = EraBoundTime + { eraBoundTimeSeconds :: NominalDiffTime + -- ^ Time relative to the start time of the network. + } + deriving stock (Eq, Show, Generic) + deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "eraBoundTime", LowerFirst]] EraBoundTime + -- | Bounds of an era. data EraBound = EraBound { eraBoundEpoch :: !EpochNo -- ^ Epoch number bounding this era. , eraBoundSlot :: !SlotNo -- ^ Absolute slot number bounding this era. - , eraBoundTime :: !NominalDiffTime + , eraBoundTime :: !EraBoundTime -- ^ Time relative to the start time of the network. } deriving stock (Eq, Show, Generic) deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "eraBound", LowerFirst]] EraBound ------------------------------------------------------------------ --- Types for @/protocol-params@ endpoint. +-- Types for @/protocol-parameters@ endpoint. ------------------------------------------------------------------ +-- | Lovelaces. +newtype AsLovelace = AsLovelace + { asLovelaceLovelace :: Natural + -- ^ Lovelaces. + } + deriving stock (Eq, Show, Generic) + deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "asLovelace", LowerFirst]] AsLovelace + +-- | Number of bytes. +newtype AsBytes = AsBytes + { asBytesBytes :: Natural + -- ^ Number of bytes. + } + deriving stock (Eq, Show, Generic) + deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "asBytes", LowerFirst]] AsBytes + +-- | Represents lovelaces. +newtype AsAda = AsAda + { asAdaAda :: AsLovelace + -- ^ See `AsLovelace`. + } + deriving stock (Eq, Show, Generic) + deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "asAda", LowerFirst]] AsAda + -- | Current accepted protocol version. An increase in the major version indicates a hard fork, and the minor version a soft fork (meaning old software can validate but not produce new blocks). data ProtocolVersion = ProtocolVersion { protocolVersionMajor :: !Natural @@ -127,16 +168,16 @@ data ProtocolVersion = ProtocolVersion deriving stock (Eq, Show, Generic) deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "protocolVersion", LowerFirst]] ProtocolVersion --- | Pair of memory & steps for the given type. -data MemoryStepsWith i = MemoryStepsWith - { memoryStepsWithMemory :: !i - , memoryStepsWithSteps :: !i +-- | Pair of memory & cpu units for the given type. +data MemoryCpuWith i = MemoryCpuWith + { memoryCpuWithMemory :: !i + , memoryCpuWithCpu :: !i } deriving stock (Eq, Show, Generic) - deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "memoryStepsWith", LowerFirst]] (MemoryStepsWith i) + deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "memoryCpuWith", LowerFirst]] (MemoryCpuWith i) -- | A cost model is a vector of coefficients that are used to compute the execution units required to execute a script. Its specifics depend on specific versions of the Plutus interpreter it is used with. -newtype CostModel = CostModel (Map Text Integer) +newtype CostModel = CostModel [Int64] deriving (Eq, Show) deriving newtype (ToJSON, FromJSON) @@ -146,7 +187,7 @@ data CostModels = CostModels , costModelsPlutusV2 :: !CostModel } deriving stock (Eq, Show, Generic) - deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "costModels", Rename "PlutusV1" "plutus:v1", Rename "PlutusV2" "plutus:v2"]] CostModels + deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "costModels", CamelToSnake]] CostModels -- | Maestro's represents rational numbers as string with numerator and denominator demarcated by \'\/\', example: @"1/3"@. newtype MaestroRational = MaestroRational { unMaestroRational :: Rational } @@ -207,50 +248,51 @@ instance IsTimestamped TimestampedProtocolParameters where -- | Protocol parameters for the latest epoch. data ProtocolParameters = ProtocolParameters - { protocolParametersProtocolVersion :: !ProtocolVersion - -- ^ See `ProtocolVersion`. - , protocolParametersMinFeeConstant :: !Natural - -- ^ The linear factor for the minimum fee calculation for given epoch /AKA/ @min_fee_b@ and @tx_fee_fixed@. - , protocolParametersMinFeeCoefficient :: !Natural - -- ^ The constant factor for the minimum fee calculation /AKA/ @min_fee_a@ and @tx_fee_per_byte@. - , protocolParametersMaxBlockBodySize :: !Natural + { + protocolParametersCollateralPercentage :: !Natural + -- ^ The percentage of the transactions fee which must be provided as collateral when including non-native scripts. + , protocolParametersDesiredNumberOfStakePools :: !Natural + -- The equilibrium target number of stake pools. This is the \"k\" incentives parameter from the design document, /AKA/ @n_opt@, @stake_pool_target@. + , protocolParametersMaxBlockBodySize :: !AsBytes -- ^ Maximum block body size. - , protocolParametersMaxBlockHeaderSize :: !Natural + , protocolParametersMaxBlockHeaderSize :: !AsBytes -- ^ Maximum block header size. - , protocolParametersMaxTxSize :: !Natural + , protocolParametersMaxCollateralInputs :: !Natural + -- ^ The maximum number of collateral inputs allowed in a transaction. + , protocolParametersMaxExecutionUnitsPerBlock :: !(MemoryCpuWith Natural) + -- ^ The maximum number of execution memory & steps allowed to be used in a single block. + , protocolParametersMaxExecutionUnitsPerTransaction :: !(MemoryCpuWith Natural) + -- ^ The maximum number of execution memory & steps allowed to be used in a single transaction. + , protocolParametersMaxTransactionSize :: !AsBytes -- ^ Maximum transaction size. - , protocolParametersStakeKeyDeposit :: !Natural + , protocolParametersMaxValueSize :: !AsBytes + -- ^ Maximum size of the /value/ part of an output in a serialized transaction. + , protocolParametersMinFeeCoefficient :: !Natural + -- ^ The constant factor for the minimum fee calculation /AKA/ @min_fee_a@ and @tx_fee_per_byte@. + , protocolParametersMinFeeConstant :: !AsAda + -- ^ The linear factor for the minimum fee calculation for given epoch /AKA/ @min_fee_b@ and @tx_fee_fixed@. + , protocolParametersMinStakePoolCost :: !AsAda + -- ^ The minimum value that stake pools are permitted to declare for their cost parameter. + , protocolParametersMinUtxoDepositCoefficient :: !Natural + -- ^ The cost per UTxO size. Cost per UTxO /word/ for Alozno. Cost per UTxO /byte/ for Babbage and later. + , protocolParametersMonetaryExpansion :: !MaestroRational + -- ^ The monetary expansion rate. This determines the fraction of the reserves that are added to the fee pot each epoch. This is the \"rho\" incentives parameter from the design document. + , protocolParametersPlutusCostModels :: !CostModels + -- ^ See `CostModels`. + , protocolParametersScriptExecutionPrices :: !(MemoryCpuWith MaestroRational) + -- ^ The price per unit memory & price per reduction step corresponding to abstract notions of the relative memory usage and script execution steps respectively. + , protocolParametersStakeCredentialDeposit :: !AsAda -- The deposit required to register a stake address. - , protocolParametersPoolDeposit :: !Natural + , protocolParametersStakePoolDeposit :: !AsAda -- ^ The amount of a pool registration deposit in lovelaces /AKA/ @stake_pool_deposit@. - , protocolParametersPoolRetirementEpochBound :: !EpochNo - -- ^ The maximum number of epochs into the future that stake pools are permitted to schedule a retirement /AKA/ @pool_retire_max_epoch@, @e_max@. - , protocolParametersDesiredNumberOfPools :: !Natural - -- The equilibrium target number of stake pools. This is the \"k\" incentives parameter from the design document, /AKA/ @n_opt@, @stake_pool_target@. - , protocolParametersPoolInfluence :: !MaestroRational + , protocolParametersStakePoolPledgeInfluence :: !MaestroRational -- The influence of the pledge in stake pool rewards. This is the \"a_0\" incentives parameter from the design document. - , protocolParametersMonetaryExpansion :: !MaestroRational - -- ^ The monetary expansion rate. This determines the fraction of the reserves that are added to the fee pot each epoch. This is the \"rho\" incentives parameter from the design document. + , protocolParametersStakePoolRetirementEpochBound :: !EpochNo + -- ^ The maximum number of epochs into the future that stake pools are permitted to schedule a retirement /AKA/ @pool_retire_max_epoch@, @e_max@. , protocolParametersTreasuryExpansion :: !MaestroRational -- ^ The fraction of the fee pot each epoch that goes to the treasury. This is the \"tau\" incentives parameter from the design document, /AKA/ @treasury_cut@. - , protocolParametersMinPoolCost :: !Natural - -- ^ The minimum value that stake pools are permitted to declare for their cost parameter. - , protocolParametersPrices :: !(MemoryStepsWith MaestroRational) - -- ^ The price per unit memory & price per reduction step corresponding to abstract notions of the relative memory usage and script execution steps respectively. - , protocolParametersMaxExecutionUnitsPerTransaction :: !(MemoryStepsWith Natural) - -- ^ The maximum number of execution memory & steps allowed to be used in a single transaction. - , protocolParametersMaxExecutionUnitsPerBlock :: !(MemoryStepsWith Natural) - -- ^ The maximum number of execution memory & steps allowed to be used in a single block. - , protocolParametersMaxValueSize :: !Natural - -- ^ Maximum size of the /value/ part of an output in a serialized transaction. - , protocolParametersCollateralPercentage :: !Natural - -- ^ The percentage of the transactions fee which must be provided as collateral when including non-native scripts. - , protocolParametersMaxCollateralInputs :: !Natural - -- ^ The maximum number of collateral inputs allowed in a transaction. - , protocolParametersCoinsPerUtxoByte :: !Natural - -- ^ The cost per UTxO size. Cost per UTxO /word/ for Alozno. Cost per UTxO /byte/ for Babbage and later. - , protocolParametersCostModels :: !CostModels - -- ^ See `CostModels`. + , protocolParametersVersion :: !ProtocolVersion + -- ^ See `ProtocolVersion`. } deriving stock (Eq, Show, Generic) deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier '[StripPrefix "protocolParameters", CamelToSnake]] ProtocolParameters