Skip to content

Latest commit

 

History

History
82 lines (72 loc) · 26.5 KB

builtin-functions.md

File metadata and controls

82 lines (72 loc) · 26.5 KB
Raw

Plutus Core Builtin Functions Reference

This document serves as a reference to the Plutus Core builtin functions, aka DefaultFun. It is primarily meant for Pluto users and Plutarch developers/contributors. As such, it contains information about forcing. That is, how many times each of these builtins need to be forced to actually use them.

Note: If you spot any mistakes/have any related questions that this guide lacks the answer to, please don't hesitate to raise an issue. The goal is to have high quality documentation for Pluto and Plutarch users!

Cross Reference

Note: The "Type" column of the table below is primarily for documentation reasons. After all, it's all Untyped Plutus Core. However, most of these types do need to be adhered to. There are a few cases where some flexibility allowed. These cases will be noted on the table itself.

Note: For brevity, BuiltinType is referred to just Type in the table. So Integer actually refers to BuiltinInteger. BuiltinUnit is written as ().

Note: Plutarch either provides direct synonyms to these builtin functions, or provides a safer wrapper around them. Consult the Plutarch guide. However, if you must to use the builtins directly in Plutarch, see Plutus Core Builtins section on the Plutarch guide.

DefaultFun Type Forces Description Pluto Usage
AddInteger Integer -> Integer -> Integer 0 Sum 2 integers and return the result. AddInteger 1 2 -- 3
SubtractInteger Integer -> Integer -> Integer 0 Subtract fist integer by second and return the result. SubtractInteger 5 2 -- 3
MultiplyInteger Integer -> Integer -> Integer 0 Multiply 2 integers and return the result. MultiplyInteger 3 3 -- 9
DivideInteger Integer -> Integer -> Integer 0 Divide first integer by second and return the result. DivideInteger 6 2 -- 3
QuotientInteger Integer -> Integer -> Integer 0 Quotient of first integer by second and return the result. QuotientInteger 5 2 -- 2
RemainderInteger Integer -> Integer -> Integer 0 Remainder of first integer by second and return the result. RemainderInteger 5 2 -- 1
ModInteger Integer -> Integer -> Integer 0 Modulus of first integer by second and return the result. ModInteger 5 2 -- 1
EqualsInteger Integer -> Integer -> Bool 0 Equality between two integers. EqualsInteger 1 1 -- True
LessThanInteger Integer -> Integer -> Bool 0 LT comparison between two integers. LessThanInteger 1 3 -- True
LessThanEqualsInteger Integer -> Integer -> Bool 0 LTE comparison between two integers. LessThanEqualsInteger 1 1 -- True
AppendByteString ByteString -> ByteString -> ByteString 0 Concatenate two bytestrings. AppendByteString 0xfe 0xab -- 0xfeab
ConsByteString Integer -> ByteString -> ByteString 0 Prepend a byte, represented by a natural number (Integer), to a bytestring. ConsByteString 65 0xab -- 0x41ab
SliceByteString Integer -> Integer -> ByteString -> ByteString 0 Slice a bytestring using given indices (inclusive on both ends). SliceByteString 1 3 0x4102afde5b2a -- 0x02afde
LengthOfByteString1 ByteString -> Integer 0 Get the length of a bytestring. LengthByteString 0x4102afde5b2a -- 6
IndexByteString ByteString -> Integer -> Integer 0 Get the byte at given index from a bytestring. IndexByteString 0x4102afde5b2a 2 -- 175
EqualsByteString ByteString -> ByteString -> Bool 0 Equality between two bytestrings. EqualsByteString 0xab 0xab -- True
LessThanByteString ByteString -> ByteString -> Bool 0 LT comparison between two bytestrings. LessThanByteString 0x10 0xab -- True
LessThanEqualsByteString2 ByteString -> ByteString -> Bool 0 LTE comparison between two bytestrings. LessThanEqualByteString 0x10 0x10 -- True
Sha2_256 ByteString -> PByteString 0 Hash a bytestring using SHA-256.
Sha3_256 ByteString -> PByteString 0 Hash a bytestring using SHA3-256.
Blake2b_256 ByteString -> ByteString 0 Hash a bytestring using Blake2B-25.
VerifySignature ByteString :--> ByteString :--> ByteString :--> PBool 0 Given PubKey, Message, and Signature, verify the signature.
AppendString String -> String -> String 0 Concatenate two strings/texts. AppendString "foo" "bar" -- "foobar"
EqualsString String -> String -> Bool 0 Equality between two strings/texts. EqualsString "foo" "foo" -- True
EncodeUtf8 String -> ByteString 0 Encode a string/text using UTF-8.
DecodeUtf8 ByteString -> String 0 Decode a bytestring using UTF-8.
IfThenElse Bool -> a -> a -> a3 1 if-then-else as a function. Both branches are strictly evaluated, since UPLC is strict. ! IfThenElse True 42 7 -- 42
ChooseUnit () -> a -> a 1 "Choose" (catamorphism) on the unit type. Since the unit type has only one representation - it just has one branch. ! ChooseUnit () 42 -- 42
Trace String -> a -> a 1 Log the message given by the first argument and return the second argument. ! Trace "foo" 1 -- 1
FstPair Pair a b -> a 2 Get the first member of the pair. ! ! FstPair (MkPairData (data 1) (data [42, 0xfe])) -- data 1
SndPair Pair a b -> a 2 Get the second member of the pair. ! ! SndPair (MkPairData (data 1) (data [42, 0xfe])) -- data [42, 0xfe]
ChooseList List a -> b -> b -> b3 2 "Choose" (catamorphism) on a builtin list. Return the second argument if list was empty/nil, otherwise return the third argument. As usual, both arguments are evaluated before choosing. ! ! ChooseList (MkNilData ()) 0x41 0xab -- 0x41
MkCons a -> List a -> List a 1 Prepend an element onto a list. The list element type must be the same as the 1st arg type. ! MkCons (data 1) (MkNilData ()) -- [data 1]
HeadList List a -> a 1 Get the first element of a list. Errors if list is empty. ! HeadList (! MkCons (data 1) (MkNilData ())) -- data 1
TailList List a -> List a 1 Get the tail of a list (i.e everything but the first element). Errors if list is empty. ! TailList (! MkCons (data 1) (MkNilData ())) -- []
NullList List a -> Bool 1 Returns True if given list is empty. ! NullList (MkNilData ())
ChooseData Data -> a -> a -> a -> a -> a -> a3 1 "Choose" (catamorphism) on Data. It has 5 branches. The first branch (second argument) is returned for Constr, the second branch for Map, the third for List, the fourth for I, and finally, the fifth for B. As usual, all arguments are evaluated before choosing. ! ChooseData (data 0xbc) 0 1 2 3 4 -- 4
ConstrData Integer -> List Data -> Data 0 Create a Constr data with a constructor id and its fields, as a builtin list of Data elements. Constrdata 0 (MkNilData ()) -- data sigma0.[]
MapData List (Pair Data Data) -> Data 0 Wrap a bytestring into a Data. Returns a B data value. MapData (MkNilPairData ()) -- data {}
ListData List Data -> Data 0 Wrap a builtin list of Data elements into a Data. Returns a List data value. ListData (! MkCons (data 1) (MkNilData ())) -- data [1]
IData Integer -> Data 0 Wrap an integer into a Data. Returns a I data value. IData 42 -- data 42
BData ByteString -> Data 0 Wrap a bytestring into a Data. Returns a B data value. BData 0xab -- data 0xab
UnConstrData Data -> Pair Integer (List Data) 0 Get the constructor id and the fields in a pair from a Constr data value. Fails if the Data isn't a Constr data. UnConstrData (data sigma0.[]) -- (0, [])
UnMapData Data -> List (Pair Data Data) 0 Extract a List (Pair Data Data) from a Map data value. Fails if the Data isn't a Map data. UnMapData (data { 0xab = 1 }) -- [(0xab, 1)]
UnListData Data -> List Data 0 Extract a List Data from a List data value. Fails if the Data isn't a List data. UnListData (data [1]) -- [data 1]
UnIData Data -> Integer 0 Extract a Integer from a I data value. Fails if the Data isn't a I data. UnIData (data 42) -- 42
UnBData Data -> ByteString 0 Extract a ByteString from a B data value. Fails if the Data isn't a B data. UnBData (data 0xab) -- 0xab
EqualsData Data -> Data -> Bool 0 Equality between two data values. EqualsData (data [5, 0xab]) (data [5, 0xab]) -- True
MkPairData Data -> Data -> Pair Data Data 0 Make a pair of Data values. MkPairData (data 1) (data [42, 0xfe]) -- (data 1, data [42, 0xfe])
MkNilData () -> List Data 0 Make a nil list of Data. MkNilData () -- []
MkNilPairData () -> List (Pair Data Data) 0 Make a nil list of Pair Data Data. MkNilPairData () -- []

1: LengthOfByteString is called LengthByteString in Pluto.

2: LessThanEqualsByteString is called LessThanEqualByteString in Pluto.

3: This can actually take in different types for its branches. The type of one branch could be Integer, whereas the other could be Data, and so on.

Useful Links