diff --git a/README.md b/README.md index d98034bd..408b6b97 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,17 @@ This plugin was tested with: - npm/npx v7.21.1 - Docker v20.10.8: - Make sure you have a running Docker daemon. -- Linux OS / macOS: - - For developers using Windows, the recommended way is to use WSL 2. +- Linux / macOS: + - On Windows, we recommend using WSL 2. ## Install ``` npm install @shardlabs/starknet-hardhat-plugin ``` +Add the following line to the top of your `hardhat.config.ts` (or `hardhat.config.js`): +```typescript +import "@shardlabs/starknet-hardhat-plugin"; +``` ## Use This plugin adds the following tasks which target the source/artifact/test directories of your Hardhat project: @@ -40,7 +44,7 @@ module.exports = { ``` you can use it by calling `npx hardhat starknet-deploy --starknet-network myNetwork`. -The `alpha` testnet is available by default, you don't need to specify it. +The Alpha testnet is available by default, you don't need to specify it. ## Test To test Starknet contracts with Mocha, use the regular Hardhat `test` task which expects test files in your designated test directory: @@ -49,12 +53,11 @@ npx hardhat test ``` Read more about the network used in tests in the [Testing network](#testing-network) section. +These examples are inspired by the [official Python tutorial](https://www.cairo-lang.org/docs/hello_starknet/unit_tests.html). -Test your contracts in the following manner (comparable to the [official Python tutorial](https://www.cairo-lang.org/docs/hello_starknet/unit_tests.html)). - -All function names, argument names and return value names should be referred to by names specified in contract source files. - -`BigInt` is used because `felt` may be too big for javascript. Use `BigInt` like `BigInt("10")` or `10n`. +### Important note +- `BigInt` is used because `felt` may be too big for javascript. Use it like `BigInt("10")` or, since ES2020, like `10n`. +- All function names, argument names and return value names should be referred to by the names specified in contract source files. ```typescript import { expect } from "chai"; @@ -80,7 +83,13 @@ describe("My Test", function () { await contract.invoke("increase_balance", { amount: BigInt("20") }); const { res } = await contract.call("get_balance"); // call method by name and receive the result by name - expect(res).to.deep.equal(BigInt(40)); // since ECMAScript 2020, you can also use 40n instead of BigInt(40) + expect(res).to.deep.equal(BigInt(40)); // you can also use 40n instead of BigInt(40) + }); + + it("should work for a previously deployed contract", async function () { + const contractFactory = await starknet.getContractFactory("MyContract"); + const contract = contractFactory.getContractAt("0x123..."); // you might wanna put an actual address here + await contract.invoke(...); }); /** @@ -108,12 +117,6 @@ describe("My Test", function () { expect(res).to.deep.equal(BigInt(30)); }); - it("should work for a previously deployed contract", async function () { - const contractFactory = await starknet.getContractFactory("MyContract"); - const contract = contractFactory.getContractAt("0x123..."); // you might wanna put an actual address here - await contract.invoke(...); - }); - /** * Assumes there is a file MyAuthContract.cairo whose compilation artifacts have been generated. * The contract is assumed to have: @@ -129,11 +132,7 @@ describe("My Test", function () { const contract = await authContractFactory.deploy({ lucky_user: publicKey, initial_balance: 10 }); // signature is calculated for each transaction according to `publicKey` used and `amount` passed - const signature = [ - BigInt("123..."), - BigInt("456...") - ]; - + const signature = [BigInt("123..."), BigInt("456...")]; await contract.invoke("increase_balance", { user: publicKey, amount: 20 }, signature); // notice how `res` is mapped to `balance` @@ -171,14 +170,14 @@ module.exports = { ... cairo: { // The default in this version of the plugin - version: "0.5.2" + version: "0.6.0" } ... }; ``` ### Testing network -If you don't specify a `mocha.starknetNetwork`, the program defaults to using the alpha testnet for Mocha tests. +If you don't specify a `mocha.starknetNetwork`, the program defaults to using the Alpha testnet for Mocha tests. A faster approach, but still in beta-phase, is to use [starknet-devnet](https://github.com/Shard-Labs/starknet-devnet), a Ganache-like local testnet. diff --git a/package.json b/package.json index d94f928b..9d588c71 100644 --- a/package.json +++ b/package.json @@ -1,11 +1,21 @@ { "name": "@shardlabs/starknet-hardhat-plugin", - "version": "0.3.0", + "version": "0.3.1", "description": "Plugin for using Starknet tools within Hardhat projects", "main": "dist/index.js", "files": [ "dist" ], + "keywords": [ + "starknet", + "hardhat", + "plugin", + "starkware", + "cairo", + "compile", + "deploy", + "test" + ], "repository": { "type": "git", "url": "https://github.com/Shard-Labs/starknet-hardhat-plugin.git" diff --git a/scripts/test.sh b/scripts/test.sh index cdda9719..9891bf65 100755 --- a/scripts/test.sh +++ b/scripts/test.sh @@ -4,6 +4,7 @@ set -e rm -rf starknet-hardhat-example git clone -b plugin --single-branch git@github.com:Shard-Labs/starknet-hardhat-example.git cd starknet-hardhat-example +git log -n 1 npm install CONFIG_FILE_NAME="hardhat.config.ts" diff --git a/src/constants.ts b/src/constants.ts index ef7ee8c4..81de9c59 100644 --- a/src/constants.ts +++ b/src/constants.ts @@ -4,8 +4,8 @@ export const ABI_SUFFIX = "_abi.json"; export const DEFAULT_STARKNET_SOURCES_PATH = "contracts"; export const DEFAULT_STARKNET_ARTIFACTS_PATH = "starknet-artifacts"; export const DOCKER_REPOSITORY = "shardlabs/cairo-cli"; -export const DEFAULT_DOCKER_IMAGE_TAG = "0.5.2"; +export const DEFAULT_DOCKER_IMAGE_TAG = "0.6.0"; export const DEFAULT_STARKNET_NETWORK = "alpha"; -export const ALPHA_URL = "https://alpha3.starknet.io:443" +export const ALPHA_URL = "https://alpha4.starknet.io:443" export const CHECK_STATUS_TIMEOUT = 1000; // ms export const LEN_SUFFIX = "_len"; diff --git a/src/index.ts b/src/index.ts index 9d65ef83..b8f6f930 100644 --- a/src/index.ts +++ b/src/index.ts @@ -47,7 +47,7 @@ async function traverseFiles( */ function processExecuted(executed: ProcessResult): number { if (executed.stdout.length) { - console.log(executed.stdout.toString()); + console.log(adaptLog(executed.stdout.toString())); } if (executed.stderr.length) { @@ -257,6 +257,7 @@ task("starknet-deploy", "Deploys Starknet contracts which have been compiled.") const providedStarknetNetwork: string = args.starknetNetwork || process.env.STARKNET_NETWORK; if (providedStarknetNetwork) { + hre.starknet.network = providedStarknetNetwork; const httpNetwork = hre.config.networks[providedStarknetNetwork]; args.gatewayUrl = args.gatewayUrl || httpNetwork.url; } @@ -313,7 +314,7 @@ async function findPath(traversable: string, name: string) { } extendEnvironment(hre => { - hre.starknet = lazyObject(() => ({ + hre.starknet = { getContractFactory: async contractName => { const metadataPath = await findPath(hre.config.paths.starknetArtifacts, `${contractName}.json`); if (!metadataPath) { @@ -344,5 +345,5 @@ extendEnvironment(hre => { feederGatewayUrl: testNetwork.url }); } - })); + }; }); diff --git a/src/type-extensions.ts b/src/type-extensions.ts index 790cf497..d041f7a1 100644 --- a/src/type-extensions.ts +++ b/src/type-extensions.ts @@ -36,13 +36,20 @@ type StarknetContractFactoryType = StarknetContractFactory; declare module "hardhat/types/runtime" { interface HardhatRuntimeEnvironment { dockerWrapper: DockerWrapper; - /** - * Fetches a compiled contract by name. E.g. if the contract is defined in MyContract.cairo, - * the provided string should be `MyContract`. - * @param name the case-sensitive contract name - */ + starknet: { + /** + * Fetches a compiled contract by name. E.g. if the contract is defined in MyContract.cairo, + * the provided string should be `MyContract`. + * @param name the case-sensitive contract name + * @returns a factory for generating instances of the desired contract + */ getContractFactory: (name: string) => Promise; + + /** + * The selected starknet-network, present when specified with --starknet-network. + */ + network?: string; } } diff --git a/src/utils.ts b/src/utils.ts index 23ecef3c..3fc259d1 100644 --- a/src/utils.ts +++ b/src/utils.ts @@ -7,7 +7,7 @@ export function adaptLog(msg: string): string { return msg .replace("--network", "--starknet-network") - .replace("--gateway_url", "--gateway-url"); + .replace("gateway_url", "gateway-url"); } const DOCKER_HOST = "host.docker.internal";