Skip to main content

Built-in Functions

The built-in functions are divided into several categories: Contract, SubContract, Map, Asset, Utils, Chain, Conversion, ByteVec, Cryptography. All built-in functions are suffixed with !. All of the byte encoding use Big Endian byte order.

Contract Functions


encodeFields

fn <ContractName>.encodeFields!(...) -> (ByteVec, ByteVec)

Encode the fields for creating a contract

@param ... the fields of the to-be-created target contract

@returns two ByteVecs: the first one is the encoded immutable fields, and the second one is the encoded mutable fields


createContract

fn createContract!(bytecode:ByteVec, encodedImmFields:ByteVec, encodedMutFields:ByteVec) -> (ByteVec)

Creates a new contract without token issuance.

@param bytecode the bytecode of the contract to be created

@param encodedImmFields the encoded immutable fields as a ByteVec

@param encodedMutFields the encoded mutable fields as a ByteVec

@returns the id of the created contract


createContractWithToken

fn createContractWithToken!(bytecode:ByteVec, encodedImmFields:ByteVec, encodedMutFields:ByteVec, issueTokenAmount:U256, issueTo?:Address) -> (ByteVec)

Creates a new contract with token issuance.

@param bytecode the bytecode of the contract to be created

@param encodedImmFields the encoded immutable fields as a ByteVec

@param encodedMutFields the encoded mutable fields as a ByteVec

@param issueTokenAmount the amount of token to be issued

@param issueTo (optional) a designated address to receive issued token

@returns the id of the created contract


copyCreateContract

fn copyCreateContract!(contractId:ByteVec, encodedImmFields:ByteVec, encodedMutFields:ByteVec) -> (ByteVec)

Creates a new contract without token issuance by copying another contract's code. This costs less gas than createContract!(...).

@param contractId the id of the contract to be copied

@param encodedImmFields the encoded immutable fields as a ByteVec

@param encodedMutFields the encoded mutable fields as a ByteVec

@returns the id of the created contract


copyCreateContractWithToken

fn copyCreateContractWithToken!(contractId:ByteVec, encodedImmFields:ByteVec, encodedMutFields:ByteVec, issueTokenAmount:U256, issueTo?:Address) -> (ByteVec)

Creates a new contract with token issuance by copying another contract's code. This costs less gas than createContractWithToken!(...).

@param contractId the id of the contract to be copied

@param encodedImmFields the encoded immutable fields as a ByteVec

@param encodedMutFields the encoded mutable fields as a ByteVec

@param issueTokenAmount the amount of token to be issued

@param issueTo (optional) a designated address to receive issued token

@returns the id of the created contract


selfAddress

fn selfAddress!() -> (Address)

Returns the address of the contract.

@returns the address of the contract


selfContractId

fn selfContractId!() -> (ByteVec)

Returns the id (ByteVec) of the contract.

@returns the id (ByteVec) of the contract


selfTokenId

fn selfTokenId!() -> (ByteVec)

Returns the token id (ByteVec) of the contract.

@returns the token id (ByteVec) of the contract


tokenId

fn tokenId!(contract:<Contract>) -> (ByteVec)

Returns the id of the contract

@param contract the contract variable

@returns the id of the contract


contractId

fn contractId!(contract:<Contract>) -> (ByteVec)

Returns the id of the contract

@param contract the contract variable

@returns the id of the contract


contractAddress

fn contractAddress!(contract:<Contract>) -> (Address)

Returns the address of the contract

@param contract the contract variable

@returns the address of the contract


callerContractId

fn callerContractId!() -> (ByteVec)

Returns the contract id of the caller.

@returns the contract id of the caller


callerAddress

fn callerAddress!() -> (Address)
  1. When used in a TxScript, returns the transaction caller, which is the first input address when all input addresses are the same. If not all input addresses are the same, callAddress!() function fails.
  2. When used in a contract function called directly from TxScript, returns the transaction caller as explained in 1)
  3. When used in a contract function called from another contract, returns the address of the calling contract.

@returns the address of the caller


contractInitialStateHash

fn contractInitialStateHash!(contractId:ByteVec) -> (ByteVec)

Returns the initial state hash of the contract.

@param contractId the id of the input contract

@returns the initial state hash of the contract


contractCodeHash

fn contractCodeHash!(contractId:ByteVec) -> (ByteVec)

Returns the contract code hash of the contract.

@param contractId the id of the input contract

@returns the contract code hash of the contract


callerInitialStateHash

fn callerInitialStateHash!() -> (ByteVec)

Returns the initial state hash of the caller contract.

@returns the initial state hash of the caller contract


callerCodeHash

fn callerCodeHash!() -> (ByteVec)

Returns the contract code hash of the caller contract.

@returns the contract code hash of the caller contract


contractExists

fn contractExists!(contractId:ByteVec) -> (Bool)

Checks whether the contract exists with the given id.

@param contractId the input contract id to be tested

@returns ture if the contract exists on the chain, false otherwise


destroySelf

fn destroySelf!(refundAddress:Address) -> ()

Destroys the contract and transfer the remaining assets to a designated address.

@param refundAddress the address to receive the remaining assets in the contract

@returns


migrate

fn migrate!(newBytecode:ByteVec) -> ()

Migrates the code of the contract.

@param newBytecode the new bytecode for the contract to migrate to

@returns


migrateWithFields

fn migrateWithFields!(newBytecode:ByteVec, newEncodedImmFields:ByteVec, newEncodedMutFields:ByteVec) -> ()

Migrates both the code and the fields of the contract.

@param newBytecode the bytecode for the contract to migrate to

@param newEncodedImmFields the encoded immutable fields for the contract to migrate to

@param newEncodedMutFields the encoded mutable fields for the contract to migrate to

@returns


isCalledFromTxScript

fn isCalledFromTxScript!() -> (Bool)

Checks whether the function is called by a TxScript.

@returns true if the function is called by a TxScript, false otherwise


selfContract

fn selfContract!() -> (<Contract>)

Returns self contract

@returns self contract


SubContract Functions


createSubContract

fn createSubContract!(subContractPath:ByteVec, bytecode:ByteVec, encodedImmFields:ByteVec, encodedMutFields:ByteVec) -> (ByteVec)

Creates a new sub-contract without token issuance.

@param subContractPath the path of the sub-contract to be created

@param bytecode the bytecode of the sub-contract to be created

@param encodedImmFields the encoded immutable fields as a ByteVec

@param encodedMutFields the encoded mutable fields as a ByteVec

@returns the id of the created contract


createSubContractWithToken

fn createSubContractWithToken!(subContractPath:ByteVec, bytecode:ByteVec, encodedImmFields:ByteVec, encodedMutFields:ByteVec, issueTokenAmount:U256, issueTo?:Address) -> (ByteVec)

Creates a new sub-contract with token issuance.

@param subContractPath the path of the sub-contract to be created

@param bytecode the bytecode of the sub-contract to be created

@param encodedImmFields the encoded immutable fields as a ByteVec

@param encodedMutFields the encoded mutable fields as a ByteVec

@param issueTokenAmount the amount of token to be issued

@param issueTo (optional) a designated address to receive issued token

@returns the id of the created contract


copyCreateSubContract

fn copyCreateSubContract!(subContractPath:ByteVec, contractId:ByteVec, encodedImmFields:ByteVec, encodedMutFields:ByteVec) -> (ByteVec)

Creates a new sub-contract without token issuance by copying another contract's code. This costs less gas than createSubContract!(...).

@param subContractPath the path of the sub-contract to be created

@param contractId the id of the contract to be copied

@param encodedImmFields the encoded immutable fields as a ByteVec

@param encodedMutFields the encoded mutable fields as a ByteVec

@returns the id of the created contract


copyCreateSubContractWithToken

fn copyCreateSubContractWithToken!(subContractPath:ByteVec, contractId:ByteVec, encodedImmFields:ByteVec, encodedMutFields:ByteVec, issueTokenAmount:U256, issueTo?:Address) -> (ByteVec)

Creates a new sub-contract with token issuance by copying another contract's code. This costs less gas than createSubContractWithToken!(...).

@param subContractPath the path of the sub-contract to be created

@param contractId the id of the contract to be copied

@param encodedImmFields the encoded immutable fields as a ByteVec

@param encodedMutFields the encoded mutable fields as a ByteVec

@param issueTokenAmount the amount of token to be issued

@param issueTo (optional) a designated address to receive issued token

@returns the id of the created contract


subContractId

fn subContractId!(subContractPath:ByteVec) -> (ByteVec)

Returns the id of the sub contract.

@param subContractPath the path of the sub-contract

@returns the id of the sub contract


subContractIdOf

fn subContractIdOf!(contract:<Contract>, subContractPath:ByteVec) -> (ByteVec)

Returns the id of the sub contract.

@param contract the parent contract of the sub-contract

@param subContractPath the path of the sub-contract

@returns the id of the sub contract


subContractIdInParentGroup

fn subContractIdInParentGroup!(contract:<Contract>, subContractPath:ByteVec) -> (ByteVec)

Returns the id of the sub contract.

@param contract the parent contract of the sub-contract

@param subContractPath the path of the sub-contract

@returns the id of the sub contract


Map Functions


map.insert

fn <map>.insert!(depositorAddress: Address, key: <Bool | U256 | I256 | Address | ByteVec>, value: Any) -> ()

Insert a key/value pair into the map. No brace syntax is required, as the minimal storage deposit will be deducted from the approved assets by the VM

@param depositorAddress the address to pay the minimal storage deposit (0.1 ALPH) for the new map entry

@param key the key to insert

@param value the value to insert

@returns


map.remove

fn <map>.remove!(depositRecipient: Address, key: <Bool | U256 | I256 | Address | ByteVec>) -> ()

Remove a key from the map

@param depositRecipient the address to receive the redeemed minimal storage deposit

@param key the key to remove

@returns


map.contains

fn <map>.contains!(key: <Bool | U256 | I256 | Address | ByteVec>) -> Bool

Check whether the map contains a bindiing for the key

@param key the key to check

@returns true if there is a binding for key in this map, false otherwise


Asset Functions


approveToken

fn approveToken!(fromAddress:Address, tokenId:ByteVec, amount:U256) -> ()

Approves the usage of certain amount of token from the given address

@param fromAddress the address to approve token from

@param tokenId the token to be approved

@param amount the amount of the token to be approved

@returns


tokenRemaining

fn tokenRemaining!(address:Address, tokenId:ByteVec) -> (U256)

Returns the amount of the remaining token amount in the input assets of the function.

@param address the input address

@param tokenId the token id

@returns the amount of the remaining token amount in the input assets of the function


transferToken

fn transferToken!(fromAddress:Address, toAddress:Address, tokenId:ByteVec, amount:U256) -> ()

Transfers token from the input assets of the function.

@param fromAddress the address to transfer token from

@param toAddress the address to transfer token to

@param tokenId the token to be transferred

@param amount the amount of token to be transferred

@returns


transferTokenFromSelf

fn transferTokenFromSelf!(toAddress:Address, tokenId:ByteVec, amount:U256) -> ()

Transfers the contract's token from the input assets of the function.

@param toAddress the address to transfer token to

@param tokenId the token to be transferred

@param amount the amount of token to be transferred

@returns


transferTokenToSelf

fn transferTokenToSelf!(fromAddress:Address, tokenId:ByteVec, amount:U256) -> ()

Transfers token to the contract from the input assets of the function.

@param fromAddress the address to transfer token from

@param tokenId the token to be transferred

@param amount the amount of token to be transferred

@returns


burnToken

fn burnToken!(address:Address, tokenId:ByteVec, amount:U256) -> ()

Burns token from the input assets of the function.

@param address the address to burn token from

@param tokenId the token to be burnt

@param amount the amount of token to be burnt

@returns


lockApprovedAssets

fn lockApprovedAssets!(address:Address, timestamp:U256) -> ()

Locks the current approved assets.

@param address the address to lock assets to

@param timestamp the timestamp that the assets will be locked until

@returns


payGasFee

fn payGasFee!(payer:Address, amount:U256) -> ()

Pay gas fee.

@param payer payer of the gas

@param amount the amount of gas to be paid in ALPH

@returns


Utils Functions


assert

fn assert!(condition:Bool, errorCode:U256) -> ()

Tests the condition or checks invariants.

@param condition the condition to be checked

@param errorCode the error code to throw if the check fails

@returns


checkCaller

fn checkCaller!(condition:Bool, errorCode:U256) -> ()

Checks conditions of the external caller of the function.

@param condition the condition to be checked

@param errorCode the error code to throw if the check fails

@returns


isAssetAddress

fn isAssetAddress!(address:Address) -> (Bool)

Returns whether an address is an asset address.

@param address the input address to be tested

@returns true if the address is an asset address, false otherwise


isContractAddress

fn isContractAddress!(address:Address) -> (Bool)

Returns whether an address is a contract address.

@param address the input address to be tested

@returns true if the address is a contract address, false otherwise


zeros

fn zeros!(n:U256) -> (ByteVec)

Returns a ByteVec of zeros.

@param n the number of zeros

@returns a ByteVec of zeros


panic

fn panic!(errorCode?: U256) -> (Never)

Terminates the application immediately.

@param errorCode (optional) the error code to be thrown when the panic!(...) is called

@returns


mulModN

fn mulModN!(x:U256, y:U256, n:U256) -> (U256)

Returns compute the x * y % n.

@param x x

@param y y

@param n n

@returns compute the x * y % n


addModN

fn addModN!(x:U256, y:U256, n:U256) -> (U256)

Returns compute the (x + y) % n.

@param x x

@param y y

@param n n

@returns compute the (x + y) % n


u256Max

fn u256Max!() -> (U256)

Returns the max value of U256.

@returns the max value of U256


i256Max

fn i256Max!() -> (I256)

Returns the max value of I256.

@returns the max value of I256


i256Min

fn i256Min!() -> (I256)

Returns the min value of I256.

@returns the min value of I256


groupOfAddress

fn groupOfAddress!(address:Address) -> (U256)

Returns the group of the input address.

@param address the input address

@returns the group of the input address


len

fn len!(array) -> (U256)

Get the length of an array

@param an array

@returns the length of an array


nullContractAddress

fn nullContractAddress!() -> (Address)

Returns the null contract address with contract id being zeros.

@returns the null contract address with contract id being zeros


minimalContractDeposit

fn minimalContractDeposit!() -> (U256)

The minimal contract deposit

@returns the minimal ALPH amount for contract deposit


mapEntryDeposit

fn mapEntryDeposit!() -> (U256)

The amount of ALPH required to create a map entry, which is '0.1 ALPH' since Rhone upgrade

@returns the amount of ALPH required to create a map entry


Chain Functions


networkId

fn networkId!() -> (ByteVec)

Returns the network id (a single byte).

@returns the network id (a single byte)


blockTimeStamp

fn blockTimeStamp!() -> (U256)

Returns the block timestamp in milliseconds.

@returns the block timestamp in milliseconds


blockTarget

fn blockTarget!() -> (U256)

Returns the block difficulty target.

@returns the block difficulty target


txId

fn txId!() -> (ByteVec)

Returns the current transaction id.

@returns the current transaction id


txInputAddress

fn txInputAddress!(txInputIndex:U256) -> (Address)

Returns the n-th transaction input address.

@param txInputIndex the index of the transaction input

@returns the n-th transaction input address


txInputsSize

fn txInputsSize!() -> (U256)

Returns the number of transaction inputs.

@returns the number of transaction inputs


txGasPrice

fn txGasPrice!() -> (U256)

Returns the current transaction gas price.

@returns the current transaction gas price


txGasAmount

fn txGasAmount!() -> (U256)

Returns the current transaction gas amount.

@returns the current transaction gas amount


txGasFee

fn txGasFee!() -> (U256)

Returns the current transaction gas fee.

@returns the current transaction gas fee


verifyAbsoluteLocktime

fn verifyAbsoluteLocktime!(lockUntil:U256) -> ()

Verifies that the absolute locktime is before the block timestamp (milliseconds), otherwise it fails.

@param lockUntil the timestamp until which the lock is valid

@returns


verifyRelativeLocktime

fn verifyRelativeLocktime!(txInputIndex:U256, lockDuration:U256) -> ()

Verifies that the input's creation timestamp + lock duration is before the block timestamp (milliseconds), otherwise it fails.

@param txInputIndex the index of the transaction input

@param lockDuration the duration that the input is locked for

@returns


dustAmount

fn dustAmount!() -> (U256)

Returns the dust amount of an UTXO.

@returns the dust amount of an UTXO


Conversion Functions


toI256

fn toI256!(from:U256) -> (I256)

Converts U256 to I256.

@param from a U256 to be converted

@returns a I256


toU256

fn toU256!(from:I256) -> (U256)

Converts I256 to U256.

@param from a I256 to be converted

@returns a U256


toByteVec

fn toByteVec!(from:Bool|I256|U256|Address) -> (ByteVec)

Converts Bool/I256/U256/Address to ByteVec

@param from a Bool|I256|U256|Address to be converted

@returns a ByteVec


contractIdToAddress

fn contractIdToAddress!(contractId:ByteVec) -> (Address)

Converts contract id (ByteVec) to contract address (Address).

@param contractId the input contract id

@returns a contract Address


addressToContractId

fn addressToContractId!(contractAddress:Address) -> (ByteVec)

Converts contract address (Address) to contract id (ByteVec)

@param contractAddress the input contract address

@returns a contract id


byteVecToAddress

fn byteVecToAddress!(bytes:ByteVec) -> (Address)

Converts ByteVec to Address.

@param bytes the input ByteVec

@returns an Address


u256To1Byte

fn u256To1Byte!(u256:U256) -> (ByteVec)

Converts U256 to 1 byte.

@param u256 the input U256

@returns 1 byte


u256To2Byte

fn u256To2Byte!(u256:U256) -> (ByteVec)

Converts U256 to 2 big-endian bytes.

@param u256 the input U256

@returns 2 bytes


u256To4Byte

fn u256To4Byte!(u256:U256) -> (ByteVec)

Converts U256 to 4 big-endian bytes.

@param u256 the input U256

@returns 4 bytes


u256To8Byte

fn u256To8Byte!(u256:U256) -> (ByteVec)

Converts U256 to 8 big-endian bytes.

@param u256 the input U256

@returns 8 bytes


u256To16Byte

fn u256To16Byte!(u256:U256) -> (ByteVec)

Converts U256 to 16 big-endian bytes.

@param u256 the input U256

@returns 16 bytes


u256To32Byte

fn u256To32Byte!(u256:U256) -> (ByteVec)

Converts U256 to 32 big-endian bytes.

@param u256 the input U256

@returns 32 bytes


u256ToString

fn u256ToString!(u256:U256) -> (ByteVec)

Converts U256 to string in ByteVec.

@param u256 the input U256

@returns Converted string in ByteVec


i256ToString

fn i256ToString!(i256:I256) -> (ByteVec)

Converts I256 to string in ByteVec.

@param i256 the input I256

@returns Converted string in ByteVec


boolToString

fn boolToString!(bool:Bool) -> (ByteVec)

Converts Bool to string in ByteVec.

@param bool the input Bool

@returns Converted string in ByteVec


u256From1Byte

fn u256From1Byte!(bytes:ByteVec) -> (U256)

Converts 1 byte to U256.

@param bytes the input ByteVec

@returns an U256


u256From2Byte

fn u256From2Byte!(bytes:ByteVec) -> (U256)

Converts 2 big-endian bytes to U256.

@param bytes the input ByteVec

@returns an U256


u256From4Byte

fn u256From4Byte!(bytes:ByteVec) -> (U256)

Converts 4 big-endian bytes to U256.

@param bytes the input ByteVec

@returns an U256


u256From8Byte

fn u256From8Byte!(bytes:ByteVec) -> (U256)

Converts 8 big-endian bytes to U256.

@param bytes the input ByteVec

@returns an U256


u256From16Byte

fn u256From16Byte!(bytes:ByteVec) -> (U256)

Converts 16 big-endian bytes to U256.

@param bytes the input ByteVec

@returns an U256


u256From32Byte

fn u256From32Byte!(bytes:ByteVec) -> (U256)

Converts 32 big-endian bytes to U256.

@param bytes the input ByteVec

@returns an U256


ByteVec Functions


size

fn size!(bytes:ByteVec) -> (U256)

Returns the size of the ByteVec.

@param bytes a ByteVec

@returns the size of the ByteVec


byteVecSlice

fn byteVecSlice!(bytes:ByteVec, from:U256, until:U256) -> (ByteVec)

Selects an interval of bytes.

@param bytes a ByteVec

@param from the lowest index to include from the ByteVec

@param until the lowest index to exclude from the ByteVec

@returns a ByteVec containing the elements greater than or equal to index from extending up to (but not including) index until of this ByteVec


encodeToByteVec

fn encodeToByteVec!(...any) -> (ByteVec)

Encodes inputs as big-endian ByteVec.

@param any a sequence of input values

@returns a ByteVec encoding the inputs


Cryptography Functions


blake2b

fn blake2b!(data:ByteVec) -> (ByteVec)

Computes the Blake2b-256 hash of the input.

@param data the input data to be hashed

@returns the 32 bytes hash result


keccak256

fn keccak256!(data:ByteVec) -> (ByteVec)

Computes the Keccak256 hash of the input.

@param data the input data to be hashed

@returns the hash result


sha256

fn sha256!(data:ByteVec) -> (ByteVec)

Computes the Sha256 hash of the input.

@param data the input data to be hashed

@returns the hash result


sha3

fn sha3!(data:ByteVec) -> (ByteVec)

Computes the Sha3 hash of the input.

@param data the input data to be hashed

@returns the hash result


verifyTxSignature

fn verifyTxSignature!(publicKey:ByteVec) -> ()

Verifies the transaction SecP256K1 signature of a public key. The signature is signed against the transaction id.

@param publicKey the public key (33 bytes) of the signer

@returns


getSegregatedSignature

fn getSegregatedSignature!() -> (ByteVec)

The segregated signature of the transaction

@returns the segregated signature of the transaction


verifySecP256K1

fn verifySecP256K1!(data:ByteVec, publicKey:ByteVec, signature:ByteVec) -> ()

Verifies the SecP256K1 signature of the input and public key.

@param data the data (32 bytes) that was supposed to have been signed

@param publicKey the public key (33 bytes) of the signer

@param signature the signature (64 bytes) value

@returns


verifyED25519

fn verifyED25519!(data:ByteVec, publicKey:ByteVec, signature:ByteVec) -> ()

Verifies the ED25519 signature of the input and public key.

@param data the data (32 bytes) that was supposed to have been signed

@param publicKey the public key (32 bytes) of the signer

@param signature the signature value (64 bytes)

@returns


verifyBIP340Schnorr

fn verifyBIP340Schnorr!(data:ByteVec, publicKey:ByteVec, signature:ByteVec) -> ()

Verifies the BIP340 Schnorr signature of the input and public key.

@param data the data (32 bytes) that was supposed to have been signed

@param publicKey the public key (32 bytes) of the signer

@param signature the signature value (64 bytes)

@returns


ethEcRecover

fn ethEcRecover!(data:ByteVec, signature:ByteVec) -> (ByteVec)

Recovers the ETH account that signed the data.

@param data the data that was supposed to have been signed

@param signature the signature value

@returns the ETH account that signed the data