docs
API
Generated with
docs/scalus/scalus.uplc/scalus.uplc.builtin/Builtins

Builtins

scalus.uplc.builtin.Builtins
See theBuiltins companion class
object Builtins extends Builtins

Attributes

Companion
class
Graph
Supertypes
class Builtins
class Object
trait Matchable
class Any
Self type
Builtins.type

Members list

Value members

Inherited methods

def addInteger(i1: BigInt, i2: BigInt): BigInt

Add two arbitrary-precision integers.

Add two arbitrary-precision integers.

Attributes

Example

addInteger(3, 5) == 8

Inherited from:
AbstractBuiltins (hidden)
def andByteString(shouldPad: Boolean, lhs: ByteString, rhs: ByteString): ByteString

Bitwise logical AND for ByteStrings.

Bitwise logical AND for ByteStrings.

Value parameters

lhs

The left-hand side ByteString.

rhs

The right-hand side ByteString.

shouldPad

Indicates whether to truncate the result to the length of the shorter input, or to pad with the remaining values from the longer one.

Attributes

Returns

The result of the bitwise AND operation.

See also

CIP-122. Performs a logical bitwise AND operation on each byte between two ByteStrings sequentially and returns the result(Formally result[i] = lhs[i] & rhs[i]). The argument shouldPad determines what to do in the case when ByteStrings are of different lengths. If shouldPad is false, the result will be the length of the shorter input. Otherwise, the result will be padded with the remaining values from the longer input.

Example

andByteString(false, hex"0FFF", hex"FF") == hex"0F"

andByteString(true, hex"0FFF", hex"FF") == hex"0FFF"

Inherited from:
AbstractBuiltins (hidden)
def appendByteString(a: ByteString, b: ByteString): ByteString

Concatenate two bytestrings.

Concatenate two bytestrings.

Attributes

Example

appendByteString(hex"1234", hex"5678") == hex"12345678"

Inherited from:
AbstractBuiltins (hidden)
def appendString(s1: String, s2: String): String

Concatenate two strings.

Concatenate two strings.

Attributes

Example

appendString("Hello, ", "World!") == "Hello, World!"

Inherited from:
AbstractBuiltins (hidden)
def bData(value: ByteString): Data

Construct a Data.B (bytestring) value.

Construct a Data.B (bytestring) value.

Attributes

Inherited from:
AbstractBuiltins (hidden)
def blake2b_224(bs: ByteString): ByteString

Compute BLAKE2b-224 hash.

Compute BLAKE2b-224 hash.

Attributes

Returns

a 28-byte (224-bit) hash digest

Inherited from:
AbstractBuiltins (hidden)
def blake2b_256(bs: ByteString): ByteString

Compute BLAKE2b-256 hash.

Compute BLAKE2b-256 hash.

This is the primary hash function used in Cardano for script hashing and transaction IDs.

Attributes

Returns

a 32-byte (256-bit) hash digest

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G1_add(p1: G1Element, p2: G1Element): G1Element

Add two points in the G1 group.

Add two points in the G1 group.

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G1_compress(p: G1Element): ByteString

Compress a G1 point to its 48-byte compressed form.

Compress a G1 point to its 48-byte compressed form.

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G1_equal(p1: G1Element, p2: G1Element): Boolean

Check if two G1 points are equal.

Check if two G1 points are equal.

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G1_hashToGroup(bs: ByteString, dst: ByteString): G1Element

Hash a bytestring to a G1 point using the specified domain separation tag.

Hash a bytestring to a G1 point using the specified domain separation tag.

Value parameters

bs

the bytestring to hash

dst

domain separation tag (up to 255 bytes)

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G1_multiScalarMul(scalars: Seq[BigInt], points: Seq[G1Element]): G1Element

Multi-scalar multiplication on G1.

Multi-scalar multiplication on G1.

Computes ∑(i=0 to N-1) scalar_i × point_i efficiently using Pippenger's algorithm. Both input lists must be non-empty and have equal length.

Value parameters

points

List of G1 group elements

scalars

List of scalars (integers)

Attributes

Returns

The sum of scalar multiplications

Throws
scalus.uplc.eval.BuiltinException

if either list is empty or lists have different lengths

Since

Plutus V4 (CIP-133)

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G1_neg(p: G1Element): G1Element

Negate a G1 point.

Negate a G1 point.

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G1_scalarMul(s: BigInt, p: G1Element): G1Element

Scalar multiplication of a G1 point.

Scalar multiplication of a G1 point.

Equivalent to repeated addition of the point with itself s times.

Value parameters

p

the point to multiply

s

the scalar multiplier

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G1_uncompress(bs: ByteString): G1Element

Uncompress a 48-byte compressed G1 point.

Uncompress a 48-byte compressed G1 point.

Attributes

Throws
scalus.uplc.eval.BuiltinException

if the bytestring is not a valid compressed G1 point

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G2_add(p1: G2Element, p2: G2Element): G2Element

Add two points in the G2 group.

Add two points in the G2 group.

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G2_compress(p: G2Element): ByteString

Compress a G2 point to its 96-byte compressed form.

Compress a G2 point to its 96-byte compressed form.

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G2_compressed_generator: ByteString

The compressed form of the generator point in G2, 96 bytes long.

The compressed form of the generator point in G2, 96 bytes long.

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G2_compressed_zero: ByteString

The compressed form of the point at infinity (zero) in G2, 96 bytes long.

The compressed form of the point at infinity (zero) in G2, 96 bytes long.

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G2_equal(p1: G2Element, p2: G2Element): Boolean

Check if two G2 points are equal.

Check if two G2 points are equal.

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G2_hashToGroup(bs: ByteString, dst: ByteString): G2Element

Hash a bytestring to a G2 point using the specified domain separation tag.

Hash a bytestring to a G2 point using the specified domain separation tag.

Value parameters

bs

the bytestring to hash

dst

domain separation tag (up to 255 bytes)

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G2_multiScalarMul(scalars: Seq[BigInt], points: Seq[G2Element]): G2Element

Multi-scalar multiplication on G2.

Multi-scalar multiplication on G2.

Computes ∑(i=0 to N-1) scalar_i × point_i efficiently using Pippenger's algorithm. Both input lists must be non-empty and have equal length.

Value parameters

points

List of G2 group elements

scalars

List of scalars (integers)

Attributes

Returns

The sum of scalar multiplications

Throws
scalus.uplc.eval.BuiltinException

if either list is empty or lists have different lengths

Since

Plutus V4 (CIP-133)

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G2_neg(p: G2Element): G2Element

Negate a G2 point.

Negate a G2 point.

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G2_scalarMul(s: BigInt, p: G2Element): G2Element

Scalar multiplication of a G2 point.

Scalar multiplication of a G2 point.

Equivalent to repeated addition of the point with itself s times.

Value parameters

p

the point to multiply

s

the scalar multiplier

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_G2_uncompress(bs: ByteString): G2Element

Uncompress a 96-byte compressed G2 point.

Uncompress a 96-byte compressed G2 point.

Attributes

Throws
scalus.uplc.eval.BuiltinException

if the bytestring is not a valid compressed G2 point

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_finalVerify(p1: MLResult, p2: MLResult): Boolean

Final verification step for pairing equality check.

Final verification step for pairing equality check.

Returns true if e(P1, Q1) == e(P2, Q2) where r1 = millerLoop(P1, Q1) and r2 = millerLoop(P2, Q2).

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_millerLoop(p1: G1Element, p2: G2Element): MLResult

Compute the Miller loop for a pairing.

Compute the Miller loop for a pairing.

This is the first step in computing a bilinear pairing e(P, Q) where P is in G1 and Q is in G2.

Value parameters

p1

a point in G1

p2

a point in G2

Attributes

Returns

an intermediate Miller loop result

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def bls12_381_mulMlResult(r1: MLResult, r2: MLResult): MLResult

Multiply two Miller loop results.

Multiply two Miller loop results.

Used to combine multiple pairings: e(P1,Q1) * e(P2,Q2) = mulMlResult(millerLoop(P1,Q1), millerLoop(P2,Q2))

Attributes

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def byteStringToInteger(endianness: Boolean, input: ByteString): BigInt

Convert a ByteString into a non-negative BigInt.

Convert a ByteString into a non-negative BigInt.

Leading zero bytes are ignored. The interpretation is unsigned.

Value parameters

input

The byte string to convert. Empty or all-zero strings yield 0.

statedEndiannessArg

true for big-endian interpretation, false for little-endian interpretation.

Attributes

Returns

The unsigned integer represented by the input bytes.

See also
Note

This function mirrors integerToByteString.

Example 
 // Big-endian
 byteStringToInteger(true, hex"1234") == 4660
 // Little-endian
 byteStringToInteger(false, hex"3412") == 4660
 // Leading zeros ignored
 byteStringToInteger(true,  hex"001234") == 4660
Inherited from:
AbstractBuiltins (hidden)
def chooseData[A](d: Data, constrCase: A, mapCase: A, listCase: A, iCase: A, bCase: A): A

Pattern match on a Data value by its constructor type.

Pattern match on a Data value by its constructor type.

Returns one of five values depending on the Data constructor: Constr, Map, List, I (integer), or B (bytestring).

Value parameters

bCase

value to return if d is a ByteString

constrCase

value to return if d is a Constr

d

the Data value to match

iCase

value to return if d is an Integer

listCase

value to return if d is a List

mapCase

value to return if d is a Map

Attributes

Inherited from:
AbstractBuiltins (hidden)
def chooseList[A, B](l: BuiltinList[A], e: B, ne: B): B

Pattern match on a list - return one value for empty, another for non-empty.

Pattern match on a list - return one value for empty, another for non-empty.

Value parameters

e

value to return if the list is empty

l

the list to match on

ne

value to return if the list is non-empty

Attributes

Inherited from:
AbstractBuiltins (hidden)
def chooseUnit[A]()(a: A): A

Choose based on unit value.

Choose based on unit value.

Always returns the argument after consuming the unit input.

Attributes

Inherited from:
AbstractBuiltins (hidden)
def complementByteString(byteString: ByteString): ByteString

Bitwise logical ComplementByteString for ByteStrings.

Bitwise logical ComplementByteString for ByteStrings.

Value parameters

byteString

The ByteString that to be bitwise logical completed(inverted).

Attributes

Returns

The result of the bitwise logical ComplementByteString operation.

See also

[CIP-122] (https://github.com/cardano-foundation/CIPs/tree/master/CIP-0122). Performs a bitwise logical ComplementByteString operation on the input ByteString by inverting each bit (Formally resultBit[i] = if inputBit[i] == 0 then 1 else 0).

Example

complementByteString(hex"FF") == hex"00"

complementByteString(hex"F0") == hex"0F"

Inherited from:
AbstractBuiltins (hidden)
def consByteString(char: BigInt, byteString: ByteString): ByteString

Prepend a byte to a bytestring.

Prepend a byte to a bytestring.

Value parameters

byteString

the bytestring to prepend to

char

the byte value to prepend, must be in range [0, 255]

Attributes

Throws
scalus.uplc.eval.BuiltinException

if byte value is outside [0, 255]

Example

consByteString(0x12, hex"3456") == hex"123456"

Inherited from:
AbstractBuiltins (hidden)
def constrData(ctor: BigInt, args: BuiltinList[Data]): Data

Construct a Data.Constr value.

Construct a Data.Constr value.

Value parameters

args

list of constructor arguments

ctor

constructor index (must be non-negative)

Attributes

Inherited from:
AbstractBuiltins (hidden)
def countSetBits(byteString: ByteString): BigInt

Bitwise logical countSetBits for ByteStrings.

Bitwise logical countSetBits for ByteStrings.

Value parameters

byteString

The ByteString to be counted.

Attributes

Returns

The number of set bits in the ByteString.

See also

[CIP-123] (https://github.com/cardano-foundation/CIPs/tree/master/CIP-0123). Counts the number of set bits in the input ByteString.

Example

countSetBits(hex"000F") == 4

countSetBits(hex"0000") == 0

countSetBits(hex"0001") == 1

Inherited from:
AbstractBuiltins (hidden)
def decodeUtf8(bs: ByteString): String

Decode UTF-8 bytes to a string.

Decode UTF-8 bytes to a string.

Attributes

Throws
java.lang.IllegalArgumentException

if the bytestring is not valid UTF-8

Inherited from:
AbstractBuiltins (hidden)
def divideInteger(i1: BigInt, i2: BigInt): BigInt

Divide two integers using floor division (truncate toward negative infinity).

Divide two integers using floor division (truncate toward negative infinity).

For negative dividends with positive divisors (or vice versa), this differs from truncated division (quotientInteger) by rounding toward negative infinity.

Attributes

Throws
java.lang.ArithmeticException

if divisor is zero

Example

divideInteger(7, 2) == 3

divideInteger(-7, 2) == -4 // floor division

Inherited from:
AbstractBuiltins (hidden)
def dropList[A](n: BigInt, l: BuiltinList[A]): BuiltinList[A]

Drop the first n elements from a list.

Drop the first n elements from a list.

If n is negative, no elements are dropped. If n is larger than the list length, an empty list is returned.

Attributes

Inherited from:
AbstractBuiltins (hidden)
def encodeUtf8(s: String): ByteString

Encode a string as UTF-8 bytes.

Encode a string as UTF-8 bytes.

Attributes

Example

encodeUtf8("hello") == hex"68656c6c6f"

Inherited from:
AbstractBuiltins (hidden)
def equalsByteString(a: ByteString, b: ByteString): Boolean

Check if two bytestrings are equal.

Check if two bytestrings are equal.

Attributes

Example

equalsByteString(hex"1234", hex"1234") == true

Inherited from:
AbstractBuiltins (hidden)
def equalsData(d1: Data, d2: Data): Boolean

Check if two Data values are structurally equal.

Check if two Data values are structurally equal.

Attributes

Inherited from:
AbstractBuiltins (hidden)
def equalsInteger(i1: BigInt, i2: BigInt): Boolean

Check if two integers are equal.

Check if two integers are equal.

Attributes

Example

equalsInteger(5, 5) == true

Inherited from:
AbstractBuiltins (hidden)
def equalsString(s1: String, s2: String): Boolean

Check if two strings are equal.

Check if two strings are equal.

Attributes

Inherited from:
AbstractBuiltins (hidden)
def expModInteger(base: BigInt, exponent: BigInt, modulus: BigInt): BigInt

Compute modular exponentiation: base^exponent mod modulus.

Compute modular exponentiation: base^exponent mod modulus.

Supports negative exponents via modular inverse.

Value parameters

base

the base integer

exponent

the exponent (can be negative if base is invertible mod modulus)

modulus

the modulus (must be positive)

Attributes

Returns

base^exponent mod modulus as a non-negative integer

Throws
scalus.uplc.eval.BuiltinException

if modulus <= 0, or if exponent < 0 and base is not invertible mod modulus

Example

expModInteger(2, 10, 1000) == 24 // 2^10 mod 1000

expModInteger(3, -1, 7) == 5 // modular inverse of 3 mod 7

Inherited from:
AbstractBuiltins (hidden)
def findFirstSetBit(byteString: ByteString): BigInt

Bitwise logical findFirstSetBit for ByteStrings.

Bitwise logical findFirstSetBit for ByteStrings.

Value parameters

byteString

The ByteString to be searched.

Attributes

Returns

The index of the first set bit in the ByteString from the end.

See also

[CIP-123] (https://github.com/cardano-foundation/CIPs/tree/master/CIP-0123). Finds the index of the first set bit in the input ByteString. The index is zero-based and starts from the end of the ByteString. If no set bits are found, -1 is returned.

Example

findFirstSetBit(hex"") == -1

findFirstSetBit(hex"0000") == -1

findFirstSetBit(hex"0002") == 1

findFirstSetBit(hex"FFF2") == 1

Inherited from:
AbstractBuiltins (hidden)
def fstPair[A, B](p: BuiltinPair[A, B]): A

Extract the first element of a pair.

Extract the first element of a pair.

Attributes

Inherited from:
AbstractBuiltins (hidden)
def headList[A](l: BuiltinList[A]): A

Get the first element of a list.

Get the first element of a list.

Attributes

Throws
java.util.NoSuchElementException

if the list is empty

Inherited from:
AbstractBuiltins (hidden)
def iData(value: BigInt): Data

Construct a Data.I (integer) value.

Construct a Data.I (integer) value.

Attributes

Inherited from:
AbstractBuiltins (hidden)
def ifThenElse[A](cond: Boolean, a: A, b: A): A

Conditional expression (if-then-else).

Conditional expression (if-then-else).

Returns the second argument if the condition is true, third argument otherwise.

Attributes

Example

ifThenElse(true, "yes", "no") == "yes"

Inherited from:
AbstractBuiltins (hidden)
def indexArray[A](a: BuiltinArray[A], n: BigInt): A

Access an element by index.

Access an element by index.

Attributes

Throws
IndexOutOfBoundsException

if index is out of bounds

Inherited from:
AbstractBuiltins (hidden)
def indexByteString(bs: ByteString, i: BigInt): BigInt

Returns the byte at the specified index in the ByteString

Returns the byte at the specified index in the ByteString

Attributes

Throws
scalus.uplc.eval.BuiltinException

if the index is out of bounds (offchain)

Inherited from:
AbstractBuiltins (hidden)
def insertCoin(currency: ByteString, token: ByteString, amount: BigInt, value: BuiltinValue): BuiltinValue

Insert or update a token amount in a value.

Insert or update a token amount in a value.

Value parameters

amount

The amount to set. Use 0 to remove the token.

currency

The currency symbol (policy ID), max 32 bytes.

token

The token name, max 32 bytes.

value

The value to modify.

Attributes

Returns

A new value with the token inserted/updated.

Inherited from:
AbstractBuiltins (hidden)
def integerToByteString(endianness: Boolean, length: BigInt, input: BigInt): ByteString

Convert a BigInt into a ByteString.

Convert a BigInt into a ByteString.

The conversion uses fixed-width output and explicit endianness. If lengthArg is 0, the result is a minimal-length encoding.

Value parameters

endiannessArg

true for big-endian output, false for little-endian output.

input

Unsigned integer to convert. Negative integers are rejected.

lengthArg

Desired output length in bytes. If zero, the result is minimally sized. If positive, the output must fit into the exact width, otherwise an exception is thrown.

Attributes

Returns

A byte string encoded with the requested width and endianness.

Throws
scalus.uplc.eval.BuiltinException

If the requested length is negative, exceeds the maximum, or the integer cannot be represented in the requested number of bytes.

See also
Example 
 // Big-endian, length 2:
 integerToByteString(true, 2, 4660) == hex"1234"
 // Little-endian, length 2:
 integerToByteString(false, 2, 4660) == hex"3412"
 // Minimal representation:
 integerToByteString(true, 0, 4660) == hex"1234"
Inherited from:
AbstractBuiltins (hidden)
def keccak_256(bs: ByteString): ByteString

Compute Keccak-256 hash.

Compute Keccak-256 hash.

This is the original Keccak hash (as used in Ethereum), not the NIST SHA-3 standard.

Attributes

Returns

a 32-byte (256-bit) hash digest

See also
Since

Plutus V3

Inherited from:
AbstractBuiltins (hidden)
def lengthOfArray[A](a: BuiltinArray[A]): BigInt

Get the length of an array.

Get the length of an array.

Attributes

Inherited from:
AbstractBuiltins (hidden)
def lengthOfByteString(bs: ByteString): BigInt

Returns the length of the ByteString

Returns the length of the ByteString

Attributes

Inherited from:
AbstractBuiltins (hidden)
def lessThanByteString(a: ByteString, b: ByteString): Boolean

Check if one bytestring is lexicographically less than another.

Check if one bytestring is lexicographically less than another.

Comparison is byte-by-byte, treating bytes as unsigned. Shorter bytestrings are considered less than longer ones with the same prefix.

Attributes

Example

lessThanByteString(hex"12", hex"1234") == true

Inherited from:
AbstractBuiltins (hidden)
def lessThanEqualsByteString(a: ByteString, b: ByteString): Boolean

Check if one bytestring is lexicographically less than or equal to another.

Check if one bytestring is lexicographically less than or equal to another.

Attributes

Example

lessThanEqualsByteString(hex"1234", hex"1234") == true

Inherited from:
AbstractBuiltins (hidden)
def lessThanEqualsInteger(i1: BigInt, i2: BigInt): Boolean

Check if the first integer is less than or equal to the second.

Check if the first integer is less than or equal to the second.

Attributes

Example

lessThanEqualsInteger(5, 5) == true

Inherited from:
AbstractBuiltins (hidden)
def lessThanInteger(i1: BigInt, i2: BigInt): Boolean

Check if the first integer is strictly less than the second.

Check if the first integer is strictly less than the second.

Attributes

Example

lessThanInteger(3, 5) == true

Inherited from:
AbstractBuiltins (hidden)
def listData(values: BuiltinList[Data]): Data

Construct a Data.List value.

Construct a Data.List value.

Value parameters

values

list of Data elements

Attributes

Inherited from:
AbstractBuiltins (hidden)
def listToArray[A](a: BuiltinList[A]): BuiltinArray[A]

Convert a list to an array for O(1) indexed access.

Convert a list to an array for O(1) indexed access.

Attributes

Inherited from:
AbstractBuiltins (hidden)
def lookupCoin(currency: ByteString, token: ByteString, value: BuiltinValue): BigInt

Lookup a token amount in a value.

Lookup a token amount in a value.

Value parameters

currency

The currency symbol (policy ID).

token

The token name.

value

The value to search.

Attributes

Returns

The amount of the token, or 0 if not found.

Inherited from:
AbstractBuiltins (hidden)
def mapData(values: BuiltinList[BuiltinPair[Data, Data]]): Data

Construct a Data.Map value.

Construct a Data.Map value.

Value parameters

values

list of key-value pairs

Attributes

Inherited from:
AbstractBuiltins (hidden)
def mkCons[A](a: A, l: BuiltinList[A]): BuiltinList[A]

Prepend an element to a list.

Prepend an element to a list.

Attributes

Example

mkCons(1, BuiltinList(2, 3)) == BuiltinList(1, 2, 3)

Inherited from:
AbstractBuiltins (hidden)
def mkNilData(): BuiltinList[Data]

Create an empty list of Data values.

Create an empty list of Data values.

This is a monomorphic constructor for empty lists of Data.

Attributes

Inherited from:
AbstractBuiltins (hidden)
def mkNilPairData(): BuiltinList[BuiltinPair[Data, Data]]

Create an empty list of Data pairs.

Create an empty list of Data pairs.

This is a monomorphic constructor for empty lists of Data pairs, useful for building Maps.

Attributes

Inherited from:
AbstractBuiltins (hidden)
def mkPairData(fst: Data, snd: Data): BuiltinPair[Data, Data]

Create a pair of Data values.

Create a pair of Data values.

This is a monomorphic constructor for pairs of Data.

Attributes

Inherited from:
AbstractBuiltins (hidden)
def modInteger(i1: BigInt, i2: BigInt): BigInt

Compute the modulus after floor division (divideInteger).

Compute the modulus after floor division (divideInteger).

The result has the same sign as the divisor. Satisfies: dividend == divideInteger(dividend, divisor) * divisor + modInteger(dividend, divisor)

Attributes

Throws
java.lang.ArithmeticException

if divisor is zero

Example

modInteger(7, 3) == 1

modInteger(-7, 3) == 2 // result has sign of divisor

Inherited from:
AbstractBuiltins (hidden)
def multiIndexArray[A](indices: BuiltinList[BigInt], arr: BuiltinArray[A]): BuiltinList[A]

Multi-index array access from CIP-0156.

Multi-index array access from CIP-0156.

Retrieves elements from an array at the specified indices.

Value parameters

arr

The array to index.

indices

A list of zero-based indices, in the order elements should be retrieved. In case of repeated indices, the same element is returned multiple times.

Attributes

Returns

A list containing the elements at the specified indices, in the same order.

Throws
scalus.uplc.eval.BuiltinException

If any index is out of bounds (< 0 or >= lengthOfArray).

Example 
 val arr = listToArray(mkCons(iData(10), mkCons(iData(20), mkCons(iData(30), mkNilData()))))
 multiIndexArray(BuiltinList[BigInt](0, 2), arr)
 // returns BuiltinList(iData(10), iData(30))
Inherited from:
AbstractBuiltins (hidden)
def multiplyInteger(i1: BigInt, i2: BigInt): BigInt

Multiply two arbitrary-precision integers.

Multiply two arbitrary-precision integers.

Attributes

Example

multiplyInteger(4, 5) == 20

Inherited from:
AbstractBuiltins (hidden)
def nullList[A](l: BuiltinList[A]): Boolean

Check if a list is empty.

Check if a list is empty.

Attributes

Example

nullList(BuiltinList.empty) == true

Inherited from:
AbstractBuiltins (hidden)
def orByteString(shouldPad: Boolean, lhs: ByteString, rhs: ByteString): ByteString

Bitwise logical OR for ByteStrings.

Bitwise logical OR for ByteStrings.

Value parameters

lhs

The left-hand side ByteString.

rhs

The right-hand side ByteString.

shouldPad

Indicates whether to truncate the result to the length of the shorter input, or to pad with the remaining values from the longer one.

Attributes

Returns

The result of the bitwise OR operation.

See also

CIP-122. Performs a logical bitwise OR operation on each byte between two ByteStrings sequentially and returns the result(Formally result[i] = lhs[i] | rhs[i]). The argument shouldPad determines what to do in the case when ByteStrings are of different lengths. If shouldPad is false, the result will be the length of the shorter input. Otherwise, the result will be padded with the remaining values from the longer input.

Example

orByteString(false, hex"0FFF", hex"FF") == hex"FF"

orByteString(true, hex"0FFF", hex"FF") == hex"FFFF"

Inherited from:
AbstractBuiltins (hidden)
def quotientInteger(i1: BigInt, i2: BigInt): BigInt

Compute the quotient of two integers (truncate toward zero).

Compute the quotient of two integers (truncate toward zero).

This is standard truncated division, which rounds toward zero.

Attributes

Throws
java.lang.ArithmeticException

if divisor is zero

Example

quotientInteger(7, 2) == 3

quotientInteger(-7, 2) == -3 // truncated toward zero

Inherited from:
AbstractBuiltins (hidden)
def readBit(byteString: ByteString, index: BigInt): Boolean

Bitwise logical ReadBit for ByteStrings.

Bitwise logical ReadBit for ByteStrings.

Value parameters

byteString

The ByteString that contains the bit to be read.

index

The index of the bit to be read.

Attributes

Returns

The value of the bit at the specified index.

Throws
scalus.uplc.eval.BuiltinException

if the index is out of bounds.

See also

[CIP-122] (https://github.com/cardano-foundation/CIPs/tree/master/CIP-0122). Gets the value of the bit at the specified index in the input ByteString. The index must be in the range [0 .. byteString.size * 8), otherwise BuiltinException will be thrown. Bit indexing starts from the end of the ByteString.

Example

readBit(hex"0004", 2) == true

readBit(hex"0004", 15) == false

readBit(hex"0004", 16) throws BuiltinException

Inherited from:
AbstractBuiltins (hidden)
def remainderInteger(i1: BigInt, i2: BigInt): BigInt

Compute the remainder after truncated division (quotientInteger).

Compute the remainder after truncated division (quotientInteger).

The result has the same sign as the dividend. Satisfies: dividend == quotientInteger(dividend, divisor) * divisor + remainderInteger(dividend, divisor)

Attributes

Throws
java.lang.ArithmeticException

if divisor is zero

Example

remainderInteger(7, 3) == 1

remainderInteger(-7, 3) == -1

Inherited from:
AbstractBuiltins (hidden)
def replicateByte(length: BigInt, byte: BigInt): ByteString

Bitwise logical ReplicateByte for ByteStrings.

Bitwise logical ReplicateByte for ByteStrings.

Value parameters

byte

The value of the byte to be replicated.

length

The number of times to replicate the byte.

Attributes

Returns

The result of the bitwise logical ReplicateByte operation.

Throws
scalus.uplc.eval.BuiltinException

if the length is negative or the byte value is out of bounds.

See also

[CIP-122] (https://github.com/cardano-foundation/CIPs/tree/master/CIP-0122). Replicates a byte length times and returns result as ByteString. Length must be non-negative, otherwise BuiltinException will be thrown. The byte value must be in the range [0 .. 255], otherwise BuiltinException will be thrown.

Example

replicateByte(0, 0xFF) == hex""

replicateByte(4, 0xFF) == hex"FFFFFFFF"

replicateByte(-1, 255) throws BuiltinException

replicateByte(1, -1) throws BuiltinException

replicateByte(1, 256) throws BuiltinException

Inherited from:
AbstractBuiltins (hidden)
def ripemd_160(byteString: ByteString): ByteString

Hashing primitive Ripemd_160 for ByteStrings.

Hashing primitive Ripemd_160 for ByteStrings.

Value parameters

byteString

The ByteString to be hashed.

Attributes

Returns

The result of the Ripemd_160 hash function.

See also
Inherited from:
AbstractBuiltins (hidden)
def rotateByteString(byteString: ByteString, rotation: BigInt): ByteString

Bitwise logical rotateByteString for ByteStrings.

Bitwise logical rotateByteString for ByteStrings.

Value parameters

byteString

The ByteString to be rotated.

rotation

The number of bits to rotates the ByteString.

Attributes

Returns

The result of the bitwise logical rotateByteString operation.

See also

[CIP-123] (https://github.com/cardano-foundation/CIPs/tree/master/CIP-0123). Rotates the input ByteString by the specified number of bits. A positive rotation value rotates the ByteString to the left, while a negative rotation value rotates the ByteString to the right. Rotation by more than the total number of bits is the same as the remainder after division by number of bits.

Example

rotateByteString(hex"000F", 4) == hex"00F0"

rotateByteString(hex"000F", -4) == hex"F000"

rotateByteString(hex"000F", 16) == hex"000F"

rotateByteString(hex"000F", -16) == hex"000F"

Inherited from:
AbstractBuiltins (hidden)
def scaleValue(scalar: BigInt, value: BuiltinValue): BuiltinValue

Multiply all token amounts in a value by a scalar.

Multiply all token amounts in a value by a scalar.

Value parameters

scalar

The multiplier.

value

The value to scale.

Attributes

Returns

A new value with all amounts multiplied.

Inherited from:
AbstractBuiltins (hidden)
def serialiseData(d: Data): ByteString

Serialize a Data value to CBOR format.

Serialize a Data value to CBOR format.

Attributes

Returns

the CBOR-encoded bytestring

Since

Plutus V2

Inherited from:
AbstractBuiltins (hidden)
def sha2_256(bs: ByteString): ByteString

Compute SHA2-256 hash.

Compute SHA2-256 hash.

Attributes

Returns

a 32-byte (256-bit) hash digest

Inherited from:
AbstractBuiltins (hidden)
def sha3_256(bs: ByteString): ByteString

Compute SHA3-256 hash.

Compute SHA3-256 hash.

Attributes

Returns

a 32-byte (256-bit) hash digest using Keccak-based SHA3

Inherited from:
AbstractBuiltins (hidden)
def shiftByteString(byteString: ByteString, shift: BigInt): ByteString

Bitwise logical shiftByteString for ByteStrings.

Bitwise logical shiftByteString for ByteStrings.

Value parameters

byteString

The ByteString to be shifted.

shift

The number of bits to shift the ByteString.

Attributes

Returns

The result of the bitwise logical shiftByteString operation.

See also

[CIP-123] (https://github.com/cardano-foundation/CIPs/tree/master/CIP-0123). Shifts the input ByteString by the specified number of bits. A positive shift value shifts the ByteString to the left, while a negative shift value shifts the ByteString to the right.

Example

shiftByteString(hex"000F", 4) == hex"00F0"

shiftByteString(hex"000F", 16) == hex"0000"

shiftByteString(hex"000F", -4) == hex"0000"

Inherited from:
AbstractBuiltins (hidden)
def sliceByteString(from: BigInt, len: BigInt, bs: ByteString): ByteString

Returns a new ByteString that is a slice of the original ByteString

Returns a new ByteString that is a slice of the original ByteString

Value parameters

bs

the original ByteString to slice

from

the starting index of the slice (inclusive)

len

the length of the slice

Attributes

Example 
 sliceByteString(2, 4, hex"1234567890abcdef") // returns hex"567890ab"
 sliceByteString(5, 4, hex"1234567890abcdef") // returns hex"abcdef"
 sliceByteString(9, 4, hex"1234567890abcdef") // returns hex""
 sliceByteString(0, 0, hex"1234567890abcdef") // returns hex""
Inherited from:
AbstractBuiltins (hidden)
def sndPair[A, B](p: BuiltinPair[A, B]): B

Extract the second element of a pair.

Extract the second element of a pair.

Attributes

Inherited from:
AbstractBuiltins (hidden)
def subtractInteger(i1: BigInt, i2: BigInt): BigInt

Subtract two arbitrary-precision integers.

Subtract two arbitrary-precision integers.

Attributes

Example

subtractInteger(10, 3) == 7

Inherited from:
AbstractBuiltins (hidden)
def tailList[A](l: BuiltinList[A]): BuiltinList[A]

Get all elements except the first.

Get all elements except the first.

Attributes

Throws
java.util.NoSuchElementException

if the list is empty

Inherited from:
AbstractBuiltins (hidden)
def trace[A](s: String)(a: A): A

Trace a message and return a value.

Trace a message and return a value.

Logs the string message (for debugging) and returns the second argument unchanged. In on-chain execution, traces are collected but don't affect the result.

Attributes

Inherited from:
AbstractBuiltins (hidden)
def unBData(d: Data): ByteString

Deconstruct a Data.B value.

Deconstruct a Data.B value.

Attributes

Returns

the bytestring value

Throws
java.lang.Exception

if the Data is not a ByteString

Inherited from:
AbstractBuiltins (hidden)
def unConstrData(d: Data): BuiltinPair[BigInt, BuiltinList[Data]]

Deconstruct a Data.Constr value.

Deconstruct a Data.Constr value.

Attributes

Returns

a pair of (constructor index, list of arguments)

Throws
java.lang.Exception

if the Data is not a Constr

Inherited from:
AbstractBuiltins (hidden)
def unIData(d: Data): BigInt

Deconstruct a Data.I value.

Deconstruct a Data.I value.

Attributes

Returns

the integer value

Throws
java.lang.Exception

if the Data is not an Integer

Inherited from:
AbstractBuiltins (hidden)
def unListData(d: Data): BuiltinList[Data]

Deconstruct a Data.List value.

Deconstruct a Data.List value.

Attributes

Returns

the list of Data elements

Throws
java.lang.Exception

if the Data is not a List

Inherited from:
AbstractBuiltins (hidden)
def unMapData(d: Data): BuiltinList[BuiltinPair[Data, Data]]

Deconstruct a Data.Map value.

Deconstruct a Data.Map value.

Attributes

Returns

the list of key-value pairs

Throws
java.lang.Exception

if the Data is not a Map

Inherited from:
AbstractBuiltins (hidden)
def unValueData(data: Data): BuiltinValue

Convert Data to a BuiltinValue.

Convert Data to a BuiltinValue.

Value parameters

data

The data to convert. Must be in Map ByteString (Map ByteString Integer) format.

Attributes

Returns

The BuiltinValue.

Inherited from:
AbstractBuiltins (hidden)
def unionValue(v1: BuiltinValue, v2: BuiltinValue): BuiltinValue

Merge two values by adding corresponding token amounts.

Merge two values by adding corresponding token amounts.

Value parameters

v1

The first value.

v2

The second value.

Attributes

Returns

A new value with merged amounts.

Inherited from:
AbstractBuiltins (hidden)
def valueContains(v1: BuiltinValue, v2: BuiltinValue): Boolean

Check if v1 contains at least the amounts in v2.

Check if v1 contains at least the amounts in v2.

Value parameters

v1

The container value.

v2

The value to check for containment.

Attributes

Returns

true if v1 contains at least as much of every token as v2.

Inherited from:
AbstractBuiltins (hidden)
def valueData(value: BuiltinValue): Data

Convert a BuiltinValue to Data representation.

Convert a BuiltinValue to Data representation.

Value parameters

value

The value to convert.

Attributes

Returns

The Data representation of the value.

Inherited from:
AbstractBuiltins (hidden)
def verifyEcdsaSecp256k1Signature(pk: ByteString, msg: ByteString, sig: ByteString): Boolean

Verify an ECDSA signature on the secp256k1 curve.

Verify an ECDSA signature on the secp256k1 curve.

Value parameters

msg

message hash (32 bytes, must be pre-hashed)

pk

public key (33 bytes compressed)

sig

signature (64 bytes, r||s format)

Attributes

Returns

true if the signature is valid

Throws
scalus.uplc.eval.BuiltinException

if inputs have wrong lengths

Inherited from:
AbstractBuiltins (hidden)
def verifyEd25519Signature(pk: ByteString, msg: ByteString, sig: ByteString): Boolean

Verify an Ed25519 signature.

Verify an Ed25519 signature.

Value parameters

msg

message to verify

pk

public key (32 bytes)

sig

signature (64 bytes)

Attributes

Returns

true if the signature is valid

Throws
scalus.uplc.eval.BuiltinException

if key or signature has wrong length

Inherited from:
AbstractBuiltins (hidden)
def verifySchnorrSecp256k1Signature(pk: ByteString, msg: ByteString, sig: ByteString): Boolean

Verify a Schnorr signature on the secp256k1 curve (BIP-340).

Verify a Schnorr signature on the secp256k1 curve (BIP-340).

Value parameters

msg

message (arbitrary length)

pk

public key (32 bytes x-only)

sig

signature (64 bytes)

Attributes

Returns

true if the signature is valid

Throws
scalus.uplc.eval.BuiltinException

if inputs have wrong lengths

Inherited from:
AbstractBuiltins (hidden)
def writeBits(byteString: ByteString, indexes: BuiltinList[BigInt], bit: Boolean): ByteString

Bitwise logical WriteBits for ByteStrings.

Bitwise logical WriteBits for ByteStrings.

Value parameters

bit

The value of the bit to be written.

byteString

The ByteString copy of that to be written.

indexes

The indexes of the bits to be written.

Attributes

Returns

The result of the bitwise logical WriteBits operation.

Throws
scalus.uplc.eval.BuiltinException

if the indexes are out of bounds.

See also

[CIP-122] (https://github.com/cardano-foundation/CIPs/tree/master/CIP-0122). Sets the value of the bit at the specified indexes in a copy of the input ByteString. The indexes must be in the range [0 .. byteString.size * 8), otherwise BuiltinException will be thrown. Bit indexing starts from the end of the ByteString.

Example

writeBits(hex"0000", List(0, 1, 2, 3), true) == hex"000F"

writeBits(hex"000F", List(0, 1, 2, 3), false) == hex"0000"

writeBits(hex"000F", List(16), true) throws BuiltinException

Inherited from:
AbstractBuiltins (hidden)
def xorByteString(shouldPad: Boolean, lhs: ByteString, rhs: ByteString): ByteString

Bitwise logical XOR for ByteStrings.

Bitwise logical XOR for ByteStrings.

Value parameters

lhs

The left-hand side ByteString.

rhs

The right-hand side ByteString.

shouldPad

Indicates whether to truncate the result to the length of the shorter input, or to pad with the remaining values from the longer one.

Attributes

Returns

The result of the bitwise XOR operation.

See also

[CIP-122] (https://github.com/cardano-foundation/CIPs/tree/master/CIP-0122). Performs a logical bitwise XOR operation on each byte between two ByteStrings sequentially and returns the result(Formally result[i] = lhs[i] ˆ rhs[i]). The argument shouldPad determines what to do in the case when ByteStrings are of different lengths. If shouldPad is false, the result will be the length of the shorter input. Otherwise, the result will be padded with the remaining values from the longer input.

Example

xorByteString(false, hex"0FFF", hex"FF") == hex"F0"

xorByteString(true, hex"0FFF", hex"FF") == hex"F0FF"

Inherited from:
AbstractBuiltins (hidden)
Generated with