docs: add a using viem guide to Ignition (#4661)

Add a guide to installing and using the
`@nomicfoundation/hardhat-ignition-viem` package and its support for
returning Viem contract instances from the Ignition Helper.

Update the npm installs for Ignition to include peer deps for npm 6.

Author: kanej

docs/src/content/ignition/docs/getting-started/index.md

@@ -32,30 +32,36 @@ To install Hardhat Ignition in an existing Hardhat project, you will need:
 
 You can also follow [Hardhat's Quick Start guide](../../../hardhat-runner/docs/getting-started/index.md) to create a new project from scratch to follow this guide.
 
+:::tip
+
+If you prefer to use **Viem** instead of **ethers**, check out the [Viem guide](../../../ignition/docs/guides/viem.md) for installation instructions.
+
+:::
+
 Once you have a Hardhat project ready, open a terminal in its root directory, and run:
 
 ::::tabsgroup{options="npm 7+,npm 6,yarn"}
 
 :::tab{value="npm 7+"}
 
 ```sh
-npm install --save-dev @nomicfoundation/hardhat-ignition
+npm install --save-dev @nomicfoundation/hardhat-ignition-ethers
 ```
 
 :::
 
 :::tab{value="npm 6"}
 
 ```sh
-npm install --save-dev @nomicfoundation/hardhat-ignition
+npm install --save-dev @nomicfoundation/hardhat-ignition-ethers @nomicfoundation/hardhat-ethers @nomicfoundation/hardhat-ignition @nomicfoundation/hardhat-verify @nomicfoundation/ignition-core ethers
 ```
 
 :::
 
 :::tab{value=yarn}
 
 ```sh
-yarn add --dev @nomicfoundation/hardhat-ignition
+yarn add --dev @nomicfoundation/hardhat-ignition-ethers @nomicfoundation/hardhat-ethers @nomicfoundation/hardhat-ignition @nomicfoundation/hardhat-verify @nomicfoundation/ignition-core ethers
 ```
 
 :::
@@ -69,15 +75,15 @@ Finally, add this to your config file to [enable the plugin](../../../hardhat-ru
 :::tab{value="TypeScript"}
 
 ```typescript
-import "@nomicfoundation/hardhat-ignition";
+import "@nomicfoundation/hardhat-ignition-ethers";
 ```
 
 :::
 
 :::tab{value="JavaScript"}
 
 ```javascript
-require("@nomicfoundation/hardhat-ignition");
+require("@nomicfoundation/hardhat-ignition-ethers");
 ```
 
 :::

docs/src/content/ignition/docs/guides/_dirinfo.yaml

@@ -8,3 +8,4 @@ order:
   - /modifications
   - /tests
   - /verify
+  - /viem

docs/src/content/ignition/docs/guides/tests.md

@@ -2,6 +2,12 @@
 
 If you want to test that your deployment was correctly defined, or if you want to use your Ignition Modules to simplify your test setup, continue reading this guide.
 
+:::tip
+
+If you prefer to use **Viem** instead of **ethers**, check out the [Viem guide](../../../ignition/docs/guides/viem.md) for more details.
+
+:::
+
 ## The Ignition object
 
 Requiring Hardhat Ignition within your Hardhat config will automatically add an `ignition` object to the [Hardhat Runtime Environment](../../../hardhat-runner/docs/advanced/hardhat-runtime-environment.md).
@@ -60,3 +66,17 @@ it("should set the start count to 0 by default", async function () {
   return { counter };
 });
 ```
+
+## Sending transactions with a different account
+
+The `ignition.deploy` method will default to using the first account in Hardhat network's `accounts` array as the sender for all transactions.
+
+You can change this by passing a `defaultSender` within the options object as a second argument to the `deploy` method:
+
+```typescript
+const [first, second] = await hre.ethers.getSigners();
+
+const result = await hre.ignition.deploy(CounterModule, {
+  defaultSender: second.address,
+});
+```

docs/src/content/ignition/docs/guides/viem.md

@@ -0,0 +1,149 @@
+# Using Viem
+
+Hardhat Ignition provides a variant based on using [Viem](https://viem.sh) as your connection library. Viem is a lightweight alternative to [ethers](https://docs.ethers.org) with a focus on type safety.
+
+The Viem support in Hardhat Ignition includes a helper function, for use in Hardhat tests and scripts, that allows you to deploy Ignition modules and get back the deployed contracts as fully typed Viem contract instances.
+
+## Installation
+
+To install Hardhat Ignition with Viem support in an existing Hardhat project, you will need:
+
+- Hardhat version 2.18.0 or higher
+- Viem version 1.18.0 or higher
+
+You can also follow [Hardhat's Viem Quick Start](../../../hardhat-runner/docs/advanced/using-viem#quick-start) to create a new Hardhat Viem project from scratch.
+
+From the root directory of your Hardhat project run:
+
+::::tabsgroup{options="npm 7+,npm 6,yarn"}
+
+:::tab{value="npm 7+"}
+
+```shell
+npm install --save-dev @nomicfoundation/hardhat-ignition-viem
+```
+
+:::
+
+:::tab{value="npm 6"}
+
+```shell
+npm install --save-dev @nomicfoundation/hardhat-ignition-viem @nomicfoundation/hardhat-ignition @nomicfoundation/hardhat-verify @nomicfoundation/hardhat-viem @nomicfoundation/ignition-core typescript viem
+```
+
+:::
+
+:::tab{value=yarn}
+
+```shell
+yarn add --dev @nomicfoundation/hardhat-ignition-viem @nomicfoundation/hardhat-ignition @nomicfoundation/hardhat-verify @nomicfoundation/hardhat-viem @nomicfoundation/ignition-core typescript viem
+```
+
+:::
+
+::::
+
+Then [enable the plugin](../../../hardhat-runner/docs/guides/project-setup.md#plugins-and-dependencies) in your config file:
+
+::::tabsgroup{options="TypeScript,JavaScript"}
+
+:::tab{value="TypeScript"}
+
+```typescript
+import "@nomicfoundation/hardhat-ignition-viem";
+```
+
+:::
+
+:::tab{value="JavaScript"}
+
+```javascript
+require("@nomicfoundation/hardhat-ignition-viem");
+```
+
+:::
+
+::::
+
+:::tip
+
+Only **one** Hardhat Ignition package should be imported within your Hardhat config file. Viem and ethers support cannot both be enabled at the same time.
+
+:::
+
+## The Ignition object
+
+The `@nomicfoundation/hardhat-plugin-viem` plugin adds an `ignition` object to the [Hardhat Runtime Environment](../../../hardhat-runner/docs/advanced/hardhat-runtime-environment.md).
+
+The `ignition` object exposes a `deploy` method, which takes an Ignition module, deploys it against the current network, like Hardhat Network, and returns the results of the module as typed Viem contract instances.
+
+The `deploy` method takes the Module as its first argument:
+
+```typescript
+const ApolloModule = buildModule("Apollo", (m) => {
+  const apollo = m.contract("Rocket", ["Saturn V"]);
+
+  return { apollo };
+});
+
+it("should have named the rocket Saturn V", async function () {
+  const { apollo } = await hre.ignition.deploy(ApolloModule);
+
+  assert.equal(await apollo.read.name(), "Saturn V");
+});
+```
+
+The `ignition.deploy` method returns an object with a Viem contract instance per `Future` returned as a result in the module.
+
+## Usage with Artifacts
+
+To infer the type of a Viem contract instance, the full type of the ABI must be available when initializing a `Future` within a module.
+
+For named Hardhat contracts, the ABI and type information will be retrieved automatically using [hardhat-viem's type generation](https://hardhat.org/hardhat-runner/docs/advanced/using-viem#contract-type-generation).
+
+If you are passing an artifact object to initialize a `Future` within a module, you will need to ensure the artifact's ABI is either declared with [const assertions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#const-assertions) or defined inline:
+
+```typescript
+const counterArtifact = {
+  // ...
+  abi: [...] as const, // <--- const assertion
+}
+
+const CounterModule = buildModule("Counter", (m) => {
+  const counter = m.contract("Counter", CounterArtifact, [42]);
+
+  return { counter };
+});
+```
+
+If type inference isn't working for the returned contract, it is likely that the ABI type needs a `const` assertion or to be defined inline.
+
+This is because the ABI type must be as narrow as possible for Viem to infer the correct type for the contract, and by default Typescript will broaden the types within object literals.
+
+:::tip
+
+Typescript doesn't support importing JSON as const, it will instead automatically broaden the type, breaking Viem's inference. The artifact must be defined inline within Typescript.
+
+:::
+
+See [Viem's type inference requirements](https://viem.sh/docs/typescript.html#type-inference) for more details.
+
+## Sending transactions with a different account
+
+The `ignition.deploy` method will default to using the first account in Hardhat network's `accounts` array as the sender for all transactions.
+
+You can change this by passing a `defaultSender` within the options object as a second argument to the `deploy` method:
+
+```typescript
+const [first, second] = await hre.viem.getWalletClients();
+
+const result = await hre.ignition.deploy(ApolloModule, {
+  defaultSender: second.account.address,
+});
+```
+
+## Hardhat Ignition and Hardhat Viem
+
+Hardhat Ignition leverages the [hardhat-viem](https://hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-viem) plugin for its type generation support, and inherits the same approach to [managing types and version stability](https://hardhat.org/hardhat-runner/docs/advanced/using-viem#managing-types-and-version-stability).
+
+Read the documentation on [hardhat-viem](https://hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-viem) to learn more about Hardhat's Viem capabilities.