plutus-tx-1.60.0.0: Libraries for Plutus Tx and its prelude
Safe HaskellSafe-Inferred
LanguageHaskell2010

PlutusTx.Builtins.Internal

Description

This module contains the special Haskell names that are used to map to builtin types or functions in Plutus Core.

Most users should not use this module directly, but rather use Builtins.

Please note that the documentation for each function will only include operational invariants if there are any. This documentation assumes that the type system correctly enforces and prevents any structural errors on the generated UPLC. See Note [Structural vs operational errors within builtins].

Also note that all builtin functions will fail if the CEK machine exceeds its evaluation budget. Builtin functions with dynamic costing are particularly prone to budget overruns: for example, addInteger and appendByteString differ cost based on input size, so supplying very large integers or byte strings will cause these functions to abort when the budget limit is reached and fail. See Note [Budgeting].

Synopsis
type Unroll BuiltinUnit # 
Instance details

Defined in PlutusTx.Blueprint.Definition.Unroll

type Unroll BuiltinUnit = '[BuiltinUnit]
type FromBuiltin BuiltinUnit # 
Instance details

Defined in PlutusTx.Builtins.HasBuiltin

type FromBuiltin BuiltinUnit = ()

unitval :: BuiltinUnit #

Unit

chooseUnit :: BuiltinUnit -> a -> a #

type BuiltinInteger = Integer #

addInteger :: BuiltinInteger -> BuiltinInteger -> BuiltinInteger #

Adds two integers and never fails.

subtractInteger :: BuiltinInteger -> BuiltinInteger -> BuiltinInteger #

Subtracts two integers and never fails.

multiplyInteger :: BuiltinInteger -> BuiltinInteger -> BuiltinInteger #

Multiplies two integers and never fails.

divideInteger :: BuiltinInteger -> BuiltinInteger -> BuiltinInteger #

Finds the quotient of two integers and fails when the second argument, the divisor, is zero. See Note [Integer division operations] for explanation on divideInteger, modInteger, quotientInteger, and remainderInteger.

modInteger :: BuiltinInteger -> BuiltinInteger -> BuiltinInteger #

Finds the remainder of two integers and fails when the second argument, the divisor, is zero.

quotientInteger :: BuiltinInteger -> BuiltinInteger -> BuiltinInteger #

Finds the quotient of two integers and fails when the second argument, the divisor, is zero.

remainderInteger :: BuiltinInteger -> BuiltinInteger -> BuiltinInteger #

Finds the remainder of two integers and fails when the second argument, the divisor, is zero.

lessThanInteger :: BuiltinInteger -> BuiltinInteger -> Bool #

Compares two integers and returns true when the first argument is less than the second | argument.

lessThanEqualsInteger :: BuiltinInteger -> BuiltinInteger -> Bool #

Compares two integers and returns true when the first argument is less or equal to than the | second argument.

equalsInteger :: BuiltinInteger -> BuiltinInteger -> Bool #

Checks equality of two integers and never fails.

data BuiltinByteString #

An opaque type representing Plutus Core ByteStrings.

Constructors

BuiltinByteString ~TyName uni ()) #

type Unroll BuiltinByteString # 
Instance details

Defined in PlutusTx.Blueprint.Definition.Unroll

type Unroll BuiltinByteString = '[BuiltinByteString]
type FromBuiltin BuiltinByteString # 
Instance details

Defined in PlutusTx.Builtins.HasBuiltin

type FromBuiltin BuiltinByteString = ByteString

appendByteString :: BuiltinByteString -> BuiltinByteString -> BuiltinByteString #

Appends a bytestring to another and never fails.

consByteString :: BuiltinInteger -> BuiltinByteString -> BuiltinByteString #

Appends a byte to the given bytestring. The semantics of this function differ based on [Builtin semantics variants]. - For builtin semantics variant A and B, that is for PlutusV1 and PlutusV2, this reduces the first argument modulo 256 and will never fail. - For builtin semantics variant C, that is for PlutusV3, this will expect first argument to be in range [0..255] and fail otherwise.

sliceByteString :: BuiltinInteger -> BuiltinInteger -> BuiltinByteString -> BuiltinByteString #

Slices the given bytestring and never fails. The first integer marks the beginning index and the second marks the end. Indices are expected to be 0-indexed, and when the first integer is greater than the second, it returns an empty bytestring.

lengthOfByteString :: BuiltinByteString -> BuiltinInteger #

Returns the length of the provided bytestring.

indexByteString :: BuiltinByteString -> BuiltinInteger -> BuiltinInteger #

Returns the n-th byte from the bytestring. Fails if the given index is not in the range [0..j), where j is the length of the bytestring.

emptyByteString :: BuiltinByteString #

An empty bytestring.

sha2_256 :: BuiltinByteString -> BuiltinByteString #

Computes the SHA2-256 hash of the given bytestring.

sha3_256 :: BuiltinByteString -> BuiltinByteString #

Computes the SHA3-256 hash of the given bytestring.

blake2b_224 :: BuiltinByteString -> BuiltinByteString #

Computes the Blake2b-224 hash of the given bytestring.

blake2b_256 :: BuiltinByteString -> BuiltinByteString #

Computes the Blake2b-256 hash of the given bytestring.

keccak_256 :: BuiltinByteString -> BuiltinByteString #

Computes the Keccak-256 hash of the given bytestring.

ripemd_160 :: BuiltinByteString -> BuiltinByteString #

Computes the RIPEMD-160 hash of the given bytestring.

verifyEd25519Signature :: BuiltinByteString -> BuiltinByteString -> BuiltinByteString -> Bool #

Ed25519 signature verification. The first bytestring is the public key (32 bytes), followed by an arbitrary-size message and the signature (64 bytes). The sizes of the public key and signature are enforced, and it fails when given bytestrings of incorrect size.

verifyEcdsaSecp256k1Signature :: BuiltinByteString -> BuiltinByteString -> BuiltinByteString -> Bool #

ECDSA signature verification on the SECP256k1 curve. The first bytestring is the public key (33 bytes), followed by the message hash (32 bytes) and the signature (64 bytes). The sizes of the public key and signature are enforced, and it fails when given bytestrings of incorrect size.

verifySchnorrSecp256k1Signature :: BuiltinByteString -> BuiltinByteString -> BuiltinByteString -> Bool #

Schnorr signature verification on the SECP256k1 curve. The first bytestring is the public key (32 bytes), followed by an arbitrary-length message and the signature (64 bytes). The sizes of the public key and signature are enforced, and it fails when given bytestrings of incorrect size.

traceAll :: forall (a :: Text -> a -> a #

Runs trace for each element in a foldable structure.

equalsByteString :: BuiltinByteString -> BuiltinByteString -> Bool #

Checks the equality of two bytestrings and never fails

lessThanByteString :: BuiltinByteString -> BuiltinByteString -> Bool #

Checks if the first bytestring is less than the second bytestring and never fails. Comparison of the bytestrings will behave identically to the compare implementation in Ord. It will compare two bytestrings byte by byte—lexicographical ordering.

lessThanEqualsByteString :: BuiltinByteString -> BuiltinByteString -> Bool #

Checks if the first bytestring is less than or equal to the second bytestring and never fails.

decodeUtf8 :: BuiltinByteString -> BuiltinString #

Decodes the given bytestring to a string and fails when the given bytestring is not a valid UTF-8 bytestring.

data BuiltinString #

Constructors

BuiltinString ~TyName uni ()) #

type Unroll (BuiltinList a) # 
Instance details

Defined in PlutusTx.Blueprint.Definition.Unroll

type Unroll (BuiltinList a) = Insert (BuiltinList a) (Unrolled a)
type FromBuiltin (BuiltinList a) # 
Instance details

Defined in PlutusTx.Builtins.HasBuiltin

type FromBuiltin (BuiltinList a) = [FromBuiltin a]

null :: BuiltinList a -> Bool #

Checks if the given list is empty.

head :: BuiltinList a -> a #

Takes the first element of the list and fails if given list is empty.

tail :: BuiltinList a -> BuiltinList a #

Takes the last element of the list and fails if given list is empty.

chooseList :: BuiltinList a -> b -> b -> b #

Branches out depending on the structure of given list and never fails. If given list is empty, it will take the first branch and if not it will take the second branch.

caseList' :: forall a r. r -> (a -> BuiltinList a -> r) -> BuiltinList a -> r #

Similar to chooseList but deconstructs the list in case provided list is not empty.

unsafeCaseList :: forall a r. (a -> BuiltinList a -> r) -> BuiltinList a -> r #

Similar to caseList', but empty list case is omitted so passing empty list will raise error

drop :: Integer -> BuiltinList a -> BuiltinList a #

Drops first n elements from the given list and never fails.

mkNilData :: BuiltinUnit -> BuiltinList BuiltinData #

Creates an empty data list and never fails. Prefer using constant. See Note [Constants vs built-in functions]

mkNilPairData :: BuiltinUnit -> BuiltinList (BuiltinPair BuiltinData BuiltinData) #

Creates an empty data pair list and never fails. Prefer using constant. See Note [Constants vs built-in functions]

mkCons :: a -> BuiltinList a -> BuiltinList a #

Appends a new element to the given list and never fails.

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

Instances details
Data for exact encoder as Data does not uses Generic version.

data BuiltinValue #

Constructors

BuiltinValue ~TyName uni ()) #

type FromBuiltin (BuiltinArray a) # 
Instance details

Defined in PlutusTx.Builtins.HasBuiltin

type FromBuiltin (BuiltinArray a) = Vector (FromBuiltin a)

lengthOfArray :: BuiltinArray a -> BuiltinInteger #

Returns the length of the provided array and never fails

listToArray :: BuiltinList a -> BuiltinArray a #

Converts given list into array and never fails.

indexArray :: BuiltinArray a -> BuiltinInteger -> a #

Returns the n-th element from the array. Fails if the given index is not in the range [0..j), where j is the length of the array.

data BuiltinBLS12_381_G1_Element #

Constructors

BuiltinBLS12_381_G1_Element ~Element 

Instances

Instances details
Show BuiltinBLS12_381_G1_Element # 
Instance details

Defined in PlutusTx.Builtins.Internal

Methods

showsPrec :: Int -> BuiltinBLS12_381_G1_Element -> ShowS #

show :: BuiltinBLS12_381_G1_Element -> String #

showList :: [BuiltinBLS12_381_G1_Element] -> ShowS #

NFData BuiltinBLS12_381_G1_Element # 
Instance details

Defined in PlutusTx.Builtins.Internal

Methods

rnf :: BuiltinBLS12_381_G1_Element -> () #

Eq BuiltinBLS12_381_G1_Element # 
Instance details

Defined in PlutusTx.Builtins.Internal

Methods

(==) :: BuiltinBLS12_381_G1_Element -> BuiltinBLS12_381_G1_Element -> Bool #

(/=) :: BuiltinBLS12_381_G1_Element -> BuiltinBLS12_381_G1_Element -> Bool #

HasFromBuiltin BuiltinBLS12_381_G1_Element # 
Instance details

Defined in PlutusTx.Builtins.HasBuiltin

Associated Types

type FromBuiltin BuiltinBLS12_381_G1_Element #

Methods

fromBuiltin :: BuiltinBLS12_381_G1_Element -> FromBuiltin BuiltinBLS12_381_G1_Element #

MkNil BuiltinBLS12_381_G1_Element # 
Instance details

Defined in PlutusTx.Builtins.HasOpaque

Methods

mkNil :: BuiltinList BuiltinBLS12_381_G1_Element #

Eq BuiltinBLS12_381_G1_Element # 
Instance details

Defined in PlutusTx.Eq.Class

Methods

(==) :: BuiltinBLS12_381_G1_Element -> BuiltinBLS12_381_G1_Element -> Bool #

FromData BuiltinBLS12_381_G1_Element # 
Instance details

Defined in PlutusTx.IsData.Class

Methods

fromBuiltinData :: BuiltinData -> Maybe BuiltinBLS12_381_G1_Element #

ToData BuiltinBLS12_381_G1_Element #

For the BLS12-381 G1 and G2 types we use the compress functions to convert to a ByteString and then encode that as Data as usual. We have to be more careful going the other way because we decode a Data object to (possibly) get a BuiltinByteString and then uncompress the underlying ByteString to get a group element. However uncompression can fail so we have to check what happens: we don't use bls12_381_G?_uncompress because that invokes error if something goes wrong (but we do use it for unsafeFromData).

Instance details

Defined in PlutusTx.IsData.Class

Methods

toBuiltinData :: BuiltinBLS12_381_G1_Element -> BuiltinData #

UnsafeFromData BuiltinBLS12_381_G1_Element # 
Instance details

Defined in PlutusTx.IsData.Class

Methods

unsafeFromBuiltinData :: BuiltinData -> BuiltinBLS12_381_G1_Element #

Element

bls12_381_G1_equals :: BuiltinBLS12_381_G1_Element -> BuiltinBLS12_381_G1_Element -> Bool #

Checks equality of two G1 elements and never fails.

bls12_381_G1_add :: BuiltinBLS12_381_G1_Element -> BuiltinBLS12_381_G1_Element -> BuiltinBLS12_381_G1_Element #

Adds two G1 elements and never fails.

bls12_381_G1_neg :: BuiltinBLS12_381_G1_Element -> BuiltinBLS12_381_G1_Element #

Negates a G1 element and never fails.

bls12_381_G1_scalarMul :: BuiltinInteger -> BuiltinBLS12_381_G1_Element -> BuiltinBLS12_381_G1_Element #

Multiplies a G1 element by a scalar and never fails.

bls12_381_G1_multiScalarMul :: BuiltinList BuiltinInteger -> BuiltinList BuiltinBLS12_381_G1_Element -> BuiltinBLS12_381_G1_Element #

bls12_381_G1_compress :: BuiltinBLS12_381_G1_Element -> BuiltinByteString #

Compresses a G1 element to a bytestring and never fails.

bls12_381_G1_uncompress :: BuiltinByteString -> BuiltinBLS12_381_G1_Element #

Uncompresses a bytestring to a G1 element, failing if the bytestring is not a valid compressed G1 element.

bls12_381_G1_hashToGroup :: BuiltinByteString -> BuiltinByteString -> BuiltinBLS12_381_G1_Element #

Hashes an arbitrary bytestring message to a G1 element using the given domain separation tag (DST), failing if length of the DST is bigger than 255 bytes.

bls12_381_G1_compressed_zero :: BuiltinByteString #

The compressed form of the G1 identity element.

bls12_381_G1_compressed_generator :: BuiltinByteString #

The compressed form of the G1 generator element.

data BuiltinBLS12_381_G2_Element #

Constructors

BuiltinBLS12_381_G2_Element ~Element

bls12_381_G2_equals :: BuiltinBLS12_381_G2_Element -> BuiltinBLS12_381_G2_Element -> Bool #

Checks equality of two G2 elements and never fails.

bls12_381_G2_add :: BuiltinBLS12_381_G2_Element -> BuiltinBLS12_381_G2_Element -> BuiltinBLS12_381_G2_Element #

Adds two G2 elements and never fails.

bls12_381_G2_neg :: BuiltinBLS12_381_G2_Element -> BuiltinBLS12_381_G2_Element #

Negates a G2 element and never fails.

bls12_381_G2_scalarMul :: BuiltinInteger -> BuiltinBLS12_381_G2_Element -> BuiltinBLS12_381_G2_Element #

Multiplies a G2 element by a scalar and never fails.

bls12_381_G2_multiScalarMul :: BuiltinList BuiltinInteger -> BuiltinList BuiltinBLS12_381_G2_Element -> BuiltinBLS12_381_G2_Element #

bls12_381_G2_compress :: BuiltinBLS12_381_G2_Element -> BuiltinByteString #

Compresses a G2 element to a bytestring and never fails.

bls12_381_G2_uncompress :: BuiltinByteString -> BuiltinBLS12_381_G2_Element #

Uncompresses a bytestring to a G2 element, failing if the bytestring is not a valid compressed G2 element.

bls12_381_G2_hashToGroup :: BuiltinByteString -> BuiltinByteString -> BuiltinBLS12_381_G2_Element #

Hashes an arbitrary bytestring message to a G2 element using the given domain separation tag (DST), failing if length of the DST is bigger than 255 bytes.

bls12_381_G2_compressed_zero :: BuiltinByteString #

The compressed form of the G2 identity element (also known as zero or point at infinity).

bls12_381_G2_compressed_generator :: BuiltinByteString #

The compressed form of the G2 generator element.

data BuiltinBLS12_381_MlResult #

Constructors

BuiltinBLS12_381_MlResult ~MlResult 

Instances

Instances details
Show BuiltinBLS12_381_MlResult # 
Instance details

Defined in PlutusTx.Builtins.Internal

Methods

showsPrec :: Int -> BuiltinBLS12_381_MlResult -> ShowS #

show :: BuiltinBLS12_381_MlResult -> String #

showList :: [BuiltinBLS12_381_MlResult] -> ShowS #

NFData BuiltinBLS12_381_MlResult # 
Instance details

Defined in PlutusTx.Builtins.Internal

Methods

rnf :: BuiltinBLS12_381_MlResult -> () #

Eq BuiltinBLS12_381_MlResult # 
Instance details

Defined in PlutusTx.Builtins.Internal

Methods

(==) :: BuiltinBLS12_381_MlResult -> BuiltinBLS12_381_MlResult -> Bool #

(/=) :: BuiltinBLS12_381_MlResult -> BuiltinBLS12_381_MlResult -> Bool #

HasFromBuiltin BuiltinBLS12_381_MlResult # 
Instance details

Defined in PlutusTx.Builtins.HasBuiltin

Associated Types

type FromBuiltin BuiltinBLS12_381_MlResult #

Methods

fromBuiltin :: BuiltinBLS12_381_MlResult -> FromBuiltin BuiltinBLS12_381_MlResult #

(TypeError ('Text "fromBuiltinData is not supported for BuiltinBLS12_381_MlResult") :: Constraint) => FromData BuiltinBLS12_381_MlResult # 
Instance details

Defined in PlutusTx.IsData.Class

Methods

fromBuiltinData :: BuiltinData -> Maybe BuiltinBLS12_381_MlResult #

(TypeError ('Text "toBuiltinData is not supported for BuiltinBLS12_381_MlResult") :: Constraint) => ToData 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.

Instance details

Defined in PlutusTx.IsData.Class

Methods

toBuiltinData :: BuiltinBLS12_381_MlResult -> BuiltinData #

(MlResult

bls12_381_millerLoop :: BuiltinBLS12_381_G1_Element -> BuiltinBLS12_381_G2_Element -> BuiltinBLS12_381_MlResult #

Computes the Miller loop between a G1 element and a G2 element and never fails.

bls12_381_mulMlResult :: BuiltinBLS12_381_MlResult -> BuiltinBLS12_381_MlResult -> BuiltinBLS12_381_MlResult #

Multiplies two Miller loop results and never fails.

bls12_381_finalVerify :: BuiltinBLS12_381_MlResult -> BuiltinBLS12_381_MlResult -> Bool #

Performs the final verification step of a pairing check. Returns true if e(P,Q) == e(R,S) for the given Miller loop results, and never fails.

integerToByteString :: Bool -> BuiltinInteger -> BuiltinInteger -> BuiltinByteString #

Converts the given integer to a bytestring. The first argument specifies endianness (True for big-endian), followed by the target length of the resulting bytestring and the integer itself. Fails if the target length is greater than 8192 or if the length argument is 0 and the result won't fit into 8192 bytes. See integerToByteString for its invariants in detail.

byteStringToInteger :: Bool -> BuiltinByteString -> BuiltinInteger #

Converts the given bytestring to the integer and never fails. The first argument specifies endianness (True for big-endian), followed by the bytestring.

shiftByteString :: BuiltinByteString -> BuiltinInteger -> BuiltinByteString #

Shifts the bytestring to the left if the second argument is positive, and to the right otherwise. Right-shifts fill with 0s from the left (logical shift); left-shifts fill with 0s from the right. Never fails.

rotateByteString :: BuiltinByteString -> BuiltinInteger -> BuiltinByteString #

Rotates the bytestring to the left if the second argument is positive, and to the right otherwise. Never fails.

countSetBits :: BuiltinByteString -> BuiltinInteger #

Counts the number of bits set to 1 in the bytestring and never fails.

findFirstSetBit :: BuiltinByteString -> BuiltinInteger #

Finds the index of the first bit set to 1 in the bytestring. If the bytestring consists only of 0s, it returns the length of the bytestring in bits. Never fails.

andByteString :: Bool -> BuiltinByteString -> BuiltinByteString -> BuiltinByteString #

Performs a bitwise AND on two bytestrings. The first boolean argument indicates whether to use padding (True) or truncation (False) if the bytestrings have different lengths. Never fails.

orByteString :: Bool -> BuiltinByteString -> BuiltinByteString -> BuiltinByteString #

Performs a bitwise OR on two bytestrings. The first boolean argument indicates whether to use padding (True) or truncation (False) if the bytestrings have different lengths. Never fails.

xorByteString :: Bool -> BuiltinByteString -> BuiltinByteString -> BuiltinByteString #

Performs a bitwise XOR on two bytestrings. The first boolean argument indicates whether to use padding (True) or truncation (False) if the bytestrings have different lengths. Never fails.

complementByteString :: BuiltinByteString -> BuiltinByteString #

Performs a bitwise complement on the bytestring and never fails.

readBit :: BuiltinByteString -> BuiltinInteger -> Bool #

Reads the bit at the given index in the bytestring. Fails if the index is out of bounds.

writeBits :: BuiltinByteString -> BuiltinList BuiltinInteger -> Bool -> BuiltinByteString #

Writes the given bit (third argument, True for 1, False for 0) at the specified indices (second argument) in the bytestring. Fails if any index is out of bounds.

replicateByte :: BuiltinInteger -> BuiltinInteger -> BuiltinByteString #

Creates a bytestring of a given length by repeating the given byte. Fails if the byte, second argument, is not in range [0,255], the length is negative, or when the length is greater than 8192.

expModInteger :: BuiltinInteger -> BuiltinInteger -> BuiltinInteger -> BuiltinInteger #

Computes modular exponentiation (base^exponent mod modulus). Fails if the modulus is zero or negative, or if the exponent is negative and the modular inverse does not exist.

insertCoin :: BuiltinByteString -> BuiltinByteString -> BuiltinInteger -> BuiltinValue -> BuiltinValue #

lookupCoin :: BuiltinByteString -> BuiltinByteString -> BuiltinValue -> Integer #

unionValue :: BuiltinValue -> BuiltinValue -> BuiltinValue #

valueContains :: BuiltinValue -> BuiltinValue -> Bool #

mkValue :: BuiltinValue -> BuiltinData #

unsafeDataAsValue :: BuiltinData -> BuiltinValue #

scaleValue :: Integer -> BuiltinValue -> BuiltinValue #

caseInteger :: Integer -> [a] -> a #

casePair :: forall a b r. BuiltinPair a b -> (a -> b -> r) -> r #

Case matching on a builtin pair. Continuation is needed here to make it more efficient on builtin-casing implementation.