generated from valora-inc/typescript-app-starter
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Showing
2 changed files
with
49 additions
and
75 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,97 +1,71 @@ | ||
| # typescript-app-starter | ||
| # @valora/viem-account-hsm-gcp | ||
|
|
||
| A starter template for Valora TypeScript projects with best practices. | ||
| [](https://github.com/valora-inc/viem-account-hsm-gcp/blob/main/LICENSE) | ||
| [](https://www.npmjs.com/package/@valora/viem-account-hsm-gcp) | ||
| [](https://github.com/valora-inc/viem-account-hsm-gcp/actions/workflows/workflow.yaml?query=branch%3Amain) | ||
| [](https://codecov.io/gh/valora-inc/viem-account-hsm-gcp) | ||
| [](https://github.com/valora-inc/viem-account-hsm-gcp#contributing) | ||
|
|
||
| ## What's in the stack? | ||
| Use a Google Cloud HSM key to sign transactions with [viem](https://viem.sh/). | ||
|
|
||
| - [TypeScript](https://www.typescriptlang.org/) | ||
| - Unit testing with [Jest](https://jestjs.io) | ||
| - Linting with [ESLint](https://eslint.org/), configured with [@valora/eslint-config-typescript](https://github.com/valora-inc/eslint-config-typescript) | ||
| - Automatic code formating with [Prettier](https://prettier.io/), configured with [@valora/prettier-config](https://github.com/valora-inc/prettier-config) | ||
| - Scripts using [ShellJS](https://github.com/shelljs/shelljs) | ||
| - Linted and statically checked with [TypeScript](https://www.typescriptlang.org/) | ||
| - CI/CD with [GitHub Actions](https://docs.github.com/en/actions) | ||
| - Semantic PR title enforcement with [semantic-pull-request](https://github.com/amannn/action-semantic-pull-request) | ||
| - Automated dependency updates with [Renovate](https://renovatebot.com/), configured with [valora-inc/renovate-config](https://github.com/valora-inc/renovate-config) | ||
| ## Installing the library | ||
|
|
||
| ## How to use this? | ||
|
|
||
| Above the file list, click the big green button: `Use this template`. | ||
|
|
||
| Or using [GitHub CLI](https://cli.github.com/): | ||
|
|
||
| ```sh | ||
| gh repo create --template valora-inc/typescript-app-starter valora-inc/new-repo | ||
| ``` | ||
| yarn add @valora/viem-account-hsm-gcp | ||
| ``` | ||
|
|
||
| ## Structure | ||
|
|
||
| Here's the recommended structure: | ||
|
|
||
| - [`src`](src): source code | ||
| - [`index.ts`](src/index.ts): example source file | ||
| - [`index.test.ts`](src/index.test.ts): unit tests for `index.ts` | ||
| - [`scripts`](scripts): more complex scripts in TypeScript | ||
| - [`example.ts`](scripts/example.ts): example script using [ShellJS](https://github.com/shelljs/shelljs) | ||
|
|
||
| ## Type Checking | ||
|
|
||
| This project uses [TypeScript](https://www.typescriptlang.org/). It's recommended to get TypeScript set up for your editor to get a really great in-editor experience with type checking and auto-complete. To run type checking across the whole project, run `yarn typecheck`. | ||
|
|
||
| ## Testing | ||
|
|
||
| For lower level tests of utilities and individual modules, we use [Jest](https://jestjs.io). | ||
|
|
||
| ## Test coverage checks | ||
|
|
||
| ### For private repos | ||
|
|
||
| For private repos, Jest can be configured to terminate with an error status if there is less coverage than some configurable threshold. | ||
| This project applies coverage thresholds for `yarn test:ci`, so CI checks will fail if there is insufficient test coverage. | ||
|
|
||
| Make sure to add fixture data, mocks, or other files and file paths that you don't want to count towards your coverage thresholds | ||
| to `coveragePathIgnorePatterns` in [`jest.config.js`](jest.config.js). | ||
|
|
||
| ### For public repos | ||
|
|
||
| For public repos, [Codecov](https://codecov.io) is free. The tool offers two nice features that Jest doesn't offer out of the box: | ||
|
|
||
| - "auto" coverage targets, which track the current coverage of the `main` branch. This lets you guarantee that test coverage increases over time. | ||
| - "patch" coverage, counting only the lines modified by the current PR | ||
|
|
||
| Here's how to set it up: | ||
|
|
||
| Uncomment the `Upload Coverage Report` and `Upload coverage to Codecov` steps in [`workflow.yaml`](.github/workflows/workflow.yaml). No token is needed for public repos uploading via GitHub Actions. | ||
| Note: viem is a peer dependency, so make it sure it's installed in your project. | ||
|
|
||
| If you set up Codecov, you may consider turning off Jest coverage checks for simplicity. You can do this by removing the | ||
| `coverageThreshold` parameter from [`jest.config.js`](jest.config.js). | ||
| ## Using the library | ||
|
|
||
| ## Linting | ||
| ### Simple usage | ||
|
|
||
| This project uses [ESLint](https://eslint.org/) for linting. That is configured in [`.eslintrc.js`](.eslintrc.js). | ||
| ```typescript | ||
| import { createWalletClient, http } from 'viem' | ||
| import { mainnet } from 'viem/chains' | ||
| import { gcpHsmToAccount } from '@valora/viem-account-hsm-gcp' | ||
|
|
||
| ## Formatting | ||
| const account = await gcpHsmToAccount({ | ||
| hsmKeyVersion: | ||
| 'projects/your-gcp-project/locations/global/keyRings/your-keyring/cryptoKeys/your-hsm/cryptoKeyVersions/1', | ||
| }) | ||
|
|
||
| We use [Prettier](https://prettier.io) for auto-formatting. It's recommended to install an editor plugin (like the [VSCode Prettier plugin](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)) to get auto-formatting on save. There's also a `yarn format` script you can run to format all files in the project. | ||
| const client = createWalletClient({ | ||
| account, | ||
| chain: mainnet, | ||
| transport: http(), | ||
| }) | ||
|
|
||
| ## Dependency / Unused Code Checking | ||
| // Test send a transaction to the HSM key (the HSM key needs to be funded) | ||
| const hash = await client.sendTransaction({ | ||
| to: account.address, | ||
| value: parseEther('0.001'), | ||
| }) | ||
| ``` | ||
|
|
||
| This project uses [knip](https://github.com/webpro/knip) for checking both unused dependencies and code within the repo. This tool can catch a _lot_ of stuff, including unused dependencies, functions, types, unnecessary/duplicate exports, unused class/enum members, etc. It's configured in [`.knip.json`](.knip.json). | ||
| > [!IMPORTANT] | ||
| > Make sure the key in [Google Cloud KMS](https://console.cloud.google.com/security/kms/keyrings) is a secp256k1 key. | ||
| ## Scripts | ||
| <img src="./docs/images/gcp-key-creation.png" alt="gcp-key-creation" width="500"/> | ||
|
|
||
| We use TypeScript instead of shell scripts. This is it to avoid the many pitfalls of shell scripts. | ||
| > [!TIP] | ||
| > You don't have to use an HSM key, you can use a software key as well. See the [Google Cloud KMS documentation](https://cloud.google.com/kms/docs/algorithms#protection_levels) for more information. | ||
| To run external commands we recommend using [ShellJS](https://github.com/shelljs/shelljs). | ||
| ## Resources | ||
|
|
||
| ## GitHub Actions | ||
| - [viem](https://viem.sh/) | ||
| - [@google-cloud/kms](https://www.npmjs.com/package/@google-cloud/kms) | ||
|
|
||
| We use [GitHub Actions](https://docs.github.com/en/actions) for continuous integration and deployment (CI/CD). Anything that gets into the `main` branch will be deployed using `yarn deploy` after running tests/build/etc. | ||
| ## Acknowledgements | ||
|
|
||
| Also, we use [semantic-pull-request](https://github.com/amannn/action-semantic-pull-request) to ensure PR titles match the [Conventional Commits spec](https://www.conventionalcommits.org/). It can be used in combination with [semantic-release](https://github.com/semantic-release/semantic-release) to automate releases and changelogs. | ||
| This library is a port of [@celo/wallet-hsm-gcp](https://github.com/celo-org/developer-tooling/tree/0c61e7e02c741fe10ecd1d733a33692d324cdc82/packages/sdk/wallets/wallet-hsm-gcp) to viem. | ||
|
|
||
| [`workflow.yaml`](.github/workflows/workflow.yaml) contains a step to send slack notifications on deploy failures. For this to work, your repo needs to have access to the [MAINNET_SERVICE_ACCOUNT_KEY](https://github.com/organizations/valora-inc/settings/secrets/actions/MAINNET_SERVICE_ACCOUNT_KEY) github secret. | ||
| Big thanks to the Celo team for the original implementation. | ||
|
|
||
| ## Renovate | ||
| ## Contributing | ||
|
|
||
| [Renovate](https://renovatebot.com/) ensures our dependencies are kept up to date. It's configured with our shared config in [`renovate.json5`](renovate.json5). | ||
| - [Reporting issues](https://github.com/valora-inc/viem-account-hsm-gcp/issues) | ||
| - [Submitting a pull request](https://github.com/valora-inc/viem-account-hsm-gcp/pulls) | ||
| - Publishing updates is done automatically via [semantic-release](https://github.com/semantic-release/semantic-release). | ||
| Remember to use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) or your PR will be rejected (since | ||
| merging it would mess up the changelog and version numbers). |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.