Global Functions

There are a variety of global functions available to use in ErgoScript. Here we will go through some of the most commonly used functions, (besides sigmaProp). A complete reference for all global functions and types may be found in the ErgoScript LangSpec .

Logical Functions

Logical functions describe global functions used on booleans. These functions of course include operators such as && and ||, but the following commonly used functions also exist.

AllOf

The allOf function takes a collection booleans and returns a boolean indicating whether or not all of the given booleans within the collection evaluate to true. It is equivalent to inserting && between each boolean in the collection.

AnyOf

The anyOf function takes a collection of booleans and returns a boolean indicating whether or not at least one boolean within the entire collection evaluates to true. It is equivalent to inserting || between each boolean in the collection.

XorOf

The xorOf function takes a collection of booleans and applies the XOR operation between each boolean within the collection. Therefore, the xorOf function returns true if an odd number of booleans within the collection evaluate to true. It returns false if an even number of booleans within the collection evaluate to true.

Zero-Knowledge Functions

Zero Knowledge functions are functions that may be used to evaluate SigmaProps with Zero-Knowledge needed to verify the truth of the SigmaProps given.

AtLeast

The atLeast function takes an integer k and a collection of SigmaProps and returns whether k SigmaProps within the collection evaluate to true. All SigmaProps are evaluated with zero knowledge.

ZKProof

The ZKProof function takes a block of code and evaluates all operations within the code with zero-knowledge scoping. This may be useful if some operations within your contract must be kept private. The code block used must not use any boolean operations to ensure zero-knowledge, and the entire block must evaluate into a single root SigmaProp.

Cryptographic Functions

Cryptographic functions are functions related to cryptography. Such functions include hashing, and calculation over GroupElement values.

Blake2b256

blake2b256 takes a Coll[Byte] and returns a new Coll[Byte] hashed according to the Blake2b256 algorithm. The Blake2b256 algorithm is the main hashing algorithm used within Ergo. It is also incorporated as a part of the Autolykos PoW algorithm used to mine Ergo.

Sha256

sha256 takes a Coll[Byte] and returns a new Coll[Byte] hashed according to the SHA256 hashing function.

DecodePoint

decodePoint takes a Coll[Byte] representing a Group Element and converts it into the GroupElement type.

ProveDHTuple

proveDHTuple takes four GroupElement values and constructs them into a public key represented by a SigmaProp according to the Diffie-Hellman signature protocol. This is useful for creating shared public keys in MultiSig and Ring Signature settings.

ProveDLog

proveDlog takes a GroupElement and creates a public key represented by a SigmaProp.

Compile-Time Functions

Compile-Time functions are not evaluated during the spending of the script, instead these functions are used when compiling an ErgoScript contract into the native ErgoTree language. These functions all take Strings (which is not an actual ErgoScript type) and then convert these strings into some ErgoScript type during contract compilation. These values are stored directly within the contract and cannot change once the contract has been compiled.

FromBase

Two functions, fromBase64 and fromBase58 take Strings of their respective base and convert them into a Coll[Byte] at compile time.

PK

The PK function takes an address string (which is actually just a base58 encoded GroupElement with a network identifier prefix) and converts it into a SigmaProp public key at compile time. This is actually done using many of the functions listed above.

Deserialize

The deserialize[T] function takes a type parameter T along with a base58 encoded String of binary data. The String value is converted into some value with ErgoScript type T at compile time.

Other Functions

GetVar

getVar[T] takes type parameter T along with some integer tag and returns some Context Variable with the given type that is associated with the given tag. Context Variables are specific off-chain variables that may be attached to any box at the time of transaction creation. Context variables allow for robust changes for certain parameters within your contract. It is especially useful for providing generic contracts that rely on off-chain information which may change between different spending transactions.

SubstConstants

The substConstants function has the following signature:

def substConstants[T](scriptBytes: Coll[Byte],
 positions: Coll[Int], newValues: Coll[T]): Coll[Byte]

It allows a contract to construct another contract’s propositional bytes using the given parameters. Because a contract’s address is created using its contents, inputting different constants within a contract can change it’s address(and therefore, the contract itself). This function allows for a contract of the same “template” to be created using a new set of constants. In order to be used properly, one must provide a sample of the contract’s propositional bytes(parameter scriptBytes), along with the positions at which certain constants of type T must be replaced with the values in the newValues parameter.

Example: Alcohol Sale Proxy Contract

{
    // ====== Alcohol Sale Proxy Contract Example ====== // 

    // Hard-coded constants expected at compile time are written in UpperCamelCase.

    // INPUTS:
    // license          = INPUTS(0)
    // buyerProxyInputs = INPUTS - INPUTS(0)
    //
    // OUTPUTS:
    // storeBox              = OUTPUTS(0)
    // provincialSalesTaxBox = OUTPUTS(1)
    // federalSalesTaxBox    = OUTPUTS(2)
    // buyerWalletBox        = OUTPUTS(3)
    // minerFeeBox           = OUTPUTS(4)
    //
    // (*) Note: 
    //           1. Mining fee box is always the last box in the set of OUTPUTS of a transaction,
    //              I am just showing this for clarity, but it will not be accessed in this contract.
        //           2. If there is any that change remains in the proxy, 
    //              it is sent back to the buyer wallet.

    // Contract variables
    val buyerPK: SigmaProp          = PK(buyerPKString)
    val buyerProxyInputs: Coll[Box] = INPUTS.filter({ (input: Box) => input.propositionBytes == SELF.propositionBytes })
    val buyerAmount: Long           = buyerProxyInputs.fold(0L)({ (input: Box, acc: Long) => acc + input.value })
    val provincialSalesTax: Long    = (AlcoholSaleAmount * ProvincialSalesTaxNum) / ProvincialSalesTaxDenom
    val federalSalesTax: Long       = (AlcoholSaleAmount * FederalSalesTaxNum) / FederalSalesTaxDenom
    val totalCost: Long             = AlcoholSaleAmount + provincialSalesTax + federalSalesTax + MinerFee

    // Variables associated with the buyer's license
    val license = INPUTS(0)
    val id      = license.R4[Coll[Byte]].get
    val name    = license.R5[Coll[Byte]].get
    val bDay    = license.R6[Coll[Byte]].get
    val address = license.R7[Coll[Byte]].get
    val expDate = license.R8[Coll[Byte]].get

    // Context variables needed for the proxy contract, assuming they are provided correctly
    val licenseTemplateContractBytes = getVar[Coll[Byte]](0).get

    // Substitute the constants of the license template contract bytes
    // and create the new contract bytes for the buyer's license
    val newLicenseContractBytes = {

        // New positions
        val newPositions_SigmaProp: Coll[Int] = Coll(0)
        val newPositions_Coll_Byte: Coll[Int] = Coll(1, 2, 3, 4, 5)

        // New constants
        val newConstants_SigmaProp: Coll[SigmaProp] = Coll(buyerPK)
        val newConstants_Coll_Byte: Coll[Byte] = Coll(id, name, bDay, address, expDate)

        // New contract bytes with substituted buyer PK
        val newContractBytes_SigmaProp = substConstants(licenseTemplateContractBytes, newPositions_SigmaProp, newConstants_SigmaProp)

        // New contract bytes with substituted buyer license information
        val newContractBytes_Coll_Byte = substConstants(newContractBytes_SigmaProp, newPositions_Coll_Byte, newConstants_Coll_Byte)
        val newContractBytes = newContractBytes_Coll_Byte

        newContractBytes
    }

    // Check for a valid sale
    val validSale = {

        // Check for a valid license 
        val validLicense = {
            allOf(Coll(
                BuyerLicenseContractBytes == newLicenseContractBytes,
                license.propositionBytes == newLicenseContractBytes
            ))
        }

        // Check for a valid proxy amount
            val validProxyAmount = {
                buyerAmount >= totalAmount
        }

        // Check for a valid store
        val validStore = {
            val storeBox = OUTPUTS(0)
            storeBox.propBytes == StoreBoxPropositionBytes
        }

        // Check for valid sales taxes
        val validSalesTaxes = {

            // Check for a valid provincial tax
            val validProvincialSalesTax = {
                val provincialSalesTaxBox = OUTPUTS(1)
                allOf(Coll(
                    (provincialSalesTaxBox.propositionBytes == ProvincialSalesTaxPK),
                    (provincialSalesTaxBox.value >= provincialSalesTax)
                ))
            }

            // Check for a valid federal tax
            val validFederalSalesTax = {
                val federalSalesTaxBox = OUTPUTS(2)
                allOf(Coll(
                    (federalSalesTaxBox.propositionBytes == FederalSalesTaxPK),
                    (federalSalesTaxBox.value >= federalSalesTax)
                ))
            }

                // Demand that both sales taxes are valid
                allOf(Coll(
                    validProvincialSalesTax,
                    validFederalSalesTax
                ))

        }

        // Check for a valid buyer wallet to return any change
        val validBuyerWallet = {
            if (buyerAmount > totalCost) {
                val buyerWalletBox = OUTPUTS(3)
                buyerWalletBox.propositionBytes == buyerPK.propBytes
            } else {
                true
            }
        }       

        // Demand that all the conditions are valid
        allOf(Coll(
            validLicense,
            validProxyAmount,
            validStore,
            validSalesTaxes,
            validBuyerWallet
        ))

    }

    // Check for a valid refund
    val validRefund = {
        val refundWalletBox = OUTPUTS(0)
        allOf(Coll(
            (refundWalletBox.propositionBytes == buyerPK.propBytes),
            (refundWalletBox.value >= buyerAmount - MinerFee)
        ))
    }

    // Obtain the appropriate sigma proposition
    sigmaProp(anyOf(Coll(
        validSale,
        validRefund
    )))

}