Skip to main content

Built-in Functions

The built-in functions are divided into several categories: Contract, SubContract, 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​

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)

Returns the address of the caller. When used in a TxScript, it returns the unique input address if the input addresses are the same, otherwise it fails.

@returns the address of the caller. When used in a TxScript, it returns the unique input address if the input addresses are the same, otherwise it fails

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

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

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

@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.

@returns the block timestamp

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, 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, 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