| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
PlutusLedgerApi.V3
Description
The interface to Plutus V3 for the ledger.
Synopsis
- type SerialisedScript = 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
| :: forall m. MonadError ScriptDecodeError m | |
| => MajorProtocolVersion | which major protocol version the script was submitted in. |
| -> SerialisedScript | the script to deserialise. |
| -> m ScriptForEvaluation |
The deserialization from a serialised script into a ScriptForEvaluation,
ready to be evaluated on-chain.
Called inside phase-1 validation (i.e., deserialisation error is a phase-1 error).
uncheckedDeserialiseUPLC :: SerialisedScript -> DefaultFun () #
Deserialises a SerialisedScript back into an AST. Does *not* do
ledger-language-version-specific checks like for allowable builtins.
Running scripts
Arguments
| :: MajorProtocolVersion | Which protocol version to run the operation in |
| -> VerboseMode | Whether to produce log output |
| -> EvaluationContext | Includes the cost model to use for tallying up the execution costs |
| -> ExBudget | The resource budget which must not be exceeded during evaluation |
| -> ScriptForEvaluation | The script to evaluate |
| -> Data | The |
| -> (LogOutput, Either EvaluationError ExBudget) |
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
| :: MajorProtocolVersion | Which protocol version to run the operation in |
| -> VerboseMode | Whether to produce log output |
| -> EvaluationContext | Includes the cost model to use for tallying up the execution costs |
| -> ScriptForEvaluation | The script to evaluate |
| -> Data | The |
| -> (LogOutput, Either EvaluationError ExBudget) |
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 evaluateScriptRestricting, which
also returns the used budget.
CIP-1694
newtype ColdCommitteeCredential #
Constructors
| ColdCommitteeCredential Credential |
Constructors
| TxCertRegStaking Credential (Maybe Lovelace) | Register staking credential with an optional deposit amount |
| TxCertUnRegStaking Credential (Maybe Lovelace) | Un-Register staking credential with an optional refund amount |
| TxCertDelegStaking Credential Delegatee | Delegate staking credential to a Delegatee |
| TxCertRegDeleg Credential Delegatee Lovelace | Register and delegate staking credential to a Delegatee in one certificate. Note that deposit is mandatory. |
| TxCertRegDRep DRepCredential Lovelace | Register a DRep with a deposit value. The optional anchor is omitted. |
| TxCertUpdateDRep DRepCredential | Update a DRep. The optional anchor is omitted. |
| TxCertUnRegDRep DRepCredential Lovelace | UnRegister a DRep with mandatory refund value |
| TxCertPoolRegister | A digest of the PoolParams |
Fields
| |
| TxCertPoolRetire PubKeyHash RepIsStuckError GovernanceAction :: Type -> Type) (Rep GovernanceAction))) | |
newtype ChangedParameters #
A Plutus Data object containing proposed parameter changes. The Data object contains
a Map with one entry per changed parameter, from the parameter ID to the new value.
Unchanged parameters are not included.
The mapping from parameter IDs to parameters can be found in conway.cddl.
Invariant: This map is non-empty, and the keys are stored in ascending order.
This Data object has the following format (in pseudocode):
ChangedParametersData = Map ChangedIdData ChangedManyValueData ChangedIdData = I Integer ChangedManyValueData = ChangedSingleValueData | List[ChangedSingleValueData...] -- ^ an arbitrary-length, heterogeneous (integer or ratio) list of values (to support sub-parameters)
ChangedSingleValueData = I Integer -- a proposed integer value | List[I Integer, I Integer] -- a proposed numerator,denominator (ratio value) -- ^ a 2-exact element list; *BE CAREFUL* because this can be alternatively (ambiguously) interpreted -- as a many-value data (sub-parameter) of two integer single-value data.
, where Map,I,List are the constructors of Data
and Integer is the usual arbitrary-precision PlutusTx/Haskell Integer.
Constructors
| ChangedParameters | |
Fields | |
Instances
| RepIsStuckError ProposalProcedure :: Type -> Type) (Rep ProposalProcedure))) |
Protocol version
newtype 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
| MajorProtocolVersion | |
Fields
| |
Counts CPU units in picoseconds: maximum value for SatInt is 2^63 ps, or appproximately 106 days.
Constructors
| ExCPU Data.SatInt | |
| Num SatInt | In the |
Defined in Data.SatInt | |
fromSatInt :: Num a => SatInt -> a #
An optimized version of fromIntegral . unSatInt.
Cost model
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 DefaultMachineParameters per language
version, which we put into a cache (represented by an association list) in order to avoid costly
recomputation of machine parameters.
In order to get the appropriate DefaultMachineParameters at validation time we look it up in the
cache using a semantics variant as a key. We compute the semantics variant from the protocol
version using the stored function. Note that the semantics variant depends on the language version
too, but the latter is known statically (because each language version has its own evaluation
context), hence there's no reason to require it to be provided at runtime.
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 EvaluationContext.
The reason why we associate a DefaultMachineParameters with a semantics variant rather than a
protocol version are
- generally there are far more protocol versions than semantics variants supported by a specific language version, so we save on pointless duplication of bundles of machine parameters
- builtins don't know anything about protocol versions, only semantics variants. It is therefore more semantically precise to associate bundles of machine parameters with semantics variants than with protocol versions
Instances
Arguments
| :: (MonadError CostModelApplyError m, MonadWriter [CostModelApplyWarn] m) | |
| => [Int64] | the (updated) cost model parameters of the protocol |
| -> m EvaluationContext |
Build the EvaluationContext.
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 ParamName. If the parameters are
supplied in the wrong order then script cost calculations will be incorrect.
IMPORTANT: The evaluation context of every Plutus version must be recreated upon a protocol update with the updated cost model parameters.
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
| Text Int64 # A raw representation of the ledger's cost model parameters. The associated keys/names to the parameter values are arbitrarily set by the plutus team; the ledger does not hold any such names. See Note [Cost model parameters] assertWellFormedCostModelParams :: MonadError CostModelApplyError m => CostModelParams -> m () # Context typesdata ScriptContext # The context that the currently-executing script can access. Constructors
Instances
Types for representing transactionsAn address may contain two credentials,
the payment credential and optionally a Constructors
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
Instances
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
TxInfo for PlutusV3 Constructors
A transaction output, consisting of a target address, a value, optionally a datum/datum hash, and optionally a reference script. Constructors
A reference to a transaction output. This is a
pair of a transaction ID ( Constructors
data OutputDatum # The datum attached to an output: either nothing; a datum hash; or the datum itself (an "inline datum"). Constructors
Instances
IntervalsAn interval of 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 Constructors
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. RatioRepresents an arbitrary-precision ratio. The following two invariants are maintained:
ratio :: Integer -> Integer -> Maybe Rational # Safely constructs a unsafeRatio :: Integer -> Integer -> Rational # denominator :: Rational -> Integer # Returns the denominator of its argument. This will always be greater than, or equal to, 1, although the type does not describe this. NoteIt is not true in general that fromHaskellRatio :: Rational -> Rational # Converts a GHC Note: Does not work on-chain. toHaskellRatio :: Rational -> Rational # Association mapsA Use If cost minimisation is required, then you can use Most operations on Take care when using Instances
unsafeFromList :: [(k, v)] -> Map k v # Unsafely create a Newtypes and hash typesnewtype 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
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
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
DataA generic "data" type. The main constructor The other constructors are various primitives. Constructors
data BuiltinData # A type corresponding to the Plutus Core builtin equivalent of The point of this type is to be an opaque equivalent of 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 Constructors
Instances
Instances
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||