Contracts Management

How to manage contracts

⚠️ Required: Your project must follow the required structure and it must be initialized to use the following functions.

deployContractByName(props)

Deploys contract code located inside a Cadence file. Returns the transaction result.

Arguments

Props object accepts the following fields:

NameTypeOptionalDescription
namestringname of the file in contracts folder (with .cdc extension) and name of the contract (please note those should be the same)
toAddress(optional) account address, where contract will be deployed. If this is not specified, framework will create new account with randomized alias.
addressMapAddressMap(optional) object to use for address mapping of existing deployed contracts
args[Any](optional) arguments, which will be passed to contract initializer. (optional) if template does not expect any arguments.
updateboolean(optional) whether to update deployed contract. Default: false
transformers[CadenceTransformer]an array of operators to modify the code, before submitting it to network

Returns

TypeDescription
ResponseObjectResult of the deploying transaction.

Usage

1
import path from "path";
2
import { init, emulator, deployContractByName } from "@onflow/flow-js-testing";
3
4
const main = async () => {
5
const basePath = path.resolve(__dirname, "../cadence");
6
7
await init(basePath);
8
await emulator.start();
9
10
// We will deploy our contract to the address that corresponds to "Alice" alias
11
const to = await getAccountAddress("Alice");
12
13
// We assume there is a file on "../cadence/contracts/Wallet.cdc" path
14
const name = "Wallet";
15
16
// Arguments will be processed and type matched in the same order as they are specified
17
// inside of a contract template
18
const args = [1337, "Hello", { name: "Alice" }];
19
20
const [deploymentResult, err] = await deployContractByName({ to, name });
21
console.log({ deploymentResult }, { err });
22
}
23
24
await emulator.stop();
25
};
26
27
main();

In a bit more rare case you would want to deploy contract code not from existing template file, but rather from string representation of it. deployContract method will help you achieve this.

deployContract(props)

Deploys contract code specified as string. Returns the transaction result.

Arguments

Props object accepts the following fields:

NameTypeOptionalDescription
contractCodestringstring representation of contract
namestringname of the contract to be deployed. Should be the same as the name of the contract provided in contractCode
toAddressaccount address, where contract will be deployed. If this is not specified, framework will create new account with randomized alias.
addressMapAddressMapobject to use for import resolver. Default: {}
args[Any]arguments, which will be passed to contract initializer. Default: []
updatebooleanwhether to update deployed contract. Default: false
transformers[CadenceTransformer]an array of operators to modify the code, before submitting it to network

Returns

TypeDescription
ResponseObjectResult of the deploying transaction.

Usage

1
import path from "path"
2
import {
3
init,
4
emulator,
5
getAccountAddress,
6
deployContract,
7
executeScript,
8
} from "@onflow/flow-js-testing"
9
;(async () => {
10
const basePath = path.resolve(__dirname, "../cadence")
11
12
await init(basePath)
13
await emulator.start()
14
15
// We can specify, which account will hold the contract
16
const to = await getAccountAddress("Alice")
17
18
const name = "Wallet"
19
const code = `
20
pub contract Wallet{
21
pub let balance: UInt
22
init(balance: UInt){
23
self.balance = balance
24
}
25
}
26
`
27
const args = [1337]
28
29
await deployContract({to, name, code, args})
30
31
const [balance, err] = await executeScript({
32
code: `
33
import Wallet from 0x01
34
pub fun main(): UInt{
35
return Wallet.balance
36
}
37
`,
38
})
39
console.log({balance}, {err})
40
41
await emulator.stop()
42
})()

While framework have automatic import resolver for Contracts you might want to know where it's currently deployed. We provide a method getContractAddress for this.

getContractAddress(name)

Returns address of the account where the contract is currently deployed.

Arguments

NameTypeDescription
namestringname of the contract

Returns

TypeDescription
Address0x prefixed address

Usage

1
import path from "path"
2
import {init, emulator, deployContractByName, getContractAddress} from "../src"
3
;(async () => {
4
const basePath = path.resolve(__dirname, "./cadence")
5
6
await init(basePath)
7
await emulator.start()
8
9
// if we omit "to" it will be deployed to Service Account
10
// but let's pretend we don't know where it will be deployed :)
11
await deployContractByName({name: "Hello"})
12
13
const contractAddress = await getContractAddress("Hello")
14
console.log({contractAddress})
15
16
await emulator.stop()
17
})()

📣 Framework does not support contracts with identical names deployed to different accounts. While you can deploy contract to a new address, the internal system, which tracks where contracts are deployed, will only store last address.