namillum

# @zilliqa-js/contract > Classes for managing Scilla smart contracts on the Zilliqa blockchain. ## Interfaces ```typescript 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` - a `Provider` instance - `signer`: `Wallet` - a `Wallet` instance, used for signing transactions. ##### Returns - `Contracts` - a `Contracts` 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` - a `Transaction` with `nonce` and `senderAddress`. ###### 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 by `scilla-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` - a `Contract` 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 by `scilla-checker`. ###### Returns - `Contract` - a `Contract` 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` - a `Contract` 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 underlying `Transaction`. This can be used to manually provide `nonce` and `pubKey`, if it is desirable to sign the underlying transaction with a non-default account in the `Wallet`. - `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 resolved `Promise` does not indicate that the `Contract` is deployed, as the underlying `Transaction` may be confirmed by the blockchain but unsuccessful, due to lack of `gas`, 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 matters_ - `args`: `Value[]` - JSON-encoded array of transition arguments. - `params`: `CallParams` - a subset of `TxParams`. Passed to the underlying `Transaction`. - `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 state - `indices` : `string[]` - optional variable. If the `variableName` is a `Map`, an array of indices may be provided. ###### Returns - `Promise<State>` - the Contract Init.