=============== LIBRARY RULES =============== From library maintainers: - Install the provider package for your cloud together with the core: hardhat-kms with @hardhat-kms/aws, @hardhat-kms/gcp, @hardhat-kms/azure or @hardhat-kms/turnkey, and list only the provider in plugins. - Run npx hardhat kms accounts to see each key's address, then pin it with the key's address field so a changed key fails loudly, and run npx hardhat kms accounts --check-sign to prove the credentials may sign. ### Install example dependencies with npm install Source: https://github.com/aelmanaa/hardhat-kms/blob/main/examples/README.md Run inside a copied example folder to install its dependencies. The package.json lists hardhat-kms and @hardhat-kms/aws with a caret range, equivalent to npm install --save-dev hardhat-kms @hardhat-kms/aws. Requires an AWS KMS key with ECC_SECG_P256K1 key spec and AWS credentials. ```sh npm install ``` -------------------------------- ### Install beta channel with npm, pnpm, or Yarn Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/explanation/versioning.md Install both packages from the `beta` dist-tag to test a version before promotion. Other packages (`@hardhat-kms/gcp`, `@hardhat-kms/azure`, `@hardhat-kms/turnkey`, `@hardhat-kms/safe`) install the same way. ```sh npm install --save-dev hardhat-kms@beta @hardhat-kms/aws@beta ``` ```sh pnpm add --save-dev hardhat-kms@beta @hardhat-kms/aws@beta ``` ```sh yarn add --dev hardhat-kms@beta @hardhat-kms/aws@beta ``` -------------------------------- ### Install hardhat-kms and @hardhat-kms/turnkey with Yarn Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/turnkey-setup.md Install the hardhat-kms plugin and the Turnkey provider package as dev dependencies using Yarn. Yarn 4 needs `nodeLinker: node-modules`; see the install guide for settings. ```sh yarn add --dev hardhat-kms @hardhat-kms/turnkey ``` -------------------------------- ### AWS: create role and attach signing policy Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/github-actions-oidc.md Create the role using trust-policy.json, then attach the hardhat-kms-deployer signing policy from the AWS setup guide. Replace with the actual ARN. ```sh aws iam create-role \ --role-name hardhat-kms-deploy \ --assume-role-policy-document file://trust-policy.json aws iam attach-role-policy --role-name hardhat-kms-deploy --policy-arn ``` -------------------------------- ### Install viem for core.account.viem-missing Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/reference/errors.md Required when connection.kms.getAccount cannot load the viem package. Install viem as a dev dependency using your package manager. ```bash npm install --save-dev viem ``` ```bash pnpm add -D viem ``` ```bash yarn add -D viem ``` -------------------------------- ### Install hardhat-kms and @hardhat-kms/turnkey with pnpm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/turnkey-setup.md Install the hardhat-kms plugin and the Turnkey provider package as dev dependencies using pnpm. Note that pnpm 11 and later need an `allowBuilds` entry; see the install guide for settings. ```sh pnpm add --save-dev hardhat-kms @hardhat-kms/turnkey ``` -------------------------------- ### Install hardhat-kms and @hardhat-kms/gcp with pnpm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/gcp-kms-setup.md Install the plugin and the GCP provider package using pnpm. pnpm 11 and later need an allowBuilds entry; see the install guide for settings. ```sh pnpm add --save-dev hardhat-kms @hardhat-kms/gcp ``` -------------------------------- ### Install hardhat-kms for local key or Ledger Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/propose-safe-transactions.md Install the required packages for using hardhat-kms with a local key or Ledger. Requires hardhat@^3.18.0, hardhat-kms, @hardhat-kms/safe, viem, and @nomicfoundation/hardhat-keystore. ```sh npm install --save-dev "hardhat@^3.18.0" hardhat-kms @hardhat-kms/safe viem @nomicfoundation/hardhat-keystore ``` -------------------------------- ### Install hardhat-kms and @hardhat-kms/gcp with Yarn Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/gcp-kms-setup.md Install the plugin and the GCP provider package using Yarn. Yarn 4 needs nodeLinker: node-modules; see the install guide for settings. ```sh yarn add --dev hardhat-kms @hardhat-kms/gcp ``` -------------------------------- ### Safe propose output example Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/propose-safe-transactions.md Example output printed to stdout after the service stores the proposal. Includes the SafeTx hash, Safe address, chain ID, nonce, threshold, owners, signer, and a link to the Safe app. ```text Proposed SafeTx 0x56d0c8521d3e248f74c1dd600311b5b2809fef7b70666a5badbebd5abbe91500 Safe 0xfFDBcab93921F1967577E66cc5E739571eB56F19 on chain 11155111, nonce 4 Threshold 2 of 3: 0x4a62316623ad457F02cDC5D997deD67a383EC569, 0x70997970C51812dc3A010C7d01b50e0d17dc79C8, 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 Signed by 0x4a62316623ad457F02cDC5D997deD67a383EC569 https://app.safe.global/transactions/tx?safe=sep:0xfFDBcab93921F1967577E66cc5E739571eB56F19&id=multisig_0xfFDBcab93921F1967577E66cc5E739571eB56F19_0x56d0c8521d3e248f74c1dd600311b5b2809fef7b70666a5badbebd5abbe91500 ``` -------------------------------- ### Install hardhat-kms and @hardhat-kms/azure with Yarn Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/azure-key-vault-setup.md Install the plugin and the Azure provider package using Yarn. Yarn 4 needs `nodeLinker: node-modules`; see the install guide for settings. ```sh yarn add --dev hardhat-kms @hardhat-kms/azure ``` -------------------------------- ### Install latest channel with npm, pnpm, or Yarn Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/explanation/versioning.md Default install takes the `latest` dist-tag. Use the package manager of your choice; all three commands install `hardhat-kms` and `@hardhat-kms/aws` as dev dependencies. ```sh npm install --save-dev hardhat-kms @hardhat-kms/aws ``` ```sh pnpm add --save-dev hardhat-kms @hardhat-kms/aws ``` ```sh yarn add --dev hardhat-kms @hardhat-kms/aws ``` -------------------------------- ### Install hardhat-kms and @hardhat-kms/turnkey with npm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/turnkey-setup.md Install the hardhat-kms plugin and the Turnkey provider package as dev dependencies using npm. This is the first step before configuring the plugin in the Hardhat config. ```sh npm install --save-dev hardhat-kms @hardhat-kms/turnkey ``` -------------------------------- ### Install hardhat-kms and @hardhat-kms/azure with pnpm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/azure-key-vault-setup.md Install the plugin and the Azure provider package using pnpm. pnpm 11 and later need an `allowBuilds` entry; see the install guide for settings. ```sh pnpm add --save-dev hardhat-kms @hardhat-kms/azure ``` -------------------------------- ### Install hardhat-kms and @hardhat-kms/azure with npm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/azure-key-vault-setup.md Install the plugin and the Azure provider package using npm. The Azure package brings the Azure SDK (@azure/keyvault-keys and @azure/identity) with it, so no additional installs are needed. ```sh npm install --save-dev hardhat-kms @hardhat-kms/azure ``` -------------------------------- ### Deploy workflow with OIDC sign-in for AWS, GCP, and Azure Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/github-actions-oidc.md Save as `.github/workflows/deploy.yml`. Runs on manual dispatch, waits for a reviewer, installs and builds, signs in to the cloud, checks the key can sign, then runs the deploy script. Keep only the sign-in step for your key's cloud and delete the other two with their secrets. `id-token: write` applies to every step, so `npm ci --ignore-scripts` avoids dependency install scripts and no dependency cache is restored. Each action is pinned to a full commit SHA with its version in a comment. ```yaml name: Deploy on: workflow_dispatch: permissions: {} jobs: deploy: runs-on: ubuntu-latest environment: deploy permissions: contents: read id-token: write # lets the job request the OIDC token steps: # Every step of this job can request an OIDC token, so no dependency install script runs # here (--ignore-scripts), and no dependency cache is restored. Installing and building # before the sign-in steps keeps the credentials they export out of the install and the # compiler download. - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: node-version: 24 package-manager-cache: false # setup-node caches npm when package.json names it - run: npm ci --ignore-scripts - run: npx hardhat build # AWS KMS - uses: aws-actions/configure-aws-credentials@e1253824e5c10ff9df46874f81ed3ec929e19cfd # v6.3.0 with: role-to-assume: ${{ secrets.AWS_ROLE_ARN }} aws-region: ${{ vars.AWS_REGION }} mask-aws-account-id: true # Google Cloud KMS: direct workload identity federation, no service account. - uses: google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093 # v3.0.0 with: workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }} # Azure Key Vault: signs the Azure CLI in, which the plugin then uses. - uses: azure/login@a641126d1b8aa4d1fa005f4f92df94a3a4c4c906 # v3.1.0 with: client-id: ${{ secrets.AZURE_CLIENT_ID }} tenant-id: ${{ secrets.AZURE_TENANT_ID }} allow-no-subscriptions: true - name: Check that the key signs env: DEPLOYER_KEY: ${{ secrets.DEPLOYER_KEY }} SEPOLIA_RPC_URL: ${{ secrets.SEPOLIA_RPC_URL }} run: npx hardhat --network sepolia kms accounts --balances --check-sign - name: Deploy env: DEPLOYER_KEY: ${{ secrets.DEPLOYER_KEY }} SEPOLIA_RPC_URL: ${{ secrets.SEPOLIA_RPC_URL }} run: npx hardhat run --network sepolia scripts/deploy.ts ``` -------------------------------- ### Install hardhat-kms and @hardhat-kms/gcp with npm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/gcp-kms-setup.md Install the plugin and the GCP provider package using npm. The GCP package brings the Google Cloud SDK with it, so nothing else is needed. npm prints a harmless deprecation warning about node-domexception. ```sh npm install --save-dev hardhat-kms @hardhat-kms/gcp ``` -------------------------------- ### Install packed packages with pnpm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/install-before-release.md Copies the packed .tgz files into a vendor directory and installs them as dev dependencies using pnpm. The install records the path in package.json, so a copy inside the project keeps working after the clone moves. ```sh mkdir -p vendor cp /packages/hardhat-kms/hardhat-kms-.tgz /packages/hardhat-kms-aws/hardhat-kms-aws-.tgz vendor/ pnpm add --save-dev ./vendor/hardhat-kms-.tgz ./vendor/hardhat-kms-aws-.tgz ``` -------------------------------- ### Install @alchemy/wallet-apis and viem (npm, pnpm, Yarn) Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/alchemy-wallet-apis.md Install the Wallet APIs package and viem as a dev dependency. @alchemy/wallet-apis 5.3.0 requires viem ^2.45.0 as a peer dependency, and getAccount needs viem 2.55.13 or later, so keep viem at that version or newer. ```sh npm install --save-dev @alchemy/wallet-apis viem ``` ```sh pnpm add --save-dev @alchemy/wallet-apis viem ``` ```sh yarn add --dev @alchemy/wallet-apis viem ``` -------------------------------- ### Install packed packages with Yarn Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/install-before-release.md Copies the packed .tgz files into a vendor directory and installs them as dev dependencies using Yarn. The install records the path in package.json, so a copy inside the project keeps working after the clone moves. ```sh mkdir -p vendor cp /packages/hardhat-kms/hardhat-kms-.tgz /packages/hardhat-kms-aws/hardhat-kms-aws-.tgz vendor/ yarn add --dev ./vendor/hardhat-kms-.tgz ./vendor/hardhat-kms-aws-.tgz ``` -------------------------------- ### Install Hardhat TypeChain plugin Source: https://github.com/aelmanaa/hardhat-kms/blob/main/examples/ethers/README.md Installs the Hardhat 3 TypeChain plugin as a dev dependency to generate contract types from the compiled ABI. ```sh npm install --save-dev @nomicfoundation/hardhat-typechain ``` -------------------------------- ### Build and pack packages from a clone Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/install-before-release.md Clones the repository, installs dependencies, builds, and packs the core and AWS provider packages into .tgz files. Requires Git, Node.js 22.18+, and pnpm 12. For other providers, pack the corresponding package directory instead. ```sh git clone https://github.com/aelmanaa/hardhat-kms.git cd hardhat-kms pnpm install pnpm build (cd packages/hardhat-kms && pnpm pack) (cd packages/hardhat-kms-aws && pnpm pack) ``` -------------------------------- ### Install Ignition and viem helpers with Yarn Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/deploy-with-ignition.md Install the Hardhat Ignition packages as dev dependencies using Yarn. Required for any Hardhat 3 project using Ignition modules. ```sh yarn add --dev @nomicfoundation/hardhat-ignition @nomicfoundation/hardhat-ignition-viem ``` -------------------------------- ### Install hardhat-kms and AWS provider (pnpm) Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/aws-kms-setup.md Install the hardhat-kms plugin and its AWS provider package as dev dependencies using pnpm. Note: pnpm 11 and later need an `allowBuilds` entry. ```sh pnpm add --save-dev hardhat-kms @hardhat-kms/aws ``` -------------------------------- ### Install hardhat-kms and AWS provider (npm) Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/aws-kms-setup.md Install the hardhat-kms plugin and its AWS provider package as dev dependencies using npm. This is the first step in setting up AWS KMS signing. ```sh npm install --save-dev hardhat-kms @hardhat-kms/aws ``` -------------------------------- ### Install Ignition and viem helpers with pnpm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/deploy-with-ignition.md Install the Hardhat Ignition packages as dev dependencies using pnpm. Required for any Hardhat 3 project using Ignition modules. ```sh pnpm add --save-dev @nomicfoundation/hardhat-ignition @nomicfoundation/hardhat-ignition-viem ``` -------------------------------- ### Install Ignition and viem helpers with npm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/deploy-with-ignition.md Install the Hardhat Ignition packages as dev dependencies using npm. Required for any Hardhat 3 project using Ignition modules. ```sh npm install --save-dev @nomicfoundation/hardhat-ignition @nomicfoundation/hardhat-ignition-viem ``` -------------------------------- ### Initialize an empty directory for Hardhat 3 (Yarn) Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/install-before-release.md Sets up a Yarn 4 project with type module. Required before installing hardhat-kms in an empty directory; without it, Hardhat 3 stops with 'Hardhat only supports ESM projects'. For Yarn 1, use 'yarn init -y' instead. ```sh yarn init -2 npm pkg set type=module ``` -------------------------------- ### Configure pnpm allowBuilds for esbuild and protobufjs Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/install-before-release.md Add to pnpm-workspace.yaml to fix ERR_PNPM_IGNORED_BUILDS. The plugin needs neither install script. Add other packages named by pnpm with value false. ```yaml allowBuilds: esbuild: false protobufjs: false # Google Cloud only ``` -------------------------------- ### Install hardhat-kms and AWS provider (Yarn) Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/aws-kms-setup.md Install the hardhat-kms plugin and its AWS provider package as dev dependencies using Yarn. Note: Yarn 4 needs `nodeLinker: node-modules`. ```sh yarn add --dev hardhat-kms @hardhat-kms/aws ``` -------------------------------- ### Add access policy with get and sign key permissions Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/reference/errors.md For azure.service.403-access-policy errors, add an access policy for the identity with the get and sign key permissions, as shown in step 2 of the Azure setup guide. Example command: az keyvault set-policy --name --object-id --key-permissions get sign. ```bash az keyvault set-policy --name --object-id --key-permissions get sign ``` -------------------------------- ### Initialize an empty directory for Hardhat 3 (pnpm) Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/install-before-release.md Creates a package.json with type module for pnpm. Required before installing hardhat-kms in an empty directory; without it, Hardhat 3 stops with 'Hardhat only supports ESM projects'. ```sh pnpm init pnpm pkg set type=module ``` -------------------------------- ### Script output: amount and transaction hash Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/return-funds.md Example output showing the amount sent and the transaction hash. The script prints these lines after a successful transfer. ```text sending … ETH from to sent in ``` -------------------------------- ### Create Hardhat project from viem template (npm) Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/tutorials/first-deploy-aws.md Initializes a Hardhat project using the node-test-runner-viem template in a new directory. The --yes flag lets npx download Hardhat without prompting. ```sh mkdir kms-tutorial cd kms-tutorial npx --yes hardhat@latest --init --template node-test-runner-viem ``` -------------------------------- ### Create Hardhat project from viem template (pnpm) Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/tutorials/first-deploy-aws.md Initializes a Hardhat project using the node-test-runner-viem template in a new directory. pnpm dlx does not ask for confirmation. ```sh mkdir kms-tutorial cd kms-tutorial pnpm dlx hardhat@latest --init --template node-test-runner-viem ``` -------------------------------- ### kms verify example invocations Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/reference/tasks.md Example invocations of kms verify. A message starting with '-' must be placed after '--' so Hardhat does not treat it as an option. ```bash npx hardhat kms verify --address 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 "hello world" 0xa461…5b1b npx hardhat kms verify --data --from-file --key deployer permit.json 0x… npx hardhat kms verify --address 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 -- "-1 ETH" 0x… ``` -------------------------------- ### List tutorial groups and vaults Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/tutorials/first-deploy-azure.md List groups created by the tutorial, then list vaults in the chosen group. More than one group means earlier runs left groups behind. ```sh az group list --tag created-by=hardhat-kms-tutorial --query '[].name' --output tsv az keyvault list --resource-group "${RG:?set RG to a group name from the list above}" --query '[].name' --output tsv ``` -------------------------------- ### Enable required Google Cloud APIs for Workload Identity Federation Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/github-actions-oidc.md Run this gcloud command to enable the four APIs listed in Google's guide for Workload Identity Federation with deployment pipelines. Enabling an API grants no permission. The iamcredentials.googleapis.com API is not called by this setup but is included per Google's guide. ```sh gcloud services enable iam.googleapis.com sts.googleapis.com cloudresourcemanager.googleapis.com \ iamcredentials.googleapis.com --project my-project ``` -------------------------------- ### Create Hardhat project from viem template (Yarn) Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/tutorials/first-deploy-aws.md Initializes a Hardhat project using the node-test-runner-viem template in a new directory. Pins Yarn 4 and approves forge-std repository because Hardhat does not run under Yarn 4's default Plug'n'Play linker. ```sh mkdir kms-tutorial cd kms-tutorial yarn init -2 printf 'nodeLinker: node-modules\napprovedGitRepositories:\n - "https://github.com/foundry-rs/forge-std.git"\n' >> .yarnrc.yml yarn dlx hardhat@latest --init --template node-test-runner-viem ``` -------------------------------- ### Example output of kms accounts with --kms azure Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/multiple-keys.md Shows the table of keys and the address pins to add. Entries with different pins or third-party provider keys are never merged and get a row each. ```text NAME PROVIDER SOURCE ADDRESS PIN PROTECTION KEY ID treasury gcp kms.keys 0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826 none HSM gcp: ops azure kms.keys 0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB none - azure: also: AZURE_KEY_VAULT_KEY_ID Address pins to add to each key's config: kms.keys.treasury: address: "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826", kms.keys.ops: address: "0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB", ``` -------------------------------- ### Configure Turnkey key in hardhat.config.ts Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/turnkey-setup.md Adds `@hardhat-kms/turnkey` to the plugins array and defines a Turnkey-backed key named `deployer` with `organizationId`, `address`, and `apiPrivateKey` as configuration variables. The `address` is required and written literally; the plugin signs with it and checks every signature against it. The `sepolia` network uses `kmsAccounts: ["deployer"]`. ```ts import hardhatKmsTurnkey from "@hardhat-kms/turnkey"; import { configVariable, defineConfig } from "hardhat/config"; export default defineConfig({ plugins: [hardhatKmsTurnkey], kms: { keys: { deployer: { provider: "turnkey", organizationId: configVariable("TURNKEY_ORGANIZATION_ID"), // The wallet account's address, from step 2. Written here, not read from a variable. address: "0x08cb1216C95149DF66978b574E484869512CE2bF", apiPrivateKey: configVariable("TURNKEY_API_PRIVATE_KEY"), }, }, }, networks: { sepolia: { type: "http", url: configVariable("SEPOLIA_RPC_URL"), chainId: 11155111, kmsAccounts: ["deployer"], }, }, }); ``` -------------------------------- ### Create Turnkey wallet and Ethereum account Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/turnkey-setup.md Creates a Turnkey wallet named 'hardhat' with an admin key, then creates an Ethereum account in that wallet and lists accounts to get the address. The address is used in the policy (step 4) and config (step 6); copy it exactly as printed because case sensitivity is not documented. ```sh turnkey wallets create --name hardhat --key-name admin turnkey wallets accounts create --wallet hardhat --address-format ADDRESS_FORMAT_ETHEREUM --key-name admin turnkey wallets accounts list --wallet hardhat --key-name admin ``` -------------------------------- ### Install packed packages with npm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/install-before-release.md Copies the packed .tgz files into a vendor directory and installs them as dev dependencies using npm. The install records the path in package.json, so a copy inside the project keeps working after the clone moves. ```sh mkdir -p vendor cp /packages/hardhat-kms/hardhat-kms-.tgz /packages/hardhat-kms-aws/hardhat-kms-aws-.tgz vendor/ npm install --save-dev ./vendor/hardhat-kms-.tgz ./vendor/hardhat-kms-aws-.tgz ``` -------------------------------- ### Ignition deployment and verification output Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/tutorials/first-deploy-aws.md Example output after deploying Counter and verifying on Blockscout and Sourcify. Both explorers may report 'already verified' because the template's Counter is common; Blockscout may instead end with '✅ Contract verified successfully on Blockscout!'. Open the printed Explorer link to confirm verification. ```text [ CounterModule ] successfully deployed 🚀 Deployed Addresses CounterModule#Counter - 0xc93b1fa3aB9Db68E28897528246b7ec4C5492865 Verifying deployed contracts Verifying contract "contracts/Counter.sol:Counter" for network sepolia... === Blockscout === The contract at 0xc93b1fa3aB9Db68E28897528246b7ec4C5492865 has already been verified on Blockscout. If you need to verify a partially verified contract, please use the --force flag. Explorer: https://eth-sepolia.blockscout.com/address/0xc93b1fa3aB9Db68E28897528246b7ec4C5492865#code === Sourcify === The contract at 0xc93b1fa3aB9Db68E28897528246b7ec4C5492865 has already been verified on Sourcify. If you need to verify a partially verified contract, please use the --force flag. Explorer: https://sourcify.dev/server/repo-ui/11155111/0xc93b1fa3aB9Db68E28897528246b7ec4C5492865 ``` -------------------------------- ### Install hardhat-kms with Yarn Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/install-before-release.md Installs the AWS provider for hardhat-kms with Yarn. Requires Hardhat ^3.18.0. For other clouds, replace @hardhat-kms/aws with the appropriate package. For Safe proposals, add @hardhat-kms/safe viem. ```sh yarn add --dev "hardhat@^3.18.0" hardhat-kms @hardhat-kms/aws ``` -------------------------------- ### Check signing credentials with hardhat kms accounts --check-sign Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/tutorials/first-deploy-azure.md Run `hardhat kms accounts --check-sign` to verify your credentials may sign with the key. The command prints a table with one row for the key; `matches` under `PIN` and `ok` under `SIGN` prove signing works and signatures recover to the pinned address. The check signs a random message, not a transaction, so it needs no funds. On `FAILED`, read the `error:` line under the row and fix the cause before step 5. ```sh npx hardhat kms accounts --check-sign ``` ```sh pnpm hardhat kms accounts --check-sign ``` ```sh yarn hardhat kms accounts --check-sign ``` -------------------------------- ### Install hardhat-kms with pnpm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/install-before-release.md Installs the AWS provider for hardhat-kms with pnpm. Requires Hardhat ^3.18.0. For other clouds, replace @hardhat-kms/aws with the appropriate package. For Safe proposals, add @hardhat-kms/safe viem. ```sh pnpm add --save-dev "hardhat@^3.18.0" hardhat-kms @hardhat-kms/aws ``` -------------------------------- ### Run return-funds script with RETURN_TO Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/return-funds.md Sets the RETURN_TO environment variable to an address with no code and runs the script via Hardhat. Prints the amount and transaction hash; a tiny amount stays behind due to fee reservation. Running again stops with an error if the balance does not cover the fee. ```sh RETURN_TO= npx hardhat run scripts/return-funds.ts ``` -------------------------------- ### List API keys with get_api_keys Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/turnkey-setup.md Lists all API keys for a user to identify leaked keys. Must be run with a root user's key (here 'admin') because the deny policy prevents the API user from managing its own keys. ```sh turnkey request --path /public/v1/query/get_api_keys --body '{ "organizationId": "'"$ORGANIZATION_ID"'", "userId": "" }' --key-name admin ``` -------------------------------- ### Install @hardhat-kms/gcp with hardhat-kms Source: https://github.com/aelmanaa/hardhat-kms/blob/main/packages/hardhat-kms-gcp/README.md Install the Google Cloud KMS provider for Hardhat 3. Requires Node.js 22.13.0 or later. The package must be installed at the same version as hardhat-kms. ```sh npm install --save-dev "hardhat@^3.18.0" hardhat-kms @hardhat-kms/gcp ``` -------------------------------- ### createKeyAdapter() Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/reference/api/hardhat-kms/types.md Builds the adapter for one key. A handler builds adapters for its own provider ids and calls next for any other key. ```APIDOC ## createKeyAdapter() ### Description Builds the adapter for one key. A handler builds adapters for its own provider ids and calls `next` for any other key. The first-party provider packages, such as @hardhat-kms/aws, use this hook too. A key that no handler claims fails with an error; for `aws`, `gcp` and `azure` keys, the error names the package to install. The plugin validates only the fields every key shares. A handler validates the rest of an `ExternalKmsKeyConfig`'s `userConfig` itself; configuration variables in it are `ResolvedConfigurationVariable` objects. The plugin rejects an adapter without `describe()`, without a signing method, or without `getPublicKey` or `getAddress` when the key has no `address` pin. It verifies every signature an adapter returns. ### Method createKeyAdapter ### Parameters #### Parameters - `context` (HookContext) - Required - The Hardhat runtime, without tasks. - `key` (KmsKeyConfig) - Required - The resolved key. - `next` (function) - Required - Passes the key to the next handler. ### Returns `Promise` - The key's adapter. ``` -------------------------------- ### Example output of kms address Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/reference/tasks.md Example output showing the derived address with EIP-55 checksum. ```text 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 ``` -------------------------------- ### Sample output of who-signed.ts for AWS key Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/who-signed.md Example output showing candidate signing events for two transactions from an AWS key. Events are listed newest first within a window from two minutes before the block to five seconds after. Nearby events may not be the actual signer; retried requests are logged per try and an event can appear under multiple transactions. ```text chain 11155111, history from cloudtrail-event-history, 2026-10-05T09:00:00.000Z to 2026-10-05T09:15:00.000Z 0xaaaa…: nonce 18, mined 2026-10-05T09:07:48.000Z, 4 sign event(s) in the 120 s before 2026-10-05T09:07:42.000Z principal arn:aws:iam::111122223333:user/deployer agent aws-sdk-js/3.1146.0 … hardhat-kms/0.8.0 2026-10-05T09:06:36.000Z principal arn:aws:iam::111122223333:user/deployer agent aws-sdk-js/3.1146.0 … hardhat-kms/0.8.0 2026-10-05T09:06:07.000Z principal arn:aws:iam::111122223333:user/deployer agent aws-sdk-js/3.1146.0 … hardhat-kms/0.8.0 2026-10-05T09:06:05.000Z principal arn:aws:iam::111122223333:user/deployer agent aws-sdk-js/3.1146.0 … hardhat-kms/0.8.0 0xbbbb…: nonce 17, mined 2026-10-05T09:06:48.000Z, 4 sign event(s) in the 120 s before 2026-10-05T09:06:36.000Z principal arn:aws:iam::111122223333:user/deployer agent aws-sdk-js/3.1146.0 … hardhat-kms/0.8.0 2026-10-05T09:06:07.000Z principal arn:aws:iam::111122223333:user/deployer agent aws-sdk-js/3.1146.0 … hardhat-kms/0.8.0 2026-10-05T09:06:05.000Z principal arn:aws:iam::111122223333:user/deployer agent aws-sdk-js/3.1146.0 … hardhat-kms/0.8.0 2026-10-05T09:05:21.000Z principal arn:aws:iam::111122223333:user/deployer agent aws-sdk-js/3.1146.0 … hardhat-kms/0.8.0 ``` -------------------------------- ### Install @hardhat-kms/safe with npm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/packages/hardhat-kms-safe/README.md Install the package in a Hardhat 3 project. Requires hardhat-kms at the same version and viem ^2.55.13. Node.js 22.13.0 or later is required. ```sh npm install --save-dev "hardhat@^3.18.0" hardhat-kms @hardhat-kms/safe viem ``` -------------------------------- ### Check KMS signing permissions (Yarn) Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/tutorials/first-deploy-aws.md Run the KMS accounts check with Yarn to verify that your credentials can sign with the key. The output table shows `matches` under PIN and `ok` under SIGN when successful; `FAILED` indicates a permissions issue. ```sh yarn hardhat kms accounts --check-sign ``` -------------------------------- ### Run hardhat kms history command Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/who-signed.md Use the `history` task to read sign events for a key named `deployer` within a time window. `--since` and `--until` accept ISO 8601 times, dates, or durations like `30m`, `6h`, or `7d`. Without `--since`, it reads the 24 hours before `--until` (defaults to now), prints at most 100 events newest first, and `--limit` can increase to 1000. No `--network` is needed and it signs nothing. ```sh npx hardhat kms history deployer --since 2026-10-05T09:00:00Z --until 2026-10-05T09:15:00Z ``` -------------------------------- ### Check hardhat-kms install with yarn hardhat kms --help Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/install-before-release.md Runs `yarn hardhat kms --help` to verify the plugin is installed. Hardhat lists the plugin's tasks: `kms accounts`, `kms address`, `kms history`, `kms public-key`, `kms sign`, `kms sign-auth`, `kms sign-tx` and `kms verify`. With `@hardhat-kms/safe`, it also lists `kms safe`. If it answers `Error HHE404: Task "kms" not found`, the packages are installed but the plugin is not in `plugins`. ```sh yarn hardhat kms --help ``` -------------------------------- ### Get activity details with turnkey request Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/turnkey-setup.md Use `get_activity` to read the pending activity by its id, taking `organizationId` and `activityId`. Check that the status is still `ACTIVITY_STATUS_CONSENSUS_NEEDED` or `ACTIVITY_STATUS_AUTHENTICATORS_NEEDED`, note its `fingerprint`, and verify `canReject`. ```sh turnkey request --path /public/v1/query/get_activity --body '{ "organizationId": "'"$ORGANIZATION_ID"'", "activityId": "" }' --key-name admin ``` -------------------------------- ### Deploy and verify with Yarn Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/tutorials/first-deploy-aws.md Same deployment and verification command as the npm variant, but run with Yarn. Ignition asks to confirm the network (answer y); each transaction usually costs one KMS Sign call. Naming the sender by address keeps the deployer consistent when accounts or keys are added later. ```sh yarn hardhat ignition deploy ignition/modules/Counter.ts --network sepolia --verify --default-sender "$DEPLOYER_ADDRESS" ``` -------------------------------- ### Check hardhat-kms install with pnpm hardhat kms --help Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/install-before-release.md Runs `pnpm hardhat kms --help` to verify the plugin is installed. Hardhat lists the plugin's tasks: `kms accounts`, `kms address`, `kms history`, `kms public-key`, `kms sign`, `kms sign-auth`, `kms sign-tx` and `kms verify`. With `@hardhat-kms/safe`, it also lists `kms safe`. If it answers `Error HHE404: Task "kms" not found`, the packages are installed but the plugin is not in `plugins`. ```sh pnpm hardhat kms --help ``` -------------------------------- ### Deploy and verify with pnpm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/tutorials/first-deploy-aws.md Same deployment and verification command as the npm variant, but run with pnpm. Ignition asks to confirm the network (answer y); each transaction usually costs one KMS Sign call. Naming the sender by address keeps the deployer consistent when accounts or keys are added later. ```sh pnpm hardhat ignition deploy ignition/modules/Counter.ts --network sepolia --verify --default-sender "$DEPLOYER_ADDRESS" ``` -------------------------------- ### Check hardhat-kms install with npx hardhat kms --help Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/install-before-release.md Runs `npx hardhat kms --help` to verify the plugin is installed. Hardhat lists the plugin's tasks: `kms accounts`, `kms address`, `kms history`, `kms public-key`, `kms sign`, `kms sign-auth`, `kms sign-tx` and `kms verify`. With `@hardhat-kms/safe`, it also lists `kms safe`. If it answers `Error HHE404: Task "kms" not found`, the packages are installed but the plugin is not in `plugins`. ```sh npx hardhat kms --help ``` -------------------------------- ### Install @hardhat-kms/turnkey with npm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/packages/hardhat-kms-turnkey/README.md Install the Turnkey provider for hardhat-kms in a Hardhat 3 project. Requires hardhat-kms at the same version and Node.js 22.13.0 or later. ```sh npm install --save-dev "hardhat@^3.18.0" hardhat-kms @hardhat-kms/turnkey ``` -------------------------------- ### Output of kms accounts --check-sign Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/tutorials/first-deploy-gcp.md Example table output from `hardhat kms accounts --check-sign` showing one row for the deployer key. `matches` under PIN and `ok` under SIGN prove that credentials may sign and signatures recover to the pinned address. On FAILED, read the `error:` line under the row and fix the cause before step 5. ```text NAME PROVIDER SOURCE ADDRESS PIN PROTECTION SIGN KEY ID deployer gcp kms.keys matches HSM ok gcp:projects//locations//keyRings/hardhat-kms-tutorial/cryptoKeys/deployer/cryptoKeyVersions/1 ``` -------------------------------- ### kms safe propose example on sepolia Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/reference/tasks.md Example command that proposes a Safe transaction on the sepolia network, sending 1000 wei to a specified address. ```bash npx hardhat --network sepolia kms safe propose 0xfFDBcab93921F1967577E66cc5E739571eB56F19 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 --value 1000 ``` -------------------------------- ### kms accounts output example Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/reference/tasks.md Example output of the kms accounts command, showing the table with key details and address pins to add to the config. ```text NAME PROVIDER SOURCE ADDRESS PIN PROTECTION KEY ID deployer aws kms.keys 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 matches - aws:alias/deployer sepolia.kmsAccounts[1] gcp kmsAccounts 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 none HSM gcp: also: mainnet.kmsAccounts[0] AWS_KMS_KEY_ID aws --kms FAILED - - aws: error: aws, create adapter, key aws:: AWS KMS keys need the @hardhat-kms/aws plugin. Install it with `npm install --save-dev @hardhat-kms/aws` and add it to `plugins` in your Hardhat config Address pins to add to each key's config: networks.sepolia.kmsAccounts[1]: address: "0x70997970C51812dc3A010C7d01b50e0d17dc79C8", networks.mainnet.kmsAccounts[0]: address: "0x70997970C51812dc3A010C7d01b50e0d17dc79C8", ``` -------------------------------- ### Check KMS signing permissions (pnpm) Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/tutorials/first-deploy-aws.md Run the KMS accounts check with pnpm to verify that your credentials can sign with the key. The output table shows `matches` under PIN and `ok` under SIGN when successful; `FAILED` indicates a permissions issue. ```sh pnpm hardhat kms accounts --check-sign ``` -------------------------------- ### Check KMS key signs on sepolia (scripts/check-kms.ts) Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/guides/aws-kms-setup.md Lists accounts on sepolia and signs the message 'hello' with the last account, which is the KMS account. Run with `npx hardhat run scripts/check-kms.ts`. The KMS address comes last in `eth_accounts`; each run calls `GetPublicKey` once before the first signature, then `Sign` once per signature (or more on retries). An `address` pin does not save that call because the plugin checks the public key against the pin before releasing a signature. ```TypeScript import { network } from "hardhat"; const { provider } = await network.create("sepolia"); const accounts = await provider.request({ method: "eth_accounts" }); const address: unknown = Array.isArray(accounts) ? accounts.at(-1) : undefined; if (typeof address !== "string") { throw new Error("no accounts"); } const signature = await provider.request({ method: "personal_sign", params: ["0x68656c6c6f", address], }); console.log(address, signature); ``` -------------------------------- ### Install @hardhat-kms/azure with npm Source: https://github.com/aelmanaa/hardhat-kms/blob/main/packages/hardhat-kms-azure/README.md Install the Azure provider for hardhat-kms in a Hardhat 3 project. Requires hardhat-kms at the same version and Node.js 22.13.0 or later. ```sh npm install --save-dev "hardhat@^3.18.0" hardhat-kms @hardhat-kms/azure ``` -------------------------------- ### kms public-key example output Source: https://github.com/aelmanaa/hardhat-kms/blob/main/docs/user/reference/tasks.md Example output of the kms public-key task: a 65-byte public key as 0x04 followed by 128 lowercase hex digits. ```text 0x048318535b54105d4a7aae60c08fc45f9687181b4fdfc625bd1a753fa7397fed753547f11ca8696646f2f3acb08e31016afac23e630c5d11f59f61fef57b0d2aa5 ```