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!
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,
BuiltinTypeis referred to justTypein the table. SoIntegeractually refers toBuiltinInteger.BuiltinUnitis 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.