| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
PlutusLedgerApi.V1
Description
The interface to Plutus V1 for the ledger.
Synopsis
- newtype ScriptHash = ScriptHash {}
- newtype Redeemer = Redeemer {}
- newtype RedeemerHash = RedeemerHash BuiltinByteString
- newtype Datum = Datum {}
- newtype DatumHash = DatumHash BuiltinByteString
- newtype Context = Context BuiltinData
- data ScriptError
- = EvaluationError ![Ord a) => a -> Interval a -> Bool
- data Data
- data BuiltinData = BuiltinData ~Data
- class ToData a where
- toBuiltinData :: a -> BuiltinData
- class FromData a where
- fromBuiltinData :: BuiltinData -> Maybe a
- class UnsafeFromData a where
- unsafeFromBuiltinData :: BuiltinData -> a
- toData :: ToData a => a -> Data
- fromData :: FromData a => Data -> Maybe a
- unsafeFromData :: UnsafeFromData a => Data -> a
- dataToBuiltinData :: Data -> BuiltinData
- builtinDataToData :: BuiltinData -> Data
- class Monad m => MonadError e (m :: Type -> Type) | m -> e
Scripts
newtype ScriptHash #
Type representing the BLAKE2b-224 hash of a script. 28 bytes.
This is a simple type without any validation, use with caution. You may want to add checks for its invariants. See the Shelley ledger specification.
Constructors
| ScriptHash | |
Fields | |
newtype RedeemerHash #
Type representing the BLAKE2b-256 hash of a redeemer. 32 bytes.
This is a simple type without any validation, use with caution. You may want to add checks for its invariants. See the Shelley ledger specification.
Constructors
| RedeemerHash BuiltinByteString |
Type representing the BLAKE2b-256 hash of a datum. 32 bytes.
This is a simple type without any validation, use with caution. You may want to add checks for its invariants. See the Shelley ledger specification.
Constructors
| DatumHash BuiltinByteString |
Information about the state of the blockchain and about the transaction
that is currently being validated, represented as a value in Data.
Constructors
| Context BuiltinData |
Instances
| DeserialiseFailureInfo | an error from the underlying CBOR/serialise library |
| RemainderError !ByteString | Script was successfully parsed, but more (runaway) bytes encountered after script's position |
| LedgerLanguageNotAvailableError | the plutus version of the given script is not enabled yet |
Fields
| |
| PlutusCoreLanguageNotAvailableError | |
Fields
| |
Instances
| CompiledCode a -> SerialisedScript # Turns a program which was compiled using the 'PlutusTx' toolchain into a binary format that is understood by the network and can be stored on-chain. serialiseUPLC :: DefaultFun () -> SerialisedScript # Turns a program's AST (most likely manually constructed) into a binary format that is understood by the network and can be stored on-chain. Arguments
The deserialization from a serialised script into a uncheckedDeserialiseUPLC :: SerialisedScript -> DefaultFun () # Deserialises a Running scriptsArguments
Evaluates a script, with a cost model and a budget that restricts how many resources it can use according to the cost model. Also returns the budget that was actually used. Can be used to calculate budgets for scripts, but even in this case you must give a limit to guard against scripts that run for a long time or loop. Arguments
Evaluates a script, returning the minimum budget that the script would need
to evaluate successfully. This will take as long as the script takes, if you need to
limit the execution time of the script also, you can use Protocol versionnewtype MajorProtocolVersion # This represents the major component of the Cardano protocol version. The ledger can only supply the major component of the protocol version, not the minor component, and Plutus should only need to care about the major component anyway. This relies on careful understanding between us and the ledger as to what this means. Constructors
Counts CPU units in picoseconds: maximum value for SatInt is 2^63 ps, or appproximately 106 days. Constructors
fromSatInt :: Num a => SatInt -> a # An optimized version of The enumeration of all possible cost model parameter names for this language version. IMPORTANT: The order of appearance of the data constructors here matters. DO NOT REORDER. See Note [Quotation marks in cost model parameter constructors] See Note [Cost model parameters from the ledger's point of view] Constructors Instances
tagWithParamNames :: forall k m. (Enum k, Bounded k, MonadError CostModelApplyError m, MonadWriter [CostModelApplyWarn] m) => [Int64] -> m [(k, Int64)] # Given an ordered list of parameter values, tag them with their parameter names. If the passed parameter values are more than expected: the function will ignore the extraneous values at the tail of the list, if the passed values are less than expected: the function will throw an error; for more information, see Note [Cost model parameters from the ledger's point of view] Evaluationdata EvaluationError # Errors that can be thrown when evaluating a Plutus script. Constructors
data EvaluationContext # An opaque type that contains all the static parameters that the evaluator needs to evaluate a script. This is so that they can be computed once and cached, rather than being recomputed on every evaluation. Different protocol versions may require different bundles of machine parameters, which allows us for
example to tweak the shape of the costing function of a builtin, so that the builtin costs less.
Currently this means that we have to create multiple In order to get the appropriate To say it differently, there's a matrix of semantics variants indexed by (LL, PV) pairs and we
cache its particular row corresponding to the statically given LL in an The reason why we associate a
Instances
Shared helper for the evaluation functions: Given a 1) applies the term to a list of assertWellFormedCostModelParams :: MonadError CostModelApplyError m => CostModelParams -> m () # Evaluation contextArguments
Build the The input is a list of cost model parameters (which are integer values) passed from the ledger. IMPORTANT: the cost model parameters MUST appear in the correct order,
matching the names in IMPORTANT: The evaluation context of every Plutus version must be recreated upon a protocol update with the updated cost model parameters. type CostModelParams = RepIsStuckError ScriptPurpose :: Type -> Type) (Rep ScriptPurpose))) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A transaction ID, i.e. the hash of a transaction. Hashed with BLAKE2b-256. 32 byte.
This is a simple type without any validation, use with caution. You may want to add checks for its invariants. See the Shelley ledger specification.
Constructors
| TxId | |
Fields | |
A transaction output, consisting of a target address (Address), a value (Value),
and optionally a datum hash (DatumHash).
Constructors
| TxOut | |
Fields
| |
A reference to a transaction output. This is a
pair of a transaction ID (TxId), and an index indicating which of the outputs
of that transaction we are referring to.
Constructors
| TxOutRef | |
Fields
| |
findOwnInput :: ScriptContext -> Maybe TxInInfo #
Find the input currently being validated.
findDatum :: DatumHash -> TxInfo -> Maybe Datum #
Find the data corresponding to a data hash, if there is one
findDatumHash :: Datum -> TxInfo -> Maybe DatumHash #
Find the hash of a datum, if it is part of the pending transaction's hashes
findContinuingOutputs :: ScriptContext -> [Integer] #
Finds all the outputs that pay to the same script address that we are currently spending from, if any.
getContinuingOutputs :: ScriptContext -> [TxOut] #
Get all the outputs that pay to the same script address we are currently spending from, if any.
pubKeyOutputsAt :: PubKeyHash -> TxInfo -> [Value] #
Get the values paid to a public key address by a pending transaction.
valuePaidTo :: TxInfo -> PubKeyHash -> Value #
Get the total value paid to a public key address by a pending transaction.
spendsOutput :: TxInfo -> TxId -> Integer -> Bool #
Check if the pending transaction spends a specific transaction output (identified by the hash of a transaction and an index into that transactions' outputs)
txSignedBy :: TxInfo -> PubKeyHash -> HasFromOpaque arep a => arep -> a #
Bytes
newtype LedgerBytes #
Constructors
| LedgerBytes | |
Fields | |
Instances
| IsString LedgerBytes # | Read in arbitrary This is mostly used together with GHC's OverloadedStrings extension
to specify at the source code any IMPORTANT: the |
Defined in PlutusLedgerApi.V1.Bytes Methods fromString :: String -> LedgerBytes # | |
| Generic LedgerBytes # | |
Defined in PlutusLedgerApi.V1.Bytes Associated Types type Rep LedgerBytes :: Type -> Type # | |
| Show LedgerBytes # | The |
data LedgerBytesError #
An error that is encountered when converting a ByteString to a LedgerBytes.
Constructors
| UnpairedDigit | Odd number of bytes in the original bytestring. |
| NotHexit !Char | A non-hex digit character ([^A-Fa-f0-9]) encountered during decoding. |
Instances
| Exception LedgerBytesError # | |
Defined in PlutusLedgerApi.V1.Bytes Methods toException :: LedgerBytesError -> SomeException # | |
| Show LedgerBytesError # | |
Defined in PlutusLedgerApi.V1.Bytes Methods showsPrec :: Int -> LedgerBytesError -> ShowS # show :: LedgerBytesError -> String # showList :: [LedgerBytesError] -> ShowS # | |
fromBytes :: ByteString -> LedgerBytes #
Lift a Haskell bytestring to the Plutus abstraction LedgerBytes
fromHex :: ByteString -> Either LedgerBytesError LedgerBytes #
Convert a hex-encoded (Base16) ByteString to a LedgerBytes.
May return an error (LedgerBytesError).
bytes :: LedgerBytes -> Text #
Encode a ByteString value to Base16 (i.e. hexadecimal), then
decode with UTF-8 to a Text.
Certificates
A representation of the ledger DCert. Some information is digested, and not included
Constructors
| DCertDelegRegKey StakingCredential | |
| DCertDelegDeRegKey StakingCredential | |
| DCertDelegDelegate | |
Fields
| |
| DCertPoolRegister | A digest of the PoolParams |
Fields
| |
| DCertPoolRetire PubKeyHash RepIsStuckError DCert :: Type -> Type) (Rep DCert))) | |
Credentials
data StakingCredential #
Staking credential used to assign rewards.
Constructors
| StakingHash Credential | The staking hash is the |
| StakingPtr | The certificate pointer, constructed by the given
slot number, transaction and certificate indices.
NB: The fields should really be all |
data Credential #
Credentials required to unlock a transaction output.
Constructors
| PubKeyCredential PubKeyHash | The transaction that spends this output must be signed by the private key.
See |
| ScriptCredential ScriptHash | The transaction that spends this output must include the validator script and
be accepted by the validator. See |
Instances
| RepIsStuckError Credential :: Type -> Type) (Rep Credential))) |
Value
The Value type represents a collection of amounts of different currencies.
We can think of Value as a vector space whose dimensions are currencies.
Operations on currencies are usually implemented pointwise. That is,
we apply the operation to the quantities for each currency in turn. So
when we add two Values the resulting Value has, for each currency,
the sum of the quantities of that particular currency in the argument
Value. The effect of this is that the currencies in the Value are "independent",
and are operated on separately.
Whenever we need to get the quantity of a currency in a Value where there
is no explicit quantity of that currency in the Value, then the quantity is
taken to be zero.
There is no 'Ord Value' instance since Value is only a partial order, so compare can't
do the right thing in some cases.
currencySymbolValueOf :: Value -> CurrencySymbol -> Integer #
Get the total value of the currency symbol in the Value map.
Assumes that the underlying map doesn't contain duplicate keys.
Note that each token of the currency symbol may have a value that is positive, zero or negative.
flattenValue :: Value -> [(CurrencySymbol, TokenName, Integer)] #
Convert a Value to a simple list, keeping only the non-zero amounts.
Note that the result isn't sorted, meaning v1 == v2 doesn't generally imply
flattenValue v1 == flattenValue v2. Additionally, the entries in the
result are listed in reverse order of the underlying data of the original ‘Value’.
For instance, the lovelace entry which ordinarily appears first in the ‘Value’
will appear last in the result.
Also assumes that there are no duplicate keys in the Value Map.
singleton :: CurrencySymbol -> TokenName -> Integer -> Value #
Make a Value containing only the given quantity of the given currency.
unionWith :: (Integer -> Integer -> Integer) -> Value -> Value -> Value #
Combine two Value maps with the argument function.
Assumes the well-definedness of the two maps.
valueOf :: Value -> CurrencySymbol -> TokenName -> Integer #
Get the quantity of the given currency in the Value.
Assumes that the underlying map doesn't contain duplicate keys.
Currency symbols
newtype CurrencySymbol #
ByteString representing the currency, hashed with BLAKE2b-224.
It is empty for Ada, 28 bytes for MintingPolicyHash.
Forms an AssetClass along with TokenName.
A Value is a map from CurrencySymbol's to a map from TokenName to an Integer.
This is a simple type without any validation, use with caution. You may want to add checks for its invariants. See the Shelley ledger specification.
Constructors
| CurrencySymbol | |
Fields | |
Instances
| RepIsStuckError CurrencySymbol :: Type -> Type) (Rep CurrencySymbol))) |
currencySymbol :: ByteString -> CurrencySymbol #
Creates CurrencySymbol from raw ByteString.
The CurrencySymbol of the Ada currency.
symbols :: Value -> [CurrencySymbol] #
The list of CurrencySymbols of a Value.
Token names
ByteString of a name of a token.
Shown as hex-encoded bytes.
Should be no longer than 32 bytes, empty for Ada.
Forms an AssetClass along with a CurrencySymbol.
This is a simple type without any validation, use with caution. You may want to add checks for its invariants. See the Shelley ledger specification.
Constructors
| TokenName | |
Fields | |
Instances
| RepIsStuckError AssetClass :: Type -> Type) (Rep AssetClass))) |
assetClass :: CurrencySymbol -> TokenName -> AssetClass #
The curried version of AssetClass constructor
assetClassValue :: AssetClass -> Integer -> Value #
A Value containing the given amount of the asset class.
assetClassValueOf :: Value -> AssetClass -> Integer #
Get the quantity of the given AssetClass class in the Value.
Addresses
An address may contain two credentials,
the payment credential and optionally a StakingCredential.
Constructors
| Address | |
Fields
| |
pubKeyHashAddress :: PubKeyHash -> Address #
The address that should be targeted by a transaction output locked by the public key with the given hash.
toPubKeyHash :: Address -> Maybe PubKeyHash #
The PubKeyHash of the address, if any
toScriptHash :: Address -> Maybe ScriptHash #
The validator hash of the address, if any
scriptHashAddress :: ScriptHash -> Address #
The address that should be used by a transaction output locked by the given validator script hash.
stakingCredential :: Address -> Maybe StakingCredential #
The staking credential of an address (if any)
Crypto
newtype PubKeyHash #
The hash of a public key. This is frequently used to identify the public key, rather than the key itself. Hashed with BLAKE2b-224. 28 bytes.
This is a simple type without any validation, use with caution. You may want to add checks for its invariants. See the Shelley ledger specification.
Constructors
| PubKeyHash | |
Fields | |
Instances
| Unroll PubKeyHash = '[PubKeyHash] |
Time
POSIX time is measured as the number of milliseconds since 1970-01-01T00:00:00Z.
This is not the same as Haskell's RepIsStuckError DiffMilliSeconds :: Type -> Type) (Rep DiffMilliSeconds)))
fromMilliSeconds :: DiffMilliSeconds -> POSIXTime #
Simple conversion from DiffMilliSeconds to POSIXTime.
Intervals
An interval of as.
The interval may be either closed or open at either end, meaning that the endpoints may or may not be included in the interval.
The interval can also be unbounded on either side.
The Eq instance gives equality of the intervals, not structural equality.
There is no Enum in order to
handle non-inclusive endpoints. For this reason, it may not be safe to
use Intervals with non-inclusive endpoints on types whose Enum
instances have partial methods.
Constructors
| Interval | |
Fields
| |
from a is an Interval that includes all values that are
greater than or equal to a. In math. notation: [a,+∞]
to a is an Interval that includes all values that are
smaller than or equal to a. In math. notation: [-∞,a]
lowerBound :: a -> LowerBound a #
Construct a lower bound from a value. The resulting bound includes all values that are equal or greater than the input value.
upperBound :: a -> UpperBound a #
Construct an upper bound from a value. The resulting bound includes all values that are equal or smaller than the input value.
strictLowerBound :: a -> LowerBound a #
Construct a strict lower bound from a value. The resulting bound includes all values that are (strictly) greater than the input value.
strictUpperBound :: a -> UpperBound a #
Construct a strict upper bound from a value. The resulting bound includes all values that are (strictly) smaller than the input value.
interval :: a -> a -> Interval a #
interval a b includes all values that are greater than or equal to a
and smaller than or equal to b. Therefore it includes a and b. In math. notation: [a,b]
hull :: (Ord a) => Interval a -> Interval a -> Interval a #
'intersection a b' is the largest interval that is contained in a and in
b, if it exists.
overlaps :: (Ord a) => Interval a -> Interval a -> Bool #
Check whether two intervals overlap, that is, whether there is a value that is a member of both intervals.
isEmpty :: (Ord a) => a -> Interval a -> Bool #
Check if a value is later than the end of an Interval.
Data
A generic "data" type.
The main constructor Constr represents a datatype value in sum-of-products
form: Constr i args represents a use of the ith constructor along with its arguments.
The other constructors are various primitives.
Constructors
| Constr DefaultUni Data) |
data BuiltinData #
A type corresponding to the Plutus Core builtin equivalent of Data.
The point of this type is to be an opaque equivalent of Data, so as to
ensure that it is only used in ways that the compiler can handle.
As such, you should use this type in your on-chain code, and in any data structures that you want to be representable on-chain.
For off-chain usage, there are conversion functions builtinDataToData and
dataToBuiltinData, but note that these will not work on-chain.
Constructors
| BuiltinData ~Data |
Instances
| BuiltinBLS12_381_G1_Element | For the BLS12-381 G1 and G2 types we use the | |||||
Defined in BuiltinBLS12_381_MlResult | We do not provide instances of any of these classes for BuiltinBLS12_381_MlResult since there is no serialisation format: we expect that values of that type will only occur as the result of on-chain computations. | |||||
Defined in PlutusTx.IsData.Class Methods toBuiltinData :: [a] -> BuiltinData # | ||||||
| (ToData k, ToData v) => ToData (Map k v) | Hand-written instances to use the underlying | |||||
Defined in PlutusTx.IsData.Class Methods fromBuiltinData :: BuiltinData -> Maybe [a] # | ||||||
| (FromData k, FromData v) => FromData (Map k v) | A hand-written transformation from | |||||
Defined in error if this fails.
This is typically much faster than When implementing this function, make sure to call This is a simple type without any validation, use with caution. Instances
unsafeFromData :: UnsafeFromData a => Data -> a # Convert a value from Note: off-chain only. dataToBuiltinData :: Data -> BuiltinData # NOT a builtin. Converts a builtinDataToData :: BuiltinData -> Data # NOT a builtin. Converts a Errorsclass Monad m => MonadError e (m :: Type -> Type) | m -> e # The strategy of combining computations that can throw exceptions by bypassing bound functions from the point an exception is thrown to the point that it is handled. Is parameterized over the type of error information and
the monad type constructor.
It is common to use Minimal complete definition BuiltinFailure logs. This is to compensate for the historical lack of error message content in operational errors (structural ones don't have this problem) in our evaluators (the CK and CEK machines). It would be better to fix the underlying issue and allow operational evaluation errors to carry some form of content, but for now we just fix the symptom in order for the end user to see the error message that they are supposed to see. The fix even makes some sense: what we do here is we emulate logging when the thrown unlifting error is an operational one, i.e. this is similar to what some builtins do manually (like when a crypto builtin fails and puts info about the failure into the logs). | ||||||