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)
- 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. - When used in a contract function called directly from TxScript, returns the transaction caller as explained in 1)
- 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