@zilliqa-js/contract
v3.5.0
Published
Contract-related functionality.
Downloads
4,236
Keywords
Readme
@zilliqa-js/contract
Classes for managing Scilla smart contracts on the Zilliqa blockchain.
Interfaces
interface DeployParams {
gasPrice: BN;
gasLimit: Long;
nonce?: number;
pubKey?: string;
}
interface CallParams {
amount: BN;
gasPrice: BN;
gasLimit: Long;
nonce?: number;
pubKey?: string;
}
interface Field {
name: string;
type: string;
}
interface Transition {
name: string;
params: Field[];
}
interface ABI {
name: string;
fields: Field[];
params: Field[];
transitions: Transition[];
}
interface Value {
vname: string;
type: string;
value: string;
}
type Init = Value[];
type State = any;
Classes
Contracts
A factory class for creating Contract
instances. Useful for managing
Provider
instances set on Contract
s. The factory is mainly used by the
top-level module exported by @zilliqa-js/zilliqa
.
Contracts(provider: Provider, signer?: Wallet): Contracts
Parameters
provider
:Provider
- aProvider
instancesigner
:Wallet
- aWallet
instance, used for signing transactions.
Returns
Contracts
- aContracts
instance.
Members
provider: Provider
signer: Wallet
Static Methods
static getAddressForContract(tx: Transaction): string
Computes the address for a contract deployment by concatenating senderAddress
and nonce
and hasing the resulting bytes. Note that this method will not
compute an accurate address if the provided nonce
is not up to date with the
actual nonce on the blockchain.
Parameters
tx
:Transaction
- aTransaction
withnonce
andsenderAddress
.
Returns
- The compute contract address.
Instance Methods
at(address: string, abi: ABI, code: string, init?: Init, state?: State): Contract
Constructs a Contract
with the provided parameters. It is recommended that
this method by used only to construct contracts that have already been deployed.
Parameters
address
:string
- the contract address.abi
:ABI
(optional) - the ABI return byscilla-checker
with-contractinfo
flag.code
:string
(optional) - UTF-8 encoded Scilla smart contract code.init
:Init
(optional) - the initialisation parameters of the smart contract.state
:State
(optional) - the current smart contract state.
Returns
Contract
- aContract
instance.
new(code: string, init: Init, abi?: ABI): Contract
Constructs a Contract
with the provided parameters, that is not deployed. The
contract may subsequently be deployed.
Parameters
code
:string
- UTF-8 encoded Scilla smart contract code.init
:Init
- the initialisation parameters of the smart contract.abi
:ABI
(optional) - the ABI return byscilla-checker
.
Returns
Contract
- aContract
instance.
Contract(factory: Contracts, code?: string, address?: string, abi?: ABI, init?: Init, state?: State): Contracts
A class representing a single smart contract. Allows for deployment and calling the smart contract's transitions.
Parameters
factory
: Contracts - the creating factory instance.code
:string
(Optional) - UTF-8 Scilla smart contract code.address
:string
(Optional)init
:any
(Optional) - contract initialisation parameters.state
:any
(Optional) - contract state.abi
:string
(Optional) - scilla interface
Returns
Contract
- aContract
instance.
Contract
Members
factory: Contracts
provider: Provider
signer: Wallet
init: Init
abi?: ABI
(Optional) state?: State
(Optional)
address?: string
(Optional) code?: string
(Optional)
status: ContractStatus
Instance Methods
isInitialised(): boolean
Returns true
if no attempt has been made to deploy the Contract
, or its
status is unknown.
Returns
boolean
isDeployed(): boolean
Returns true
if the contract has been successfully deployed.
Returns
boolean
isRejected(): boolean
Returns true
if the contract deployment attempt was rejected by the network.
Returns
boolean
deploy(params: DeployParams, attempts: number = 33, interval: number = 1000): Promise<Contract>
Deploys a contract to the blockchain. This method will automatically generate
and sign the underlying Transaction
and broadcast it. The status of the
Contract
may then be ascertained by using isRejected
or isDeployed
, once
the Promise
resolves.
Parameters
params
:DeployParams
- a subset of TxParams. Passed to the underlyingTransaction
. This can be used to manually providenonce
andpubKey
, if it is desirable to sign the underlying transaction with a non-default account in theWallet
.attempts
(Optional - default 33):number
- the number of times to poll the lookup node for transaction receipt.interval
(Optional - default 1000):number
- the amount of time to wait between attempts. increases linearly (numAttempts * interval
).
Returns
Promise<Contract>
- will be rejected if a network error occurs. A resolvedPromise
does not indicate that theContract
is deployed, as the underlyingTransaction
may be confirmed by the blockchain but unsuccessful, due to lack ofgas
, and so on.
call(transition: string, args: Value[], params: CallParams): Promise<Transaction>
Calls a transition of the current contract. At the moment, this is a low-level interface for interacting with simple smart contracts.
Parameters
transition
:string
- the exact name of the contract transition to be invoked. case mattersargs
:Value[]
- JSON-encoded array of transition arguments.params
:CallParams
- a subset ofTxParams
. Passed to the underlyingTransaction
.attempts
(Optional - default 20):number
- the number of times to poll the lookup node for transaction receipt.interval
(Optional - default 1000):number
- the amount of time to wait between attempts. increases linearly (numAttempts * interval
).
Returns
Promise<Transaction>
- the Transaction that has been signed and broadcast to the network.
getState(): Promise<State>
Queries the blockchain for the smart contract's state. Note that this method will return the entire state of the smart contract. As a result, if you have a large amount of data stored in a smart contract do not use this method on a client. Instead, use a server-side layer to cache and proxy such queries.
Parameters
None
Returns
Promise<State>
- the Contract state.
getInit(): Promise<State>
Queries the blockchain for the smart contract's init (a.k.a. immutable variables of a contract)
Parameters
None
Returns
Promise<State>
- the Contract Init.
getSubState(variableName: string, indices: string[]): Promise<State>
Queries the contract state, filtered by the variable names. This function is the
filtered version of getState
. As getSubState
performs the filtering,
variableName
of a field is required.
If the subState
is not found, this returns a null
response.
Parameters
variableName
:string
- the variable name within a stateindices
:string[]
- optional variable. If thevariableName
is aMap
, an array of indices may be provided.
Returns
Promise<State>
- the Contract Init.